docs/parrotbyte.pod

   1 # Copyright (C) 2001-2007, Parrot Foundation.
   2 # $Id$
   3
   4 =head1 NAME
   5
   6 docs/parrotbyte.pod - The Parrot Bytecode (PBC) Format
   7
   8 =head1 Format of the Parrot bytecode
   9
  10 The 18-byte header consists of:
  11
  12   0                                           7
  13   +----------+----------+----------+----------+
  14   |         Parrot Magic = 0x 13155a1         |
  15   +----------+----------+----------+----------+
  16
  17 B<Magic> is stored in native byteorder. The loader uses the byteorder header to
  18 convert the Magic to verify. More specifically, ALL words (non-bytes) in the
  19 bytecode file are stored in native order, unless otherwise specified.
  20
  21   8          9         10         11
  22   +----------+----------+----------+
  23   | Wordsize | Byteorder| FloatType|
  24   +----------+----------+----------+
  25
  26 The B<Wordsize> (or C<opcode_t> size) must be 4 (32-bit) or 8 (64 bit). The
  27 bytecode loader is responsible for transforming the file into the VM native
  28 wordsize on the fly. For performance, a utility F<pbc_dump> is provided to convert
  29 PBCs on disk if they cannot be recompiled. See F<src/pbc_dump.c> for more
  30 information.
  31
  32 B<Byteorder> currently supports two values: (0-Little Endian, 1-Big Endian)
  33
  34 B<FloatType> 0 is IEEE 754 8 byte double, FloatType 1 is
  35 i386 little endian 12 byte long double.
  36
  37   11        12         13         14         15         16
  38   +----------+----------+----------+----------+----------+
  39   |  Major   |  Minor   |  Patch   | BC Major | BC Minor |
  40   +----------+----------+----------+----------+----------+
  41
  42 B<Major>, B<Minor>, B<Patch> for the version of Parrot that wrote
  43 the bytecode file.
  44
  45 B<BC Major> and B<BC Minor> are for the internal bytecode version.
  46
  47   16        17         18         19         20         21         22
  48   +----------+----------+----------+----------+----------+----------+
  49   | UUID type| UUID size|  *UUID data                               |
  50   +----------+----------+----------+----------+----------+----------+
  51
  52 After the UUID type and size comes the UUID data pointer.
  53
  54   22*
  55   +----------+----------+----------+----------+
  56   |         dir_format      (1)               |
  57   +----------+----------+----------+----------+
  58   |         padding         (0)               |
  59   +----------+----------+----------+----------+
  60
  61 B<dir_format> has length opcode_t and value 1 for PBC FORMAT 1,
  62 defined in F<packfile.h>
  63
  64 =head1 PBC FORMAT 1
  65
  66 All segments are aligned at a 16 byte boundary. All segments share a common
  67 header and are kept in directories, which itself is a PBC segment. All offsets
  68 and sizes are in native opcodes of the machine that produced the PBC.
  69
  70 After the PBC header, the first PBC directory follows at offset 24*
  71 starting with a:
  72
  73 =head2 Format 1 Segment Header
  74
  75   +----------+----------+----------+----------+
  76   | total size in opcodes including this size |
  77   +----------+----------+----------+----------+
  78   |         internal type (itype)             |
  79   +----------+----------+----------+----------+
  80   |         internal id   (id)                |
  81   +----------+----------+----------+----------+
  82   |         size of opcodes following         |
  83   +----------+----------+----------+----------+
  84
  85 The B<size> entry may be followed by a stream of B<size> opcodes (starting 16
  86 byte aligned), which may of course be no opcode stream at all for size zero.
  87
  88 After this common segment header there can be segment specific data determined
  89 by the segment type. A segment without additional data, like the bytecode
  90 segment, is a B<default> segment. No additional routines are required to unpack
  91 such a segment.
  92
  93 =head2 Directory Segment
  94
  95   +----------+----------+----------+----------+
  96   | number of directory entries               |
  97   +----------+----------+----------+----------+
  98
  99   +----------+----------+----------+----------+
 100   | segment type                              |
 101   +----------+----------+----------+----------+
 102   | segment name ...                          |
 103   | ...        0x00       padding             |
 104   +----------+----------+----------+----------+
 105   | segment offset                            |
 106   +----------+----------+----------+----------+
 107   | segment op_count                          |
 108   +----------+----------+----------+----------+
 109
 110 The B<op_count> at B<offset> must match the segments B<op_count> and is used to
 111 verify the PBCs integrity.
 112
 113 Currently these segment types are defined:
 114
 115 =over 4
 116
 117 =item 0
 118
 119 Directory segment
 120
 121 =item 1
 122
 123 Unknown segment (conforms to a default segment)
 124
 125 =item 2
 126
 127 Fixup segment
 128
 129 =item 3
 130
 131 Constant table segment
 132
 133 =item 4
 134
 135 Bytecode segment
 136
 137 =item 5
 138
 139 Debug segment
 140
 141 =back
 142
 143 =head2 Segment Names
 144
 145 This is not determined yet.
 146
 147 =head2 Unknown (default) and byte code segments
 148
 149 These have only the common segment header and the opcode stream appended. The
 150 opcode stream is an F<mmap()>ed memory region, if your operating system
 151 supports this (and if the PBC was read from a disk file). You have therefore to
 152 consider these data as readonly.
 153
 154 =head2 Fixup segment
 155
 156   +----------+----------+----------+----------+
 157   | number of fixup entries                   |
 158   +----------+----------+----------+----------+
 159
 160   +----------+----------+----------+----------+
 161   | fixup type   (0)                          |
 162   +----------+----------+----------+----------+
 163   | label   name ...                          |
 164   | ...        0x00       padding             |
 165   +----------+----------+----------+----------+
 166   | label offset                              |
 167   +----------+----------+----------+----------+
 168
 169 Fixup type B<enum_fixup_sub>, has a label symbol that is the name
 170 of the "sub" and an offset into the constant table, referencing a Sub, Closure
 171 or Coroutine PMC.
 172
 173 =head2 Debug Segment
 174
 175 The opcode stream will contain one line number per bytecode instruction. No
 176 information as to what file that line is from will be stored in this stream.
 177
 178 The header will start with a count of the number of source file to bytecode
 179 position mappings that are in the header.
 180
 181   0 (relative)
 182   +----------+----------+----------+----------+
 183   |   number of source => bytecode mappings   |
 184   +----------+----------+----------+----------+
 185
 186 A source to bytecode position mapping simply states that the bytecode that
 187 starts from the specified offset up until the offset in the next mapping, or
 188 if there is none up until the end of the bytecode, has its source in
 189 location X.
 190
 191 A mapping always starts with the offset in the bytecode, followed by the
 192 type of the mapping.
 193
 194   0 (relative)
 195   +----------+----------+----------+----------+
 196   |              bytecode offset              |
 197   +----------+----------+----------+----------+
 198
 199   4
 200   +----------+----------+----------+----------+
 201   |                mapping type               |
 202   +----------+----------+----------+----------+
 203
 204 There are 3 mapping types.
 205
 206 Type B<0> means there is no source available for the bytecode starting at the
 207 given offset. No further data is stored with this type of mapping; the next
 208 mapping continues immediately after it.
 209
 210 Type B<1> means the source is available in a file. An index into the constants
 211 table follows, which will point to a string containing the filename.
 212
 213 Type B<2> means the source is available in a source segment. Another integer
 214 follows, which will specify which source file in the source segment to use.
 215
 216 Note that the ordering of the offsets into the bytecode must be sequential;
 217 a mapping for offset 100 cannot follow a mapping for offset 200, for
 218 example.
 219
 220 =head2 CONSTANT TABLE SEGMENT
 221
 222   0 (relative)
 223   +----------+----------+----------+----------+
 224   |            Constant Count (N)             |
 225   +----------+----------+----------+----------+
 226
 227 For each constant:
 228
 229   +----------+----------+----------+----------+
 230   |             Constant Type (T)             |
 231   +----------+----------+----------+----------+
 232   |                                           |
 233   |        S bytes of constant content        |
 234   :       appropriate for representing        :
 235   |              a value of type T            |
 236   |                                           |
 237   +----------+----------+----------+----------+
 238
 239
 240 =head2 CONSTANTS
 241
 242 For integer constants:
 243
 244   << integer constants are represented as manifest constants in
 245      the byte code stream currently, limiting them to 32 bit values. >>
 246
 247 For number constants (S is constant, and is equal to C<sizeof(FLOATVAL)>):
 248
 249   +----------+----------+----------+----------+
 250   |                                           |
 251   |             S' bytes of Data              |
 252   |                                           |
 253   +----------+----------+----------+----------+
 254
 255 where
 256
 257   S' = S + (S % 4) ? (4 - (S % 4)) : 0
 258
 259 If S' E<gt> S, then the extra bytes are filled with zeros.
 260
 261
 262 For string constants (S varies, and is the size of the particular string):
 263
 264   4, 4 + (16 + S'0), 4 + (16 + S'0) + (16 + S'1)
 265   +----------+----------+----------+----------+
 266   |                   Flags                   |
 267   +----------+----------+----------+----------+
 268   |                  Encoding                 |
 269   +----------+----------+----------+----------+
 270   |                   Type                    |
 271   +----------+----------+----------+----------+
 272   |                  Size (S)                 |
 273   +----------+----------+----------+----------+
 274   |                                           |
 275   :             S' bytes of Data              :
 276   |                                           |
 277   +----------+----------+----------+----------+
 278
 279 where
 280
 281   S' = S + (S % 4) ? (4 - (S % 4)) : 0
 282
 283 If S' E<gt> S, then the extra bytes are filled with zeros.
 284
 285
 286 =head2 BYTE CODE SEGMENT
 287
 288 The pieces that can be found in the byte code segment are as follows:
 289
 290   +----------+----------+----------+----------+
 291   |              Operation Code               |
 292   +----------+----------+----------+----------+
 293
 294   +----------+----------+----------+----------+
 295   |             Register Argument             |
 296   +----------+----------+----------+----------+
 297
 298   +----------+----------+----------+----------+
 299   |    Integer Argument (Manifest Constant)   |
 300   +----------+----------+----------+----------+
 301
 302   +----------+----------+----------+----------+
 303   |   String Argument (Constant Table Index)  |
 304   +----------+----------+----------+----------+
 305
 306   +----------+----------+----------+----------+
 307   |   Number Argument (Constant Table Index)  |
 308   +----------+----------+----------+----------+
 309
 310   +----------+----------+----------+----------+
 311   |    PMC Argument (Constant Table Index)    |
 312   +----------+----------+----------+----------+
 313
 314 The number of arguments and the type of each argument can usually be determined
 315 by consulting Parrot::Opcode, or programmatically by obtaining the op_info_t
 316 structure for the opcode in question.
 317
 318 There are currently 4 opcodes that can take a variable number of arguments:
 319 set_args, get_params, set_returns and get_results. These ops always have one
 320 required argument, which is a PMC constant. Calling the elements VTABLE
 321 function on this PMC will give the number of extra variable arguments that
 322 follow.
 323
 324
 325 =head2 SOURCE CODE SEGMENT
 326
 327 Currently there are no utilities that use this segment, even though it is
 328 mentioned in some of the early Parrot documents.
 329
 330 =head1 SEE ALSO
 331
 332 F<packfile.c>, F<packfile.h>, F<packout.c>, F<packdump.c>, F<pf/*.c>, and the
 333 B<pbc_dump> utility F<pbc_dump.c>.
 334