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

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

       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 displayed to provide some sort of context.  The
              edited region appears in the middle of this  window.   The  default  window  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  argument 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 hexadecimal 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 offset 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 offset 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 offset 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 offset 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 determines 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 convert to 16 bytes or an error will occur.  The offset
              increments by 16 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.

       mac hex
              A sequence of hexadecimal octets.  Octets may be separated by a colon for  clarity.
              The  number  of  octets must convert 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 increments 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 increments 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 increments 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 increments 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 increments 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 increments 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 increments 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 increments 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 center 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 without 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 ]