Add generated files.binutils-2_25

1 files changed, 369 insertions, 0 deletions

diff --git a/bfd/doc/mmo.texi b/bfd/doc/mmo.texi
new file mode 100644
index 0000000..f9c2358
--- /dev/null
+++ b/bfd/doc/mmo.texi
@@ -0,0 +1,369 @@
+@section mmo backend
+The mmo object format is used exclusively together with Professor
+Donald E.@: Knuth's educational 64-bit processor MMIX.  The simulator
+@command{mmix} which is available at
+@url{http://mmix.cs.hm.edu/src/index.html}
+understands this format.  That package also includes a combined
+assembler and linker called @command{mmixal}.  The mmo format has
+no advantages feature-wise compared to e.g. ELF.  It is a simple
+non-relocatable object format with no support for archives or
+debugging information, except for symbol value information and
+line numbers (which is not yet implemented in BFD).  See
+@url{http://mmix.cs.hm.edu/} for more
+information about MMIX.  The ELF format is used for intermediate
+object files in the BFD implementation.
+
+@c We want to xref the symbol table node.  A feature in "chew"
+@c requires that "commands" do not contain spaces in the
+@c arguments.  Hence the hyphen in "Symbol-table".
+@menu
+* File layout::
+* Symbol-table::
+* mmo section mapping::
+@end menu
+
+@node File layout, Symbol-table, mmo, mmo
+@subsection File layout
+The mmo file contents is not partitioned into named sections as
+with e.g.@: ELF.  Memory areas is formed by specifying the
+location of the data that follows.  Only the memory area
+@samp{0x0000@dots{}00} to @samp{0x01ff@dots{}ff} is executable, so
+it is used for code (and constants) and the area
+@samp{0x2000@dots{}00} to @samp{0x20ff@dots{}ff} is used for
+writable data.  @xref{mmo section mapping}.
+
+There is provision for specifying ``special data'' of 65536
+different types.  We use type 80 (decimal), arbitrarily chosen the
+same as the ELF @code{e_machine} number for MMIX, filling it with
+section information normally found in ELF objects. @xref{mmo
+section mapping}.
+
+Contents is entered as 32-bit words, xor:ed over previous
+contents, always zero-initialized.  A word that starts with the
+byte @samp{0x98} forms a command called a @samp{lopcode}, where
+the next byte distinguished between the thirteen lopcodes.  The
+two remaining bytes, called the @samp{Y} and @samp{Z} fields, or
+the @samp{YZ} field (a 16-bit big-endian number), are used for
+various purposes different for each lopcode.  As documented in
+@url{http://mmix.cs.hm.edu/doc/mmixal.pdf},
+the lopcodes are:
+
+@table @code
+@item lop_quote
+0x98000001.  The next word is contents, regardless of whether it
+starts with 0x98 or not.
+
+@item lop_loc
+0x9801YYZZ, where @samp{Z} is 1 or 2.  This is a location
+directive, setting the location for the next data to the next
+32-bit word (for @math{Z = 1}) or 64-bit word (for @math{Z = 2}),
+plus @math{Y * 2^56}.  Normally @samp{Y} is 0 for the text segment
+and 2 for the data segment.  Beware that the low bits of non-
+tetrabyte-aligned values are silently discarded when being
+automatically incremented and when storing contents (in contrast
+to e.g. its use as current location when followed by lop_fixo
+et al before the next possibly-quoted tetrabyte contents).
+
+@item lop_skip
+0x9802YYZZ.  Increase the current location by @samp{YZ} bytes.
+
+@item lop_fixo
+0x9803YYZZ, where @samp{Z} is 1 or 2.  Store the current location
+as 64 bits into the location pointed to by the next 32-bit
+(@math{Z = 1}) or 64-bit (@math{Z = 2}) word, plus @math{Y *
+2^56}.
+
+@item lop_fixr
+0x9804YYZZ.  @samp{YZ} is stored into the current location plus
+@math{2 - 4 * YZ}.
+
+@item lop_fixrx
+0x980500ZZ.  @samp{Z} is 16 or 24.  A value @samp{L} derived from
+the following 32-bit word are used in a manner similar to
+@samp{YZ} in lop_fixr: it is xor:ed into the current location
+minus @math{4 * L}.  The first byte of the word is 0 or 1.  If it
+is 1, then @math{L = (@var{lowest 24 bits of word}) - 2^Z}, if 0,
+then @math{L = (@var{lowest 24 bits of word})}.
+
+@item lop_file
+0x9806YYZZ.  @samp{Y} is the file number, @samp{Z} is count of
+32-bit words.  Set the file number to @samp{Y} and the line
+counter to 0.  The next @math{Z * 4} bytes contain the file name,
+padded with zeros if the count is not a multiple of four.  The
+same @samp{Y} may occur multiple times, but @samp{Z} must be 0 for
+all but the first occurrence.
+
+@item lop_line
+0x9807YYZZ.  @samp{YZ} is the line number.  Together with
+lop_file, it forms the source location for the next 32-bit word.
+Note that for each non-lopcode 32-bit word, line numbers are
+assumed incremented by one.
+
+@item lop_spec
+0x9808YYZZ.  @samp{YZ} is the type number.  Data until the next
+lopcode other than lop_quote forms special data of type @samp{YZ}.
+@xref{mmo section mapping}.
+
+Other types than 80, (or type 80 with a content that does not
+parse) is stored in sections named @code{.MMIX.spec_data.@var{n}}
+where @var{n} is the @samp{YZ}-type.  The flags for such a
+sections say not to allocate or load the data.  The vma is 0.
+Contents of multiple occurrences of special data @var{n} is
+concatenated to the data of the previous lop_spec @var{n}s.  The
+location in data or code at which the lop_spec occurred is lost.
+
+@item lop_pre
+0x980901ZZ.  The first lopcode in a file.  The @samp{Z} field forms the
+length of header information in 32-bit words, where the first word
+tells the time in seconds since @samp{00:00:00 GMT Jan 1 1970}.
+
+@item lop_post
+0x980a00ZZ.  @math{Z > 32}.  This lopcode follows after all
+content-generating lopcodes in a program.  The @samp{Z} field
+denotes the value of @samp{rG} at the beginning of the program.
+The following @math{256 - Z} big-endian 64-bit words are loaded
+into global registers @samp{$G} @dots{} @samp{$255}.
+
+@item lop_stab
+0x980b0000.  The next-to-last lopcode in a program.  Must follow
+immediately after the lop_post lopcode and its data.  After this
+lopcode follows all symbols in a compressed format
+(@pxref{Symbol-table}).
+
+@item lop_end
+0x980cYYZZ.  The last lopcode in a program.  It must follow the
+lop_stab lopcode and its data.  The @samp{YZ} field contains the
+number of 32-bit words of symbol table information after the
+preceding lop_stab lopcode.
+@end table
+
+Note that the lopcode "fixups"; @code{lop_fixr}, @code{lop_fixrx} and
+@code{lop_fixo} are not generated by BFD, but are handled.  They are
+generated by @code{mmixal}.
+
+This trivial one-label, one-instruction file:
+
+@example
+ :Main TRAP 1,2,3
+@end example
+
+can be represented this way in mmo:
+
+@example
+ 0x98090101 - lop_pre, one 32-bit word with timestamp.
+ <timestamp>
+ 0x98010002 - lop_loc, text segment, using a 64-bit address.
+              Note that mmixal does not emit this for the file above.
+ 0x00000000 - Address, high 32 bits.
+ 0x00000000 - Address, low 32 bits.
+ 0x98060002 - lop_file, 2 32-bit words for file-name.
+ 0x74657374 - "test"
+ 0x2e730000 - ".s\0\0"
+ 0x98070001 - lop_line, line 1.
+ 0x00010203 - TRAP 1,2,3
+ 0x980a00ff - lop_post, setting $255 to 0.
+ 0x00000000
+ 0x00000000
+ 0x980b0000 - lop_stab for ":Main" = 0, serial 1.
+ 0x203a4040   @xref{Symbol-table}.
+ 0x10404020
+ 0x4d206120
+ 0x69016e00
+ 0x81000000
+ 0x980c0005 - lop_end; symbol table contained five 32-bit words.
+@end example
+@node Symbol-table, mmo section mapping, File layout, mmo
+@subsection Symbol table format
+From mmixal.w (or really, the generated mmixal.tex) in the
+MMIXware package which also contains the @command{mmix} simulator:
+``Symbols are stored and retrieved by means of a @samp{ternary
+search trie}, following ideas of Bentley and Sedgewick. (See
+ACM--SIAM Symp.@: on Discrete Algorithms @samp{8} (1997), 360--369;
+R.@:Sedgewick, @samp{Algorithms in C} (Reading, Mass.@:
+Addison--Wesley, 1998), @samp{15.4}.)  Each trie node stores a
+character, and there are branches to subtries for the cases where
+a given character is less than, equal to, or greater than the
+character in the trie.  There also is a pointer to a symbol table
+entry if a symbol ends at the current node.''
+
+So it's a tree encoded as a stream of bytes.  The stream of bytes
+acts on a single virtual global symbol, adding and removing
+characters and signalling complete symbol points.  Here, we read
+the stream and create symbols at the completion points.
+
+First, there's a control byte @code{m}.  If any of the listed bits
+in @code{m} is nonzero, we execute what stands at the right, in
+the listed order:
+
+@example
+ (MMO3_LEFT)
+ 0x40 - Traverse left trie.
+        (Read a new command byte and recurse.)
+
+ (MMO3_SYMBITS)
+ 0x2f - Read the next byte as a character and store it in the
+        current character position; increment character position.
+        Test the bits of @code{m}:
+
+        (MMO3_WCHAR)
+        0x80 - The character is 16-bit (so read another byte,
+               merge into current character.
+
+        (MMO3_TYPEBITS)
+        0xf  - We have a complete symbol; parse the type, value
+               and serial number and do what should be done
+               with a symbol.  The type and length information
+               is in j = (m & 0xf).
+
+               (MMO3_REGQUAL_BITS)
+               j == 0xf: A register variable.  The following
+                         byte tells which register.
+               j <= 8:   An absolute symbol.  Read j bytes as the
+                         big-endian number the symbol equals.
+                         A j = 2 with two zero bytes denotes an
+                         unknown symbol.
+               j > 8:    As with j <= 8, but add (0x20 << 56)
+                         to the value in the following j - 8
+                         bytes.
+
+               Then comes the serial number, as a variant of
+               uleb128, but better named ubeb128:
+               Read bytes and shift the previous value left 7
+               (multiply by 128).  Add in the new byte, repeat
+               until a byte has bit 7 set.  The serial number
+               is the computed value minus 128.
+
+        (MMO3_MIDDLE)
+        0x20 - Traverse middle trie.  (Read a new command byte
+               and recurse.)  Decrement character position.
+
+ (MMO3_RIGHT)
+ 0x10 - Traverse right trie.  (Read a new command byte and
+        recurse.)
+@end example
+
+Let's look again at the @code{lop_stab} for the trivial file
+(@pxref{File layout}).
+
+@example
+ 0x980b0000 - lop_stab for ":Main" = 0, serial 1.
+ 0x203a4040
+ 0x10404020
+ 0x4d206120
+ 0x69016e00
+ 0x81000000
+@end example
+
+This forms the trivial trie (note that the path between ``:'' and
+``M'' is redundant):
+
+@example
+ 203a     ":"
+ 40       /
+ 40      /
+ 10      \
+ 40      /
+ 40     /
+ 204d  "M"
+ 2061  "a"
+ 2069  "i"
+ 016e  "n" is the last character in a full symbol, and
+       with a value represented in one byte.
+ 00    The value is 0.
+ 81    The serial number is 1.
+@end example
+
+@node mmo section mapping, , Symbol-table, mmo
+@subsection mmo section mapping
+The implementation in BFD uses special data type 80 (decimal) to
+encapsulate and describe named sections, containing e.g.@: debug
+information.  If needed, any datum in the encapsulation will be
+quoted using lop_quote.  First comes a 32-bit word holding the
+number of 32-bit words containing the zero-terminated zero-padded
+segment name.  After the name there's a 32-bit word holding flags
+describing the section type.  Then comes a 64-bit big-endian word
+with the section length (in bytes), then another with the section
+start address.  Depending on the type of section, the contents
+might follow, zero-padded to 32-bit boundary.  For a loadable
+section (such as data or code), the contents might follow at some
+later point, not necessarily immediately, as a lop_loc with the
+same start address as in the section description, followed by the
+contents.  This in effect forms a descriptor that must be emitted
+before the actual contents.  Sections described this way must not
+overlap.
+
+For areas that don't have such descriptors, synthetic sections are
+formed by BFD.  Consecutive contents in the two memory areas
+@samp{0x0000@dots{}00} to @samp{0x01ff@dots{}ff} and
+@samp{0x2000@dots{}00} to @samp{0x20ff@dots{}ff} are entered in
+sections named @code{.text} and @code{.data} respectively.  If an area
+is not otherwise described, but would together with a neighboring
+lower area be less than @samp{0x40000000} bytes long, it is joined
+with the lower area and the gap is zero-filled.  For other cases,
+a new section is formed, named @code{.MMIX.sec.@var{n}}.  Here,
+@var{n} is a number, a running count through the mmo file,
+starting at 0.
+
+A loadable section specified as:
+
+@example
+ .section secname,"ax"
+ TETRA 1,2,3,4,-1,-2009
+ BYTE 80
+@end example
+
+and linked to address @samp{0x4}, is represented by the sequence:
+
+@example
+ 0x98080050 - lop_spec 80
+ 0x00000002 - two 32-bit words for the section name
+ 0x7365636e - "secn"
+ 0x616d6500 - "ame\0"
+ 0x00000033 - flags CODE, READONLY, LOAD, ALLOC
+ 0x00000000 - high 32 bits of section length
+ 0x0000001c - section length is 28 bytes; 6 * 4 + 1 + alignment to 32 bits
+ 0x00000000 - high 32 bits of section address
+ 0x00000004 - section address is 4
+ 0x98010002 - 64 bits with address of following data
+ 0x00000000 - high 32 bits of address
+ 0x00000004 - low 32 bits: data starts at address 4
+ 0x00000001 - 1
+ 0x00000002 - 2
+ 0x00000003 - 3
+ 0x00000004 - 4
+ 0xffffffff - -1
+ 0xfffff827 - -2009
+ 0x50000000 - 80 as a byte, padded with zeros.
+@end example
+
+Note that the lop_spec wrapping does not include the section
+contents.  Compare this to a non-loaded section specified as:
+
+@example
+ .section thirdsec
+ TETRA 200001,100002
+ BYTE 38,40
+@end example
+
+This, when linked to address @samp{0x200000000000001c}, is
+represented by:
+
+@example
+ 0x98080050 - lop_spec 80
+ 0x00000002 - two 32-bit words for the section name
+ 0x7365636e - "thir"
+ 0x616d6500 - "dsec"
+ 0x00000010 - flag READONLY
+ 0x00000000 - high 32 bits of section length
+ 0x0000000c - section length is 12 bytes; 2 * 4 + 2 + alignment to 32 bits
+ 0x20000000 - high 32 bits of address
+ 0x0000001c - low 32 bits of address 0x200000000000001c
+ 0x00030d41 - 200001
+ 0x000186a2 - 100002
+ 0x26280000 - 38, 40 as bytes, padded with zeros
+@end example
+
+For the latter example, the section contents must not be
+loaded in memory, and is therefore specified as part of the
+special data.  The address is usually unimportant but might
+provide information for e.g.@: the DWARF 2 debugging format.