ack/modules/src/read_em/read_em.3

.TH READ_EM 3ACK "March 17, 1986"
.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,
\fIem_arg\fR, containing a possible argument,
and two other fields for special purposes explained later.
.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 \fIema_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	ema_ilb" \nau
an instruction label.
.PD 0
.IP "nof_ptyp	ema_dlb" \nau
an offset from a numeric data label.
.IP "	ema_szoroff" \nau
The
\fIema_szoroff\fR field contains the offset and the
\fIema_dlb\fR field contains the label.
.IP "sof_ptyp	ema_dnam" \nau
an offset from a non-numeric data label.
.IP "	ema_szoroff" \nau
The \fIema_szoroff\fR field contains the offset and the \fIema_dnam\fR field
contains the label, represented as a string.
.IP "cst_ptyp	ema_cst" \nau
a numeric constant.
.IP "pro_ptyp	ema_pnam" \nau
a procedure name, not including the '$',
represented as a string.
.IP "str_ptyp	ema_string" \nau
a string constant.
.IP "	ema_szoroff" \nau
The string is found in \fIema_string\fR, represented as a row of bytes, of
length \fIema_szoroff\fR.
.IP "ico_ptyp	ema_string" \nau
an integer constant.
.IP "	ema_szoroff" \nau
A string representation of the constant is found in \fIema_string\fR.
It has size \fIema_szoroff\fR bytes on the target machine.
.IP "uco_ptyp	ema_string" \nau
an unsigned constant.
.IP "	ema_szoroff" \nau
A string representation of the constant is found in \fIema_string\fR.
It has size \fIema_szoroff\fR bytes on the target machine.
.IP "fco_ptyp	ema_string" \nau
a floating constant.
.IP "	ema_szoroff" \nau
A string representation of the constant is found in \fIema_string\fR.
It has size \fIema_szoroff\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.
.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.
.SH AUTHOR
Ceriel J.H. Jacobs <ceriel@cs.vu.nl>