| blob | 6c17bd51bf43c739bc497d8ac680c638d70f94a3 |
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 field is not implemented yet and is set to 0.
394 =item * PMC Constants
396 PMCs that can be saved in packfiles as constants implement the freeze and thaw
397 vtable functions. Their frozen data is placed in a string, stored in the same
398 format as a string constant.
400 =item * Key Constants
402 Key constants are made up a number of components, where one component is a
403 "dimension" in the key. The number of components in the key is stored at the
404 start of the constant.
406 +--------+--------+--------------------------------------------------------+
407 | Offset | Length | Description |
408 +--------+--------+--------------------------------------------------------+
409 | 1 | 1 | Number of key components that follow. |
410 +--------+--------+--------------------------------------------------------+
412 Following this are C<n> entries of two words each that specify the key's
413 type and value. The key value may be a register or another constant, but not
414 another key constant. All constants other than integer constants are indexes
415 into the constants table.
417 +--------+--------+--------------------------------------------------------+
418 | Offset | Length | Description |
419 +--------+--------+--------------------------------------------------------+
420 | 0 | 1 | Type of the key. Must be one of: |
421 | | | 0x00 - Integer register |
422 | | | 0x01 - String register |
423 | | | 0x02 - PMC register |
424 | | | 0x03 - Number register |
425 | | | 0x10 - Integer constant |
426 | | | 0x11 - String constant (constant table index) |
427 | | | 0x12 - PMC constant (constant table index) |
428 | | | 0x13 - Number constant (constant table index) |
429 +--------+--------+--------------------------------------------------------+
430 | 1 | 1 | Value of the key. |
431 +--------+--------+--------------------------------------------------------+
433 =back
435 =head4 Fixup Segment
437 The fixup segment maps names of subs to offsets in the bytecode stream.
439 The number of fixup table entries, n, is given by the last field of the
440 segment header.
442 This is followed by n fixup table entries, of variable length, that take the
443 following form.
445 +--------+--------+--------------------------------------------------------+
446 | Offset | Length | Description |
447 +--------+--------+--------------------------------------------------------+
448 | 0 | 1 | Type of the fixup. Must be: |
449 | | | 0x01 - Subroutine fixup constant string |
450 | | | 0x02 - Subroutine fixup ascii string |
451 +--------+--------+--------------------------------------------------------+
452 | 1 | - | The label that is being fixed up. A string constant, |
453 | | | stored as an index into the constants table in the 01 |
454 | | | case, a NULL terminated ASCII string padded to word |
455 | | | length with zeroes in the 02. |
456 +--------+--------+--------------------------------------------------------+
457 | - | 1 | This is an index into the constants table for the sub |
458 | | | PMC corresponding to the label. |
459 +--------+--------+--------------------------------------------------------+
462 =head4 PIR Debug Segment
464 This segment stores the filenames and line numbers of PIR code that was
465 compiled to bytecode. The segment comes in two parts.
467 =over 4
469 =item A list of mappings between instructions in the bytecode and line
470 numbers, with one entry per instruction
472 =item A list of mappings between offsets in the bytecode and filenames,
473 indicating that the bytecode from that point on until the next entry was
474 generated from the PIR found in the given filename
476 =back
478 The length of the table of line number mappings is given by the last field
479 of the segment header.
481 Then comes the table:
483 +--------+--------+--------------------------------------------------------+
484 | Offset | Length | Description |
485 +--------+--------+--------------------------------------------------------+
486 | 0 | 1 | Line number for the offset in the bytecode. |
487 +--------+--------+--------------------------------------------------------+
489 Then comes an opcode with n, the number of file mappings.
491 Then come n mappings.
493 +--------+--------+--------------------------------------------------------+
494 | Offset | Length | Description |
495 +--------+--------+--------------------------------------------------------+
496 | 0 | 1 | Offset in the bytecode. |
497 +--------+--------+--------------------------------------------------------+
498 | 1 | 1 | A string constant holding the filename, stored as an |
499 | | | index into the constants table. |
500 +--------+--------+--------------------------------------------------------+
503 =head4 Annotations Segment
505 Annotations allow any instruction in the bytecode stream to have zero or more
506 key/value pairs associated with it. These can be retrieved at runtime. High
507 level languages can use annotations to store file names, line numbers, column
508 numbers and any other data, for debug purposes or otherwise, that they need.
510 The segment comes in three parts:
512 =over 4
514 =item A list of annotation keys (for example, "line" and "file").
516 =item An annotation groups table, used to group together annotations for a
517 particular HLL source file (an annotation group starting clears all active
518 annotations, so they will not spill over between source files; it also
519 allows for faster lookup of annotations).
521 {{ TODO: Does it clear all annotations, or all annotation groups? }}
523 =item A list of indexes into the bytecode stream and key/value pairings (for
524 example, starting at instruction 235, the annotation "line" has value "42").
526 =back
528 The last field of the segment header is not used.
530 The first word in the segment supplies the number of keys.
532 +--------+--------+--------------------------------------------------------+
533 | Offset | Length | Description |
534 +--------+--------+--------------------------------------------------------+
535 | 1 | 1 | Number of annotation key entries that follow. |
536 | | | n |
537 +--------+--------+--------------------------------------------------------+
539 Following this are C<n> annotation key entries. There is one entry per key
540 (such as "line" or "file"), but the bytecode may be annotated many times
541 with that key. Key entries take the following format.
543 +--------+--------+--------------------------------------------------------+
544 | Offset | Length | Description |
545 +--------+--------+--------------------------------------------------------+
546 | 0 | 1 | Index into the constants table of a string containing |
547 | | | the name of the key. |
548 +--------+--------+--------------------------------------------------------+
549 | 1 | 1 | The type of value that is stored with the key. |
550 | | | 0x00 - Integer |
551 | | | 0x01 - String Constant |
552 | | | 0x02 - Number Constant |
553 | | | 0x03 - PMC Constant |
554 +--------+--------+--------------------------------------------------------+
556 The annotation groups table comes next. This starts with a single integer to
557 specify the number of entries in the table.
559 +--------+--------+--------------------------------------------------------+
560 | Offset | Length | Description |
561 +--------+--------+--------------------------------------------------------+
562 | 1 | 1 | Number of annotation group entries that follow. |
563 +--------+--------+--------------------------------------------------------+
565 A group entry maps an offset in the bytecode segment to an offset in the list
566 of annotations (that is, offset 0 refers to the first word following this
567 table). The list of offsets into the bytecode segment (and by the definition
568 of this segment, the offsets into the annotations list) must be in ascending
569 order.
571 +--------+--------+--------------------------------------------------------+
572 | Offset | Length | Description |
573 +--------+--------+--------------------------------------------------------+
574 | 0 | 1 | Offset into the bytecode segment where the |
575 | | | instructions for a particular high level source file |
576 | | | start. |
577 +--------+--------+--------------------------------------------------------+
578 | 1 | 1 | Offset into the annotations list specifying where the |
579 | | | annotations for the given instruction start. |
580 +--------+--------+--------------------------------------------------------+
582 The rest of the segment is made up of a sequence of bytecode offset to key and
583 value mappings. First comes the number of them that follow:
585 +--------+--------+--------------------------------------------------------+
586 | Offset | Length | Description |
587 +--------+--------+--------------------------------------------------------+
588 | 1 | 1 | Number of bytecode to keypair mappings that follow. |
589 | | | n |
590 +--------+--------+--------------------------------------------------------+
592 Then there are n entries of the following format:
594 +--------+--------+--------------------------------------------------------+
595 | Offset | Length | Description |
596 +--------+--------+--------------------------------------------------------+
597 | 0 | 1 | Offset into the bytecode segment, in words, of the |
598 | | | instruction being annotated. At runtime, this will |
599 | | | correspond to the program counter. |
600 +--------+--------+--------------------------------------------------------+
601 | 1 | 1 | The key of the annotation, specified as an index into |
602 | | | the zero-based list of keys specified in the first |
603 | | | part of the segment. That is, if key "line" was the |
604 | | | first entry and "file" the second, they would have |
605 | | | indices 0 and 1 respectively. |
606 +--------+--------+--------------------------------------------------------+
607 | 2 | 2 | The value of the annotation. If the annotation type |
608 | | | (specified with the key) is an integer, the value is |
609 | | | placed directly into this word. Otherwise, an index |
610 | | | into the constants table is used. |
611 +--------+--------+--------------------------------------------------------+
613 Note that the value of an annotation with a particular key is taken to apply
614 to all following instructions up to the point of a new value being specified
615 for that key with another annotation. This means that if 20 instructions make
616 up the compiled form of a single line of code, only one line annotation is
617 required. Note that this also implies that annotations must be placed in
618 the same order as the instructions.
620 =head3 Packfile PMCs
622 A packfile can be represented in memory by Parrot as a tree of PMCs. These
623 provide a programmatic way to construct and walk packfiles, both for the
624 Parrot internals and from programs running on the Parrot VM.
626 {{ TODO... ManagedStruct and UnmanagedStruct may be helpful for these;
627 consider switching these PMCs over to use them at some point. }}
630 =head4 Packfile.pmc
632 This PMC represents the packfile overall. It will be constructed by the VM
633 when reading a packfile. It implements the following methods and vtable
634 functions.
636 =over 4
638 =item * C<get_string> (vtable)
640 Serializes this packfile data structure into a bytestream ready to be written
641 to disk (that is, maps from PMCs to on-disk representation).
643 =item * C<set_string_native> (vtable)
645 Takes a string containing an entire packfile in the on-disk format, attempts
646 to unpack it into a tree of Packfile PMCs and sets this Packfile PMC to
647 represent the top of that tree (that is, maps from on-disk representation to a
648 tree of PMCs).
650 =item * C<get_integer_keyed_str> (vtable)
652 Used to get data about fields in the header that have an integer value. Valid
653 keys are:
655 =over 4
657 =item wordsize
659 =item byteorder
661 =item fptype
663 =item version_major
665 =item version_minor
667 =item version_patch
669 =item bytecode_major
671 =item bytecode_minor
673 =item uuid_type
675 =back
677 =item * C<get_string_keyed_str> (vtable)
679 Used to get data about fields in the header that have a string value. Valid
680 keys are:
682 =over 4
684 =item uuid
686 =back
688 =item * C<set_integer_keyed_str> (vtable)
690 Used to set fields in the packfile header. Some fields are not allowed to be
691 written since they are determined by the VM when serializing the packfile for
692 storage on disk. The fields that may be set are:
694 =over 4
696 =item version_major
698 =item version_minor
700 =item version_patch
702 =item uuid_type
704 =back
706 Be very careful when setting a version number; you should usually trust the VM
707 to do the right thing with this.
709 Setting the uuid_type will not result in immediate re-computation of the
710 UUID, but rather will only cause it to be computed using the selected
711 algorithm when the packfile is serialized (by calling the C<get_string>
712 vtable function). Setting an invalid uuid_type value will cause an exception
713 to be thrown immediately.
715 =item * C<get_directory()>
717 Returns the PackfileDirectory PMC that represents the directory segment at the
718 start of the packfile.
720 =back
722 =head4 PackfileSegment.pmc
724 An abstract PMC that is the base class for all other segments. It has two
725 abstract methods, which are to be implemented by all subclasses. They will not
726 be listed under the method list for other segment PMCs to save space.
728 =over 4
730 =item * C<STRING* pack()>
732 Packs the segment into the on-disk format and returns a string holding it.
734 =item * C<unpack(STRING*)>
736 Takes the packed representation for a segment of the given type and then
737 unpacks it, setting this PMC to represent that segment as a result of the
738 unpacking. If an error occurs during the unpacking process, an exception will
739 be thrown.
741 =back
743 =head4 PackfileDirectory.pmc (isa PackfileSegment)
745 This PMC represents a directory segment. Essentially it is an hash of
746 PackfileSegment PMCs. It implements the following methods:
748 =over 4
750 =item * C<elements> (vtable)
752 Gets the number of segments listed in the directory.
754 =item * C<get_pmc_keyed_str> (vtable)
756 Searches the directory for a segment with the given name and, if one exists,
757 returns a PackfileSegment PMC (or one of its subclasses) representing it.
759 =item * C<set_pmc_keyed_str> (vtable)
761 Adds a PackfileSegment PMC (or a subclass of it) to the directory with the
762 name specified by the key. This is the only way to add another segment to the
763 directory. If a segment of the given name already exists in the directory, it
764 will be replaced with the supplied PMC.
766 =item * C<delete_keyed_str> (vtable)
768 Removes the PackfileSegment PMC from the directory which has the name
769 specified by the key. This is the only way to remove a segment from the
770 directory.
772 =item * C<get_iter> (vtable)
774 Returns iterator for existing keys.
776 =back
778 =head4 PackfileRawSegment.pmc (isa PackfileSegment)
780 This PMC presents a segment of a packfile as an array of integers. This is the
781 lowest possible level of access to a segment, and covers both the default and
782 bytecode segment types. It implements the following methods:
784 =over 4
786 =item * C<get_type>
788 Get type of PackfileRawSegment.
790 =item * C<set_type>
792 Set type of PackfileRawSegment.
794 =item * C<get_iter>
796 Returns iterator for Segment.
798 =item * C<get_integer_keyed_int> (vtable)
800 Reads the integer at the specified offset into the segment, excluding the data
801 in the common segment header but including the data making up additional
802 fields in the header for a specific type of segment.
804 =item * C<set_integer_keyed_int> (vtable)
806 Stores an integer at the specified offset into the segment. Will throw an
807 exception if the segment is memory mapped.
809 =item * C<elements> (vtable)
811 Gets the length of the segment in words, excluding the length of the common
812 segment but including the data making up additional fields in the header for a
813 specific type of segment.
815 =back
817 =head4 PackfileConstantTable.pmc (isa PackfileSegment)
819 This PMC represents a constants table. It provides access to constants through
820 the keyed integer interface (the interpreter may choose to access underlying
821 structures directly to improve performance, however).
823 The table of constants can be added to using the keyed set methods; it will
824 grow automatically.
826 The PMC implements the following methods:
828 =over 4
830 =item * C<get_iter>
832 Returns iterator for stored Constants.
834 =item * C<elements> (vtable)
836 Gets the number of constants contained in the table.
838 =item * C<get_number_keyed_int> (vtable)
840 Gets the value of the number constant at the specified index in the constants
841 table. If the constant at that position in the table is not a number, an
842 exception will be thrown.
844 =item * C<get_string_keyed_int> (vtable)
846 Gets the value of the string constant at the specified index in the constants
847 table. If the constant at that position in the table is not a string, an
848 exception will be thrown.
850 =item * C<get_pmc_keyed_int> (vtable)
852 Gets the value of the PMC or key constant at the specified index in the
853 constants table. If the constant at that position in the table is not a PMC
854 or key, an exception will be thrown.
856 =item * C<set_number_keyed_int> (vtable)
858 Sets the value of the number constant at the specified index in the constants
859 table. If the constant at that position in the table is not already a number
860 constant, an exception will be thrown. If it does not exist, the table will be
861 extended.
863 =item * C<set_string_keyed_int> (vtable)
865 Sets the value of the string constant at the specified index in the constants
866 table. If the constant at that position in the table is not already a string
867 constant, an exception will be thrown. If it does not exist, the table will be
868 extended.
870 =item * C<set_pmc_keyed_int> (vtable)
872 Sets the value of the PMC or key constant at the specified index in the
873 constants table. If the constant at that position in the table is not already
874 a PMC or key constant, an exception will be thrown. If it does not exist, the
875 table will be extended.
877 =item * C<int get_type(int)>
879 Returns an integer value denoting the type of the constant at the specified
880 index. Possible values are:
882 +--------+-----------------------------------------------------------------+
883 | Value | Constant Type |
884 +--------+-----------------------------------------------------------------+
885 | 0x00 | No Constant |
886 +--------+-----------------------------------------------------------------+
887 | 0x6E | Number Constant |
888 +--------+-----------------------------------------------------------------+
889 | 0x73 | String Constant |
890 +--------+-----------------------------------------------------------------+
891 | 0x70 | PMC Constant |
892 +--------+-----------------------------------------------------------------+
893 | 0x6B | Key Constant |
894 +--------+-----------------------------------------------------------------+
896 =back
898 =head4 PackfileFixupTable.pmc (isa PackfileSegment)
900 This PMC provides a keyed integer interface to the fixup table. Each entry in
901 the table is represented by a PackfileFixupEntry PMC. It implements the
902 following methods:
904 =over 4
906 =item * C<get_iter> (vtable)
908 Returns iterator for stored fixup entries.
910 =item * C<elements> (vtable)
912 Gets the number of entries in the fixup table.
914 =item * C<get_pmc_keyed_int> (vtable)
916 Gets a PackfileFixupEntry PMC for the fixup entry at the position given in
917 the key. If the index is out of range, an exception will be thrown.
919 =item * C<set_pmc_keyed_int> (vtable)
921 Used to add a PackfileFixupEntry PMC to the fixups table or to replace an
922 existing one. If the PMC that is supplied is not of type PackfileFixupEntry,
923 an exception will thrown.
925 =back
927 =head4 PackfileFixupEntry.pmc
929 This PMC represents an entry in the fixup table. It implements the following
930 methods.
932 =over 4
934 =item * C<get_string> (vtable)
936 Gets the label field of the fixup entry.
938 =item * C<set_string_native> (vtable)
940 Sets the label field of the fixup entry.
942 =item * C<get_integer> (vtable)
944 Gets the offset field of the fixup entry.
946 =item * C<set_integer_native> (vtable)
948 Sets the offset field of the fixup entry.
950 =item * C<int get_type()>
952 Gets the type of the fixup entry. See the entries table for possible fixup
953 types.
955 =item * C<set_type(int)>
957 Sets the type of the fixup entry. See the entries table for possible fixup
958 types. Specifying an invalid type will result in an exception.
960 =back
962 =head4 PackfileAnnotations.pmc (isa PackfileSegment)
964 This PMC represents the bytecode annotations table. The following methods are
965 implemented:
967 =over 4
969 =item * C<elements> (vtable)
971 Gets the number of annotations in the table.
973 =item * C<get_iter> (vtable)
975 Get iterator for stored annotations.
977 =item * C<get_pmc_keyed_int> (vtable)
979 Gets the annotation at the specified index. If there is no annotation at that
980 index, an exception will be thrown. The PMC that is returned will always be a
981 PackfileAnnotation PMC.
983 =item * C<set_pmc_keyed_int> (vtable)
985 Sets the annotation at the specified index. If there is no annotation at that
986 index, it is added to the list of annotations. An exception will be thrown
987 unless all of the following conditions are met:
989 =over 4
991 =item - The type of the PMC passed is PackfileAnnotation
993 =item - The entry at the previous index is defined
995 =item - The offset of the previous entry is less than this entry
997 =item - The offset of the next entry, if it exists, is greater than this entry
999 =back
1001 =back
1003 =head4 PackfileAnnotation.pmc
1005 This PMC represents an individual bytecode annotation entry in the annotations
1006 segment. It implements the following methods:
1008 =over 4
1010 =item * C<int get_offset()>
1012 Gets the offset into the bytecode of the instruction that is being annotated.
1014 =item * C<set_offset(int)>
1016 Sets the offset into the bytecode of the instruction that is being annotated.
1018 =item * C<int get_name()>
1020 Gets the name of the annotation.
1022 =item * C<int set_name()>
1024 Sets the name of the annotation.
1026 =item * C<get_integer> (vtable)
1028 Gets the integer value of the annotation.
1030 =item * C<set_integer> (vtable)
1032 Sets the integer value of the annotation.
1034 =item * C<get_string> (vtable)
1036 Gets the string value of the annotation.
1038 =item * C<set_string> (vtable)
1040 Sets the string value of the annotation.
1042 =item * C<get_number> (vtable)
1044 Gets the number value of the annotation.
1046 =item * C<set_number> (vtable)
1048 Sets the number value of the annotation.
1050 =back
1052 =head2 Language Notes
1054 None.
1056 =head2 Attachments
1058 None.
1060 =head2 Footnotes
1062 =head3 Changes From Previous Versions
1064 A number of things in this PDD differ from the older implementation,
1065 and few items with the more convenient PMC access are not yet implemented.
1066 This section details these changes from the old implementation
1067 and some of the reasoning behind them.
1069 =head4 Packfile Header
1071 The format of the packfile header changed completely, based upon a
1072 proposal at
1073 L<http://groups.google.com/group/perl.perl6.internals/browse_thread/thread/1f1af615edec7449/ebfdbb5180a9d813?lnk=gst>
1074 and the requirement to have a UUID. The old INT field in the previous header
1075 format is used nowhere in Parrot and was removed, the parrot patch version
1076 number along with the major and minor was added. The opcode type is also gone
1077 due to non-use. The opcode type is always long.
1079 The version number now reflects the earliest version of Parrot that is capable
1080 of running the bytecode file, to enable cross-version compatibility that will
1081 be needed in the future.
1084 =head4 Segment Header
1086 Having the type associated with the segment inside the VM is fine, but since
1087 it is in the directory segment anyway it seems odd to duplicate it here. Also
1088 removed the id (did not seem to be used anywhere) and the second size (always
1089 computable by knowing the size of this header, so it appears redundant).
1092 =head4 Fixup Segment
1094 We need to support unicode sub names, so fixup labels should be an index into
1095 the constants table to the relevant string instead of just a C string as they
1096 are now.
1099 =head4 Annotations Segment
1101 This is new and replaces and builds upon the debug segment. See here for some
1102 on-list discussion:
1104 L<http://groups.google.com/group/perl.perl6.internals/browse_thread/thread/b0d36dafb42d96c4/4d6ad2ad2243e677?lnk=gst&rnum=2#4d6ad2ad2243e677>
1107 =head4 Packfile PMCs
1109 This idea will see packfiles and segments within them being represented by
1110 PMCs, easing memory management and providing an interface to packfiles for
1111 Parrot programs.
1113 Here are mailing list comments that provide one of the motivations or hints
1114 of the original proposal.
1116 L<http://groups.google.com/group/perl.perl6.internals/browse_thread/thread/778ea0ac4c8676f7/b249306b543b040a?lnk=gst&q=packfile+PMCs&rnum=2#b249306b543b040a>
1118 =head2 References
1120 None.
1122 =cut
1124 __END__
1125 Local Variables:
1126 fill-column:78
1127 End:
1128 vim: expandtab shiftwidth=4: