csu3_am335x/EVSE/GPL/plc-utils.LNX.2.1.20/source/nda/ampinit.1

.TH ampinit 1 "Mar 2014" "plc-utils-2.1.6" "Qualcomm Atheros Powerline Toolkit"

.SH NAME
ampinit - Qualcomm Atheros Production Device Manager

.SH SYNOPSIS
.BR ampinit
.RI [ options ] 
.RI [ device ] 
.RI [ device ] 
[...]

.SH DESCRIPTION
The Production Device Manager performs basic device operations using the raw Ethernet protocol described in the Atheros HomePlug AV Firmware Technical Reference Manual.
It can be used to initialize devices, interrogate and control them and upgrade them when on-board NVRAM is present.

.PP
This program is part of the Qualcomm Atheros Powerline Toolkit.
It supports the AR7400, QCA7450 and similar chipsets.
See program \fBint6kp\fR to support the legacy INT6000, INT6300, INT6400 and similar chipsets.
See program \fBplcinit\fR to support the newer QCA6410, QCA7000, AR7420 and similar chipsets.

.PP
This program is a \fBproduction version\fR of \fBamptool\fR and may not be distributed without the explicit permission of Qualcomm Atheros, Ocala FL USA.

.SH OPTIONS

.TP
-\fBa\fR
Read device attributes using VS_OP_ATTRIBUTES.
Attributes are short strings and integers that describe device hardware and firmware.
They are concatenated to form the output that is similar to option -\fBr\fR but derived differently.

.TP
.RB - b
Requests and prints a device enumeration table on stdout using VS_EM_ID_TABLE.
An enumeration table contains MAC addresses of known devices on the Ethernet (H1) side of a powerline device.
This option is only supported on EoC enabled devices.

.TP
-\fBB \fIbutton\fR
Press the simple connect pushbutton using VS_PB_ENC.
The \fBaction\fR can be specified by number 1, 2, 3 or 4 or by symbol "\fBjoin\fR", "\fBleave\fR", "\fBstatus\fR" or "\fBreset\fR", respectively.
Use 1 on both devices that are expected to join.
Use 2 only on the device that is expected to leave the network.

.TP
-\fBC \fImodule\fR
Write (commit) downloaded modules to NVRAM using VS_MOD_NVM.
The \fBmodule\fR can be spedified by number 1=NVM, 2=PIB and 3=BOTH or string "nvm", "pib" or "both".
Module 3 is equivalent to option -\fBF\fR which writes the NVM and PIB together.
You cannot force flash NVRAM using this option.
Use option -\fBFF\fR to force flash.

.TP
-\fBd\fR \fIfilename\fR
Read Watchdog Report from the device and write it to the named file in binary format using VS_WD_RPT.
The report file can be sent to Qualcomm Atheros for technical analysis.
No assumptions are made based on filename and no filename convetions are enforced; however, you should use a \fB.log\fR file extension to indicate binary format.

.TP
-\fBD\fR \fIxx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx\fR
Define the 16 octet Device Access Key (DAK) in hex format.
The DAK is used by options -\fBJ\fR, -\fBC\fR and -\fBF\fR.
It may also be specified as "key1" or "key2" as explained in the \fBKEYS\fR section.
You may omit this option on the command line when the device DAK happens to be the same as the program default of "key1".

.TP
.RB - 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.

.TP
.RB - E
Erase NVRAM on the specified device using VS_PTS_NVM and reboot.
This option is similar to option -\fBF\fR or -\fBFF\fR but writes all ones to NVRAM instead of downloaded firmware or paratemeters.
Any firmware or parameters that have been downloaded pending flash will be lost when the device reboots.
You must also specify the device \fBDAK\fR using option -\fBD\fR or the erase operation will fail without indication.
This operation can only be performed on the local device.
Attempts to erase a remote device are ignored.
Some firmware versions do not permit the operation and those that do permit it will prevent it on INT6000 devices.

.TP
.RB - f
Read flash memory parameters using VS_GET_NVM.
An error will be reported if no flash memory is present.

.TP
.RB - F [ F ]
Write previously downloaded MAC and PIB to NVRAM using VS_MOD_NVM.
Adding a second \fBF\fR here or another -\fBF\fR anywhere on the command line will \fBforce-flash\fR a blank or corrupted NVRAM.
Firmware loaded from NVRAM will treat force-flash as an error.
Unlike program \fBamptool\fR, this program modifies factory default settings by erasing the User PIB and rewriting the Factory PIB.

.TP
.RB - g
Read multicast group information discovered while IGMP snooping using VS_MULTICAST_INFO.

.TP
-\fBi\fR \fIinterface\fR
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 \fBeth1\fR because most people use \fBeth0\fR 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.

