| blob | 7162e8b0a3ea87be532b3ab4b9394e7bfd526427 |
1 # Copyright (C) 2001-2009, Parrot Foundation.
2 # $Id$
4 =head1 PDD 13: Bytecode
6 =head2 Abstract
8 This PDD describes the file format for Parrot Bytecode (PBC) files and the
9 interface through which they may be manipulated programmatically.
11 =head2 Version
13 $Revision$
15 =head2 Synopsis
17 Parrot bytecode is a binary representation of instructions and data for
18 execution on the virtual machine.
20 =head2 Description
22 PBC, Parrot bytecode, is the binary format used internally by the Parrot VM to
23 store the data necessary to execute a compiled PIR program. The sequence of
24 instructions making up a Parrot program, a constants table, an annotations
25 table and any ancillary data are stored in a PBC. These files usually have
26 the extension C<.pbc>.
28 The PBC format is designed so that any valid PBC file can be read and executed
29 by Parrot on any platform, but may be encoded more optimally for a particular
30 platform.
32 It is possible to add arbitrary annotations to the instruction sequence, for
33 example line numbers in high level languages and other debug data.
35 PMCs are be used to represent packfiles and packfile segments to provide a
36 programmatic interface, both to Parrot programs and Parrot internals.
38 =head2 Implementation
40 =head3 Packfiles
42 This section of the documentation describes the format of Parrot packfiles.
43 These contain the bytecode (sequence of instructions), constants table, fixup
44 table, debug data, annotations and possibly more.
46 Note that, unless otherwise stated, all offsets and lengths are given in terms
47 of Parrot opcodes, not bytes. An opcode corresponds to the word size, defined
48 as long. The ptrsize is silently assumed to be the same as the opcode size.
51 =head4 Packfile Header
53 PBC files start with a variable length header. All data in this header is
54 stored as strings or in a single byte so endianness and word size need not be
55 considered when reading it.
57 Note that in this section only, offsets and lengths are in bytes.
59 +--------+--------+--------------------------------------------------------+
60 | Offset | Length | Description |
61 +--------+--------+--------------------------------------------------------+
62 | 0 | 8 | 0xFE 0x50 0x42 0x43 0x0D 0x0A 0x1A 0x0A |
63 | | | Parrot "Magic String" to identify a PBC file. In C, |
64 | | | this is the string C<\376PBC\r\n\032\n> or |
65 | | | C<\xfe\x50\x42\x43\x0d\x0a\x1a\x0a>. |
66 +--------+--------+--------------------------------------------------------+
67 | 8 | 1 | Word size in bytes of words making up the segments of |
68 | | | the PBC file. Must be one of: |
69 | | | 0x04 - 4 byte (32-bit) words |
70 | | | 0x08 - 8 byte (64-bit) words |
71 +--------+--------+--------------------------------------------------------+
72 | 9 | 1 | Byte order within the words making up the segments of |
73 | | | the PBC file. Must be one of: |
74 | | | 0x00 - Little Endian |
75 | | | 0x01 - Big Endian |
76 +--------+--------+--------------------------------------------------------+
77 | 10 | 1 | The encoding of floating point numbers in the file. |
78 | | | Must be one of: |
79 | | | 0x00 - IEEE 754 8 byte double |
80 | | | 0x01 - i386 little endian 12 byte long double |
81 | | | 0x02 - IEEE 754 16 byte long double |
82 +--------+--------+--------------------------------------------------------+
83 | 11 | 1 | Major version number of the version of Parrot that |
84 | | | wrote this bytecode file. For example, if Parrot 0.9.5 |
85 | | | wrote it, this byte would have the value 0. |
86 +--------+--------+--------------------------------------------------------+
87 | 12 | 1 | Minor version number of the version of Parrot that |
88 | | | wrote this bytecode file. For example, if Parrot 0.9.5 |
89 | | | wrote it, this byte would have the value 9. |
90 +--------+--------+--------------------------------------------------------+
91 | 13 | 1 | Patch version number of the version of Parrot that |
92 | | | wrote this bytecode file. For example, if Parrot 0.9.5 |
93 | | | wrote it, this byte would have the value 5. |
94 +--------+--------+--------------------------------------------------------+
95 | 14 | 1 | Major version number of the bytecode file format. See |
96 | | | the section below on bytecode file format version |
97 | | | numbers. |
98 +--------+--------+--------------------------------------------------------+
99 | 15 | 1 | Minor version number of the bytecode file format. See |
100 | | | the section below on bytecode file format version |
101 | | | numbers. |
102 +--------+--------+--------------------------------------------------------+
103 | 16 | 1 | The type of the UUID associated with this packfile. |
104 | | | Must be one of: |
105 | | | 0x00 - No UUID |
106 | | | 0x01 - MD5 |
107 +--------+--------+--------------------------------------------------------+
108 | 17 | 1 | Length of the UUID associated with this packfile. May |
109 | | | be zero if the type of the UUID is 0x00. Maximum |
110 | | | value is 255. |
111 +--------+--------+--------------------------------------------------------+
112 | 18 | u | A UUID of u bytes in length, where u was specified as |
113 | | | the length of the UUID in the previous field. Be sure |
114 | | | that UUIDs are stored and read as strings. The UUID is |
115 | | | computed by applying the hash function specified in |
116 | | | the UUID type field over the entire packfile not |
117 | | | including this header and its trailing zero padding. |
118 +--------+--------+--------------------------------------------------------+
119 | 18 + u | n | Zero-padding to make the total header length a |
120 | | | multiple of 16 bytes in length. |
121 | | | n = u % 16 ? 16 - (u % 16) : 0 |
122 +--------+--------+--------------------------------------------------------+
124 Everything beyond the header is an opcode, with word length and byte ordering
125 as defined in the header. If the word length and byte ordering of the machine
126 that is reading the PBC file do not match these, it needs to transform the
127 words making up the rest of the packfile.
129 =over 4
131 =item * Bytecode File Version Numbers
133 The bytecode file version number exists to decouple the format of the bytecode
134 file from the version of the Parrot implementation that is reading/writing it.
135 It has a major and a minor part.
137 The major version number should be incremented whenever there is a change to
138 the layout of bytecode files. This includes new segments, changes to segment
139 headers or changes to the format of the data held within a segment.
141 The minor version number should be incremented in all other cases when a
142 change is made that means a previous version of Parrot would not be able to
143 run the program encoded in the packfile. This includes:
145 =over 4
147 =item Opcode renumbering
149 =item Addition of new opcodes and removal of existing ones
151 =item Addition of new core PMCs and removal of existing ones
153 =item Changes to the interface (externally visible behaviour) of an opcode or
154 PMC
156 =back
158 Parrot currently exits when reading an incompatible bytecode file
159 version number. It is possible for a single version of Parrot to support
160 reading and writing more than one bytecode file format, but this is not
161 currently implemented. Future versions of Parrot may also provide a
162 bytecode migration tool, to convert a bytecode file to a more recent
163 format.
165 The bytecode format versions are listed in the PBC_COMPAT file, sorted
166 with the latest version first in the file:
168 MAJOR.MINOR DATE NAME DESCRIPTION
170 =back
172 We should be aware that some systems such as a Sparc/PPC 64-bit use strict
173 8-byte ptr_alignment per default, and all C<(opcode_t*)cursor++> or
174 C<(opcode_t*)cursor +=> advances must ensure that the cursor ptr is 8-byte
175 aligned. We enforce 16-byte alignment at the start and end of all segments
176 and ptrsize alignment for all items (strings, integers, and opcode_t ops),
177 but not in-between, esp. with 4-byte integers and 4-byte opcode_t pointers.
179 So we relax pointer alignment strictness on Sparc64, but may add a
180 C<--64compat> option to parrot in the future to produce 8-byte aligned data.
181 Operations on aligned pointers are much faster than on un-aligned pointers.
184 =head4 Directory Format Header
186 Packfiles contain a directory describing the segments that it contains.
187 This header specifies the format of the directory.
189 +--------+--------+--------------------------------------------------------+
190 | Offset | Length | Description |
191 +--------+--------+--------------------------------------------------------+
192 | 0 | 1 | The format of the directory. Must be: |
193 | | | 0x01 - Directory Format 1 |
194 +--------+--------+--------------------------------------------------------+
195 | 1 | 3 | Must be: |
196 | | | 0x00 0x00 0x00 - Reserved |
197 +--------+--------+--------------------------------------------------------+
199 Currently only C<Format 1> exists. In the future, the format of the
200 directory may change. A single version of Parrot may then become capable of
201 generating and reading files of more than one directory format. This header
202 enables Parrot to detect whether it is able to read the directory segment in
203 the packfile.
205 This header must be followed immediately by a directory segment.
208 =head4 Packfile Segment Header
210 All segments, regardless of type, start with a 1 opcode segment header. All
211 other segments below are prefixed with this.
213 +--------+--------+--------------------------------------------------------+
214 | Offset | Length | Description |
215 +--------+--------+--------------------------------------------------------+
216 | 0 | 1 | The total size of the segment in opcodes, including |
217 | | | this header. |
218 +--------+--------+--------------------------------------------------------+
219 | 1 | 1 | Internal type of the segment |
220 +--------+--------+--------------------------------------------------------+
221 | 2 | 1 | Internal id |
222 +--------+--------+--------------------------------------------------------+
223 | 3 | 1 | Size of the following op array, 0 if none |
224 +--------+--------+--------------------------------------------------------+
227 =head4 Segment Padding
229 All segments must have trailing zero (NULL) values appended so they are a
230 multiple of 16 bytes in length. (This allows wordsize support of up to
231 128 bits.)
234 =head4 Directory Segment
236 This segment lists the other segments that make up the packfile and where in
237 the file they are located. It must occur immediately after the directory
238 format header. Only one of these segments may occur in a packfile. In the
239 future, a hierarchy of directories may be allowed.
241 The directory segment adds one additional header after the standard packfile
242 header data, which specifies the number of entries in the directory.
244 +--------+--------+--------------------------------------------------------+
245 | Offset | Length | Description |
246 +--------+--------+--------------------------------------------------------+
247 | 1 | 1 | The number of entries in the directory. |
248 +--------+--------+--------------------------------------------------------+
250 Following this are C<n> variable length entries formatted as described in the
251 following table. Offsets are in words, but are given relative to the start of
252 an individual entry.
254 +--------+--------+--------------------------------------------------------+
255 | Offset | Length | Description |
256 +--------+--------+--------------------------------------------------------+
257 | 0 | 1 | The type of the segment. Must be one of the following: |
258 | | | 0x00 - Reserved (Directory Segment) |
259 | | | 0x01 - Default Segment |
260 | | | 0x02 - Fixup Segment |
261 | | | 0x03 - Constant Table Segment |
262 | | | 0x04 - Bytecode Segment |
263 | | | 0x05 - PIR Debug Segment |
264 | | | 0x06 - Annotations Segment |
265 +--------+--------+--------------------------------------------------------+
266 | 1 | n | The name of the segment, as a (NULL terminated) ASCII |
267 | | | C string. This must be padded with trailing NULL |
268 | | | (zero) values to be a full word in size. |
269 +--------+--------+--------------------------------------------------------+
270 | n + 1 | 1 | The offset to the segment, relative to the start of |
271 | | | the packfile. Specified as a number of words, where |
272 | | | the word size is that specified in the header. (Parrot |
273 | | | may need to do some computation to transform this to |
274 | | | an offset in terms of its own word size.) As segments |
275 | | | must always be aligned on 16-byte boundaries, this |
276 | | | scheme scales up to 128-bit platforms. |
277 +--------+--------+--------------------------------------------------------+
278 | n + 2 | 1 | The length of the segment, including its header, in |
279 | | | words. This must match the length stored at the start |
280 | | | of the header of the segment the entry is describing. |
281 +--------+--------+--------------------------------------------------------+
284 =head4 Default Segment
286 The default segment has no additional headers. It will, if possible, be memory
287 mapped. More than one may exist in the packfile, and they are identified by
288 name. They may be used for storing any data that does not fit into any other
289 segment, for example the source code from a high level language (HLL).
292 =head4 Bytecode Segment
294 This segment has no additional headers. It stores a stream of instructions in
295 bytecode format, with the length given in the last field of the segment
296 header.
298 Instructions have variable length. Each instruction starts with an operation
299 code (opcode).
301 +--------+--------+--------------------------------------------------------+
302 | Offset | Length | Description |
303 +--------+--------+--------------------------------------------------------+
304 | 0 | 1 | A valid Parrot opcode, as specified in the opcode |
305 | | | list include/parrot/oplib/ops.h. |
306 +--------+--------+--------------------------------------------------------+
308 Zero or more operands follow the opcode. All opcodes take a fixed number of
309 operands. An individual operand is always one word in length and may be of
310 one of the following forms.
312 +------------------+-------------------------------------------------------+
313 | Operand Type | Description |
314 +------------------+-------------------------------------------------------+
315 | Register | An integer specifying a register number. |
316 +------------------+-------------------------------------------------------+
317 | Integer Constant | An integer that is the constant itself. That is, the |
318 | | constant is stored directly in the instruction |
319 | | stream. Storing integer constants of length greater |
320 | | than 32 bits has undefined behaviour and should be |
321 | | considered unportable. |
322 +------------------+-------------------------------------------------------+
323 | Number Constant | An index into the constants table. |
324 +------------------+-------------------------------------------------------+
325 | String Constant | An index into the constants table. |
326 +------------------+-------------------------------------------------------+
327 | PMC Constant | An index into the constants table. |
328 +------------------+-------------------------------------------------------+
331 =head4 Constants Segment
333 This segment stores number, string and PMC constants.
335 The first element is the number of constants contained.
337 +--------+--------+--------------------------------------------------------+
338 | Offset | Length | Description |
339 +--------+--------+--------------------------------------------------------+
340 | 2 | 1 | The number of constants in the table. |
341 +--------+--------+--------------------------------------------------------+
343 Following this are C<n> constants, each with a single word header specifying
344 the type of constant that follows.
346 +--------+--------+--------------------------------------------------------+
347 | Offset | Length | Description |
348 +--------+--------+--------------------------------------------------------+
349 | 0 | 1 | The type of the constant. Must be one of: |
350 | | | 0x00 - No constant |
351 | | | 0x6E - Number constant (ASCII 'n') |
352 | | | 0x73 - String constant (ASCII 's') |
353 | | | 0x70 - PMC constant (ASCII 'p') |
354 | | | 0x6B - Key constant (ASCII 'k') |
355 +--------+--------+--------------------------------------------------------+
357 All constants that are not a multiple of the word size in length must be
358 padded with trailing zero bytes up to a word size boundary.
360 =over 4
362 =item * Number Constants
364 The number is stored in the format defined in the Packfile header. Any padding
365 that is needed will follow.
367 =item * String Constants
369 String constants are stored in the following format, with offsets relative to
370 the start of the constant including its type.
372 +--------+--------+--------------------------------------------------------+
373 | Offset | Length | Description |
374 +--------+--------+--------------------------------------------------------+
375 | 1 | 1 | Flags, copied from the string structure. |
376 +--------+--------+--------------------------------------------------------+
377 | 2 | 1 | Character set; either the index of a built-in one or a |
378 | | | dynamically loaded one whose index is in a range given |
379 | | | in the dependencies table. Note that dynamically |
380 | | | loaded character sets are not currently supported. |
381 +--------+--------+--------------------------------------------------------+
382 | 3 | 1 | Encoding, either the index of a built-in one or a |
383 | | | dynamically loaded one whose index is in a range given |
384 | | | in the dependencies table. Note that dynamically |
385 | | | loaded encodings are not currently supported. |
386 +--------+--------+--------------------------------------------------------+
387 | 4 | 1 | Length of the string data in bytes. |
388 +--------+--------+--------------------------------------------------------+
389 | 5 | n | String data with trailing zero padding as required. |
390 +--------+--------+--------------------------------------------------------+
392 Note: The encoding and charset are currently packed together with the Flags,
393 using an unique field of Length 1.
396 =item * PMC Constants
398 PMCs that can be saved in packfiles as constants implement the freeze and thaw
399 vtable functions. Their frozen data is placed in a string, stored in the same
400 format as a string constant.
402 =item * Key Constants
404 Key constants are made up a number of components, where one component is a
405 "dimension" in the key. The number of components in the key is stored at the
406 start of the constant.
408 +--------+--------+--------------------------------------------------------+
409 | Offset | Length | Description |
410 +--------+--------+--------------------------------------------------------+
411 | 1 | 1 | Number of key components that follow. |
412 +--------+--------+--------------------------------------------------------+
414 Following this are C<n> entries of two words each that specify the key's
415 type and value. The key value may be a register or another constant, but not
416 another key constant. All constants other than integer constants are indexes
417 into the constants table.
419 +--------+--------+--------------------------------------------------------+
420 | Offset | Length | Description |
421 +--------+--------+--------------------------------------------------------+
422 | 0 | 1 | Type of the key. Must be one of: |
423 | | | 0x00 - Integer register |
424 | | | 0x01 - String register |
425 | | | 0x02 - PMC register |
426 | | | 0x03 - Number register |
427 | | | 0x10 - Integer constant |
428 | | | 0x11 - String constant (constant table index) |
429 | | | 0x12 - PMC constant (constant table index) |
430 | | | 0x13 - Number constant (constant table index) |
431 +--------+--------+--------------------------------------------------------+
432 | 1 | 1 | Value of the key. |
433 +--------+--------+--------------------------------------------------------+
435 =back
437 =head4 Fixup Segment
439 The fixup segment maps names of subs to offsets in the bytecode stream.
441 The number of fixup table entries, n, is given by the last field of the
442 segment header.
444 This is followed by n fixup table entries, of variable length, that take the
445 following form.
447 +--------+--------+--------------------------------------------------------+
448 | Offset | Length | Description |
449 +--------+--------+--------------------------------------------------------+
450 | 0 | 1 | Type of the fixup. Must be: |
451 | | | 0x01 - Subroutine fixup constant string |
452 | | | 0x02 - Subroutine fixup ascii string |
453 +--------+--------+--------------------------------------------------------+
454 | 1 | - | The label that is being fixed up. A string constant, |
455 | | | stored as an index into the constants table in the 01 |
456 | | | case, a NULL terminated ASCII string padded to word |
457 | | | length with zeroes in the 02. |
458 +--------+--------+--------------------------------------------------------+
459 | - | 1 | This is an index into the constants table for the sub |
460 | | | PMC corresponding to the label. |
461 +--------+--------+--------------------------------------------------------+
464 =head4 PIR Debug Segment
466 This segment stores the filenames and line numbers of PIR code that was
467 compiled to bytecode. The segment comes in two parts.
469 =over 4
471 =item A list of mappings between instructions in the bytecode and line
472 numbers, with one entry per instruction
474 =item A list of mappings between offsets in the bytecode and filenames,
475 indicating that the bytecode from that point on until the next entry was
476 generated from the PIR found in the given filename
478 =back
480 The length of the table of line number mappings is given by the last field
481 of the segment header.
483 Then comes the table:
485 +--------+--------+--------------------------------------------------------+
486 | Offset | Length | Description |
487 +--------+--------+--------------------------------------------------------+
488 | 0 | 1 | Line number for the offset in the bytecode. |
489 +--------+--------+--------------------------------------------------------+
491 Then comes an opcode with n, the number of file mappings.
493 Then come n mappings.
495 +--------+--------+--------------------------------------------------------+
496 | Offset | Length | Description |
497 +--------+--------+--------------------------------------------------------+
498 | 0 | 1 | Offset in the bytecode. |
499 +--------+--------+--------------------------------------------------------+
500 | 1 | 1 | A string constant holding the filename, stored as an |
501 | | | index into the constants table. |
502 +--------+--------+--------------------------------------------------------+
505 =head4 Annotations Segment
507 Annotations allow any instruction in the bytecode stream to have zero or more
508 key/value pairs associated with it. These can be retrieved at runtime. High
509 level languages can use annotations to store file names, line numbers, column
510 numbers and any other data, for debug purposes or otherwise, that they need.
512 The segment comes in three parts:
514 =over 4
516 =item A list of annotation keys (for example, "line" and "file").
518 =item An annotation groups table, used to group together annotations for a
519 particular HLL source file (an annotation group starting clears all active
520 annotations, so they will not spill over between source files; it also
521 allows for faster lookup of annotations).
523 {{ TODO: Does it clear all annotations, or all annotation groups? }}
525 =item A list of indexes into the bytecode stream and key/value pairings (for
526 example, starting at instruction 235, the annotation "line" has value "42").
528 =back
530 The last field of the segment header is not used.
532 The first word in the segment supplies the number of keys.
534 +--------+--------+--------------------------------------------------------+
535 | Offset | Length | Description |
536 +--------+--------+--------------------------------------------------------+
537 | 1 | 1 | Number of annotation key entries that follow. |
538 | | | n |
539 +--------+--------+--------------------------------------------------------+
541 Following this are C<n> annotation key entries. There is one entry per key
542 (such as "line" or "file"), but the bytecode may be annotated many times
543 with that key. Key entries take the following format.
545 +--------+--------+--------------------------------------------------------+
546 | Offset | Length | Description |
547 +--------+--------+--------------------------------------------------------+
548 | 0 | 1 | Index into the constants table of a string containing |
549 | | | the name of the key. |
550 +--------+--------+--------------------------------------------------------+
551 | 1 | 1 | The type of value that is stored with the key. |
552 | | | 0x00 - Integer |
553 | | | 0x01 - String Constant |
554 | | | 0x02 - Number Constant |
555 | | | 0x03 - PMC Constant |
556 +--------+--------+--------------------------------------------------------+
558 The annotation groups table comes next. This starts with a single integer to
559 specify the number of entries in the table.
561 +--------+--------+--------------------------------------------------------+
562 | Offset | Length | Description |
563 +--------+--------+--------------------------------------------------------+
564 | 1 | 1 | Number of annotation group entries that follow. |
565 +--------+--------+--------------------------------------------------------+
567 A group entry maps an offset in the bytecode segment to an offset in the list
568 of annotations (that is, offset 0 refers to the first word following this
569 table). The list of offsets into the bytecode segment (and by the definition
570 of this segment, the offsets into the annotations list) must be in ascending
571 order.
573 +--------+--------+--------------------------------------------------------+
574 | Offset | Length | Description |
575 +--------+--------+--------------------------------------------------------+
576 | 0 | 1 | Offset into the bytecode segment where the |
577 | | | instructions for a particular high level source file |
578 | | | start. |
579 +--------+--------+--------------------------------------------------------+
580 | 1 | 1 | Offset into the annotations list specifying where the |
581 | | | annotations for the given instruction start. |
582 +--------+--------+--------------------------------------------------------+
584 The rest of the segment is made up of a sequence of bytecode offset to key and
585 value mappings. First comes the number of them that follow:
587 +--------+--------+--------------------------------------------------------+
588 | Offset | Length | Description |
589 +--------+--------+--------------------------------------------------------+
590 | 1 | 1 | Number of bytecode to keypair mappings that follow. |
591 | | | n |
592 +--------+--------+--------------------------------------------------------+
594 Then there are n entries of the following format:
596 +--------+--------+--------------------------------------------------------+
597 | Offset | Length | Description |
598 +--------+--------+--------------------------------------------------------+
599 | 0 | 1 | Offset into the bytecode segment, in words, of the |
600 | | | instruction being annotated. At runtime, this will |
601 | | | correspond to the program counter. |
602 +--------+--------+--------------------------------------------------------+
603 | 1 | 1 | The key of the annotation, specified as an index into |
604 | | | the zero-based list of keys specified in the first |
605 | | | part of the segment. That is, if key "line" was the |
606 | | | first entry and "file" the second, they would have |
607 | | | indices 0 and 1 respectively. |
608 +--------+--------+--------------------------------------------------------+
609 | 2 | 2 | The value of the annotation. If the annotation type |
610 | | | (specified with the key) is an integer, the value is |
611 | | | placed directly into this word. Otherwise, an index |
612 | | | into the constants table is used. |
613 +--------+--------+--------------------------------------------------------+
615 Note that the value of an annotation with a particular key is taken to apply
616 to all following instructions up to the point of a new value being specified
617 for that key with another annotation. This means that if 20 instructions make
618 up the compiled form of a single line of code, only one line annotation is
619 required. Note that this also implies that annotations must be placed in
620 the same order as the instructions.
622 =head3 Packfile PMCs
624 A packfile can be represented in memory by Parrot as a tree of PMCs. These
625 provide a programmatic way to construct and walk packfiles, both for the
626 Parrot internals and from programs running on the Parrot VM.
628 {{ TODO... ManagedStruct and UnmanagedStruct may be helpful for these;
629 consider switching these PMCs over to use them at some point. }}
632 =head4 Packfile.pmc
634 This PMC represents the packfile overall. It will be constructed by the VM
635 when reading a packfile. It implements the following methods and vtable
636 functions.
638 =over 4
640 =item * C<get_string> (vtable)
642 Serializes this packfile data structure into a bytestream ready to be written
643 to disk (that is, maps from PMCs to on-disk representation).
645 =item * C<set_string_native> (vtable)
647 Takes a string containing an entire packfile in the on-disk format, attempts
648 to unpack it into a tree of Packfile PMCs and sets this Packfile PMC to
649 represent the top of that tree (that is, maps from on-disk representation to a
650 tree of PMCs).
652 =item * C<get_integer_keyed_str> (vtable)
654 Used to get data about fields in the header that have an integer value. Valid
655 keys are:
657 =over 4
659 =item wordsize
661 =item byteorder
663 =item fptype
665 =item version_major
667 =item version_minor
669 =item version_patch
671 =item bytecode_major
673 =item bytecode_minor
675 =item uuid_type
677 =back
679 =item * C<get_string_keyed_str> (vtable)
681 Used to get data about fields in the header that have a string value. Valid
682 keys are:
684 =over 4
686 =item uuid
688 =back
690 =item * C<set_integer_keyed_str> (vtable)
692 Used to set fields in the packfile header. Some fields are not allowed to be
693 written since they are determined by the VM when serializing the packfile for
694 storage on disk. The fields that may be set are:
696 =over 4
698 =item version_major
700 =item version_minor
702 =item version_patch
704 =item uuid_type
706 =back
708 Be very careful when setting a version number; you should usually trust the VM
709 to do the right thing with this.
711 Setting the uuid_type will not result in immediate re-computation of the
712 UUID, but rather will only cause it to be computed using the selected
713 algorithm when the packfile is serialized (by calling the C<get_string>
714 vtable function). Setting an invalid uuid_type value will cause an exception
715 to be thrown immediately.
717 =item * C<get_directory()>
719 Returns the PackfileDirectory PMC that represents the directory segment at the
720 start of the packfile.
722 =back
724 =head4 PackfileSegment.pmc
726 An abstract PMC that is the base class for all other segments. It has two
727 abstract methods, which are to be implemented by all subclasses. They will not
728 be listed under the method list for other segment PMCs to save space.
730 =over 4
732 =item * C<STRING* pack()>
734 Packs the segment into the on-disk format and returns a string holding it.
736 =item * C<unpack(STRING*)>
738 Takes the packed representation for a segment of the given type and then
739 unpacks it, setting this PMC to represent that segment as a result of the
740 unpacking. If an error occurs during the unpacking process, an exception will
741 be thrown.
743 =back
745 =head4 PackfileDirectory.pmc (isa PackfileSegment)
747 This PMC represents a directory segment. Essentially it is an hash of
748 PackfileSegment PMCs. It implements the following methods:
750 =over 4
752 =item * C<elements> (vtable)
754 Gets the number of segments listed in the directory.
756 =item * C<get_pmc_keyed_str> (vtable)
758 Searches the directory for a segment with the given name and, if one exists,
759 returns a PackfileSegment PMC (or one of its subclasses) representing it.
761 =item * C<set_pmc_keyed_str> (vtable)
763 Adds a PackfileSegment PMC (or a subclass of it) to the directory with the
764 name specified by the key. This is the only way to add another segment to the
765 directory. If a segment of the given name already exists in the directory, it
766 will be replaced with the supplied PMC.
768 =item * C<delete_keyed_str> (vtable)
770 Removes the PackfileSegment PMC from the directory which has the name
771 specified by the key. This is the only way to remove a segment from the
772 directory.
774 =item * C<get_iter> (vtable)
776 Returns iterator for existing keys.
778 =back
780 =head4 PackfileRawSegment.pmc (isa PackfileSegment)
782 This PMC presents a segment of a packfile as an array of integers. This is the
783 lowest possible level of access to a segment, and covers both the default and
784 bytecode segment types. It implements the following methods:
786 =over 4
788 =item * C<get_type>
790 Get type of PackfileRawSegment.
792 =item * C<set_type>
794 Set type of PackfileRawSegment.
796 =item * C<get_iter>
798 Returns iterator for Segment.
800 =item * C<get_integer_keyed_int> (vtable)
802 Reads the integer at the specified offset into the segment, excluding the data
803 in the common segment header but including the data making up additional
804 fields in the header for a specific type of segment.
806 =item * C<set_integer_keyed_int> (vtable)
808 Stores an integer at the specified offset into the segment. Will throw an
809 exception if the segment is memory mapped.
811 =item * C<elements> (vtable)
813 Gets the length of the segment in words, excluding the length of the common
814 segment but including the data making up additional fields in the header for a
815 specific type of segment.
817 =back
819 =head4 PackfileConstantTable.pmc (isa PackfileSegment)
821 This PMC represents a constants table. It provides access to constants through
822 the keyed integer interface (the interpreter may choose to access underlying
823 structures directly to improve performance, however).
825 The table of constants can be added to using the keyed set methods; it will
826 grow automatically.
828 The PMC implements the following methods:
830 =over 4
832 =item * C<get_iter>
834 Returns iterator for stored Constants.
836 =item * C<elements> (vtable)
838 Gets the number of constants contained in the table.
840 =item * C<get_number_keyed_int> (vtable)
842 Gets the value of the number constant at the specified index in the constants
843 table. If the constant at that position in the table is not a number, an
844 exception will be thrown.
846 =item * C<get_string_keyed_int> (vtable)
848 Gets the value of the string constant at the specified index in the constants
849 table. If the constant at that position in the table is not a string, an
850 exception will be thrown.
852 =item * C<get_pmc_keyed_int> (vtable)
854 Gets the value of the PMC or key constant at the specified index in the
855 constants table. If the constant at that position in the table is not a PMC
856 or key, an exception will be thrown.
858 =item * C<set_number_keyed_int> (vtable)
860 Sets the value of the number constant at the specified index in the constants
861 table. If the constant at that position in the table is not already a number
862 constant, an exception will be thrown. If it does not exist, the table will be
863 extended.
865 =item * C<set_string_keyed_int> (vtable)
867 Sets the value of the string constant at the specified index in the constants
868 table. If the constant at that position in the table is not already a string
869 constant, an exception will be thrown. If it does not exist, the table will be
870 extended.
872 =item * C<set_pmc_keyed_int> (vtable)
874 Sets the value of the PMC or key constant at the specified index in the
875 constants table. If the constant at that position in the table is not already
876 a PMC or key constant, an exception will be thrown. If it does not exist, the
877 table will be extended.
879 =item * C<int get_type(int)>
881 Returns an integer value denoting the type of the constant at the specified
882 index. Possible values are:
884 +--------+-----------------------------------------------------------------+
885 | Value | Constant Type |
886 +--------+-----------------------------------------------------------------+
887 | 0x00 | No Constant |
888 +--------+-----------------------------------------------------------------+
889 | 0x6E | Number Constant |
890 +--------+-----------------------------------------------------------------+
891 | 0x73 | String Constant |
892 +--------+-----------------------------------------------------------------+
893 | 0x70 | PMC Constant |
894 +--------+-----------------------------------------------------------------+
895 | 0x6B | Key Constant |
896 +--------+-----------------------------------------------------------------+
898 =back
900 =head4 PackfileFixupTable.pmc (isa PackfileSegment)
902 This PMC provides a keyed integer interface to the fixup table. Each entry in
903 the table is represented by a PackfileFixupEntry PMC. It implements the
904 following methods:
906 =over 4
908 =item * C<get_iter> (vtable)
910 Returns iterator for stored fixup entries.
912 =item * C<elements> (vtable)
914 Gets the number of entries in the fixup table.
916 =item * C<get_pmc_keyed_int> (vtable)
918 Gets a PackfileFixupEntry PMC for the fixup entry at the position given in
919 the key. If the index is out of range, an exception will be thrown.
921 =item * C<set_pmc_keyed_int> (vtable)
923 Used to add a PackfileFixupEntry PMC to the fixups table or to replace an
924 existing one. If the PMC that is supplied is not of type PackfileFixupEntry,
925 an exception will thrown.
927 =back
929 =head4 PackfileFixupEntry.pmc
931 This PMC represents an entry in the fixup table. It implements the following
932 methods.
934 =over 4
936 =item * C<get_string> (vtable)
938 Gets the label field of the fixup entry.
940 =item * C<set_string_native> (vtable)
942 Sets the label field of the fixup entry.
944 =item * C<get_integer> (vtable)
946 Gets the offset field of the fixup entry.
948 =item * C<set_integer_native> (vtable)
950 Sets the offset field of the fixup entry.
952 =item * C<int get_type()>
954 Gets the type of the fixup entry. See the entries table for possible fixup
955 types.
957 =item * C<set_type(int)>
959 Sets the type of the fixup entry. See the entries table for possible fixup
960 types. Specifying an invalid type will result in an exception.
962 =back
964 =head4 PackfileAnnotations.pmc (isa PackfileSegment)
966 This PMC represents the bytecode annotations table. The following methods are
967 implemented:
969 =over 4
971 =item * C<elements> (vtable)
973 Gets the number of annotations in the table.
975 =item * C<get_iter> (vtable)
977 Get iterator for stored annotations.
979 =item * C<get_pmc_keyed_int> (vtable)
981 Gets the annotation at the specified index. If there is no annotation at that
982 index, an exception will be thrown. The PMC that is returned will always be a
983 PackfileAnnotation PMC.
985 =item * C<set_pmc_keyed_int> (vtable)
987 Sets the annotation at the specified index. If there is no annotation at that
988 index, it is added to the list of annotations. An exception will be thrown
989 unless all of the following conditions are met:
991 =over 4
993 =item - The type of the PMC passed is PackfileAnnotation
995 =item - The entry at the previous index is defined
997 =item - The offset of the previous entry is less than this entry
999 =item - The offset of the next entry, if it exists, is greater than this entry
1001 =back
1003 =back
1005 =head4 PackfileAnnotation.pmc
1007 This PMC represents an individual bytecode annotation entry in the annotations
1008 segment. It implements the following methods:
1010 =over 4
1012 =item * C<int get_offset()>
1014 Gets the offset into the bytecode of the instruction that is being annotated.
1016 =item * C<set_offset(int)>
1018 Sets the offset into the bytecode of the instruction that is being annotated.
1020 =item * C<int get_name()>
1022 Gets the name of the annotation.
1024 =item * C<int set_name()>
1026 Sets the name of the annotation.
1028 =item * C<get_integer> (vtable)
1030 Gets the integer value of the annotation.
1032 =item * C<set_integer> (vtable)
1034 Sets the integer value of the annotation.
1036 =item * C<get_string> (vtable)
1038 Gets the string value of the annotation.
1040 =item * C<set_string> (vtable)
1042 Sets the string value of the annotation.
1044 =item * C<get_number> (vtable)
1046 Gets the number value of the annotation.
1048 =item * C<set_number> (vtable)
1050 Sets the number value of the annotation.
1052 =back
1054 =head2 Language Notes
1056 None.
1058 =head2 Attachments
1060 None.
1062 =head2 Footnotes
1064 =head3 Changes From Previous Versions
1066 A number of things in this PDD differ from the older implementation,
1067 and few items with the more convenient PMC access are not yet implemented.
1068 This section details these changes from the old implementation
1069 and some of the reasoning behind them.
1071 =head4 Packfile Header
1073 The format of the packfile header changed completely, based upon a
1074 proposal at
1075 L<http://groups.google.com/group/perl.perl6.internals/browse_thread/thread/1f1af615edec7449/ebfdbb5180a9d813?lnk=gst>
1076 and the requirement to have a UUID. The old INT field in the previous header
1077 format is used nowhere in Parrot and was removed, the parrot patch version
1078 number along with the major and minor was added. The opcode type is also gone
1079 due to non-use. The opcode type is always long.
1081 The version number now reflects the earliest version of Parrot that is capable
1082 of running the bytecode file, to enable cross-version compatibility that will
1083 be needed in the future.
1086 =head4 Segment Header
1088 Having the type associated with the segment inside the VM is fine, but since
1089 it is in the directory segment anyway it seems odd to duplicate it here. Also
1090 removed the id (did not seem to be used anywhere) and the second size (always
1091 computable by knowing the size of this header, so it appears redundant).
1094 =head4 Fixup Segment
1096 We need to support unicode sub names, so fixup labels should be an index into
1097 the constants table to the relevant string instead of just a C string as they
1098 are now.
1101 =head4 Annotations Segment
1103 This is new and replaces and builds upon the debug segment. See here for some
1104 on-list discussion:
1106 L<http://groups.google.com/group/perl.perl6.internals/browse_thread/thread/b0d36dafb42d96c4/4d6ad2ad2243e677?lnk=gst&rnum=2#4d6ad2ad2243e677>
1109 =head4 Packfile PMCs
1111 This idea will see packfiles and segments within them being represented by
1112 PMCs, easing memory management and providing an interface to packfiles for
1113 Parrot programs.
1115 Here are mailing list comments that provide one of the motivations or hints
1116 of the original proposal.
1118 L<http://groups.google.com/group/perl.perl6.internals/browse_thread/thread/778ea0ac4c8676f7/b249306b543b040a?lnk=gst&q=packfile+PMCs&rnum=2#b249306b543b040a>
1120 =head2 References
1122 None.
1124 =cut
1126 __END__
1127 Local Variables:
1128 fill-column:78
1129 End:
1130 vim: expandtab shiftwidth=4: