Provided by: plc-utils-extra_0.0.6+git20230504.1ba7d5a0-1_amd64 bug

NAME

       xml2pib - Qualcomm Atheros XML driven PIB editor

SYNOPSIS

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

DESCRIPTION

       The  Atheros PIB XML Editor modifies an Atheros PIB file based on XML instructions defined
       in one or more instruction files.  Instruction files must be  valid  XML  and  conform  to
       schema  file  piboffset.xsd  or errors will occur.  Always validate XML files against this
       schema with a validating parser before  submitting  them  to  this  program.   Firefox  or
       Internet Explorer are suitable for validation purposes purpose.

       This  program is part of the Qualcomm Atheros Powerline Toolkit.  See the AMP man page for
       an overview and installation instructions.

OPTIONS

       -f filename
              The XML instruction file.  XML instruction  files  must  conform  to  the  Qualcomm
              Atheros  scheme designed for this purpose.  If more that one .xml file is specified
              then edits are applied in order of filename such that later edit  instructions  can
              over-write  eariler  instructions.  Instruction files usually have a .xml extension
              but this program makes no assumption based on filename and  does  not  enforce  any
              filename conventions.

       -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.  This option has no effect at this time.

       -v     Print additional information.  This option has no effect at this time.

       -?,--help
              Print  program  help  summary  on  stdout.  This option takes precedence over other
              options on the command line.

       -!,--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.

ARGUMENTS

       pib-file
              An Atheros parameter filename.  Only one parameter file can be edited at a time and
              so care must be taken to avoid the use  of  wildcard  filenames.   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

       <pib>  The  Parameter Information Block subject to edit.  There is exactly one pib defined
              in an instruction file.

       <object>
              A data region withn a pib.  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 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 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 and 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.   The  object  name is actually irrelevant.  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.

INSTRUCTIONS

       An  example  instruction  file  follows.   It references the Qualcomm Atheros XML PIB Edit
       schema file, piboffset.xsd, that is shown above so that a validating parser can  find  the
       schema  and  perform  document  checks.   The  remainder of the file describes a series of
       object names, offsets, lengths and values that describe the edits to be performed.

          <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.

               # 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.

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

       The following example does nothing because no instruction files are specified.

               # xml2pib abc.pib

SEE ALSO

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

CREDITS

        Charles Maier