Inferno's DIS(2 )

NAME

dis - read Dis object files

SYNOPSIS

include "dis.m";
dis := load Dis Dis->PATH;

Inst: adt
{
	op:		int;
	addr:	int;
	mid:		int;
	src:		int;
	dst:		int;
};

Type: adt
{
	size:	int;
	map:		array of byte;
};

Data: adt
{
	op:	int;		# encoded op
	n:	int;		# number of elements
	off:	int;		# byte offset in data space
	pick {
	Zero =>		# DEFZ
	Bytes =>		# DEFB
		bytes:	array of byte;
	Words =>		# DEFW
		words:	array of int;
	String =>		# DEFS
		str:	string;
	Reals =>		# DEFF
		reals:	array of real;
	Array =>		# DEFA
		typex:	int;
		length:	int;
	Aindex =>		# DIND
		index:	int;
	Arestore =>	# DAPOP
	Bigs =>		# DEFL
		bigs:		array of big;
	}
};

Link: adt
{
	pc:		int;
	desc:	int;
	sig:		int;
	name:	string;
};

Import: adt
{
	sig:	int;
	name:	string;
};

Except: adt
{
	s:	string;
	pc:	int;
};

Handler: adt
{
	pc1:	int;
	pc2:	int;
	eoff:	int;
	ne:	int;
	t:	ref Type;
	etab:	array of ref Except;
};

Mod: adt
{
	name:	string;
	srcpath:	string;

	magic:	int;
	rt:		int;
	ssize:	int;
	isize:	int;
	dsize:	int;
	tsize:	int;
	lsize:	int;
	entry:	int;
	entryt:	int;

	inst:	array of ref Inst;
	types:	array of ref Type;
	data:	list of ref Data;
	links:	array of ref Link;
	imports:	array of array of ref Import;
	handlers:	array of ref Handler;

	sign:	array of byte;
};

init:	fn();
loadobj:	fn(file: string): (ref Mod, string);
op2s:	fn(op: int): string;
inst2s:	fn(i: ref Inst): string;

DESCRIPTION

The Dis module decodes the contents of a Dis object file containing a single module, of the format defined by dis(6). The module defines many constants, giving symbolic names to Dis instruction codes, addressing mode masks, magic numbers, and other bits of the object code.

Init must be called before any other function, to initialise the module.

Loadobj reads a Dis object file from file, and returns a reference to a Mod adt that represents the module's contents, as the first element of the tuple; the string element of the tuple is nil. On error, the string element contains a diagnostic, and the reference is nil.

Op2s returns the assembly-language representation, as used by asm(1), of the Dis operation code op. It returns the string `OPop' if op does not correspond to a known operation code.

Inst2s returns a string corresponding to a disassembly of Dis instruction i, including addressing modes.

The module defines integer constants giving symbolic names to the Dis instruction codes, all of the form Iname where name is the name of the instruction, all in upper case:

: INOP, IALT, INBALT, ... INEWZ, INEWAZ, IRAISE

The name MAXDIS is also defined; it has the value of the first unassigned Dis operation code.

Most of the members of the adt types have an obvious interpretation on reference to dis(6).

The adt Mod represents a single module. It contains values extracted from the module's header, and references to structures representing the contents of the Dis file's code, data, type and external linkage sections:

magic: The constant XMAGIC (unsigned Dis module) or the constant SMAGIC (signed Dis module).
sign: If magic is SMAGIC, the sign field contains the bytes in the signature section of the module header. Otherwise, there is no signature and sign is nil.
name: The name of the implementation module.
srcpath: The source of the dis file relative to the inferno root.
rt: Run-time options: a bit mask of the constants MUSTCOMPILE, DONTCOMPILE and SHAREMP.
ssize: Stack extent
isize: Number of instructions
dsize: Size in bytes of the module's global data area
tsize: Number of type descriptors
lsize: Number of external linkage descriptors
entry: PC (instruction offset) of the default entry point for the module
entryt: Index of the type descriptor for the module's entry point
inst: Array representing the contents of the code segment; length m.isize
types: Array of the module's type descriptors; length m.tsize
data: list of data descriptors representing instructions for creating the module's data segment
links: array of the module's external linkage descriptors (for exported functions); length m.lsize
imports: an array of import descriptor tables, one table for each module imported by this module. Each table is an array of pairs giving the signature and name of each function imported.
handlers: an array of exception handlers used in this module. Each handler consists of the range of pc's it covers, the exception structure offset within the frame, the number of declared exceptions (as opposed to strings) in the handler, the type (if any) of any memory to clear when the exception occurs and a table of exceptions. The latter is an array containing pairs of exceptions and pc values. The final entry gives the pc to jump to in the '*' case or -1 if not applicable.

The Type adt represents the value of a type descriptor:

size: Size in bytes of the object represented by this descriptor
map: Bitmap describing the location of pointers in the object (see dis(6))

The Link adt represents the value of a link descriptor:

name: Name of the exported function
pc: Instruction index in Mod.code of the function's entry point
desc: Index in Mod.types of the type describing the function's stack frame
sig: Integer hash of the function's type signature

The Inst adt represents a single Dis instruction in the instruction stream. The member op is the Dis instruction code. The member addr contains the addressing mode flags for middle, source and destination operands. Constants are defined to help unpack it.

The middle operand description is selected by the constant mask ARM:

: i.addr & ARM

The valid results and interpretation are as follows:

AXNON: No middle operand.
AXIMM: $n
AXINF: n(fp)
AXINM: n(mp)

The source operand's addressing mode is extracted as follows:

: (i.addr>>3)&AMASK

The following combinations are valid, where n is the value in i.src:

AXXX: No operand
AFP: The operand is n(fp)
AMP: The operand is n(mp)
AIMM: The operand is $n (ie, immediate literal n)
AIND|AFP: The operand is si(fi(fp))
AIND|AMP: The operand is si(fi(mp))

where fi is the offset for the first indirection, extracted from n:

: (n>>16)&16rFFFF),

and si is the offset for the second indirection, also extracted from n:

: (n&16rFFFF).

The destination addressing mode is interpreted in a similar way, except that the addressing mode is extracted as follows:

: (i.addr&AMASK)

and the value of the offset n is found in i.dst. Fi and si are extracted from n as before.

Finally, Data adt represents a data item, which tells the system's module loader how to initialise part of the module's global data segment. It has the following members:

op: the encoded type and length; usually ignored: the pick tag and n, below, usually suffice
n: the number of data values
off: the byte offset of the first data value to initialise, relative to the current loading base

The alternatives of the pick select the correct variant to see the data values encoded in the object file as Limbo values of the correct type. The interpretation is straightforward for the tags Bytes, Words, Bigs and Reals: the corresponding array members are arrays of n elements of the appropriate type. The remaining cases are as follows:

String: The member str has the decoded representation of the corresponding n data bytes from the object file.
Array: The member typex is the index in Mod.types of the array's type, and member length is its length.
Aindex: This alternative can appear only following a value of Data.Array. The member index is an index into the corresponding array as represented in the global data space, which determines a new loading base address for subsequent Data items. The previous base address is stacked on an internal stack.
Arestore: Pop the address from the internal address stack and make that the current loading address. The request marks the end of a sequence of Data items initialising an array.

SOURCE

/appl/lib/dis.b

SEE ALSO

disdep(1), wm/rt in wm-misc(1), dis(6)
"The Dis Virtual Machine", in Volume 2.

DIS(2 ) Rev: Tue Mar 31 02:42:38 GMT 2015