READ_EM(3ACK)

NAME
EM_open, EM_getinstr, EM_close, EM_mkcalls - a module to read EM assembly code

SYNOPSIS
#include <em_spec.h>
#include <em_mnem.h>
#include <em_pseu.h>
#include <em_flag.h>
#include <em_ptyp.h>
#include <em.h>
#include <em_comp.h>

int EM_open(filename)
EM_close()
char *filename;

int EM_getinstr(instr) struct e_instr *instr;

int EM_mkcalls(instr)
struct e_instr *instr;

char *EM_error;

unsigned int EM_lineno;

char *EM_filename;

int EM_wordsize, EM_pointersize;

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.

EM_open must be called as initializer of the package. If filename is a null pointer, reading is done from standard input, otherwise it is done from the file filename. EM_open returns 1 on success and 0 on failure with an error message in EM_error. EM_close must be called after all other calls to this package.

EM_getinstr reads an EM instruction, and returns it in the structure pointed to by instr. This structure has the following layout:

/*
 * (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;

The named types arith and label refer to types on the local machine that are suitable for doing arithmetic and storing EM numeric labels respectively. Common definitions are long for arith and unsigned int for label.

The e_instr structure consists of the fields em_type, containing the type of this e_instr, em_opcode, containing the opcode of an instruction, and em_arg, containing a possible argument.

The possible values of em_type, defined in <em_comp.h>, are summarized below:

Value	Selector
    Meaning

EM_MNEM	em_opcode
    an EM machine instruction.
em_arg
    The em_opcode field contains the opcode of the instruction, and em_arg may contain an argument. If em_argtype indicates that there is no argument, em_cst is set to 0.
EM_PSEU	em_opcode
    an EM pseudo instruction.
em_arg
    The em_opcode field contains the opcode, and em_arg may contain an argument. As consecutive CON-pseudos are allocated consecutively, a CON delivered by EM_getinstr 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 e_arg structure, and we want to keep the e_arg 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 em_nlocals. If it is -1, it was omitted.
EM_STARTMES	em_arg
    the start of a MES pseudo.
    There is one argument: the message number. The other arguments, if any, are delivered as separate EM_MESARG's.
EM_MESARG	em_arg
    an argument of a MES pseudo.
EM_ENDMES	none
    the end of a MES pseudo.
EM_DEFILB	em_ilb
    an instruction label definition.
    The field em_ilb contains the label (instruction labels are always numeric).
EM_DEFDLB	em_dlb
    a numeric data label definition.
    The field em_dlb contains the label.
EM_DEFDNAM	em_dnam
    a non-numeric data label definition.
    The field em_dnam contains the label.
EM_ERROR	none
    an error in the input that makes the rest of the data in the structure meaningless.
    EM_error contains an error message.
EM_FATAL	none
    a fatal error.
    EM_error contains an error message.
EM_EOF	none
    end of file

The e_arg structure consists of the fields the field ema_argtype, containing the type of this argument or 0 if absent, the field ema_arg, containing the value of the argument, and ema_szoroff, containing an optional offset or size. The possible values of ema_argtype, defined in <em_ptyp.h>, are summarized below:

Value	Selector
    Meaning

0	none
    no argument.

ilb_ptyp	em_ilb
    an instruction label.
nof_ptyp	em_dlb
    an offset from a numeric data label.
em_off
    The em_off field contains the offset and the em_dlb field contains the label.
sof_ptyp	em_dnam
    an offset from a non-numeric data label.
em_off
    The em_off field contains the offset and the em_dnam field contains the label, represented as a string.
cst_ptyp	em_cst
    a numeric constant.
pro_ptyp	em_pnam
    a procedure name, not including the '$', represented as a string.
str_ptyp	em_string
    a string constant.
em_size
    The string is found in em_string, represented as a row of bytes, of length em_size.
ico_ptyp	em_string
    an integer constant.
em_size
    A string representation of the constant is found in em_string. It has size em_size bytes on the target machine.
uco_ptyp	em_string
    an unsigned constant.
em_size
    A string representation of the constant is found in em_string. It has size em_size bytes on the target machine.
fco_ptyp	em_string
    a floating constant.
em_size
    A string representation of the constant is found in em_string. It has size em_size bytes on the target machine.

When an error occurs, EM_error is set to indicate the reason. EM_getinstr 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.

The routine EM_mkcalls "translates" the EM instruction indicated by instr into calls of the procedural interface defined in em_code(3L). It returns 1 if it succeeds, 0 if it fails for some reason. The reason can then be found in EM_error.

EM_lineno contains the line number of the last line read by EM_getinstr.

EM_filename contains a filename. It usually contains the value given as parameter to EM_open, but may have a different value, when the input was the result of some preprocessing.

EM_wordsize and EM_pointersize contain the wordsize and pointersize, but only after the first (pseudo-)instruction has successfully been read.

FILES
~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

MODULES
em_code(3), string(3), system(3), ~em/lib/em_data.a

SEE ALSO
em_code(3)
A.S. Tanenbaum, H. v Staveren, E.G. Keizer, J.W. Stevenson, "Description of a Machine Architecture for use with Block Structured Languages", Informatica Rapport IR-81, Vrije Universiteit, Amsterdam, 1983.

REMARKS
All strings must be considered to be contained in a static area, so must be copied to be saved.

BUGS
As CON's and ROM's may be delivered in several parts, the count fields in a static exchange may be wrong.

Please report bugs to the author.

AUTHOR
Ceriel J.H. Jacobs <ceriel@cs.vu.nl>