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

NAME

       plc  -  Qualcomm  Atheros  Powerline Toolkit: tools to manage and control HomePlug 1.0 and
       HomePlug AV devices

SYNOPSIS

       A summary of Qualcomm Atheros Powerline Toolkit commands.

DESCRIPTION

       HomePlug 1.0 and HomePlug AV are industry standard protocols for powerline communications.
       Qualcomm  Atheros  manufactures  a  family of chipsets that conform to these standards and
       have various USB, PCI, Ethernet, MII, SPI and UART host interfaces.

       The HomePlug 1.0 protocol is based on IEEE-802.3, has ethertype 0x887B  and  uses  special
       message formats.

       The  HomePlug AV protocol is based on IEEE-802.3, has ethertype 0x88E1 and special message
       formats.  A subset of those message formats are left unspecified so that  chipset  vendors
       can define message formats for their own products.  QCA vendor specific management message
       formats are described in the QCA HomePlugAV Firmware  Technical  Reference  Manual.   This
       toolkit  uses these messages to communicate with QCA powerline devices.  Customers may use
       the toolkit to send  these  messages,  explore  device  behavior  and  develop  their  own
       applications.

       Each  program in the toolkit deals with a narrow aspect of QCA powerline device management
       but they can be called from shell scripts to perform complex tasks.  With  them,  one  can
       identify  chipset  hardware  and  firmware version, reset devices, flash devices, identify
       other QCA network devices, validate *.pib and *.nvm  files,  sniff  HomePlug  AV  Ethernet
       frames, send generic Ethernet frames and so on.

       The  source  code  is  designed  to  demonstrate  and  educate and may be modified without
       obligation to Qualcomm Atheros.  The QCA Application  Engineering  Team  would  appreciate
       feedback  concerning  changes that improve the usability, reliability or efficiency.  Keep
       in mind that these tools are supposed to be small and simple.

