[t] Refactor some namespace pmc tests to use throws_like
[parrot.git] / docs / parrotbyte.pod
bloba3b6f5f13d79996bb7e552d8890799ce953e872b
1 # Copyright (C) 2001-2007, Parrot Foundation.
2 # $Id$
4 =head1 NAME
6 docs/parrotbyte.pod - The Parrot Bytecode (PBC) Format
8 =head1 Format of the Parrot bytecode
10 The 18-byte header consists of:
12   0                                           7
13   +----------+----------+----------+----------+
14   |         Parrot Magic = 0x 13155a1         |
15   +----------+----------+----------+----------+
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.
21   8          9         10         11
22   +----------+----------+----------+
23   | Wordsize | Byteorder| FloatType|
24   +----------+----------+----------+
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.
32 B<Byteorder> currently supports two values: (0-Little Endian, 1-Big Endian)
34 B<FloatType> 0 is IEEE 754 8 byte double, FloatType 1 is
35 i386 little endian 12 byte long double.
37   11        12         13         14         15         16
38   +----------+----------+----------+----------+----------+
39   |  Major   |  Minor   |  Patch   | BC Major | BC Minor |
40   +----------+----------+----------+----------+----------+
42 B<Major>, B<Minor>, B<Patch> for the version of Parrot that wrote
43 the bytecode file.
45 B<BC Major> and B<BC Minor> are for the internal bytecode version.
47   16        17         18         19         20         21         22
48   +----------+----------+----------+----------+----------+----------+
49   | UUID type| UUID size|  *UUID data                               |
50   +----------+----------+----------+----------+----------+----------+
52 After the UUID type and size comes the UUID data pointer.
54   22*
55   +----------+----------+----------+----------+
56   |         dir_format      (1)               |
57   +----------+----------+----------+----------+
58   |         padding         (0)               |
59   +----------+----------+----------+----------+
61 B<dir_format> has length opcode_t and value 1 for PBC FORMAT 1,
62 defined in F<packfile.h>
64 =head1 PBC FORMAT 1
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.
70 After the PBC header, the first PBC directory follows at offset 24*
71 starting with a:
73 =head2 Format 1 Segment Header
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   +----------+----------+----------+----------+
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.
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.
93 =head2 Directory Segment
95   +----------+----------+----------+----------+
96   | number of directory entries               |
97   +----------+----------+----------+----------+
99   +----------+----------+----------+----------+
100   | segment type                              |
101   +----------+----------+----------+----------+
102   | segment name ...                          |
103   | ...        0x00       padding             |
104   +----------+----------+----------+----------+
105   | segment offset                            |
106   +----------+----------+----------+----------+
107   | segment op_count                          |
108   +----------+----------+----------+----------+
110 The B<op_count> at B<offset> must match the segments B<op_count> and is used to
111 verify the PBCs integrity.
113 Currently these segment types are defined:
115 =over 4
117 =item 0
119 Directory segment
121 =item 1
123 Unknown segment (conforms to a default segment)
125 =item 2
127 Fixup segment
129 =item 3
131 Constant table segment
133 =item 4
135 Bytecode segment
137 =item 5
139 Debug segment
141 =back
143 =head2 Segment Names
145 This is not determined yet.
147 =head2 Unknown (default) and byte code segments
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.
154 =head2 Fixup segment
156   +----------+----------+----------+----------+
157   | number of fixup entries                   |
158   +----------+----------+----------+----------+
160   +----------+----------+----------+----------+
161   | fixup type   (0)                          |
162   +----------+----------+----------+----------+
163   | label   name ...                          |
164   | ...        0x00       padding             |
165   +----------+----------+----------+----------+
166   | label offset                              |
167   +----------+----------+----------+----------+
169 Fixup type B<0>, known as enum_fixup_label, has a label symbol and an offset
170 into the bytecode.
172 Fixup type B<1>, known as enum_fixup_sub, has a label symbol that is the name
173 of the "sub" and an offset into the constant table, referencing a Sub, Closure
174 or Coroutine PMC.
176 =head2 Debug Segment
178 The opcode stream will contain one line number per bytecode instruction. No
179 information as to what file that line is from will be stored in this stream.
181 The header will start with a count of the number of source file to bytecode
182 position mappings that are in the header.
184   0 (relative)
185   +----------+----------+----------+----------+
186   |   number of source => bytecode mappings   |
187   +----------+----------+----------+----------+
189 A source to bytecode position mapping simply states that the bytecode that
190 starts from the specified offset up until the offset in the next mapping, or
191 if there is none up until the end of the bytecode, has it's source in
192 location X.
194 A mapping always starts with the offset in the bytecode, followed by the
195 type of the mapping.
197   0 (relative)
198   +----------+----------+----------+----------+
199   |              bytecode offset              |
200   +----------+----------+----------+----------+
202   4
203   +----------+----------+----------+----------+
204   |                mapping type               |
205   +----------+----------+----------+----------+
207 There are 3 mapping types.
209 Type B<0> means there is no source available for the bytecode starting at the
210 given offset. No further data is stored with this type of mapping; the next
211 mapping continues immediately after it.
213 Type B<1> means the source is available in a file. An index into the constants
214 table follows, which will point to a string containing the filename.
216 Type B<2> means the source is available in a source segment. Another integer
217 follows, which will specify which source file in the source segment to use.
219 Note that the ordering of the offsets into the bytecode must be sequential;
220 a mapping for offset 100 cannot follow a mapping for offset 200, for
221 example.
223 =head2 CONSTANT TABLE SEGMENT
225   0 (relative)
226   +----------+----------+----------+----------+
227   |            Constant Count (N)             |
228   +----------+----------+----------+----------+
230 For each constant:
232   +----------+----------+----------+----------+
233   |             Constant Type (T)             |
234   +----------+----------+----------+----------+
235   |                                           |
236   |        S bytes of constant content        |
237   :       appropriate for representing        :
238   |              a value of type T            |
239   |                                           |
240   +----------+----------+----------+----------+
243 =head2 CONSTANTS
245 For integer constants:
247   << integer constants are represented as manifest constants in
248      the byte code stream currently, limiting them to 32 bit values. >>
250 For number constants (S is constant, and is equal to C<sizeof(FLOATVAL)>):
252   +----------+----------+----------+----------+
253   |                                           |
254   |             S' bytes of Data              |
255   |                                           |
256   +----------+----------+----------+----------+
258 where
260   S' = S + (S % 4) ? (4 - (S % 4)) : 0
262 If S' E<gt> S, then the extra bytes are filled with zeros.
265 For string constants (S varies, and is the size of the particular string):
267   4, 4 + (16 + S'0), 4 + (16 + S'0) + (16 + S'1)
268   +----------+----------+----------+----------+
269   |                   Flags                   |
270   +----------+----------+----------+----------+
271   |                  Encoding                 |
272   +----------+----------+----------+----------+
273   |                   Type                    |
274   +----------+----------+----------+----------+
275   |                  Size (S)                 |
276   +----------+----------+----------+----------+
277   |                                           |
278   :             S' bytes of Data              :
279   |                                           |
280   +----------+----------+----------+----------+
282 where
284   S' = S + (S % 4) ? (4 - (S % 4)) : 0
286 If S' E<gt> S, then the extra bytes are filled with zeros.
289 =head2 BYTE CODE SEGMENT
291 The pieces that can be found in the byte code segment are as follows:
293   +----------+----------+----------+----------+
294   |              Operation Code               |
295   +----------+----------+----------+----------+
297   +----------+----------+----------+----------+
298   |             Register Argument             |
299   +----------+----------+----------+----------+
301   +----------+----------+----------+----------+
302   |    Integer Argument (Manifest Constant)   |
303   +----------+----------+----------+----------+
305   +----------+----------+----------+----------+
306   |   String Argument (Constant Table Index)  |
307   +----------+----------+----------+----------+
309   +----------+----------+----------+----------+
310   |   Number Argument (Constant Table Index)  |
311   +----------+----------+----------+----------+
313   +----------+----------+----------+----------+
314   |    PMC Argument (Constant Table Index)    |
315   +----------+----------+----------+----------+
317 The number of arguments and the type of each argument can usually be determined
318 by consulting Parrot::Opcode, or programmatically by obtaining the op_info_t
319 structure for the opcode in question.
321 There are currently 4 opcodes that can take a variable number of arguments:
322 set_args, get_params, set_returns and get_results. These ops always have one
323 required argument, which is a PMC constant. Calling the elements VTABLE
324 function on this PMC will give the number of extra variable arguments that
325 follow.
328 =head2 SOURCE CODE SEGMENT
330 Currently there are no utilities that use this segment, even though it is
331 mentioned in some of the early Parrot documents.
333 =head1 SEE ALSO
335 F<packfile.c>, F<packfile.h>, F<packout.c>, F<packdump.c>, F<pf/*.c>, and the
336 B<pbc_dump> utility F<pbc_dump.c>.