modules/src/em_code/em_code.3X

   1 .TH EM_CODE 3 "$Revision: 1.14 $"
   2 .ad
   3 .SH NAME
   4 emcode \- EM code interface for compilers
   5 .SH SYNOPSIS
   6 .nf
   7 .B #include <em.h>
   8 .PP
   9 .B void C_init(wsize, psize)
  10 .B arith wsize, psize;
  11 .PP
  12 .B int C_open(filename)
  13 .B void C_close()
  14 .B int C_busy()
  15 .B char *filename;
  16 .PP
  17 .B void C_magic()
  18 .PP
  19 .B void C_df_dlb(l)
  20 .B void C_df_dnam(s)
  21 .B void C_df_ilb(l)
  22 .B label l; char *s;
  23 .PP
  24 .B void C_pro(s, l)
  25 .B void C_pro_narg(s)
  26 .B void C_end(l)
  27 .B void C_end_narg()
  28 .B char *s; arith l;
  29 .PP
  30 .B void C_exa_dlb(l)
  31 .B void C_exa_dnam(s)
  32 .B void C_exp(s)
  33 .B void C_ina_dlb(l)
  34 .B void C_ina_dnam(s)
  35 .B void C_inp(s)
  36 .B char *s; label l;
  37 .PP
  38 .BI "void C_bss_" cstp ()
  39 .BI "void C_hol_" cstp ()
  40 .BI "void C_con_" cstp ()
  41 .BI "void C_rom_" cstp ()
  42 .PP
  43 .B #include <em_mes.h>
  44 .B void C_mes_begin(ms)
  45 .BI "void C_" cstp ()
  46 .B void C_mes_end()
  47 .B int ms;
  48 .PP
  49 .B void C_exc(c1, c2)
  50 .B arith c1, c2;
  51 .PP
  52 .BI "void C_" mnem ()
  53 .BI "void C_" mnem _dlb()
  54 .BI "void C_" mnem _dnam()
  55 .BI "void C_" mnem _narg()
  56 .PP
  57 .B void C_insertpart(id)
  58 .B int id;
  59 .PP
  60 .B void C_beginpart(id)
  61 .B int id;
  62 .PP
  63 .B void C_endpart(id)
  64 .B int id;
  65 .PP
  66 .B int C_getid()
  67 .PP
  68 .B char *C_tmpdir;
  69 .PP
  70 .B #include <em.h>
  71 .PP
  72 .B int C_out(p)
  73 .B struct e_instr *p;
  74 .PP
  75 .B char *C_error;
  76 .fi
  77 .SH DESCRIPTION
  78 This package provides a procedural EM code interface to be used in
  79 compilers and other EM code producing programs.
  80 The basic idea behind this package is to simplify the program writer's task
  81 of producing EM code in any form, either compact or human-readable
  82 EM assembly code or a sequence of procedure calls.
  83 .PP
  84 The named types
  85 .B arith
  86 and
  87 .B label
  88 refer to types on the local
  89 machine that are suitable for doing arithmetics and storing EM numeric labels
  90 respectively.
  91 Common definitions are
  92 .B long
  93 for
  94 .B arith
  95 and
  96 .B
  97 unsigned int
  98 for
  99 .BR label .
 100 .PP
 101 .B C_init()
 102 should be called to initialize the module.
 103 .I Wsize
 104 is the word size and
 105 .I psize
 106 the pointer size on the target machine.
 107 Checking implementations of this module use these values to check
 108 whether arguments of an instruction are legal.
 109 .PP
 110 .BI C_open( filename )
 111 should be invoked as initialiser for
 112 a sequence of calls that produce EM code on file
 113 .IR filename .
 114 When
 115 .I filename
 116 is a null pointer, the code is produced on standard output.
 117 Some implementations, such as fast back ends, may ignore the parameter.
 118 .B C_close
 119 causes some internal buffers to be flushed and the output file to be closed.
 120 All subsequent routines, except for
 121 .BR C_busy ,
 122 must be invoked between the calls to
 123 .B C_open
 124 and
 125 .BR C_close .
 126 .PP
 127 .B C_busy
 128 can be invoked in order
 129 to detect whether EM code is currently being generated, i.e. whether
 130 .B C_open
 131 is invoked without a corresponding
 132 .BR C_close .
 133 If this is the case,
 134 .B C_busy
 135 returns a 1.
 136 .PP
 137 .B C_magic()
 138 produces the EM magic word.
 139 .PP
 140 Two routines can be used to generate code for the definitions of global data
 141 labels:
 142 .BI C_df_dlb( l )
 143 for numeric labels
 144 .BI . l
 145 and
 146 .BI C_df_dnam( s )
 147 for alphanumeric labels
 148 .IR s .
 149 .PP
 150 .BI C_df_ilb( l )
 151 produces EM code for instruction label
 152 .IR l .
 153 .PP
 154 The routines for producing the EM procedure delimiters are:
 155 .PP
 156 .RS
 157 .TS
 158 box;
 159 l|l.
 160 routine EM pattern
 161 =
 162 \&\fBC_pro(\fP\fIs\fP\fB,\ \fP\fIl\fP\fB)\fP    \fBpro\ \fP\fIs\fP\fB,\ \fP\fIl\fP
 163 _
 164 \&\fBC_pro_narg(\fP\fIs\fP\fB)\fP       \fBpro\ \fP\fIs\fP\fB,\ ?\fP
 165 _
 166 \&\fBC_end(\fP\fIl\fP\fB)\fP    \fBend\ \fP\fIl\fP
 167 _
 168 \&\fBC_end_narg()\fP    \fBend\ ?\fP
 169 .TE
 170 .RE
 171 .PP
 172 A set of routines, concerning the scope definition pseudo instructions, is:
 173 .PP
 174 .RS
 175 .TS
 176 box;
 177 l|l.
 178 routine EM pattern
 179 =
 180 \&\fBC_exa_dnam(\fP\fIs\fP\fB)\fP       \fBexa \fP\fIs\fP
 181 _
 182 \&\fBC_exa_dlb(\fP\fIl\fP\fB)\fP        \fBexa .\fP\fIl\fP
 183 _
 184 \&\fBC_exp(\fP\fIs\fP\fB)\fP    \fBexp $\fP\fIs\fP
 185 _
 186 \&\fBC_ina_dnam(\fP\fIs\fP\fB)\fP       \fBina \fP\fIs\fP
 187 _
 188 \&\fBC_ina_dlb(\fP\fIl\fP\fB)\fP        \fBina .\fP\fIl\fP
 189 _
 190 \&\fBC_inp(\fP\fIs\fP\fB)\fP    \fBinp $\fP\fIs\fP
 191 .TE
 192 .RE
 193 .PP
 194 In the set of
 195 .B storage-declaration
 196 pseudo instructions, we can
 197 distinguish four groups, one for each type of storage declaration:
 198 .BR con ,
 199 .BR rom ,
 200 .B bss
 201 and
 202 .BR hol .
 203 .PP
 204 The
 205 .BR con / rom
 206 instructions are generated by
 207 .BI C_con_ cstp
 208 and
 209 .BI C_rom_ cstp ,
 210 respectively.
 211 The type of the initialization value and the number and type of the parameters
 212 are determined by
 213 .I cstp
 214 according to the following table:
 215 .PP
 216 .RS
 217 .TS
 218 box;
 219 l|l|l|l
 220 l|l|l|l
 221 l|n|l|l.
 222 \&\fIcstp\fP    number of       type of description
 223         parameters      parameters
 224 =
 225 \&\fBcst\fP     1       \fBarith\fP     word-sized integer of \fBarith\fP-type
 226 _
 227 \&\fBicon\fP    2       \fBchar *\fP    integer in string representation
 228                 \fBarith\fP     number of bytes on target machine
 229 _
 230 \&\fBucon\fP    2       \fBchar *\fP    unsigned integer in string representation
 231                 \fBarith\fP     number of bytes on target machine
 232 _
 233 \&\fBfcon\fP    2       \fBchar *\fP    floating in string representation
 234                 \fBarith\fP     number of bytes on target machine
 235 _
 236 \&\fBscon\fP    2       \fBchar *\fP    row of bytes
 237                 \fBarith\fP     length of the row of bytes
 238 _
 239 \&\fBdnam\fP    2       \fBchar *\fP    alphanumeric global data label
 240                 \fBarith\fP     offset (possibly 0)
 241 _
 242 \&\fBdlb\fP     2       \fBlabel\fP     numeric global data label
 243                 \fBarith\fP     offset (possibly 0)
 244 _
 245 \&\fBilb\fP     1       \fBlabel\fP     instruction label
 246 _
 247 \&\fBpnam\fP    1       \fBchar *\fP    procedure identifier
 248 .TE
 249 .RE
 250 .PP
 251 As an example of the use of the
 252 .BR con / rom
 253 routines, consider the
 254 following
 255 .B con
 256 instruction:
 257 .RS
 258 con 23I4, "hello world", .12, table + 12, *33
 259 .RE
 260 A sequence of calls to get this, is
 261 .RS
 262 .nf
 263 C_con_icon("23", (arith)4);
 264 C_con_scon("hello world", (arith) 11);
 265 C_con_dlb((label)12, (arith)0);
 266 C_con_dnam("table", (arith)12);
 267 C_con_ilb((label)33);
 268 .fi
 269 .RE
 270 .PP
 271 A
 272 .B bss
 273 or
 274 .B hol
 275 instruction is produced by invoking
 276 .BI C_bss_ cstp
 277 or
 278 .BI C_hol_ cstp
 279 where
 280 .I cstp
 281 indicates the type of value that is used at initialisation.
 282 The parameter list of
 283 .BI C_bss_ cstp
 284 and
 285 .BI C_hol_ cstp
 286 is similar to that of the corresponding
 287 .BI C_con_ cstp,
 288 except that it is preceeded by an
 289 .BR arith -typed
 290 operand
 291 .I nbytes,
 292 and followed by an
 293 .BR int -typed
 294 operand
 295 .IR init ;
 296 .I nbytes
 297 indicates the number of bytes to reserve for the data;
 298 .I init
 299 has value 1 if the initialization is strictly necessary and 0 if not.
 300 Note that, according to the EM definition, an initialisation type of
 301 .B scon
 302 is not allowed in the
 303 .BR bss / hol
 304 instruction.
 305 .PP
 306 Another set of routines is that of the EM
 307 .B mes
 308 pseudo instructions.
 309 As there is an undefined number of messages and each type of message has
 310 its own number of parameters and each parameter its own type,
 311 the user is responsible for building his own message lists.
 312 Such a list consists of a list of
 313 .BI C_ cstp
 314 routine calls enclosed
 315 by
 316 .BI C_mes_begin( ms )
 317 where
 318 .I ms
 319 is the message number,
 320 and
 321 .BR C_mes_end() .
 322 .PP
 323 .I C_exc
 324 produces the EM
 325 .B exc
 326 .IR c1 , c2
 327 instruction.
 328 The use of this function may cause trouble in some implementations of this
 329 module.
 330 A fast back end, for instance, may refuse to implement
 331 .IR C_exc .
 332 The use of this function is therefore not recommended.
 333 .PP
 334 The final class of routines is that of the EM machine-instruction generating
 335 routines
 336 .BI C_ mnem,
 337 .BI C_ mnem _dlb ,
 338 .BI C_ mnem _dnam
 339 and
 340 .BI C_ mnem _narg .
 341 The best way to describe them is according to section 11.3 of [EM].
 342 Depending on the class of the argument (as indicated by a letter), one
 343 or more routines are available for each machine instruction.
 344 The following table gives an overview of the available routines for
 345 the EM machine instruction
 346 .IR mnem :
 347 .PP
 348 .RS
 349 .TS
 350 box;
 351 l|l|l|l
 352 l|l|l|l
 353 l|l|n|l.
 354 class   routine(s)      number of       type of
 355                 parameters      parameter(s)
 356 =
 357 [\fBcdflnorsz\fP]       \fBC_\fP\fImnem\fP      1       \fBarith\fP
 358 _
 359 \&\fBw\fP       \fBC_\fP\fImnem\fP      1       \fBarith\fP
 360         \fBC_\fP\fImnem\fP\fB_narg\fP   0
 361 _
 362 \&\fBg\fP       \fBC_\fP\fImnem\fP      1       \fBarith\fP
 363         \fBC_\fP\fImnem\fP\fB_dnam\fP   2       \fBchar *\fP
 364                         \fBarith\fP
 365         \fBC_\fP\fImnem\fP\fB_dlb\fP    2       \fBlabel\fP
 366                         \fBarith\fP
 367 _
 368 \&\fBp\fP       \fBC_\fP\fImnem\fP      1       \fBchar *\fP
 369 _
 370 \&\fBb\fP       \fBC_\fP\fImnem\fP      1       \fBlabel\fP
 371 _
 372 \&\fB\-\fP      \fBC_\fP\fImnem\fP      0
 373 .TE
 374 .RE
 375 .PP
 376 The available routines for, for example, the EM machine instruction
 377 .B adi
 378 (with argument class
 379 .BR w )
 380 are
 381 .BI C_adi( w )
 382 for
 383 .B adi
 384 with a given argument, and
 385 .B C_adi_narg()
 386 for
 387 .B adi
 388 with an argument on top of the stack.
 389 Likewise are the available routines for
 390 .BR loe
 391 (which instruction has argument class
 392 .BR g ):
 393 .BI C_loe( g )
 394 where
 395 .I g
 396 is a constant,
 397 .BI C_loe_dnam( g , o )
 398 where
 399 .I g
 400 is an alphanumeric label, and
 401 .BI C_loe_dlb( g , o )
 402 where
 403 .I g
 404 is a numeric label.
 405 The latter two routines have the (possibly zero) offset
 406 .I o
 407 as second parameter.
 408 .PP
 409 The
 410 .IR C_insertpart ,
 411 .IR C_beginpart ,
 412 and
 413 .I C_endpart
 414 routines together implement a mechanism for re-arranging the generated code.
 415 A call to
 416 .I C_insertpart
 417 indicates that part
 418 .I id
 419 is to be inserted at the current position.
 420 The routines
 421 .I C_beginpart
 422 and
 423 .I C_endpart
 424 indicate begin and end of part
 425 .IR id .
 426 The order in which the parts are defined is not significant.
 427 However, when
 428 .I C_close
 429 is called, all parts that have been inserted, must also be defined.
 430 Parts may themselves again have sub-parts.
 431 .PP
 432 The routine
 433 .I C_getid
 434 can be used to obtain a valid and unique part
 435 .IR id .
 436 .PP
 437 On implementations with limited memory, the mechanism is implemented with a
 438 temporary file.
 439 The directory in which this file resides is indicated by
 440 .IR C_tmpdir .
 441 The default is the #define TMP_DIR from ~em/h/em_path.h.
 442 The user can change this by just changing
 443 .I C_tmpdir
 444 before calling
 445 .IR C_open.
 446 .PP
 447 .I C_out
 448 accepts a structure as delivered by the
 449 .I read_em
 450 module, and produces code for it. It returns 1 if it succeeds, 0 if it fails
 451 for some reason. The reason can then be found in \fIC_error\fP. The
 452 .I C_out
 453 routine replaces the EM_mkcalls routine.
 454 .SH FILES
 455 .nf
 456 ~em/modules/h/em.h
 457 ~em/modules/lib/libemk.a: library for generating compact EM code
 458 ~em/modules/lib/libeme.a: library for generating human-readable EM code
 459 ~em/lib.bin/em_data.a: library needed when using libeme.a
 460 .fi
 461 .SH MODULES
 462 .nf
 463 libemk.a: alloc(3), system(3), string(3)
 464 libeme.a: alloc(3), print(3), system(3), string(3)
 465 .fi
 466 .SH SEE ALSO
 467 read_em(3), em_mes(3)
 468 .SH REFERENCES
 469 .IP [EM] 6
 470 Andrew S. Tanenbaum, Hans van Staveren, Ed G. Keizer, Johan W. Stevenson,
 471 .B
 472 "Description of a Machine Architecture for use with Block Structured Languages",
 473 Informatica Rapport IR-81, Vrije Universiteit, Amsterdam, 1983.
 474 .LP
 475 .SH DIAGNOSTICS
 476 .I C_open
 477 returns 1 if the open is successful and 0 if not.
 478 .PP
 479 When a read, write or open fails, the routine
 480 .I C_failed
 481 is called. The user can override its default definition by supplying his
 482 own. The default just gives an error message and quits.
 483 .PP
 484 When an error occurs with the
 485 .I C_insertpart
 486 mechanism, the routine
 487 .I C_internal_error
 488 is called. Again, the user can override its default definition by supplying his
 489 own. Such errors, however, are caused by a programming error of the user.
 490 .SH REMARKS
 491 Some of the routines in this module may be implemented as macros. So,
 492 do not try to take the address of these functions.
 493 .SH BUGS
 494 It is not possible to indicate that the argument of
 495 .B C_con_cst ()
 496 must be seen as an unsigned value.