Provided by: plc-utils-extra_0.0.6+git20211210.358dfcf-2_amd64 bug

NAME

       amprate - Qualcomm Atheros AR7x00 PHY Rate Monitor

SYNOPSIS

       amprate [options] [device] [device] [...]

DESCRIPTION

       The Atheros PHY Rate Utility polls one or more devices and prints the average transmit and
       receive PHY rates between a device and each neighboring network device.  Output is column-
       oriented and suitable for loading into a spreadsheet or being read by a simple program.

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

COMMENTS

       This program version is identical to legacy program int6k, except for options  -t  and  -T
       which  use  version  1  of the Qualcomm Atheros VS_NW_INFO vendor-specific message.  Older
       firmware versions may not recognize this message version.

OPTIONS

       -c     Display coded PHY rates.  Coded PHY rates are displayed by default so  this  option
              is  redundant  but  it  has  been kept for backword compatibility.  This option and
              option -u are mutually exclusive.

       -d seconds
              Traffic duration in seconds per connection.  Directional traffic is  systematically
              sent  between  each  pair  of  powerline  network  devices for this period of time.
              Consequently, the total time needed to generate traffic between all network devices
              will be approximately n! times this value, so don''t get carried away.  The minimum
              value is 1 second and the maximum value is 60 seconds.

       -e     Redirects stderr messages to stdout.  By convention status and error  messages  are
              printed  on  stderr while primary program output is printed on stdout.  This option
              prints all output on stdout in cases where this is desired.

       -i interface
              Select the host Ethernet interface.  All requests are sent via this host  interface
              and  only  reponses  received  via this host interface are recognized.  The default
              interface is  eth1  because  most  people  use  eth0  as  their  principle  network
              connection;  however,  if  environment  string  "PLC"  is  defined  then  it  takes
              precedence over the default interface.  This  option  then  takes  precedence  over
              either default.

       -n     Reads  the  average  transmit and receive PHY rate for wach device using VS_NW_INFO
              and prints it on stdout.  Each output line displays the ethernet interface,  source
              address, destination address and either the transmit or receive PHY rate.

       -o milliseconds
              Read  timeout  in milliseconds.  Values range from 0 through UINT_MAX.  This is the
              maximum time allowed for a response.  The default  is  shown  in  brackets  on  the
              program menu.

       -r     Reads  device hardware and software revision information using VS_SW_VER and prints
              it on stdout.

       -R     Resets the device using VS_RS_DEV.

       -t     Generate powerline traffic between the local device and each remote device on  each
              powerline  network connected to the host.  It does not generate any traffic between
              remote powerline device pairs.   This  option  is  especially  useful  when  remote
              powerline  devices are not connected to Ethernet devices capable of sending traffic
              back to the host.

       -T     Generate powerline traffic between all devices on each powerline network  connected
              to  the host.  This option is similar to option -t but it takes much longer because
              traffic is  systematically  generated  between  each  pair  of  powerline  devices.
              Consequently,  the  time  to  complete  will  increase factorially as the number of
              network devices increases.  Such complete  traffic  path  coverage  is  not  always
              needed.

       -u     Display un-coded PHY rates.  Coded PHY rates are displayed by default.  This option
              and option -c are mutually exclusive.

       -q     Enter quiet mode.  Progress messages are suppressed.

       -v     Enter verbose mode.  All Etherenet frames sent  or  received  by  the  program  are
              displayed on stdout.

       -x     Exit  program  on  first error with a non-zero exit code.  This option allows shell
              scripts to detect failed or incomplete operations and take the appropriate action.

       -?,--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

       device The MAC address of some powerline device.  More than one address may be  specified.
              If  more than one address is specified then operations are performed on each device
              in turn.  The default address is local.  See DEVICES for information about symbolic
              device addresses.

DEVICES

       Powerline  devices  use Ethernet Media Access Control (MAC) addresses.  A MAC address is a
       48-bit value entered as 12 hexadecimal digits in upper, lower  or  mixed  character  case.
       Octets   may   be  separated  with  colons  for  clarity.   For  example,  "00b052000001",
       "00:b0:52:00:00:01" and "00b052:000001" are valid and equivalent.

       The following MAC addresses are special and may be entered by name instead of number.

       all    Same as "broadcast".

       broadcast
              A synonym for the Ethernet  broadcast  address,  FF:FF:FF:FF:FF:FF.   All  devices,
              whether local, remote or foreign recognize messages sent to this address.  A remote
              device is any device at the far end of a powerline connection.  A foreign device is
              any device not manufactured by Atheros.

       local  A  synonym for the Qualcomm Atheros vendor specific Local Management Address (LMA),
              00:B0:52:00:00:01.  All local Atheros devices recognize this address but remote and
              foreign  devices  do  not.   A  remote  device  is  any  device at the far end of a
              powerline connection.  A foreign device is any device not manufactured by Atheros.

REFERENCES

       See the Qualcomm  Atheros  HomePlug  AV  Firmware  Technical  Reference  Manual  for  more
       information.

EXAMPLES

       The following example displays the average transmit and receive PHY rates from each of two
       devices.  One is a local device connected to interface eth2 and  the  other  is  a  remote
       device  at  the  far end of the powerline.  In this case, they are the only two devices on
       the powerline network.  Observe the recipricol rates shown.

          # amprate -ni eth2 00:B0:52:00:00:AA 00:B0:52:00:00:BB
          eth2 00:B0:52:00:00:AA 00:B0:52:00:00:BB TX 163 mbps
          eth2 00:B0:52:00:00:AA 00:B0:52:00:00:BB RX 176 mbps
          eth2 00:B0:52:00:00:BB 00:B0:52:00:00:AA TX 176 mbps
          eth2 00:B0:52:00:00:BB 00:B0:52:00:00:AA RX 163 mbps

       The following example generates powerline traffic between the local device and each remote
       device  because  option  -t is present.  It then displays the PHY rate read from the local
       device.

          # amprate -tni eth2
          eth2 00:B0:52:00:00:AA 00:B0:52:00:00:BB TX 163 mbps
          eth2 00:B0:52:00:00:AA 00:B0:52:00:00:BB RX 176 mbps

DISCLAIMER

       Atheros HomePlug AV Vendor Specific Management Message  Entry  structure  and  content  is
       proprietary  to  Qualcomm Atheros, Ocala FL USA.  Consequently, public information may not
       be available.  Qualcomm Atheros reserves the right to modify message structure and content
       in  future  firmware releases without any obligation to notify or compensate users of this
       program.

SEE ALSO

       plc(1), amprule(1), ampstat(1), amptone(1)

CREDITS

        Nathaniel Houghton
        Charles Maier