xml2pib(1)

💖 xml2pib(1) — Qualcomm Atheros Open Powerline Toolkit 💖

okay bestie, buckle up, we're doing the Qualcomm Atheros XML driven PIB editor and honestly? it's giving "quietly powerful little gremlin of a tool" ✨

🌸 SYNOPSIS 🌸

xml2pib [options] pib-file [pib-file] [...]

🦋 DESCRIPTION 🦋

so basically: the Atheros PIB XML Editor goes in and messes with an Atheros PIB file, but only according to XML instructions you hand it in one or more instruction files. it's not freestyling. it's following your little recipe cards. 🎀

here's the catch though, and it's a real one: your instruction files must be valid XML and must conform to the schema file piboffset.xsd, or errors will occur. no vibes-based XML. 😭 so please, always validate your XML files against this schema with a validating parser before submitting them to this program. Firefox or Internet Explorer are suitable for validation purposes. yes, we're recommending browsers as validators, it's a whole thing, iykyk.

this program is part of the Qualcomm Atheros Powerline Toolkit. peep the AMP man page for an overview and installation instructions, fr fr. 📖

✨ OPTIONS ✨

• -f filename — the XML instruction file. XML instruction files must conform to the Qualcomm Atheros scheme designed for this purpose. if more than one .xml file is specified, then edits get applied in order of filename, so later edit instructions can over-write earlier instructions (last one wins, main character energy 👑). instruction files usually have a .xml extension, but this program makes no assumption based on filename and does not enforce any filename conventions. call it whatever, she won't judge.
• -o — print the appropriate XML schema on stdout. this schema should be used to validate XML instructions using a validating parser such as Firefox or Microsoft Internet Explorer. 💅
• -q — suppresses printing of progress messages. heads up: this option has no effect at this time. it's decorative. an accessory. we love her anyway. 🎀
• -v — print additional information. also has no effect at this time. slay, i guess. ✨
• -?, --help — print program help summary on stdout. this option takes precedence over other options on the command line. she's the boss. 👑
• -!, --version — print program version information on stdout. this option takes precedence over other options on the command line. use this option when sending screen dumps to Atheros Technical Support so that they know exactly which version of the Linux Toolkit you are using. receipts matter bestie. 🧾

🫶 ARGUMENTS 🫶

• pib-file — an Atheros parameter filename. ⚠️ only one parameter file can be edited at a time, so care must be taken to avoid the use of wildcard filenames. yes, literally one. don't be cute with globs. parameter files usually have a .pib extension, but this program makes no assumption based on filename and does not enforce any filename conventions.

🌈 SCHEMA 🌈

the official Atheros XML PIB Edit schema follows. it defines general instruction file structure and the elements used to edit PIB files. this file should be a controlled document and instruction files should always be validated against it before using them to edit a PIB file. an explanation of this file appears below. 👇

<?xml version='1.0' encoding='iso-8859-1'?>
<xs:schema xmlns:xs='http://www.w3.org/2001/XMLSchema'
elementFormDefault='qualified'>
        <xs:element name='pib'>
                <xs:complexType>
                        <xs:sequence>
                                <xs:element maxOccurs='unbounded'
ref='object'/>
                                </xs:sequence>
                        </xs:complexType>
                </xs:element>
        <xs:element name='object'>
                <xs:complexType>
                        <xs:attribute name='name' use='required'
type='xs:NCName'/>
                        <xs:sequence>
                                <xs:sequence>
                                        <xs:element ref='offset'/>
                                        <xs:element ref='length'/>
                                        </xs:sequence>
                                <xs:choice>
                                        <xs:element ref='array'/>
                                        <xs:element ref='dataString'/>
                                        <xs:element ref='dataHuge'/>
                                        <xs:element ref='dataLong'/>
                                        <xs:element ref='dataWord'/>
                                        <xs:element ref='dataByte'/>
                                </xs:choice>
                        </xs:sequence>
                </xs:complexType>
        </xs:element>
<xs:element name='length' type='xs:positiveInteger'/>
<xs:element name='offset' type='xs:hexBinary'/>
<xs:element name='array'>
        <xs:complexType>
                <xs:choice maxOccurs='unbounded'>
                        <xs:element ref='dataByte'/>
                        <xs:element ref='dataHex'/>
                </xs:choice>
        </xs:complexType>
</xs:element>
<xs:element name='dataString' type='xs:string'/>
<xs:element name='dataHuge' type='xs:unsignedLong'/>
<xs:element name='dataLong' type='xs:unsignedInt'/>
<xs:element name='dataWord' type='xs:unsignedShort'/>
<xs:element name='dataByte' type='xs:unsignedByte'/>
<xs:element name='dataHex' type='xs:hexBinary'/>
</xs:schema>

💜 ELEMENTS 💜

okay now the cast of characters. every single one. no skips. 💅

