mcs/class/Mono.CSharp.Debugger/README.relocation-table

   1 This is an implementation of the System.Diagnostics.SymbolStore.ISymbolWriter
   2 interface which writes a symbol file in the dwarf format.
   3
   4 The output is an assembler input file containing dwarf data with an
   5 additional ELF section called ".mono_reloc_table". This section is
   6 read by the JIT engine to map IL offsets and such to machine
   7 addresses.
   8
   9 The mono relocation table contains of
  10
  11 1. A 2-byte unsigned integer containing a version number, currently 1.
  12
  13 2. A 1-byte unsigned integer containing a flag specifying whether the
  14    object file containing this section has already been relocated.
  15
  16    The symbol writer sets this flag to zero, you must change it to 1
  17    if you write the relocated file back to disk.
  18
  19 3. A 4-byte unsigned integer containing the total size of the
  20    relocation type, but not including the size field itself.
  21
  22 4. One or more relocation entries.
  23
  24 Each entry in the relocation table has the following form:
  25
  26 1. A 1-byte unsigned integer specifying the type of this entry.
  27
  28 2. A 4-byte unsigned integer containing the size of this entry, but
  29    not including the size field itself.
  30
  31 3. A 1-byte unsigned integer specifying the ELF section of this entry.
  32
  33 4. A 2-byte unsigned offset from the beginning of the ELF section to
  34    the location which needs to be relocated. This is called the target.
  35
  36 5. Optional additional data depending on the type of the entry.
  37
  38 The following entry types are currently defined:
  39
  40 a) TARGET_ADDRESS_SIZE - 0x01
  41
  42    The target is a 1-byte unsigned integer containing the size in
  43    bytes of an address on the target machine.
  44
  45 b) IL_OFFSET - 0x02
  46
  47    The target is an integer of appropriate size to hold an address on
  48    the target machine (the assembler ensures that the object has the
  49    correct size) and contains an IL offset from the beginning of the
  50    current method which needs to be replaced with the corresponding
  51    machine address.
  52
  53    This entry has a 4-byte unsigned integer argument containing the
  54    metadata token of the current method.
  55
  56 To use the generated object file, the JIT must:
  57
  58 * Check whether the file contains a ".mono_reloc_table" section.
  59   If not, the file cannot be used (you need to change the address size
  60   field in each compilation unit header).
  61
  62 * Check whether the flag field of the relocation table (the 3rd byte
  63   of the relocation table) is zero. If it is 1, the file has already
  64   been relocated. In this case, it's best to reject the file.
  65
  66 * Set the flag field to 1.
  67
  68 * Process all relocation entries.
  69
  70 * Write the modified file back to disk.
  71
  72 To do the relocation, the JIT can assume that:
  73
  74 1.) All the relevant ELF sections are physically contiguous
  75     (a requirement from the DWARF 2 specification).
  76
  77 2.) All relocation targets holding addresses are suitable of holding
  78     an address on the target machine.
  79
  80     This means that you can do something like
  81
  82         * (void **) ptr = map_to_machine (* (void **) ptr)
  83
  84 3.) There are no other changes needed in the object file - so you can
  85     just write it back to disk once you're done with the relocation.
  86
  87
  88 Last changed March 19th, 2002
  89 Martin Baulig <martin@gnome.org>