.TP
.RB - I
Read the device PIB header using VS_RD_MOD and print the PIB major and minor revision number, Device Access Key (DAK), Network Membership Key (NMK), MAC address and other information on stdout.
The values displayed can be changed using program \fBmodpib\fR.

.TP
.RB - J
Set the Network Membership Key (NMK) on a remote device using VS_SET_KEY.
This option is similar to option -\fBK\fR but requires the remote device DAK in addition to NMK and MAC address.
The NMK value is defined using option -\fBK\fR unless you want to use the default value.
The remote DAK is defined using option -\fBD\fR unless you want to use the default value.
Programming remote device keys is complicated.
It is often easier to connect the device directly to the host and use the -\fBK\fR option.

.TP
-\fBK\fR \fIxx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx\fR
Define the Network Membership Key (NMK) value used by options -\fBM\fR or -\fBJ\fR.
The symbolic names "key1" and "key2" are recognized as described in the \fBKEY\fR section.

.TP
-\fBl\fR \fIcount\fR
Define the number of times that the command will be repeated for each device specified.
Normally, you will repeat operations on one device only.

.TP
.RB - m
Read network membership information using VS_NW_INFO.
This can be used to determine network configuration.

.TP
.RB - M
Set the Network Membership Key (NMK) on the local device using VS_SET_KEY.
The NMK value is specified using the -\fBK\fR option unless you want to use the default value.

.TP 
-\fBn\fR \fIfilename\fR
Read the entire firmware image chain from the device flash memory and write it to the named \fB.nvm\fR file using multiple VS_RD_BLK_NVM messages.
No assumptions are made based on filename and no filename conventions are enforced.
This option is performed before option -\fBN\fR when both are specified.

.TP 
-\fBN\fR \fIfilename\fR
Read the named \fB.nvm\fR file and write it to volatile memory using multiple VS_WR_MOD messages.
The file will also be written to flash memory if option -\fBF\fR is present.
No assumptions are made based on filename and no filename conventions are enforced; however, files having invalid .nvm format will be rejected.
This option is executed after -\fBn\fR when both are specified.

.TP
-\fBp\fR \fIfilename\fR
Read the entire user parameter block from the flash memory and write it to the named \fB.pib\fR file using multiple VS_RD_BLK_NVM messages.
No assumptions are made based on filename and no filename convetions are enforced.
This option is executed before option -\fBP\fR when both are specified.

.TP
-\fBP\fR \fIfilename\fR
Read the named \fB.pib\fR file and write it to volatile memory using multiple VS_WR_MOD messages.
The file will also be written to flash memory if option -\fBF\fR is present.
No assumptions are made based on filename and no filename conventions are enforced; however, files having invalid .pib format will be rejected.
This option is executed after -\fBp\fR when both are specified.

.TP
.RB - q
Suppresses status messages on stderr.

.TP
.RB - Q
Quick flash.
The program will not wait for a device to reset or the firmware to restart after writing flash memory.
This option is desirable with newer firmware that writes flash memory in the background.
It has no effect unless used with option -\fBF\fR or -\fBC\fR.

.TP
.RB - r
Read device firmware and hardware revision using VS_SW_VER.
Output is similar to option -\fBa\fR but is derived differently.
Example output might look like "eth0 00:B0:52:00:00:01 INT6300A0 INT6000-MAC-2-0-2000-1018-20070611-SP1-B NOT-UPGRADEABLE".

.TP 
.RB - R
Reset the device using VS_RS_DEV.
This option is executed after all others on the same command line.

.TP
.RB - s
Read device SDRAM configuration using VS_RD_CBLOCK.

.TP
-\fBS\fR \fIoperand\fR
This option is permitted but ignored in order to support legacy scripts that have not been kept current.
A warning message is printed to inform users that the option and operand are being ignored.

.TP
-\fBt \fItimer\fR
Read timeout in milliseconds.
Values range from 0 through UINT_MAX.
This is the maximum time allowed for a response.
The default is 50 milliseconds.

.TP
.RB - T
Restore factory defaults.
This permanently erases PIB changes made since the device was last programmed with factory default values.
The device will automatically reset and reboot.

.TP
.RB - v
Print additional information on stdout.
In particular, this option dumps incoming and outgoing packets which can be saved as text files for reference.

.TP
-\fBw \fIseconds\fR
Defines the number of \fIseconds\fR to wait before repeating command line options.
This option has no effect unless option -\fBl\fR is also specified with a non-zero value.

.TP
.RB - x
Cause the program to exit on the first error instead of continuing with remaining iterations, operations or devices.
Normally, the program reports errors and moves on to the next operation, iteration or device depending on the command line.