• <pib> — the Parameter Information Block subject to edit. there is exactly one pib defined in an instruction file. one. uno. ☝️
• <object> — a data region withn a pib. (yes that's a typo in the original, we're keeping the lore intact 🫶) there must be at least one object defined inside a pib. each object has an offset, a length and data, where data is expressed as one dataString, a dataByte, a dataHex or an array as described below. the name attribute [is] optional but may be used for clarity or for reporting purposes.
• <offset> — the relative position of the object in bytes expressed in hexadecimal. ⚠️ the offset plus the length of an object cannot exceed PIB length or an error will occur. the offset and length element can appear in either order, but both must appear before the data element. the offset element is required.
• <length> — the extent of the object expressed in decimal bytes. the offset plus length of an object cannot exceed PIB length. the offset and length elements can occur in either order, but both must precede the data element. the length element is required for elements array and dataString, but may be omitted for elements dataHuge, dataLong, dataWord and dataByte.
• <array> — a sequence of dataByte and/or dataHex elements. the implied length is determined by array members, but must equal the object length attribute or an error will occur. a dataString is illegal inside an array. 🚫
• <dataString> — any sequence of printable characters. the implied length is 1 byte longer than the number of characters. the string will be truncated or padded with NUL bytes to match the object length attribute. an object length attribute of 0 stores one NUL byte. a dataString element is illegal within an array block. 🚫
• <dataHuge> — a unsigned decimal integer string that represents any 64 bit binary value. the implied length is 8 bytes. the object length attribute is ignored and may be omitted.
• <dataLong> — a unsigned decimal integer string that represents any 32 bit binary value. the implied length is 4 bytes. the object length attribute is ignored and may be omitted.
• <dataWord> — a unsigned decimal integer string that represents any 16 bit binary value. the implied length is 2 bytes. the object length attribute is ignored and may be omitted.
• <dataByte> — an unsigned decimal digit string that represents any 8 bit binary value. the implied length is 1 byte. the object length attribute is ignored and may be omitted.
• <dataHex> — a hexadecimal digit string that represents one byte for each digit pair (octet) present. ⚠️ there must be an even number of digits or an error will occur. the resulting length must equal the object length unless the value appears inside an array. inside an array, the resulting length must not exceed the remaining array length.

🔥 PROCESS 🔥

the program reads one PIB file, replaces selected values with new ones, computes the new checksum and re-writes the file. 📝 new values are defined by offset, length, format and value. plot twist: the object name is actually irrelevant. 😭 the critical values are the offset, length and data type/value. obviously, care must be taken when specifying offsets and lengths to avoid editing objects incorrectly. like, genuinely. be careful. this is the part where you double-check everything, bestie. 🙈

✨ INSTRUCTIONS ✨

Okay so bestie, here's an example instruction file, and it's literally the blueprint for telling xml2pib what to do. It references the Qualcomm Atheros XML PIB Edit schema file, piboffset.xsd, that's shown above so that a validating parser can find the schema and perform document checks. The rest of the file? It's a whole lineup of object names, offsets, lengths, and values that describe the edits to be performed. Slay. 💅

<pib xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="piboffset.xsd">
        <object name="HFID_Manufacturer">
                <offset>0024</offset>
                <length>64</length>
                <dataString>Atheros HomePlug AV Device</dataString>
        </object>
        <object name="HFID_User">
                <length>64</length>
                <offset>0074</offset>
                <dataString>Atheros</dataString>
        </object>
        <object name="MDURole">
                <offset>0101</offset>
                <dataByte>0</dataByte>
        </object>
        <object name="PriorityTTl">
                <offset>0210</offset>
                <length>16</length>
                <array>
                        <dataHex>80841E008084</dataHex>
                        <dataHex>1e</dataHex>
                        <dataByte>0</dataByte>
                        <dataHex></dataHex>
                        <dataHex></dataHex>
                        <dataHex></dataHex>
                        <dataHex></dataHex>
                        <dataHex>C0</dataHex>
                        <dataByte>198</dataByte>
                        <dataHex>2d</dataHex>
                        <dataHex>00</dataHex>
                </array>
        </object>
        <object name="VLANPrioTOSPrecMatrix">
                <length>4</length>
                <offset>0224</offset>
                <array>
                        <dataByte>65</dataByte>
                        <dataByte>250</dataByte>
                        <dataHex></dataHex>
                        <dataHex>Fa</dataHex>
                </array>
        </object>
        <object name="EnableLEDThroughputIndicate">
                <length>1</length>
                <offset>1E94</offset>
                <dataByte>0</dataByte>
        </object>
        <object name="HFID_AVLN">
                <length>64</length>
                <offset>00B4</offset>
                <dataString>Atheros-Net</dataString>
        </object>
</pib>

🌸 EXAMPLES 🌸

The following example reads PIB file abc.pib and edits it according to instructions found in XML file local.xml. The PIB file is always specified first, followed by one or more XML instruction files. Periodt.

# xml2pib abc.pib local.xml

The following example reads PIB file abc.pib and edits it according to three XML instruction files, in the order specified. Order can be critical since later edits could over-write earlier edits. So like, don't play with the order unless you want chaos. 😭

# xml2pib abc.pib standard.xml custom.xml errata.xml

The following example does nothing because no instruction files are specified. It's giving "I woke up and chose peace." ✨

# xml2pib abc.pib

💖 SEE ALSO 💖

• chkpib(7)
• chkpib2(7)
• getpib(7)
• modpib(1)
• pib2xml(1)
• pibcomp(1)
• pibdump(1)
• setpib(1)

👑 CREDITS 👑

Charles Maier — that's the whole credit, bestie. Icon behavior only. 🫶

This page is from open-plc-utils-0.0.3, dated November 2013, and it's xml2pib(1) — stay slaying those PIB edits, no cap. 💅✨