diff options
Diffstat (limited to 'man/2/dis')
| -rw-r--r-- | man/2/dis | 488 |
1 files changed, 488 insertions, 0 deletions
diff --git a/man/2/dis b/man/2/dis new file mode 100644 index 00000000..bb3cdc91 --- /dev/null +++ b/man/2/dis @@ -0,0 +1,488 @@ +.TH DIS 2 +.SH NAME +dis \- read Dis object files +.SH SYNOPSIS +.EX +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; +.EE +.SH DESCRIPTION +The +.B Dis +module decodes the contents of a Dis object file containing a single module, +of the format defined by +.IR 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. +.PP +.B Init +must be called before any other function, to initialise the module. +.PP +.B Loadobj +reads a Dis object file from +.IR file , +and returns a reference to a +.B 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. +.PP +.B Op2s +returns the assembly-language representation, as used by +.IR asm (1), +of the Dis operation code +.IR op . +It returns the string +.IB ` OP op' +if +.I op +does not correspond to a known operation code. +.PP +.B Inst2s +returns a string corresponding to a disassembly of Dis instruction +.IR i , +including addressing modes. +.PP +The module defines integer constants giving +symbolic names to the Dis instruction codes, all of the form +.BI I name +where +.I name +is the name of the instruction, all in upper case: +.IP +.BR INOP , +.BR IALT , +.BR INBALT , +\&... +.BR INEWZ , +.BR INEWAZ , +.BR IRAISE +.PP +The name +.B MAXDIS +is also defined; it has the value of the first unassigned Dis operation code. +.PP +Most of the members of the adt types have an obvious interpretation +on reference to +.IR dis (6). +.PP +The adt +.B 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: +.TF entryt +.PD +.TP +.B magic +The constant +.B XMAGIC +(unsigned Dis module) +or the constant +.B SMAGIC +(signed Dis module). +.TP +.B sign +If +.B magic +is +.BR SMAGIC , +the +.B sign +field contains the bytes in the signature section of the module header. +Otherwise, there is no signature and +.B sign +is +.BR nil . +.TP +.B name +The name of the implementation module. +.TP +.B srcpath +The source of the dis file relative to the inferno root. +.TP +.B rt +Run-time options: a bit mask of the constants +.BR MUSTCOMPILE , +.B DONTCOMPILE +and +.BR SHAREMP . +.TP +.B ssize +Stack extent +.TP +.B isize +Number of instructions +.TP +.B dsize +Size in bytes of the module's global data area +.TP +.B tsize +Number of type descriptors +.TP +.B lsize +Number of external linkage descriptors +.TP +.B entry +PC (instruction offset) of the default entry point for the module +.TP +.B entryt +Index of the type descriptor for the module's entry point +.TP +.B inst +Array representing the contents of the code segment; +length +.IB m .isize +.TP +.B types +Array of the module's type descriptors; +length +.IB m .tsize +.TP +.B data +list of data descriptors representing instructions for creating the module's data segment +.TP +.B links +array of the module's external linkage descriptors (for exported functions); length +.IB m .lsize +.TP +.B 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. +.TP +.B 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. +.PP +The +.B Type +adt represents the value of a type descriptor: +.TF entryt +.PD +.TP +.B size +Size in bytes of the object represented by this descriptor +.TP +.B map +Bitmap describing the location of pointers in the object (see +.IR dis (6)) +.PP +The +.B Link +adt represents the value of a link descriptor: +.TF entryt +.PD +.TP +.B name +Name of the exported function +.TP +.B pc +Instruction index in +.B Mod.code +of the function's entry point +.TP +.B desc +Index in +.B Mod.types +of the type describing the function's stack frame +.TP +.B sig +Integer hash of the function's type signature +.PP +The +.B Inst +adt represents a single Dis instruction in the instruction stream. +The member +.B op +is the Dis instruction code. +The member +.B addr +contains the addressing mode flags for middle, source and destination operands. +Constants are defined to help unpack it. +.PP +The middle operand description is selected by the constant mask +.BR ARM : +.IP +.IB i ".addr & ARM" +.PP +The valid results and interpretation are as follows: +.IP +.RS +.TF AXNON +.TP +.B AXNON +No middle operand. +.TP +.B AXIMM +.BI $ n +.TP +.B AXINF +.IB n (fp) +.TP +.B AXINM +.IB n (mp) +.PD +.RE +.PP +The source operand's addressing mode is extracted as follows: +.IP +.BI ( i ".addr>>3)&AMASK" +.PP +The following combinations are valid, where +.I n +is the value in +.IB i .src : +.IP +.RS +.TF AIND|AMP +.TP +.B AXXX +No operand +.TP +.B AFP +The operand is +.IB n (fp) +.TP +.B AMP +The operand is +.IB n (mp) +.TP +.B AIMM +The operand is +.BI $ n +(ie, immediate literal +.IR n ) +.TP +.B AIND|AFP +The operand is +.IB si ( fi (fp)) +.TP +.B AIND|AMP +The operand is +.IB si ( fi (mp)) +.RE +.PD +.PP +where +.I fi +is the offset for the first indirection, extracted from +.IR n : +.IP +.BI ( n ">>16)&16rFFFF)" , +.PP +and +.I si +is the offset for the second indirection, also extracted from +.IR n: +.IP +.BI ( n "&16rFFFF)" . +.PP +The destination addressing mode is interpreted in a similar way, +except that the addressing mode is extracted as follows: +.IP +.BI ( i ".addr&AMASK)" +.PP +and the value of the offset +.I n +is found in +.IB i .dst . +.I Fi +and +.I si +are extracted from +.I n +as before. +.PP +Finally, +.B 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: +.TP +.B op +the encoded type and length; usually ignored: the +.B pick +tag and +.BR n , +below, +usually suffice +.TP +.B n +the number of data values +.TP +.B off +the byte offset of the first data value to initialise, relative to the current loading base +.PP +The alternatives of the +.B 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 +.BR Bytes , +.BR Words , +.B Bigs +and +.BR Reals : +the corresponding array members are arrays of +.B n +elements of the appropriate type. +The remaining cases are as follows: +.TF Arestore +.PD +.TP +.B String +The member +.B str +has the decoded representation of the +corresponding +.I n +data bytes from the object file. +.TP +.B Array +The member +.B typex +is the index in +.B Mod.types +of the array's type, and member +.B length +is its length. +.TP +.B Aindex +This alternative can appear only following a value of +.BR Data.Array . +The member +.B index +is an index into the corresponding array as represented in the global data space, +which determines a new loading base address for subsequent +.B Data +items. +The previous base address is stacked on an internal stack. +.TP +.B 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 +.B Data +items initialising an array. +.SH SOURCE +.B /appl/lib/dis.b +.SH SEE ALSO +.IR disdep (1), +.B wm/rt +in +.IR wm-misc (1), +.IR dis (6) +.br +"The Dis Virtual Machine", in Volume 2. |