diff --git a/tbxi/parcels_dump.py b/tbxi/parcels_dump.py index bd51ba5..3e58743 100644 --- a/tbxi/parcels_dump.py +++ b/tbxi/parcels_dump.py @@ -11,45 +11,49 @@ from .lowlevel import PrclNodeStruct, PrclChildStruct HEADER_COMMENT = """ -# Automated dump of Toolbox Parcels +# Automated dump of Toolbox Parcels (magic number 'prcl') -# Parcels contain any number of children, with each containing binary data. -# no tabs = parcel: type [flags=N] [a=STR] [b=STR] -# 1 tab = child: type [flags=N] [name=STR] [src=PATH[.lzss]] [deduplicate=1] -# 2 tabs = inline data: STR (lines get null-terminated) +# Parcels contain metadata and binary blob 'children': +# Parcel: type [flags=N] [a=STR] [b=STR] +# Child: type [flags=N] [name=STR] [src=PATH[.lzss]] [deduplicate=1] +# Inline data: STR (lines get null-terminated) -# The Trampoline interprets each parcel according to its type: -# 'prop' => match and edit an existing device tree node -# 'node' => create a new 'special' device tree node -# 'rom ' => contains the 4 MB Power Mac ROM image -# 'psum' => guide the device tree checksum +# They have a four-byte type: +# 'prop': match and edit an existing dev tree node +# 'node': special numbered node to insert into dev tree +# 'rom ': Power Macintosh ROM image +# 'psum': black/whitelists for dev tree checksum calc -# Flag Applies to Meaning -# ----- ----------- --------------------------------------------- -# F0000 prcl, child mask of 'special' node number (to create or edit) -# 00200 prcl load node only if needed to access boot disk -# 00100 child use child only in debug mode -# 00080 child add prop to special node instead of parent -# 00040 child delete existing prop (vs create new prop) -# 00020 child do not replace prop if it already exists -# 00010 prcl, child use node/child only once in the device tree -# 00008 prcl match node iff ('device_type' prop == 'a' field) AND -# 00004 prcl ('compatible' prop array contains 'b' field OR -# 00002 prcl 'name' prop of parent == 'b' field OR -# 00001 prcl 'name' prop == 'b' field) -# (NB: Here 'node' and 'prop' refer to the device tree, not to parcel types.) +# Known 'flags' in parcel and child metadata: +# Flag Applies to Meaning +# ----- ----------- --------------------------------------------- +# F0000 prcl, child bitmask of special node number (to create or edit) +# 00200 prcl load node only if needed to access boot disk +# 00100 child prop implements optional 'EtherPrintfLib' debugging +# 00080 child add prop to special node instead of parent +# 00040 child delete existing prop (vs create new prop) +# 00020 child do not replace prop if it already exists +# 00010 prcl, child use node/child only once in the dev tree +# 00008 prcl match node iff ('device_type' prop == 'a' field) AND +# 00004 prcl ('compatible' prop array contains 'b' field OR +# 00002 prcl 'name' prop of parent == 'b' field OR +# 00001 prcl 'name' prop == 'b' field) +# (NB: Here 'node' and 'prop' refer to the dev tree, not to parcel types.) # Miscellany: -# - A child's type is unimportant. -# - A child's data can be specified using inline text, or a 'src' field, but not both. -# - Appending '.lzss' to a 'src' compresses the data at the base path. -# - The 'psum' parcel selects contributors to dev tree checksum, with children in this order: -# 1. property whitelist -# 2. node 'name' whitelist -# 3. node 'name' blacklist -# 4. node 'device-type' whitelist -# 5. node 'device-type' blacklist -# - Rebuilds are not byte-perfect because the original padding contains uninitialized data. +# - A child's type is unimportant. +# - A child's data can be read from a 'src' file or from inline data prefixed +# with 2 tabs, but not both. +# - Appending '.lzss' to a 'src' compresses the data at the base path. +# - The 'psum' parcel selects contributors to dev tree checksum, with 'csta' +# children in this order: +# 1. property whitelist +# 2. node 'name' whitelist +# 3. node 'name' blacklist +# 4. node 'device-type' whitelist +# 5. node 'device-type' blacklist +# - Rebuilds are not byte-perfect because the original padding contains +# uninitialized data. """.strip()