123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328 |
- .TH READ_EM 3 "$Revision$"
- .ad
- .SH NAME
- EM_open, EM_getinstr, EM_close,
- EM_mkcalls\ \-\ a module to read EM assembly code
- .SH SYNOPSIS
- .B #include <em_spec.h>
- .br
- .B #include <em_mnem.h>
- .br
- .B #include <em_pseu.h>
- .br
- .B #include <em_flag.h>
- .br
- .B #include <em_ptyp.h>
- .br
- .B #include <em.h>
- .br
- .B #include <em_comp.h>
- .PP
- .B int EM_open(filename)
- .br
- .B EM_close()
- .br
- .B char *filename;
- .PP
- .B int EM_getinstr(instr)
- .B struct e_instr *instr;
- .PP
- .B int EM_mkcalls(instr)
- .br
- .B struct e_instr *instr;
- .PP
- .B char *EM_error;
- .PP
- .B unsigned int EM_lineno;
- .PP
- .B char *EM_filename;
- .PP
- .B int EM_wordsize, EM_pointersize;
- .SH DESCRIPTION
- This package provides routines to read EM assembly code.
- The object is to simplify the program
- writer's task of reading EM assembly code,
- either in compact or human-readable form.
- .PP
- \fIEM_open\fR must be called as initializer of the package.
- If \fIfilename\fR is a null pointer, reading is done from standard input,
- otherwise it is done from the file \fIfilename\fR.
- \fIEM_open\fR returns 1 on success and 0 on failure
- with an error message in \fIEM_error\fR.
- \fIEM_close\fR must be called after all other calls to this package.
- .PP
- \fIEM_getinstr\fR reads an EM instruction, and
- returns it in the structure pointed to by \fIinstr\fR.
- This structure has the following layout:
- .br
- .PP
- .ta \w'struct\ \ \ 'u +\w'struct e_instr *\ \ \ \ \ \ 'u +\w'em_opcode\ \ \ 'u +\w'*emu_string\ \ \ 'u
- .nf
- /*
- * (c) copyright 1987 by the Vrije Universiteit, Amsterdam, The Netherlands.
- * See the copyright notice in the ACK home directory, in the file "Copyright".
- */
- /* $Header$ */
- struct e_arg {
- int ema_argtype; /* type of this argument */
- union e_simple_arg {
- arith emu_cst; /* a cst */
- label emu_dlb; /* a numeric data label */
- label emu_ilb; /* an instruction label */
- char *emu_dnam; /* a data label */
- char *emu_pnam; /* a procedure name */
- char *emu_string; /* a string (fcon,icon,ucon,scon) */
- } ema_arg;
- arith ema_szoroff;
- };
- #define ema_cst ema_arg.emu_cst
- #define ema_dlb ema_arg.emu_dlb
- #define ema_ilb ema_arg.emu_ilb
- #define ema_dnam ema_arg.emu_dnam
- #define ema_pnam ema_arg.emu_pnam
- #define ema_nlocals ema_szoroff
- #define ema_string ema_arg.emu_string
- struct e_instr {
- int em_type; /* Type of this instr */
- #define EM_MNEM 256 /* A machine instruction */
- #define EM_PSEU 257 /* A pseudo */
- #define EM_STARTMES 258 /* Start of a MES pseudo */
- #define EM_MESARG 259 /* A member in a MES list */
- #define EM_ENDMES 260 /* End of a MES pseudo */
- #define EM_DEFILB 261 /* An instruction label definition */
- #define EM_DEFDLB 262 /* A numeric data label definition */
- #define EM_DEFDNAM 263 /* A non-numeric data label def */
- #define EM_ERROR 264 /* Recoverable error */
- #define EM_FATAL 265 /* Unrecoverable error */
- #define EM_EOF 266 /* End of file */
- int em_opcode;
- struct e_arg em_arg;
- };
- extern arith
- EM_holsize, EM_bsssize;
- extern int
- EM_holinit, EM_bssinit;
- #define em_ilb em_arg.ema_ilb
- #define em_dlb em_arg.ema_dlb
- #define em_dnam em_arg.ema_dnam
- #define em_argtype em_arg.ema_argtype
- #define em_cst em_arg.ema_cst
- #define em_pnam em_arg.ema_pnam
- #define em_nlocals em_arg.ema_nlocals
- #define em_string em_arg.ema_string
- #define em_off em_arg.ema_szoroff
- #define em_size em_arg.ema_szoroff
- /* arguments for EXC pseudo: */
- #define em_exc1 em_arg.ema_cst
- #define em_exc2 em_arg.ema_szoroff
- extern char
- *EM_error, *EM_filename;
- extern unsigned int
- EM_lineno;
- extern int
- EM_wordsize, EM_pointersize;
- .fi
- .PP
- The named types \fBarith\fR and \fBlabel\fR refer to types on the local machine
- that are suitable for doing arithmetic and storing EM numeric labels
- respectively.
- Common definitions are \fBlong\fR for \fBarith\fR and \fBunsigned int\fR for
- \fBlabel\fR.
- .PP
- The \fIe_instr\fR structure consists of the fields
- \fIem_type\fR, containing the type of this \fIe_instr\fR,
- \fIem_opcode\fR, containing the opcode of an instruction,
- and \fIem_arg\fR, containing a possible argument.
- .PP
- The possible values of
- \fIem_type\fR, defined in <em_comp.h>, are summarized below:
- .br
- .ta \w'EM_STARTMES\ \ \ 'u +\w'em_defdnam\ \ \ 'u
- .di xx
- \ka
- .br
- .di
- .IP "Value Selector" \nau
- Meaning
- .IP "EM_MNEM em_opcode" \nau
- an EM machine instruction.
- .br
- .PD 0
- .IP " em_arg" \nau
- The \fIem_opcode\fR field
- contains the opcode of the instruction, and \fIem_arg\fR may contain an
- argument. If \fIem_argtype\fR indicates that there is no argument,
- \fIem_cst\fR is set to 0.
- .IP "EM_PSEU em_opcode" \nau
- an EM pseudo instruction.
- .IP " em_arg" \nau
- The \fIem_opcode\fR field
- contains the opcode, and \fIem_arg\fR may contain an argument.
- As consecutive CON-pseudos are allocated consecutively, a CON delivered by
- \fIEM_getinstr\fR has exactly one argument.
- If the CON-pseudo read has more, they are delivered as separate CON's.
- The same holds for ROM-pseudos.
- Also, if the length of a string constant exceeds 256 characters, it will be
- delivered as several CON's or ROM's.
- There are two "special" pseudo's, that use other variables, HOL and BSS.
- They use EM_holsize, EM_holinit, EM_bsssize, and EM_bssinit, because those
- arguments do not fit in the \fIe_arg\fR structure, and we want to keep the
- \fIe_arg\fR structure as small as possible.
- The EXC pseudo has its arguments encoded as indicated in the #defines.
- The PRO pseudo has its second argument in \fIem_nlocals\fR. If it is
- -1, it was omitted.
- .IP "EM_STARTMES em_arg" \nau
- the start of a MES pseudo.
- .br
- There is one argument: the message number.
- The other arguments, if any, are delivered as separate EM_MESARG's.
- .IP "EM_MESARG em_arg" \nau
- an argument of a MES pseudo.
- .IP "EM_ENDMES none" \nau
- the end of a MES pseudo.
- .IP "EM_DEFILB em_ilb" \nau
- an instruction label definition.
- .br
- The field \fIem_ilb\fR contains the label (instruction labels are always
- numeric).
- .IP "EM_DEFDLB em_dlb" \nau
- a numeric data label definition.
- .br
- The field \fIem_dlb\fR contains the label.
- .IP "EM_DEFDNAM em_dnam" \nau
- a non-numeric data label definition.
- .br
- The field \fIem_dnam\fR contains the label.
- .IP "EM_ERROR none" \nau
- an error in the input that makes the rest of the data in the structure
- meaningless.
- .br
- \fIEM_error\fR
- contains an error message.
- .IP "EM_FATAL none" \nau
- a fatal error.
- .br
- \fIEM_error\fR contains an
- error message.
- .IP "EM_EOF none" \nau
- end of file
- .PD
- .PP
- The \fIe_arg\fR structure consists of the fields
- the field \fIema_argtype\fR, containing the type of this argument or 0
- if absent,
- the field \fIema_arg\fR, containing the value of the argument,
- and \fIema_szoroff\fR, containing an optional offset or size.
- The possible values of \fIema_argtype\fR, defined in <em_ptyp.h>,
- are summarized below:
- .br
- .ta \w'dlb_ptyp\ \ \ \ 'u +\w'em_opcode\ \ \ 'u
- .di xx
- \ka
- .br
- .di
- .IP "Value Selector" \nau
- Meaning
- .IP "0 none" \nau
- no argument.
- .IP "ilb_ptyp em_ilb" \nau
- an instruction label.
- .PD 0
- .IP "nof_ptyp em_dlb" \nau
- an offset from a numeric data label.
- .IP " em_off" \nau
- The
- \fIem_off\fR field contains the offset and the
- \fIem_dlb\fR field contains the label.
- .IP "sof_ptyp em_dnam" \nau
- an offset from a non-numeric data label.
- .IP " em_off" \nau
- The \fIem_off\fR field contains the offset and the \fIem_dnam\fR field
- contains the label, represented as a string.
- .IP "cst_ptyp em_cst" \nau
- a numeric constant.
- .IP "pro_ptyp em_pnam" \nau
- a procedure name, not including the '$',
- represented as a string.
- .IP "str_ptyp em_string" \nau
- a string constant.
- .IP " em_size" \nau
- The string is found in \fIem_string\fR, represented as a row of bytes, of
- length \fIem_size\fR.
- .IP "ico_ptyp em_string" \nau
- an integer constant.
- .IP " em_size" \nau
- A string representation of the constant is found in \fIem_string\fR.
- It has size \fIem_size\fR bytes on the target machine.
- .IP "uco_ptyp em_string" \nau
- an unsigned constant.
- .IP " em_size" \nau
- A string representation of the constant is found in \fIem_string\fR.
- It has size \fIem_size\fR bytes on the target machine.
- .IP "fco_ptyp em_string" \nau
- a floating constant.
- .IP " em_size" \nau
- A string representation of the constant is found in \fIem_string\fR.
- It has size \fIem_size\fR bytes on the target machine.
- .PD
- .PP
- When an error occurs, \fIEM_error\fR is set to indicate the reason.
- \fIEM_getinstr\fR returns 1 if all goes well, 0 if it does not.
- The EM_ERROR described above is only set when the error
- is serious enough.
- .PP
- The routine \fIEM_mkcalls\fR "translates" the EM instruction indicated
- by \fIinstr\fR
- into calls of the procedural interface defined in \fIem_code\fR(3L).
- It returns 1 if it succeeds, 0 if it fails for some reason. The
- reason can then be found in \fIEM_error\fR.
- The \fIEM_mkcalls\fP routine is obsolete. It is being replaced by the
- .I C_out
- routine of the
- .I em_code
- module.
- .PP
- \fIEM_lineno\fR contains the line number of the last line read by
- \fIEM_getinstr\fR.
- .PP
- \fIEM_filename\fR contains a filename. It usually contains the value
- given as parameter to \fIEM_open\fR, but may have a different value, when
- the input was the result of some preprocessing.
- .PP
- .I EM_wordsize
- and
- .I EM_pointersize
- contain the wordsize and pointersize, but only after the first
- (pseudo-)instruction has successfully been read.
- .SH FILES
- .nf
- ~em/modules/h/em.h
- ~em/h/em_ptyp.h
- ~em/modules/h/em_comp.h
- ~em/modules/lib/libread_emk.a: non-checking library for reading compact EM code
- ~em/modules/lib/libread_emkV.a: checking library for reading compact EM code
- ~em/modules/lib/libread_emeV.a: checking library for reading human-readable EM code
- .fi
- .SH MODULES
- em_code(3), string(3), system(3), ~em/lib/em_data.a
- .SH "SEE ALSO"
- em_code(3)
- .br
- A.S. Tanenbaum, H. v Staveren, E.G. Keizer, J.W. Stevenson, "\fBDescription
- of a Machine Architecture for use with Block Structured Languages\fR",
- Informatica Rapport IR-81, Vrije Universiteit, Amsterdam, 1983.
- .SH REMARKS
- All strings must be considered to be contained in a static area, so
- must be copied to be saved.
- .SH BUGS
- As CON's and ROM's may be delivered in several parts, the count fields in
- a static exchange may be wrong.
- .PP
- Please report bugs to the author.
|