int6kwait - Qualcomm Atheros INT6x00 Powerline Device
Procrastinator
int6kwait [options] [device] [device]
[...]
Poll a Qualcomm Atheros powerline device, waiting for one or more
events to occur before continuing or returning. The events include reset or
power off, restart or power on and network association. It is used to pause
shell scripts at critical points where a device must be in a known state
before continuing.
This program is part of the Qualcomm Atheros Powerline Toolkit.
See the plc man page for an overview and installation
instructions.
- -a
- Poll the device every few seconds using VS_NW_INFO messages until the
device indicates that a networks exists and has at least one station. This
option can give false readings if other devices have dropped off-line and
the device bridging table still holds information about them. The program
always checks for this event last if other event options are specified.
- -c count
- The number of times the program will poll the device before declaring an
event failure. The program will wait a fixed period of time between each
poll attempt. Overall wait time is count/frequency where count can
be modified using option -c. Overall wait time is always
approximate since operating system overhead and latency are not taken into
account. The default count is 300.
- -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.
- -f firmware
- The identification string for firmware that should be running after the
device starts. This option can be used to detect a failed firmware load.
If the actual identification string does not match this one once the
device starts then an error is reported. If option -x is present
then the program terminates with a non-zero exit code. This option has no
effect unless option -s is present. An identification string looks
like "INT6000-MAC-3-1-3143-1690-20071107-FINAL-B" and can be
obtained using int6k -r.
- -i
- 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.
- -p frequency
- The polling frequency expressed in polls-per-second. For example, 1 means
one poll per second and 10 means ten polls per second. Overall wait time
is count/frequency where count may be modified using option
-c. Overall wait time is always approximate since operating system
overhead and latency are not taken into account. The default frequency is
5.
- -q
- Enter quiet mode. Progress messages are suppressed.
- -r
- Poll the device every few seconds using VS_SW_VER messages until the
bootloader or runtime firmware fails to respond or the poll count
exhausts. The absence of a response indicates that the device either lost
connection to the host, lost power or has reset. The program always checks
for this event first when other events are specified.
- -R
- Reset the device then check return status. Exit program on error if option
-x is present; otherwise, repeat the reset request until the device
either accepts the request or the wait time is exceeded.
- -s
- Poll the device every few seconds using VS_SW_VER messages until the
bootloader or runtime firmware responds or the poll count exhausts. The
presence of a response indicates that the device has either connected to
the host, received power or finished reboot.
- -t
- Display the actual time in seconds taken for successful completion, or
waited for unsuccessful completion, of ecah event.
- -v
- Enter verbose mode. All Etherenet frames sent or received by the program
are displayed on stdout.
- -w seconds
- Additional time to wait once all events have occured. This wait does not
occur if any of the events timeout. When no other events are specified
this option is effectively equivalent to sleep. This option can be
used to allow the device or the network to settle. For example, a nominal
5 second wait is recommended after a device successfully associates before
attempting to transfer data.
- -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.
- device
- The Media Access Control (MAC) address of some device. Addresses are 6
hexadecimal octets optionally separated by colon. For example, the
addresses "00b052000001", "00:b0:52:00:00:01" and
"00b052:000001" are all valid and equivalent. For convenience,
the symbolic address "local" resolves to
"00:b0:52:00:00:01" and the symbolic addresses
"all" and "broadcast" both resolve to
"ff:ff:ff:ff:ff:ff".
See the Qualcomm Atheros HomePlug AV Firmware Technical Reference
Manual for more information.
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.
The following command polls the local device until firmware stops
running then polls the device until firmware starts running again. This
command can be inserted into a shell script at a point where the device must
reset and reboot before proceeding. Observer that the program waits up to 60
seconds for each event, in turn. The 60 seconds is the product of 60 poll
attempts spaced 1 second apart.
# int6kwait -rs
eth0 00:B0:52:BA:BA:01 Allow 60 seconds for Reset
eth0 00:B0:52:BA:BA:01 Allow 60 seconds for Start
The following example specifies 5 poll attempts spaced 10 seconds
apart. Less frequent polling reduces network traffic but makes the program
less responsive to events. Observe that the allotted time applies to each
event in turn.
# int6kwait -rs -p 10 -c 5
eth0 00:B0:52:BA:BA:01 Allow 50 seconds for Reset
eth0 00:B0:52:BA:BA:01 Allow 50 seconds for Start
The next example reports the actual amount of time taken for each
event to occur. Observe that the last event, device association, did not
occur within the allotted time.
# int6kwait -rsat
eth0 00:B0:52:BA:BA:01 Allow 60 seconds for Reset
etho 00:B0:52:BA:BA:01 Waited 22 seconds to Reset
eth0 00:B0:52:BA:BA:01 Allow 60 seconds for Start
etho 00:B0:52:BA:BA:01 Waited 4 seconds to Start
eth0 00:B0:52:BA:BA:01 Allow 60 seconds for Assoc
etho 00:B0:52:BA:BA:01 Waited 60 seconds for Assoc
etho 00:B0:52:BA:BA:01 Device did not Assoc
The following example illustrates use of the revision string to
detect mismatched firmware. In this example, we reset the device first,
using program int6k, then wait for it to reset then start up again.
There are also operation that can cause the device to reset.
# int6k -R
# int6kwait -xrsf INT6000-MAC-3-1-3143-1690-20071107-FINAL-B
eth0 00:B0:52:BA:BA:01 Device started wrong firmware
Immediately after a reset we wait for the firmware to stop
responding, with option -r, and then start responding, with option
-s, and then perform a string comparison against the actual firmware
revision string, with option -f. If the strings do not match then an
error is reported. In this case, the program will exit with a non-zero
return code since option -x is present.
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.
plc(1), int6k(1),
int6kf(1), int6khost(1),
int6kid(1), int6krate(1),
int6krule(1), int6kstat(1)