modules/src/read_em/read_em.3

   1 .TH READ_EM 3 "$Revision: 1.16 $"
   2 .ad
   3 .SH NAME
   4 EM_open, EM_getinstr, EM_close,
   5 EM_mkcalls\ \-\ a module to read EM assembly code
   6 .SH SYNOPSIS
   7 .B #include <em_spec.h>
   8 .br
   9 .B #include <em_mnem.h>
  10 .br
  11 .B #include <em_pseu.h>
  12 .br
  13 .B #include <em_flag.h>
  14 .br
  15 .B #include <em_ptyp.h>
  16 .br
  17 .B #include <em.h>
  18 .br
  19 .B #include <em_comp.h>
  20 .PP
  21 .B int EM_open(filename)
  22 .br
  23 .B char *filename;
  24 .PP
  25 .B void EM_close()
  26 .PP
  27 .B int EM_getinstr(instr)
  28 .B struct e_instr *instr;
  29 .PP
  30 .B int EM_mkcalls(instr)
  31 .br
  32 .B struct e_instr *instr;
  33 .PP
  34 .B char *EM_error;
  35 .PP
  36 .B unsigned int EM_lineno;
  37 .PP
  38 .B char *EM_filename;
  39 .PP
  40 .B int EM_wordsize, EM_pointersize;
  41 .SH DESCRIPTION
  42 This package provides routines to read EM assembly code.
  43 The object is to simplify the program
  44 writer's task of reading EM assembly code,
  45 either in compact or human-readable form.
  46 .PP
  47 \fIEM_open\fR must be called as initializer of the package.
  48 If \fIfilename\fR is a null pointer, reading is done from standard input,
  49 otherwise it is done from the file \fIfilename\fR.
  50 \fIEM_open\fR returns 1 on success and 0 on failure
  51 with an error message in \fIEM_error\fR.
  52 \fIEM_close\fR must be called after all other calls to this package.
  53 .PP
  54 \fIEM_getinstr\fR reads an EM instruction, and
  55 returns it in the structure pointed to by \fIinstr\fR.
  56 This structure has the following layout:
  57 .br
  58 .PP
  59 .ta \w'struct\ \ \ 'u +\w'struct e_instr *\ \ \ \ \ \ 'u +\w'em_opcode\ \ \ 'u +\w'*emu_string\ \ \ 'u
  60 .nf
  61 /*
  62  * (c) copyright 1987 by the Vrije Universiteit, Amsterdam, The Netherlands.
  63  * See the copyright notice in the ACK home directory, in the file "Copyright".
  64  */
  65 /* $Id: read_em.3,v 1.16 1994/06/24 11:21:24 ceriel Exp $ */
  66
  67 struct e_arg {
  68         int     ema_argtype;            /* type of this argument */
  69         union e_simple_arg {
  70                 arith   emu_cst;        /* a cst */
  71                 label   emu_dlb;        /* a numeric data label */
  72                 label   emu_ilb;        /* an instruction label */
  73                 char    *emu_dnam;      /* a data label */
  74                 char    *emu_pnam;      /* a procedure name */
  75                 char    *emu_string;    /* a string (fcon,icon,ucon,scon) */
  76         }       ema_arg;
  77         arith   ema_szoroff;
  78 };
  79 #define ema_cst         ema_arg.emu_cst
  80 #define ema_dlb         ema_arg.emu_dlb
  81 #define ema_ilb         ema_arg.emu_ilb
  82 #define ema_dnam        ema_arg.emu_dnam
  83 #define ema_pnam        ema_arg.emu_pnam
  84 #define ema_nlocals     ema_szoroff
  85 #define ema_string      ema_arg.emu_string
  86
  87
  88 struct e_instr {
  89         int             em_type;        /* Type of this instr */
  90 #define EM_MNEM         256             /* A machine instruction */
  91 #define EM_PSEU         257             /* A pseudo */
  92 #define EM_STARTMES     258             /* Start of a MES pseudo */
  93 #define EM_MESARG       259             /* A member in a MES list */
  94 #define EM_ENDMES       260             /* End of a MES pseudo */
  95 #define EM_DEFILB       261             /* An instruction label definition */
  96 #define EM_DEFDLB       262             /* A numeric data label definition */
  97 #define EM_DEFDNAM      263             /* A non-numeric data label def */
  98 #define EM_ERROR        264             /* Recoverable error */
  99 #define EM_FATAL        265             /* Unrecoverable error */
 100 #define EM_EOF          266             /* End of file */
 101         int             em_opcode;
 102         struct e_arg    em_arg;
 103 };
 104
 105 extern arith
 106         EM_holsize, EM_bsssize;
 107 extern int
 108         EM_holinit, EM_bssinit;
 109
 110 #define em_ilb          em_arg.ema_ilb
 111 #define em_dlb          em_arg.ema_dlb
 112 #define em_dnam         em_arg.ema_dnam
 113 #define em_argtype      em_arg.ema_argtype
 114 #define em_cst          em_arg.ema_cst
 115 #define em_pnam         em_arg.ema_pnam
 116 #define em_nlocals      em_arg.ema_nlocals
 117 #define em_string       em_arg.ema_string
 118 #define em_off          em_arg.ema_szoroff
 119 #define em_size         em_arg.ema_szoroff
 120
 121 /* arguments for EXC pseudo: */
 122 #define em_exc1         em_arg.ema_cst
 123 #define em_exc2         em_arg.ema_szoroff
 124
 125 extern char
 126         *EM_error, *EM_filename;
 127 extern unsigned int
 128         EM_lineno;
 129 extern int
 130         EM_wordsize, EM_pointersize;
 131 .fi
 132 .PP
 133 The named types \fBarith\fR and \fBlabel\fR refer to types on the local machine
 134 that are suitable for doing arithmetic and storing EM numeric labels
 135 respectively.
 136 Common definitions are \fBlong\fR for \fBarith\fR and \fBunsigned int\fR for
 137 \fBlabel\fR.
 138 .PP
 139 The \fIe_instr\fR structure consists of the fields
 140 \fIem_type\fR, containing the type of this \fIe_instr\fR,
 141 \fIem_opcode\fR, containing the opcode of an instruction,
 142 and \fIem_arg\fR, containing a possible argument.
 143 .PP
 144 The possible values of
 145 \fIem_type\fR, defined in <em_comp.h>, are summarized below:
 146 .br
 147 .ta \w'EM_STARTMES\ \ \ 'u +\w'em_defdnam\ \ \ 'u
 148 .di xx
 149                 \ka
 150 .br
 151 .di
 152 .IP "Value      Selector" \nau
 153 Meaning
 154 .IP "EM_MNEM    em_opcode" \nau
 155 an EM machine instruction.
 156 .br
 157 .PD 0
 158 .IP "   em_arg" \nau
 159 The \fIem_opcode\fR field
 160 contains the opcode of the instruction, and \fIem_arg\fR may contain an
 161 argument. If \fIem_argtype\fR indicates that there is no argument,
 162 \fIem_cst\fR is set to 0.
 163 .IP "EM_PSEU    em_opcode" \nau
 164 an EM pseudo instruction.
 165 .IP "   em_arg" \nau
 166 The \fIem_opcode\fR field
 167 contains the opcode, and \fIem_arg\fR may contain an argument.
 168 As consecutive CON-pseudos are allocated consecutively, a CON delivered by
 169 \fIEM_getinstr\fR has exactly one argument.
 170 If the CON-pseudo read has more, they are delivered as separate CON's.
 171 The same holds for ROM-pseudos.
 172 Also, if the length of a string constant exceeds 256 characters, it will be
 173 delivered as several CON's or ROM's.
 174 There are two "special" pseudo's, that use other variables, HOL and BSS.
 175 They use EM_holsize, EM_holinit, EM_bsssize, and EM_bssinit, because those
 176 arguments do not fit in the \fIe_arg\fR structure, and we want to keep the
 177 \fIe_arg\fR structure as small as possible.
 178 The EXC pseudo has its arguments encoded as indicated in the #defines.
 179 The PRO pseudo has its second argument in \fIem_nlocals\fR. If it is
 180 -1, it was omitted.
 181 .IP "EM_STARTMES        em_arg" \nau
 182 the start of a MES pseudo.
 183 .br
 184 There is one argument: the message number.
 185 The other arguments, if any, are delivered as separate EM_MESARG's.
 186 .IP "EM_MESARG  em_arg" \nau
 187 an argument of a MES pseudo.
 188 .IP "EM_ENDMES  none" \nau
 189 the end of a MES pseudo.
 190 .IP "EM_DEFILB  em_ilb" \nau
 191 an instruction label definition.
 192 .br
 193 The field \fIem_ilb\fR contains the label (instruction labels are always
 194 numeric).
 195 .IP "EM_DEFDLB  em_dlb" \nau
 196 a numeric data label definition.
 197 .br
 198 The field \fIem_dlb\fR contains the label.
 199 .IP "EM_DEFDNAM em_dnam" \nau
 200 a non-numeric data label definition.
 201 .br
 202 The field \fIem_dnam\fR contains the label.
 203 .IP "EM_ERROR   none" \nau
 204 an error in the input that makes the rest of the data in the structure
 205 meaningless.
 206 .br
 207 \fIEM_error\fR
 208 contains an error message.
 209 .IP "EM_FATAL   none" \nau
 210 a fatal error.
 211 .br
 212 \fIEM_error\fR contains an
 213 error message.
 214 .IP "EM_EOF     none" \nau
 215 end of file
 216 .PD
 217 .PP
 218 The \fIe_arg\fR structure consists of the fields
 219 the field \fIema_argtype\fR, containing the type of this argument or 0
 220 if absent,
 221 the field \fIema_arg\fR, containing the value of the argument,
 222 and \fIema_szoroff\fR, containing an optional offset or size.
 223 The possible values of \fIema_argtype\fR, defined in <em_ptyp.h>,
 224 are summarized below:
 225 .br
 226 .ta \w'dlb_ptyp\ \ \ \ 'u +\w'em_opcode\ \ \ 'u
 227 .di xx
 228                 \ka
 229 .br
 230 .di
 231 .IP "Value      Selector" \nau
 232 Meaning
 233 .IP "0  none" \nau
 234 no argument.
 235 .IP "ilb_ptyp   em_ilb" \nau
 236 an instruction label.
 237 .PD 0
 238 .IP "nof_ptyp   em_dlb" \nau
 239 an offset from a numeric data label.
 240 .IP "   em_off" \nau
 241 The
 242 \fIem_off\fR field contains the offset and the
 243 \fIem_dlb\fR field contains the label.
 244 .IP "sof_ptyp   em_dnam" \nau
 245 an offset from a non-numeric data label.
 246 .IP "   em_off" \nau
 247 The \fIem_off\fR field contains the offset and the \fIem_dnam\fR field
 248 contains the label, represented as a string.
 249 .IP "cst_ptyp   em_cst" \nau
 250 a numeric constant.
 251 .IP "pro_ptyp   em_pnam" \nau
 252 a procedure name, not including the '$',
 253 represented as a string.
 254 .IP "str_ptyp   em_string" \nau
 255 a string constant.
 256 .IP "   em_size" \nau
 257 The string is found in \fIem_string\fR, represented as a row of bytes, of
 258 length \fIem_size\fR.
 259 .IP "ico_ptyp   em_string" \nau
 260 an integer constant.
 261 .IP "   em_size" \nau
 262 A string representation of the constant is found in \fIem_string\fR.
 263 It has size \fIem_size\fR bytes on the target machine.
 264 .IP "uco_ptyp   em_string" \nau
 265 an unsigned constant.
 266 .IP "   em_size" \nau
 267 A string representation of the constant is found in \fIem_string\fR.
 268 It has size \fIem_size\fR bytes on the target machine.
 269 .IP "fco_ptyp   em_string" \nau
 270 a floating constant.
 271 .IP "   em_size" \nau
 272 A string representation of the constant is found in \fIem_string\fR.
 273 It has size \fIem_size\fR bytes on the target machine.
 274 .PD
 275 .PP
 276 When an error occurs, \fIEM_error\fR is set to indicate the reason.
 277 \fIEM_getinstr\fR returns 1 if all goes well, 0 if it does not.
 278 The EM_ERROR described above is only set when the error
 279 is serious enough.
 280 .PP
 281 The routine \fIEM_mkcalls\fR "translates" the EM instruction indicated
 282 by \fIinstr\fR
 283 into calls of the procedural interface defined in \fIem_code\fR(3L).
 284 It returns 1 if it succeeds, 0 if it fails for some reason. The
 285 reason can then be found in \fIEM_error\fR.
 286 The \fIEM_mkcalls\fP routine is obsolete. It is being replaced by the
 287 .I C_out
 288 routine of the
 289 .I em_code
 290 module.
 291 .PP
 292 \fIEM_lineno\fR contains the line number of the last line read by
 293 \fIEM_getinstr\fR.
 294 .PP
 295 \fIEM_filename\fR contains a filename. It usually contains the value
 296 given as parameter to \fIEM_open\fR, but may have a different value, when
 297 the input was the result of some preprocessing.
 298 .PP
 299 .I EM_wordsize
 300 and
 301 .I EM_pointersize
 302 contain the wordsize and pointersize, but only after the first
 303 (pseudo-)instruction has successfully been read.
 304 .SH FILES
 305 .nf
 306 ~em/modules/h/em.h
 307 ~em/h/em_ptyp.h
 308 ~em/modules/h/em_comp.h
 309 ~em/modules/lib/libread_emk.a: non-checking library for reading compact EM code
 310 ~em/modules/lib/libread_emkV.a: checking library for reading compact EM code
 311 ~em/modules/lib/libread_emeV.a: checking library for reading human-readable EM code
 312 .fi
 313 .SH MODULES
 314 em_code(3), string(3), system(3), ~em/lib.bin/em_data.a
 315 .SH "SEE ALSO"
 316 em_code(3)
 317 .br
 318 A.S. Tanenbaum, H. v Staveren, E.G. Keizer, J.W. Stevenson, "\fBDescription
 319 of a Machine Architecture for use with Block Structured Languages\fR",
 320 Informatica Rapport IR-81, Vrije Universiteit, Amsterdam, 1983.
 321 .SH REMARKS
 322 All strings must be considered to be contained in a static area, so
 323 must be copied to be saved.
 324 .SH BUGS
 325 As CON's and ROM's may be delivered in several parts, the count fields in
 326 a static exchange may be wrong.
 327 .PP
 328 Please report bugs to the author.