.TH DIS 6.SH NAMEdis \- Dis object file.SH DESCRIPTION.ds Os "\v'0.2m'\s-3\|opt\s+3\^\v'-0.2m'A Dis object file contains the executable form of a single module,and conventionally uses the file suffix.BR .dis ..PPThe following names are used in the description of the file encoding..PP.TP 10n.I byteAn unsigned 8-bit byte..TP.I wordA 32-bit integer value represented in exactly 4 bytes..TP.I longA 64-bit integer value represented in exactly 8 bytes..TP.I operandAn integer stored in a compact variable-lengthencoding selected by the two most significant bits as follows:.IP.nf0x	signed 7 bits, 1 byte.br10	signed 14 bits, 2 bytes.br11	signed 30 bits, 4 bytes.fi.TP.I stringA variable length sequence of bytes terminated by a zero byte.Names thus represented are in.IR utf (6)format..PPAll integers are encoded in two's complement format, most significant byte first..PPEvery object file has a header followed by five sections containing code, data, and several sorts of descriptors:.IP.I "header code-section type-section data-section module-name link-section".PPEach section is described in turn below..SS HeaderThe header contains a magic number,a digital signature, a flag word,sizes of the other sections, and a description of the entry point.It has the following format:.IP.EX.ft Iheader:	magic signature\*(Os runflag stack-extent		code-size data-size type-size link-size entry-pc entry-typemagic, runflag:	operandstack-extent, code-size, data-size, type-size, link-size:	operandentry-pc, entry-type:	operand.EE.PPThe magic number is defined as 819248(symbolically.BR  XMAGIC ),for modules that have not been signed cryptographically, and 923426(symbolically.BR  "SMAGIC" ),for modules that contain a signature.The symbolic names.B  "XMAGIC"and.B  SMAGICare defined by the C include file.B  "/include/isa.h"and by the Limbo module.IR dis (2)..PPThe.I signatureis present only if the magic number is.BR  "SMAGIC" .It has the form:.IP.EX.ft Isignature:	length signature-datalength:	operandsignature-data:	byte ....EE.PPA digital signature is defined by a length, followed by an array of bytes of thatlength that contain the signature in some unspecified format.Data within the signature should identify the signing authority, algorithm, and data to be signed..PP.I Runflagis a bit mask thatselects various execution options for a Dis module. The flags currently defined are:.IP.RS.TP.BR MUSTCOMPILE " (1<<0)"The module must be compiled into native instructions for execution (using a just-in-time compiler);if the implementation cannot do that,the.B loadinstruction should given an error..TP.BR DONTCOMPILE " (1<<1)"The module should not be compiled into native instructions, when that is the default for the runtime environment, butshould be interpreted.This flag may be set to allow debugging or to save memory..TP.BR  SHAREMP " (1<<2)"Each instance of the module should use the same module data for all instances of the module. There is no implicit synchronisation between threads using the shared data..TP.BR  HASLDT " (1<<4)"The dis file contains a separate import section. On older versions of the system,this section was within the data section..TP.BR  HASEXCEPT " (1<<5)"The dis file contains an exception handler section..RE.PP.IR Stack-extent ,if non-zero, gives the number of bytes by which the thread stack of this module should be extended in the event that procedure calls exhaust the allocated stack.While stack extension is transparent to programs, increasing this value may improve the efficiency of execution at the expense of using more memory..PP.IR Code-size ,.I type-sizeand.I link-sizegive the number of entries (instructions, type descriptors, linkage directives)in the corresponding sections..PP.I Data-sizeis the size in bytes of the module's global data area(not the number of items in.IR data-section )..PP.I Entry-pcis an integer index into the instruction stream that is the default entry point for this module.It should point to the first instruction of a function.Instructions are numbered from a program counter value of zero..PP.I Entry-typeis the index of the type descriptor in the type section that corresponds to the function entry point set by.IR entry-pc ..SS Code Section.PPThe code section describes a sequence of instructions for the virtual machine.There are.I code-sizeinstructions.An instruction is encoded as follows:.IP.EX.ft Iinstruction:	opcode address-mode middle-data\*(Os source-data\*(Os dest-data\*(Osopcode, address-mode:	bytemiddle-data:	operandsource-data, dest-data:	operand operand\*(Os.ft R.EE.PPThe one byte.I opcodespecifies the instruction to execute; opcodes aredefined by the virtual machine specification..PPThe.I address-modebyte specifies the addressing mode of each of the three operands: middle, source and destination. The source and destination operands are encoded by three bits and the middle operand by two bits. The bits are packed as follows:.IP.EXbit  7  6  5  4  3  2  1  0    m1 m0 s2 s1 s0 d2 d1 d0.EE.PPThe following definitions are used in the description of addressing modes:.IP.RS.TP.B OP30 bit integer operand.PD0.TP.B SO16 bit unsigned small offset from register.TP.B SI16 bit signed immediate value.TP.B LO30 bit signed large offset from register.PD.RE.PPThe middle operand is encoded as follows:.IP.RS.TF "00    SO(MP)".TP.BI "00    " "none"no middle operand	.TP.B "01    $SI"small immediate.TP.B "10    SO(FP)"small offset indirect from FP.TP.B "11    SO(MP)"small offset indirect from MP.RE.PD.PPThe.I middle-datafield is present only if the middle operand specifier of the.I address-modeis not `none'.If the field is present it is encoded as an .IR operand ..PPThe source and destination operands are encoded as follows:.IP.RS.TF "000  SO(SO(MP))".TP.B "000   LO(MP)"offset indirect from MP.TP.B "001   LO(FP)"offset indirect from FP.TP.B "010   $OP"30 bit immediate.TP.BI "011   " "\fInone\fP"no operand.TP.B "100   SO(SO(MP))"double indirect from MP.TP.B "101   SO(SO(FP))"double indirect from FP.TP.B 110\fIreserved\fP.TP.B 111\fIreserved\fP.RE.PD.PPThe.I source-dataand.I dest-datafields are present only when the corresponding.I address-modefield is not `none'.For offset indirect and immediate modes the field contains a single .I operandvalue.For double indirect modes the values are encoded as two .IR operands :the first is the register indirect offset, and the second is the final indirect offset.The offsets for double indirect addressing cannot be larger than 16 bits..SS Type SectionThe type section contains.I type-sizetype descriptors describing the layout of pointers within data types. The format of each descriptor is:.IP.EX.ft Itype-descriptor:	desc-number memsize mapsize mapdesc-number, memsize, mapsize:	operandmap:	byte ....ft R.EE.PPThe.I  desc-numberis a small integer index used to identify the descriptor to instructions such as .BR  "new" ..I Memsizeis the size in bytes of the memory described by this type..PPThe.I  mapsizefield gives the size in bytes of the following.I "map"array..I Mapis an array of bytes representinga bit map where each bit corresponds to a word in memory.The most significant bit corresponds to the lowest address.For each bit in the map,the word at the corresponding offset in the type is a pointer iff the bit is set to 1..SS Data Section.PPThe data section encodes the contents of thedata segment for the module, addressed by.B MPat run-time.The section contains a sequence of items of the following form:.IP.EX.ft Idata-item:	code count\*(Os offset data-value ...code:	bytecount, offset:	operand.EE.PPEach item contains an.I offsetinto the section, followed by one or more data values ina machine-independent encoding.As each value is placed in the data segment, the offset is incremented by the size of the datum..PPThe.I codebyte has two 4-bit fields.The bottom 4 bits of.I codegives the number of.I data-valuesif there are between 1 and 15;if there are more than 15,the low-order field is zero, and a following.I operandgives the count..PPThe top 4 bits of.I codeencode the type of each.I data-valuein the item, which determines its encoding.The defined values are:.IP.RS.TF 0000.TP.B 00018 bit bytes.TP.B 001032 bit integers, one.I wordeach.TP.B 0011string value encoded by.IR utf (6)in.I countbytes.TP.B 0100real values in IEEE754 canonical representation, 8 bytes each.TP.B 0101Array, represented by two.I wordsgiving type and length.TP.B 0110Set base for data items: one.I wordgiving an array index.TP.B 0111Restore base for data items:no operands.TP.B 100064 bit big, 8 bytes each.RE.PD.PPThe loader maintains a current base address and a stack of addresses.Each item's value is stored at the address formed by adding the current offsetto the current base address.That address initially is the base of the module's data segment.The `set base' operation immediately followsan `array'.IR data-item .It stacks the current base address and sets the current base address to theaddress of the array element selected by its operand.The `restore base' operation sets the current base address to theaddress on the top of the stack, and pops the stack..SS Module nameThe module name immediately follows the data section.It contains the name of the module implemented by the object file,as a sequence of bytes inUTF encoding, terminated by a zero byte..SS Link SectionThe link section contains an array of.I link-sizeexternal linkage items,listing the functions exported by this module.Each variable-length item contains the following:.IP.EX.ft Ilink-item:	pc desc sig fn-namepc, desc:	operandsig:	wordfn-name:	string.ft R.EE.PP.I Fn-nameis the name of an exported function.Adt member functions appear with theirfull names: the member name qualified by the adt name, in the form.IB adt-name . member-name,for instance.BR Iobuf.gets ..PP.I Pcis the instruction number of its entry point..I Descis an index value that selects a type descriptor in the type section,which gives the type of the function's stack frame..I Sigis an integer hash of the type signature of the function, used in type checking..SS Import SectionThe optional import section lists all those functions imported from othermodules. This allows type checking at load time. The size of the section inbytes is given at the start in operand form. For each module imported thereis a list of functions imported from that module. For each function, its type signature (a word) is followed bya 0 terminated list of bytes representing its name..SS Handler SectionThe final optional section lists all exception handlers declared in the module. The numberof such handlers is given at the start of the section in operand form. For each one, its formatis:.IP.EX.ft 1handler:	offset pc1 pc2 desc nlab exc-taboffset, pc1, pc2, desc, nlab:	operandexc-tab:	exc-name pc ... exc-name pc pcexc-name:	stringpc:	operand.ft R.EE.PPEach handler specifies the frame offset of its exception structure, the range of pc values it covers (from pc1 up to but not including pc2), the type descriptor of anymemory that needs destroying by the handler (or -1 if none), the number ofexceptions in the handler and then the exception table itself. The latter consistsof a list of exception names and the corresponding pc to jump to when thisexception is raised. This is then followed by the pc to jump to in any wildcard (*) caseor -1 if this is not applicable..SH SEE ALSO.IR asm (1),.IR dis (2),.IR sbl (6).br``The Dis Virtual Machine Specification'', Volume 2