Author: jonathan Date: Thu Sep 28 15:55:52 2006 New Revision: 14785 Modified: trunk/docs/pdds/clip/pdd13_bytecode.pod
Log: Add most of the changes resulting from discussion with Allison. Modified: trunk/docs/pdds/clip/pdd13_bytecode.pod ============================================================================== --- trunk/docs/pdds/clip/pdd13_bytecode.pod (original) +++ trunk/docs/pdds/clip/pdd13_bytecode.pod Thu Sep 28 15:55:52 2006 @@ -145,58 +145,43 @@ | | | 0x00 - IEEE 754 8 byte double | | | | 0x01 - i386 little endian 12 byte long double | +--------+--------+--------------------------------------------------------+ - | 11 | 1 | Major version number of the earliest version of Parrot | - | | | that should be able to run this file. For example, if | - | | | Parrot 0.9.5 was the first Parrot that was able to | - | | | run this bytecode file properly, this byte would | - | | | have the value 0. | - +--------+--------+--------------------------------------------------------+ - | 12 | 1 | Minor version number of the earliest version of Parrot | - | | | that should be able to run this file. For example, if | - | | | Parrot 0.9.5 was the first Parrot that was able to | - | | | run this bytecode file properly, this byte would | - | | | have the value 9. | - +--------+--------+--------------------------------------------------------+ - | 13 | 1 | Patch version number of the earliest version of Parrot | - | | | that should be able to run this file. For example, if | - | | | Parrot 0.9.5 was the first Parrot that was able to | - | | | run this bytecode file properly, this byte would | - | | | have the value 5. | - +--------+--------+--------------------------------------------------------+ - | 14 | 10 | Opcode fingerprint. This stores the fingerprint of the | - | | | opcodes that the Parrot this packfile was written by | - | | | was built with. This enables detection of packfiles | - | | | that can not be run by the version of Parrot reading | - | | | the file. | - | | | | - | | | The fingerprint is computed by taking the MD5 hash of | - | | | the file PBC_COMPAT, a file in the Parrot repository | - | | | that is only updated when an incompatible change is | - | | | made to the Packfile format, for example renumbering | - | | | operation codes. | - | | | | - | | | This need only be checked when running a development | - | | | version of Parrot. Release versions should choose to | - | | | accept or decline a PBC file based only on the major, | - | | | minor and patch version numbers. | + | 11 | 1 | Major version number of the version of Parrot that | + | | | wrote this bytecode file. For example, if Parrot 0.9.5 | + | | | wrote it,this byte would have the value 0. | + +--------+--------+--------------------------------------------------------+ + | 12 | 1 | Minor version number of the version of Parrot that | + | | | wrote this bytecode file. For example, if Parrot 0.9.5 | + | | | wrote it,this byte would have the value 9. | + +--------+--------+--------------------------------------------------------+ + | 13 | 1 | Patch version number of the version of Parrot that | + | | | wrote this bytecode file. For example, if Parrot 0.9.5 | + | | | wrote it,this byte would have the value 5. | + +--------+--------+--------------------------------------------------------+ + | 14 | 1 | Major version number of the bytecode file format. See | + | | | the section below on bytecode file format version | + | | | numbers. | + +--------+--------+--------------------------------------------------------+ + | 15 | 1 | Minor version number of the bytecode file format. See | + | | | the section below on bytecode file format version | + | | | numbers. | +--------+--------+--------------------------------------------------------+ - | 24 | 1 | The type of the UUID associated with this packfile. | + | 16 | 1 | The type of the UUID associated with this packfile. | | | | Must be one of: | | | | 0x00 - No UUID | | | | 0x01 - MD5 | +--------+--------+--------------------------------------------------------+ - | 25 | 1 | Length of the UUID associated with this packfile. May | + | 17 | 1 | Length of the UUID associated with this packfile. May | | | | be zero if the type of the UUID is 0x00. Maximum | | | | value is 255. | +--------+--------+--------------------------------------------------------+ - | 26 | u | A UUID of u bytes in length, where u was specified as | + | 18 | u | A UUID of u bytes in length, where u was specified as | | | | the length of the UUID in the previous field. Be sure | | | | that UUIDs are stored and read as strings. The UUID is | | | | computed by applying the hash function specified in | | | | the UUID type field over the entire packfile not | | | | including this header and the trailing zero padding. | +--------+--------+--------------------------------------------------------+ - | 26 + u | n | Zero-padding to make the total header length a | + | 18 + u | n | Zero-padding to make the total header length a | | | | multiple of 16 bytes in length. | | | | n = u % 16 == 0 ? 0 : 16 - (u % 16) | +--------+--------+--------------------------------------------------------+ @@ -206,6 +191,33 @@ that is reading the PBC file do not match these, it needs to transform the words making up the rest of the packfile. +=head4 Bytecode File Version Numbers + +The bytecode file version number exists to decouple the format of the bytecode +file from the version of the Parrot implementation that is reading/writing it. +It has a major and a minor part. + +The major version number should be incremented whenever there is a change to +the layout of bytecode files. This includes new segments, changes to segment +headers or changes to the format of the data held within a segment. + +The minor version number should be incremented in all other cases when a +change is made that means a previous version of Parrot would not be able to +run the program encoded in the packfile. This is mostly opcode re-numbering or +the addition of new opcodes. + +{{ QUESTION: Should this also include changes to the core PMC types? }} + +A single version of Parrot can support reading and writing of more than one +bytecode file format. In fact, once Parrot is in production use it will be +preferable to write as early a bytecode format as is possible, to allow the +greatest compatibility with previous Parrots. + +These versions will be listed in the PBC_COMPAT file, sorted with the latest +version first. in the format: + +MAJOR.MINOR DATE DESCRIPTION + =head3 Directory Format Header @@ -305,7 +317,8 @@ The default segment has no additional headers. It will, if possible, be memory mapped. More than one may exist in the packfile, and they are identified by -name. +name. They may be used for storing any data that does not fit into any other +segment, for example the source code from a high level language. =head3 Bytecode Segment @@ -496,7 +509,9 @@ | | | n | +--------+--------+--------------------------------------------------------+ -Following this are n annotation key entries, which take the following format. +Following this are n annotation key entries. There is one entry per key (such +as "line" or "file"), but the bytecode may be annotated many times with that +key. Key entries take the following format. +--------+--------+--------------------------------------------------------+ | Offset | Length | Description | @@ -547,6 +562,9 @@ will provide a programatic way to construct and walk packfiles, both for the Parrot internals and from programs running on the Parrot VM. +{{ QUESTION: Will the CStruct PMC make it into Parrot? If so, we may want to +change the interface of these PMCs to take advantage of it. }} + =head3 Packfile.pmc @@ -577,6 +595,8 @@ =item version_major =item version_minor =item version_patch +=item bytecode_major +=item bytecode_minor =item uuid_type =item uuid_length =back @@ -587,7 +607,6 @@ keys are: =over 4 -=item opcodefingerprint =item uuid =back @@ -632,7 +651,8 @@ Takes the packed representation for a segment of the given type and then unpacks it, setting this PMC to represent that segment as a result of the -unpacking (provided it is successfully unpacked). +unpacking. If an error occurs during the unpacking process, an exception will +be thrown. =head3 PackfileDirectory.pmc (isa PackfileSegment) @@ -669,7 +689,7 @@ will be replaced with the supplied PMC. -=head3 DefaultSegment.pmc (isa PackfileSegment) +=head3 RawSegment.pmc (isa PackfileSegment) This PMC presents a segment of a packfile as an array of integers. This is the lowest possible level of access to a segment, and covers both the default and @@ -683,7 +703,8 @@ =head4 set_integer_keyed_int (v-table) -Stores an integer at the specified offset into the segment. +Stores an integer at the specified offset into the segment. Will throw an +exception if the segment is memory mapped. =head4 elements (v-table) @@ -943,3 +964,4 @@ Local Variables: fill-column:78 End: +