TOOLS

       There are many independent programs in this package.  Significant ones are  listed  below.
       See html/overview.html for more information about the Atheros Powerline Toolkit.

       ampboot
              A  command  line  utility  to  start, and optionally flash, newer Atheros Powerline
              Devices.  It is an alternative  to  program  int6kboot  that  may  have  additional
              options specific to the AR7400.

       amphost
              A  example embedded host emulator that responds to VS_HST_ACTION messages sent from
              a flash-less device to a local host processor.  It can be used to  investigate  and
              verify  device-to-host  interaction.   The Atheros embedded API can perform similar
              functionality in a production environment.

       ampsnif
              A command line utility to enable or disable sniffer mode on  an  Atheros  Powerline
              Device.

       amptest
              A  command  line  utility to download and execute a sequence of test applets to the
              local powerline device.  It is not for general use because there are no  interlocks
              to  prevent  loading  images  designed  for  other  platforms  or loading images in
              illogical order.  It is an alternative to, and replacement for, program int6ktest.

       amptool
              A basic device manager used  to  inspect  and  control  Atheros  powerline  devices
              connected  to the local host.  It is similar to int6k but is specific to the AR7400
              chipsets.

       ampwait
              A command line utility used to pause shell  scripts  at  critical  points  where  a
              device  must  be in a known state before proceeding.  Typical cases involve waiting
              for device power off or reset, power on or restart and network device association.

       ar8236mdioblock
              Produce an MDIO block from  Atheros  AR8236  special  register  instructions.   The
              output is suitable for downloading to INT6x00 and AR7x00 powerline devices.

       ar8236regedit
              Insert values into Atheros AR8236 special registers.

       chknvm A  command  line  utility  that  validates  NVM  files  based  on  internal  header
              information, filesize, checksums and other general characteristics.  Optionally, it
              can  be  used  to  display  all  image  headers  within an NVM file or the firmware
              revision contained in the file.

       chkpib A  command  line  utility  that  validates  PIB  files  based  on  internal  header
              information, filesize, checksum, and other general characteristics.  It can also be
              used to produce a text catalog of PIB files contained in a directory.

       coqos_add
              CoQoS stream utility.  No description.

       coqos_info
              CoQoS stream utility.  No description.

       coqos_man
              CoQoS stream utility.  No description.

       coqos_mod
              CoQoS stream utility.  No description.

       coqos_rel
              CoQoS stream utility.  No description.

       efsu   A utility to send freeform Ethernet frames.   Frames  are  defined  as  text  files
              containing   hexadecimal  byte  codes  having  optional  comments  and  whitespace.
              Comments and white space are stripped from the input file and the hexadecimal  byte
              codes are transmitted as Ethernet frames.

       ethcat Send  on  or  more files to a remote UART-enabled powerline device using IEEE 802.2
              Ethernet frames.  Transmitted frames are assembled into a serial  data  stream  and
              forwarded to the local host by the remote device.

       fp     A command line utility that prints the SHA256 digest for one or more files based on
              their content.  Output can be used to compare files or identify files based  solely
              on their content despite any filename changes.

       getpib A  command  line  utility  for  extracting data from a valid PIB file based on data
              offset, length and format.  It is a companion to program setpib.  Both programs are
              intended  for  use in shell scripts.  Users must have some knowledge about the data
              they are extracting.

       hpav   An basic  packet  sniffer  that  displays  incoming  HomePlug  AV  protocol  frames
              addressed  to the host as they arrive.  The program may be run in the background as
              a daemon.

       hpavkey
              A HomePlug AV key  generator.   HomePlug  AV  devices  use  has  keys  for  various
              purposes.   This  program converts one or more pass phrases, entered on the command
              line, to either DAKs, NMKs or NIDs.  It is similar  to  hpavkeys   but  converts  a
              limited number of pass phrases at one time.

       hpavkeys
              A HomePlug AV key generator.  This program is similar to hpavkey but converts large
              number of pass phrases, read from stdin, and converts them to either DAKs, NMKs  or
              NIDs.

       int6k  A  basic  device  manager  used  to  inspect  and  control  Atheros INT6x00 devices
              connected to the local  host.   It  is  similar  to  amptool  and  plctool  but  is
              implemented  for  INT6000,  INT6300 and INT6400 devices only.  Some options work on
              newer chipsets but others do not.

       int6kbaud
              A command line utility  to  configure  UART  settings  on  a  UART-enabled  Atheros
              powerline device using the ATBR serial line command.

       int6kboot
              A  command line utility used to bootstrap powerline devices having no flash memory,
              blank flash memory or corrupted memory.  It interacts with the  Atheros  BootLoader
              to  configure  SDRAM  then  download  runtime  firmware  and PIB and start firmware
              execution.  It can also be used to force flash blank or corrupted flash memory.

       int6keth
              A command line utility to read and write device Ethernet PHY settings.

       int6kf A basic flash utility used to initialize INT6300 devices having  no  flash  memory,
              blank  flash memory or corrupted memory.  It interacts with the Atheros Boot Loader
              to download SDRAM configuration, runtime firmware and PIB.  It can also be used  to
              force flash blank or corrupted flash memory.

       int6khost
              A  example embedded host emulator that responds to VS_HST_ACTION messages sent from
              a flash-less device to a local host processor.  It can be used to  investigate  and
              verify  device-to-host  interaction.   The Atheros embedded API can perform similar
              functionality in a production environment.

       int6khost64
              An updated version of int6khost  that  omits  the  needed  for  an  external  SDRAM
              configuration  file.  It takes advantage of the memctl applet included in the newer
              *.nvm files.

       int6kid
              A command line utility to print the DAK or NMK read from one or more  devices.   It
              can  be  used  in  shell scripts to dynamically obtain device key values and insert
              them on the command line of other programs.

       int6km A basic memory read utility  used  to  inspect  INT6x000  accessible  SDRAM  memory
              locations and mapped registers.  Not all locations or registers are accessible.

       int6kmdio
              Insert values into MDIO PHY address registers using an VS_MDIO_COMMAND message.

       int6kmod
              A   command   line  utility  that  downloads  raw  modules  using   a  sequence  of
              VS_MODULE_OPERATION messages.

       int6kprobe
              A command line utility  that  detects  and  reports  neighbor  networks  using  the
              VS_DIAG_PROBE message.

       int6krate
              A  command  line utility that reports computed PHY rates for a single device or all
              devices on a logical network.  Output is designed for import into a spread sheet.

       int6krule
              A command line utility used to format and send classification rules  to  a  device.
              Classification  rules  are  specified  using  symbolic  names for actions, options,
              conditions and frame fields.

       int6kstat
              A command line utility that prints device link statistics on stdout in a relatively
              undecorated format.  Output is designed for easy interpretation by other programs.

       int6ktest
              A  command  line  utility  to  download and execute a series of test applets to the
              local powerline device.  It is not for general use because there are no  interlocks
              to  prevent  loading  images  designed  for  other  platforms  or loading images in
              illogical order.

       int6kuart
              A command line utility to send serial  line  commands  to  a  UART-enabled  Atheros
              Powerline device.  This program eliminates the need for terminal emulation software
              and can be used to download PIB and firmware files to a device over the serial line
              interface.

       int6kwait
              A  command  line  utility  used  to  pause shell scripts at critical points where a
              device must be in a known state before proceeding.  Typical cases  involve  waiting
              for device power off or reset, power on or restart and network device association.

       mac2pw A device password generator that prints a range of MAC addresses and user passwords
              on stdout.  It is an alternative  to  the  Atheros  Production  Test  System  (PTS)
              DBBuilder Utility.

       mac2pwd
              A  device  password generator that reads MAC addresses from one or more input files
              and prints addresses and passwords on stdout.  It is an alternative to the  Atheros
              Production Test System (PTS) DBBuilder utility.

       mdioblock
              Produce  an  MDIO  block  from  generic  MDIO register instructions.  The output is
              suitable for downloading to INT6x00 and AR7x00 powerline devices.

       mdiodump
              Display a binary MDIO program file in human readable form.

       mdiogen
              Generate a binary MDIO program file from a  series  of  instruction  macros.   This
              program  is  for  folks  who  know  what  they  are  doing.   It has no man page or
              instructions for use.

       mdustats
              Collect and display various MDU traffic statistics using  the  VS_MDU_TRAFFIC_STATS
              message.

       modpib A  basic  command  line  PIB  editor  used  to change the MAC, DAK and/or NMK of an
              existing PIB file.  It can also be used to change the manufacturer string,  network
              name and username strings.

       mrgpib A  command line utility to copy PIB settings from one PIB file to another where the
              PIB files have different PIB versions.

       nvmmerge
              A command line utility to merge multiple applets or NVM files  into  a  single  NVM
              file.

       nvmsplit
              A command line utility to split an NVM file into multiple NVM files each containing
              one image.  The original NVM file is preserved.

       odc    An offset-driven hex compare utility for analyzing the difference between two files
              having  a  fixed  structure.  An offset definition file is required for proper use.
              This program has been superseded by program pibcomp.

       odd    An offset-driven hex dump utility for analyzing any binary file that  has  a  fixed
              structured,  such  as  an  INT6000  PIB  file  or  an  INT5500 CFG file.  An offset
              definition file is required for proper use.  This program has  been  superseded  by
              program pibdump.

       odx    An  offset-driven  XML generator used to convert an offset definition file, used by
              programs odc and odd, to an XML edit definition file used by program pxe.

       pibdump
              Read a Qualcomm Atheros powerline parameter file and print an object driven dump on
              stdout.  This program requires an object definition file.

       pibcomp
              Read and compare two Qualcomm Atheros powerline parameter files and print an object
              driver dump for only those object that are different.  This  program  requires  and
              object definition file.

       pibruin
              A classifier rule input utility used to insert multiple classifier rules into a pib
              file.  Use program pibrump to read rules from another PIB file  or  create  a  rule
              file  manually  with  any  text  editor.  This program is an alternative to program
              int6krule.

       pibrump
              A classifier rule dump utility used to read rules from a PIB file and print them in
              a  format  similar  to  the  input  for  program int6krule.  The output can be read
              directly by program pibruin.

       plcboot
              A command line utility to start, and optionally flash, Qualcomm  Atheros  Powerline
              Devices.   It  is a newer version of program ampboot having options specific to the
              QCA6410, QCA7000 and AR7420 chipsets.

       plchost
              A example embedded host emulator that responds to VS_HST_ACTION messages sent  from
              a  flash-less  device to a local host processor.  It can be used to investigate and
              verify device-to-host interaction.  The Atheros embedded API  can  perform  similar
              functionality in a production environment.

       plcmod A   command   line   utility  that  downloads  raw  modules  using  a  sequence  of
              VS_MODULE_OPERATION messages.  This version can handle multiple module  writes  and
              modules exceeding 1400 bytes.

       plcnets
              A  powerline  network  enumerator  that  searches  all  host network interfaces for
              powerline devices and their neighbors.

       plctool

       plctest
              A command line utility to download and execute a sequence of test  applets  to  the
              local  powerline device.  It is not for general use because there are no interlocks
              to prevent loading images  designed  for  other  platforms  or  loading  images  in
              illogical order.  It is a newer version of program amptest.

       pskey  Print  the  SHA256  digest for the amplitude make stored in a PIB file.  The digest
              can be used as a fingerprint or signature for the prescaler set.

       psin   Read a prescaler file from stdin and replace the amplitude  map  stored  in  a  PIB
              file.

       psout  Read  a  PIB  file  and print a prescaler file suitable for input using psin or the
              Windows Device Manager.

       rkey   A command line utility to generate distinct HomePlug AV compliant keys from a  user
              defined  keyfile  that  seeds  the  hash  algorithm.  It can be used to dynamically
              generate distinct keys inside shell scripts or create long lists of unique keys for
              use by other programs.

       setnvm A  command line utility to modify selected header parameters for all image within a
              given NVM file.  This program  can  be  used  to  translate  legacy  NVM  files  to
              contemporary NVM file and vice verse.

       setpib A  command  line  utility  to insert arbitrary values into a PIB file based on data
              offset, length and format then compute a new  PIB  checksum.   This  program  is  a
              general  purpose program intended for use in shell scripts but it requires detailed
              knowledge of PIB structure.

       ttycat A command line utility to write one or more files to a serial device.  This program
              is a convenient tool for testing Atheros UART-enabled powerline devices.

       weeder A  command  line utility to set the programmable attenuators build into the Atheros
              Production Test System (PTS).

       There may be other programs added, from time to time, that are not listed here.

