setpib.1
Author: cmaier@cmassoc.net

    setpib(1)                                    Qualcomm Atheros Open Powerline Toolkit                                   setpib(1)

    NAME
           setpib - Qualcomm Atheros PIB File Editor

    SYNOPSIS
           setpib [options] file base [type data] [type data] [...]

    DESCRIPTION
           Replace  one  or more values in a Qualcomm Atheros powerline parameter (or PIB) file and re-compute the checksum.  Values
           are specified as a sequence of type/data pairs.  Users must know the offset, length and type of the values they change or
           problems will certainly result.  This program makes absolutely no effort to validate offsets or values.

           This  program  can  be used to change any PIB value, including those that should not be changed.  Be warned that some PIB
           values are derived from, or interact with, other PIB values.  Failure to observe such dependencies may  diminish  perfor‐
           mance or render a device inoperable.

           Atheros  does not recommend the use of this program to edit PIB parameters because small mistakes can cause big problems.
           In addition, Atheros is under no obligation to provide customers with the offset, length or type of any PIB file  parame‐
           ters.

           Atheros  recommends  using  program  modpib to change device identity parameters and the Windows Device Manager to change
           other parameters whenever possible.

           This program handles older Thunderbolt/Lightning parameter files and newer Panther/Lynx parameter  files  but  it  has  a
           larger  footprint  that may not be acceptable for embedded systems.  In cases where only the older or the newer parameter
           files are used, consider using program setpib1 for an older Thunderbolt/Lightning only version or  setpib2  for  a  newer
           Panther/Lynx only version.

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

    OPTIONS
           -q     Enable quiet mode which has not effect.

           -v     Print a hexdump of the edited region.  Print hexdump headers if this option appears twice.  The region window  may
                  be changed with option -w.

           -w window
                  The  display  window  in  bytes.  When option -v is present, PIB information surrounding the edited region is dis‐
                  played to provide some sort of context.  The edited region appears in the middle of this window.  The default win‐
                  dow is 32 bytes.  This means that the 32 bytes before and the 32 bytes after the edited region are included in the
                  display.

           -x     Repair the checksum.  By default, this program does not modify files that fail the size or checksum test on input.
                  In addition, it does not re-compute the checksum on output if no data has changed.  This option skips the size and
                  checksum test on input and re-computes the checksum on output even if no data has changed.  This option only works
                  on legacy PIB files.  It does not work on PIB files having NVM file format.

           -?, --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.
                  Usethis option when sending screen dumps to Atheros Technical Support so that they know exactly which  version  of
                  the Linux Toolkit you are using.

    ARGUMENTS
           file   The  PIB  filename.  The file must exist and will be re-written.  No assumptions are made based on filename and no
                  filename conventions are enforced.  This argument is required and must precede the base argument.

           base   The byte offset where changes will start.  The offset is expressed in hexadecimal with (or  without)  the  leading
                  "0x".   Changes  are  applied  in  order, left to right, and offset automatically increments by the correct amount
                  after each change is applied.  This permits consectuive PIB locations to be changed with one command.  This  argu‐
                  ment  is  required  and must follow the file argument.  It must also precede all format/data pairs.  Normally, you
                  must use multiple setpib commands to change non-consecutive PIB locations but  careful  use  of  format  skip  can
                  achive the same results using one command.

           type   The  implied  length  and  encoding of the data.  Valid types are byte, word, long, data and hfid.  A valid format
                  must precede each data item.  A byte is 8 bits, a word is 16 bits, a long is 32 bits and a huge is 64  bits.   The
                  format  implies  the maximum data value except for format data which is limited by the number of octets entered on
                  the command line.

           data   The information written to the current PIB offset.  Integer data may be expressed in binary, decimal or  hexadeci‐
                  mal  but  must  not  exceed the type minimum or maximum.  String data may contain any ASCII characters that can be
                  entered via keyboard but must be enclosed in quotes when spaces are included.  Binary values start with 0b  or  0B
                  and hexadecimal values start with 0x or 0X.

    FORMATS
           byte integer
                  A  signed or unsigned integer stored as 8 bits or 1 byte.  The value is expressed in decimal by default.  A binary
                  value may be expressed with a 0b prefix.  A hexadecimal value may  be  expressed  using  a  0x  prefix.   Negative
                  type/data values must appear at the end of the command line, after option "--", to avoid parsing errors.  The off‐
                  set increments by 1 prior to the next insertion.

           word integer
                  A signed or unsigned integer stored as 16 bits or 2 bytes.  The value is  expressed  in  decimal  by  default.   A
                  binary value may be expressed with a 0b prefix.  A hexadecimal value may be expressed using a 0x prefix.  Negative
                  type/data values must appear at the end of the command line, after option "--", to avoid parsing errors.  The off‐
                  set increments by 2 prior to the next insertion.

           long integer
                  A  signed  or  unsigned  integer  stored  as 32 bits or 4 bytes.  The value is expressed in decimal by default.  A
                  binary value may be expressed with a 0b prefix.  A hexadecimal value may be expressed using a 0x prefix.  Negative
                  type/data values must appear at the end of the command line, after option "--", to avoid parsing errors.  The off‐
                  set increments by 4 prior to the next insertions.

           huge integer
                  A signed or unsigned integer stored as 64 bits or 8 bytes.  The value is  expressed  in  decimal  by  default.   A
                  binary value may be expressed with a 0b prefix.  A hexadecimal value may be expressed using a 0x prefix.  The off‐
                  set increments by 8 prior to the next insertion.  Negative type/data values must appear at the end of the  command
                  line, after option "--", to avoid parsing errors.  This format is only available on hosts that support 64 bit data
                  values.

           data hex
                  A sequence of hexadecimal octets.  Octets may be separated by a colon for clarity.  The number  of  octets  deter‐
                  mines  the  number  of  bytes  written.  The offset increments by the number of bytes written.  This is similar to
                  "key" and "mac" below but accepts variable length input.

           key hex
                  A sequence of hexadecimal octets.  Octets may be separated by a colon for clarity.  The number of octets must con‐
                  vert  to 16 bytes or an error will occur.  The offset increments by 16 prior to the next insertion.  This is simi‐
                  lar "data" above but accepts only fixed length input.  This option may be used to set the DAK, NMK or NVAK values.

           mac hex
                  A sequence of hexadecimal octets.  Octets may be separated by a colon for clarity.  The number of octets must con‐
                  vert  to 6 bytes or an error will occur.  The offset increments by 6 prior to the next insertion.  This is similar
                  "data" above but accepts only fixed length input.  This option may be used to set the DAK, NMK or NVAK values.

           text string
                  An ASCII character string.  The string string length determines the number of bytes stored.  The string is  stored
                  with NUL terminator included.  It is not padded or truncated.  The offset increments by the number of bytes stored
                  prior to the next insertion.  This option may be used to enter a variable length string.

           hfid string
                  An ASCII character string.  The string is always stored as 64 bytes.  Short strings are padded on the  right  with
                  NUL  characters.   Long  strings are truncated on the right and the last byte is forced to NUL.  The offset incre‐
                  ments by 64 bytes prior to the next insertion.  This option may be used to enter user, network  and   manufacturer
                  identification strings.

           zero count
                  An  unsigned integer representing the number of consecutive bytes to fill with 0x00.  The offset increments by the
                  number of bytes written.  This option may be used to erase regions of the PIB.

           fill count
                  An unsigned integer representing the number of consecutive bytes to fill with 0xFF.  The offset increments by  the
                  number of bytes written.  This option may be used to erase regions of the PIB.

           skip count
                  An  unsigned  integer indicating the number of bytes to skip over before staring another change.  Intervening data
                  data locations are unchanged.

    TR69 DATA TYPES
           accesspassword string
                  An ASCII character string.  The string is always stored as 257 bytes.  Short strings are padded on the right  with
                  NUL  characters.   Long  strings are truncated on the right and the last byte is forced to NUL.  The offset incre‐
                  ments by 257 prior to the next insertion.

           accessusername string
                  An ASCII character string.  The string is always stored as 33 bytes.  Short strings are padded on the  right  with
                  NUL  characters.   Long  strings are truncated on the right and the last byte is forced to NUL.  The offset incre‐
                  ments by 33 prior to the next insertion.

           adminpassword string
                  An ASCII character string.  The string is always stored as 33 bytes.  Short strings are padded on the  right  with
                  NUL  characters.   Long  strings are truncated on the right and the last byte is forced to NUL.  The offset incre‐
                  ments by 33 prior to the next insertion.

           adminusername string
                  An ASCII character string.  The string is always stored as 33 bytes.  Short strings are padded on the  right  with
                  NUL  characters.   Long  strings are truncated on the right and the last byte is forced to NUL.  The offset incre‐
                  ments by 33 prior to the next insertion.

           password string
                  An ASCII character string.  The string is always stored as 257 bytes.  Short strings are padded on the right  with
                  NUL  characters.   Long  strings are truncated on the right and the last byte is forced to NUL.  The offset incre‐
                  ments by 257 prior to the next insertion.

           url string
                  An ASCII character string.  The string is always stored as 257 bytes.  Short strings are padded on the right  with
                  NUL  characters.   Long  strings are truncated on the right and the last byte is forced to NUL.  The offset incre‐
                  ments by 257 prior to the next insertion.

           username string
                  An ASCII character string.  The string is always stored as 257 bytes.  Short strings are padded on the right  with
                  NUL  characters.   Long  strings are truncated on the right and the last byte is forced to NUL.  The offset incre‐
                  ments by 257 prior to the next insertion.

    EXAMPLES
           The following example edits file abc.pib by writing decimal  value  1  at  offset  01F7  followed  by  hexadecimal  value
           00B052BABE01.   A partial dump is printed showing 16 bytes before and 16 bytes after the changed data because the default
           display windows is 16 bytes.  Unless the change occurs right at the start or end of the file, it will appear in the  cen‐
           ter of the display window.

              # setpib -v abc.pib 01F7 byte 1 data 00:B0:52:BA:BE:01
              000001D0                       00 00 00 00 00 00 00 00 00         .........
              000001E0  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
              000001F0  00 00 00 00 00 00 00 01 00 B0 52 BA BE 01 00 00  ..........R.....
              00000200  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
              00000210  00 00 00 00 00 00 00 00 00 00 00 00 00 00        ..............

           The  following  example  sets  the manufacturer HFID string in PIB file def.pib.  HFID strings are 64 characters long and
           either truncated or padded on the right with NUL characters.  You may need to enclose the string in quotes it it contains
           spaces.

              # setpib -v def.pib 24 hfid "Galactic Software Pirates, Inc."
              00000000              38 1F 00 00 30 1B EB 04 00 B0 52 00      8...0.....R.
              00000010  00 66 50 D3 E4 93 3F 85 5B 70 40 78 4D F8 15 AA  .fP...?.[p@xM...
              00000020  8D B7 00 00 47 61 6C 61 63 74 69 63 20 53 6F 66  ....Galactic Sof
              00000030  74 77 61 72 65 20 50 69 72 61 74 65 73 2C 20 49  tware Pirates, I
              00000040  6E 63 2E 00 00 00 00 00 00 00 00 00 00 00 00 00  nc..............
              00000050  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
              00000060  00 00 00 00 50 D3 E4 93 3F 85 5B 70 40 78 4D F8  ....P...?.[p@xM.
              00000070  15 AA 8D B7 49 6E 74 65 6C 6C 6F 6E 20 45 6E 61  ....Atheros Ena
              00000080  62 6C 65 64                                      bled

           The  following  example  displays the contents of PIB file abc.pib without changing any data.  The region displayed is 24
           bytes starting at offset 0x24.  The format skip specifies the region but does not change it.  By default,  the  32  bytes
           before and 32 bytes after are included in the display.  This technique can be used to inspect a specific portion of a PIB
           file.

              # setpib -v abc.pib 24 skip 64
              00000000              38 1F 00 00 30 1B EB 04 00 B0 52 00      8...0.....R.
              00000010  00 66 50 D3 E4 93 3F 85 5B 70 40 78 4D F8 15 AA  .fP...?.[p@xM...
              00000020  8D B7 00 00 47 61 6C 61 63 74 69 63 20 53 6F 66  ....Galactic Sof
              00000030  74 77 61 72 65 20 50 69 72 61 74 65 73 2C 20 49  tware Pirates, I
              00000040  6E 63 2E 00 00 00 00 00 00 00 00 00 00 00 00 00  nc..............
              00000050  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
              00000060  00 00 00 00 50 D3 E4 93 3F 85 5B 70 40 78 4D F8  ....P...?.[p@xM.
              00000070  15 AA 8D B7 49 6E 74 65 6C 6C 6F 6E 20 45 6E 61  ....Atheros Ena
              00000080  62 6C 65 64                                      bled

           The next example does the same thing for a negative value.  This is tricky because the minus sign will be interpreted  as
           the start of another option.  We must use "--" to end normal option parsing.  This is a POSIX standard feature.  See IEEE
           Std 1002.1-2001, Section 12.2, Utility Syntax Guidelines for more an explanation.

              # setpib -v abc.pib 1471 -- long -50
              00001450    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ...............
              00001460 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
              00001470 00 CE FF FF FF 00 00 00 00 00 00 00 00 00 00 00 ................
              00001480 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
              00001490 00 00 00 00 00                                  .....

           The following example computes a new checksum without changing any data.  The filename and an offset are required but  no
           other  values  are  needed.  This technique can be used to compute a new checksum after modifying the file using software
           that does not update the checksum.

              # setpib abc.pib 0 -x

    DISCLAIMER
           PIB file structure and content is proprietary to Qualcomm Atheros, Ocala FL USA.  Consequently, public information is not
           available.  Qualcomm Atheros reserves the right to modify PIB file structure or content in future firmware releases with‐
           out any obligation to notify or compensate users of this program.

    SEE ALSO
           chkpib(7), chkpib2(7), getpib(7), modpib(1), pib2xml(1), pibcomp(1), pibdump(1), xml2pib(1)

    CREDITS
            Charles Maier <cmaier@qca.qualcomm.com> ]

    open-plc-utils-0.0.3                                        Mar 2014                                                   setpib(1)

[PREV] [HOME] [NEXT]