.TP
.RB - ? ,-- help
Print program help summary on stdout.
This option takes precedence over other options on the command line.

.TP
.RB - ! ,-- 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.

.SH ARGUMENTS

.TP
\fIdevice\fR
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 \fBlocal\fR.
See \fBDEVICES\fR for information about symbolic device addresses.

.SH KEYS
Encryption keys are long, tedious to type and prone to error.
For convenience, the following symbolic names may be used to specify either a Device Access Key or Network Membership Key.
They may be entered in place of the full 16-octet key.
The DAK and NMK will always be different for a given pass phrase.

.TP
.BR key1
This will translate to the HomePlug AV compliant DAK or NMK for pass phrase "HomePlugAV" depending on context.

.TP
.BR key2
This will translate to the HomePlug AV compliant DAK or NMK for pass phrase "HomePlugAV0123" depending on context.

.TP
.BR none
Symbolic name for "00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00".

.SH 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.

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

.TP
.BR all
Same as "broadcast".

.TP
.BR broadcast
A synonym for the Ethernet broadcast address, \fBFF:FF:FF:FF:FF:FF\fR.
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.

.TP
.BR local
A synonym for the Atheros vendor specific Local Management Address (LMA), \fB00:B0:52:00:00:01\fR.
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.

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

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

.SH EXAMPLES

.PP
The following command performs 5 operations on one device.
It uploads the firmware and PIB from the device and writes them to files \fBold.nvm\fR and \fBold.pib\fR, respectively.
It reads files \fBnew.nvm\fR and \fBnew.pib\fR and downloads them as new firmware and PIB, respectively.
It commits the downloaded firmware and PIB to NVRAM after validating the device DAK.
Operations are executed in the order just described regardless of the order specified on the command line.
If you want reading and writing to occur in a different order then you must use two or more commands to accomplish tasks in the order you want.

.PP
   # ampinit -n old.nvm -p old.pib -N new.nvm -P new.pib -D 00112233445566778899AABBCCDDEEFF -F 0123456789AB 

.PP
It is not neccessary to specify all operations on one command line.
The three command lines below do essentially the same thing as the command line shown above.
Notice that this example uses -\fBC 3\fR, instead of -\fBF\fR, as an alternate way to write both firmware and parameters to NVRAM.
Specifying -\fBC 1\fR or -\fBC nvm\fR will write firmware only.
Specifying, -\fBC 2\fR or -\fBC pib\fR will write parameters only.
The value \fB3\fR is the logical OR of \fB1\fR and \fB2\fR and could be specified as -\fBC all\fR.
The device DAK must appear on the same line as option -\fBC\fR because a valid DAK is required for the commit operation.

.PP
   # ampinit -N new.nvm 01:23:45:67:89:28
   # ampinit -P new.pib 01:23:45:67:89:28
   # ampinit -C 3 -D 00:11:22:33:44:55:66:77:88:99:BB:CC:DD:EE:FF 01:23:45:67:89:28 

.PP
The next example downloads file \fBnew.nvm\fR and file \fBnew.pib\fR and force flashes the \fBlocal\fR device.
Force flashing only works with running firmware that has been downloaded and started by the Atheros Bootloader.
See \fBint6kfp\fR to download, start firmware and perform a force flash in one operation.

.PP

.PP
   # ampinit -N new.nvm -P new.pib -D 01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF -FF local 

.PP
The next two commands are equivalent.
They set the NMK on the local device to \fBkey1\fR as descripted in the \fBKEYS\fR section.
The first command resets the NMK on the local device with -\fBM\fR then specifies the NMK as \fBkey1\fR.
The second command omits the key specification since \fBkey1\fR is the program default NMK.
One could, of course, type the full encryption key.

.PP
   # ampinit -MK key1
   # ampinit -M

.PP
The next command erases the flash memory on the local device using \fBkey1\fR as the device DAK.
Assuming that the device DAK matches, NVRAM will be erased.
Some older versions of Atheros firmware do not support the erase operation.

.PP
   # ampinit -ED key1

.PP
The next command is similar to the previous example but erases only flash memory sector \fB5\fR on the local device because option -\fBX\fR was specified.
Again, some older versions of Atheros PLC firmware do not support this operation;

.PP
   # ampinit -X 5 -D key1

.SH SEE ALSO
.BR AMP ( 1 ),
.BR amptool ( 1 ),
.BR amphost ( 1 ),
.BR amprate ( 1 ),
.BR ampstat ( 1 )

.SH CREDITS
 Charles Maier <cmaier@qca.qualcomm.com>
 Nathaniel Houghton <nhoughto@qca.qualcomm.com>