Macintosh-Tools
/
tbxi
mirror of https://github.com/elliotnunn/tbxi.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Improve the comment

This commit is contained in:
Elliot Nunn 2019-08-04 21:06:50 +08:00
parent 9c2c17fed8
commit 5db5af4804
1 changed files with 38 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
tbxi/parcels_dump.py
View File

@ -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: <tab> type [flags=N] [name=STR] [src=PATH[.lzss]] [deduplicate=1]
# Inline data: <tab><tab> 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()