SEE ALSO

       amphost(1), ampinit(1), plcmod(1), amptest(1),  amptool(1),  ar8236regedit(1),  chkpib(1),
       chknvm(1), coqos_add(1), coqos_info(1), coqos_man(1), coqos_mod(1), coqos_rel(1), efsu(1),
       efbu(1),   getpib(1),   hpav(1),   hpavkey(1),   hpavkeys(1),   int6k(1),    int6kbaud(1),
       int6kboot(1), int6keth(1), int6kf(1), int6khost(1), int6khost64(1), int6kid(1), int6km(1),
       int6kmdio(1),  int6kmod(1),  int6kprobe(1),  int6krate(1),   int6krule(1),   int6kstat(1),
       int6ktest(1),  int6kuart(1),  int6kwait(1), mac2pw(1), mac2pwd(1), mdiodump(1), modpib(1),
       mrgpib(1), nvmmerge(1),  nvmsplit(1),  odc(1),  odd(1),  odx(1),  pibdump(1),  pibcomp(1),
       pibruin(1),   pibrump(1),   plcboot(1),  plchost(1),  plcmod(1),  plcinit(1),  plctest(1),
       plctool(1), plcrate(1), plcrate(1),  plcwait(1),  psin(1),  pskey(1),  psout(1),  rkey(1),
       setnvm(1), setpib(1), ttycat(1), ttyrecv(1), ttysend(1), weeder(1)

CREDITS

        Alex Vasquez
        Andy Barnes
        Bill Wike
        Charles Maier
        John Byron
        Mathieu Olivari
        Nathaniel Houghton
        Marc Bertola