Firmware
Introduction
An Atheros chipset consists of an integral CPU, ROM and proprietary circuitry. The CPU requires a minimum amount of external SDRAM to execute runtime software and store runtime configuration parameters. The INT6000 chipset also requires a minimum amount of external flash memory in order to start. The INT6300 can use external flash memory in the same way as the INT6000 or it can use a local host processor as surrogate flash memory.
On startup, the SDRAM memory controller must be configured before runtime firmware and parameters are loaded. On the INT6000, runtime firmware and configuration parameters must be loaded from external flash memory. On the INT6300, it may be loaded from external flash memory or from a external host processor. Runtime firmware determines device capability. Runtime configuration parameters determine device network identity and personality.
The following sections identify and describe firmware related components and discuss some of the routine actions required to manage them. Consult the Atheros HomePlug AV Hardware Technical Reference Manual and HomePlug AV Firmware Technical Reference Manual for more information.
Firmware Components
Device initialization involves the following components. They are described here and then referenced throughout the toolkit documentation. You may want to read and re-read this page.
Bootloader
The Bootloader is permanent software burned into the chipset. The INT6000 and INT6300 both have a Bootloader program but they behave differently because the INT6000 needs flash memory and the INT6300 does not. Neither the INT6000Bootloader nor the INT6300Bootloader can write to flash memory.
On startup, the INT6000Bootloader attempts to load runtime firmware from flash memory into SDRAM. If flash memory is not available, or the runtime firmware stored there cannot be loaded, then the INT6000Bootloader cannot continue so the device cannot function.
On startup, the INT6300Bootloader attempts to load runtime firmware from flash memory into SDRAM. If flash memory is not available, or the runtime firmware stored there cannot be loaded, then Bootloader will request runtime firmware from the local host processor.
Softloader
An optional program stored in flash memory in place of runtime firmware. This program is used on the INT6000 to support the Boot From Host operation, if needed. It is not used on the INT6300 because the INT6300Bootloader now performs similar functions. The Softloader cannot write to flash memory.
On startup, the INT6000Bootloader loads the Softloader from flash memory into SDRAM, as it would do with runtime firmware. The Softloader then requests the actual runtime firmware from local host.
Memory Configuration Parameters
A small block of information that describes the type, size and characteristics of the SDRAM available for the benefit of the Bootloader. On the INT6000, SDRAM configuration must be stored in flash memory. On the INT6300, it may be stored in flash memory or on the local host. The INT6300Bootloader attempts to read configuration information from flash memory when it is present; otherwise, it requests that information from the local host using a VS_HST_ACTION message and so the host must store this information until it is requested.
There are two SDRAM configuration file formats. The first format is used by the Windows Device Manager and the int6k2 program and typically has a .config file extension. The second format is used by the int6k program and int6kf program and typically has a .cfg file extension. The latter format is more robust and should eventually replace the format.
The Windows Device Manager form consists of 64 hexadecimal ASCII characters. Files are at least 64 bytes but only the first 64 bytes are used. Files can be modified using a text editor. ASCII hex to binary conversion and checksum computation is needed on input. The config2cfg program can be used to convert this format to Open Powerline Toolkit format.
The Open Powerline Toolkit format consists of 32 binary bytes plus a 4 byte checksum. The file size is exactly 36 bytes. No conversion or checksum computation is needed on input. The chkcfg program can be used the validate this file format because it contains a checksum.
The INT6400 chipset does not need a memory configuration parameter file because it has a different memory controller than earlier chipsets. SDRAM is now configured dynamically by an applets stored in the .nvm file.
Runtime Firmware (MAC Software)
The executable image that determines INT6000 or INT6300 capability and functionality. Runtime firmware refers to any executable image except the Bootloader which is considered to be boot firmware. Firmware files have a .nvm extension and can contain multiple firmware images. One of these images could be the parameter information block but Atheros currently distributes that as a separate file. The chknvm program can be used to detect obsolete or corrupt .nvm files. Runtime firmware can write to flash memory and must be running in order to re-program the chipset.
Parameter Information Block (PIB)
The configuration image that determines device network identity, functional capability and operational mode. The PIB structure often changes from one major firmware release to the next and often is not portable across major releases. Parameter information files have a .pib extension by convention and contain one parameter set. The chkpib program can be used to detect obsolete or corrupt PIB files.
Recent firmware releases support two PIB images in flash memory: the Factory PIB and the User PIB. The Factory PIB is the first PIB image written to flash memory. Once written, the Factory PIB cannot be changed without special software. The User PIB is created and over-written whenever the device needs to save new PIB parameters. Factory default values are restored by erasing the User PIB and rebooting the device. When a device reboots, it attempts to load the User PIB from flash memory. Failing that, it attempts to load the Factory PIB from flash memory. Failing that, it loads a Default PIB having minimum functionality. The loaded PIB becomes the Working PIB and determines runtime device identity and behavior.
Architecture Overview
The following figure illustrates a hypothetical powerline network consisting of two devices. Each device has an INT6300 with optional dedicated flash memory and an onboard processor with associated storage. The processor in each device is the local host for that device and the remote host for the other device. The processor storage is unspecified but it must be persistent. The two devices are connected via coax or powerline. The flash memory is optional in this design because it uses the INT6300 chipset.
Simple Network
The Boot Loader is permanent program that executes on startup. It detects the presence of flash memory and attempts to read SDRAM configuration from flash memory then load and runtime the firmware image and PIB from flash memory. On success, the Boot runtime firmware starts and the device assumes HomePlug AV compliant behavior. On failure, the Boot Loader requests SDRAM configuration, runtime firmware image and PIB from the local host. The local host must be prepared to respond to these requests.
On a system having no flash memory, the Boot Loader will request SDRAM configuration information from the local host. Once that is received, the Boot Loader will request a firmware image and PIB from the local host. The local host determines which firmware image and PIB to download, manages the download sequence and starts firmware execution.
Atheros software, such as the Windows Device Manager, Linux Flash Utility and Embedded API all support the Boot from Host configuration.
Once the firmware is running on the INT6300 , a remote host can forward runtime firmware and PIB to the local host via the INT6300 firmware. The remote host might reside on anotherINT6300 device, as shown in the previous figure, or be located anywhere on the HomePlug AV network. In either case, the operations described are the same.
Firmware Boot Process
The INT6300 can boot HomePlug AV firmware from either dedicated flash memory or a local host processor. This means that dedicated flash memory in not necessary when an onboard processor having persistent storage is available. The absence of dedicated flash memory and availability of an onboard host processor is called a Boot from Host configuration.
The Boot from Host configuration is of interest to customers who are committed to using a host processor in their INT6300 based product and want to use it to eliminate the additional cost of dedicated flash memory to store HomePlug AV firmware for INT6300 devices.
The Boot from Host configuration supports three operations: Upgrade Device, Update Local Host and Boot from Host. Product designers must write host software to support all three operations as described later in this document. Atheros provides an Embedded Application Program Interface to assist product designers with this effort. Obtain a copy of the HomePlug AV Application Programming Interface User's Guide from Atheros Communications, Ocala FL USA for more information.
Readers should not confuse a Boot from Host configuration with the Boot from Host operation. The former is a hardware configuration having an INT6300 with no dedicated flash memory available. The latter is the process of downloading configuration information, firmware and PIB from the local host to the device and starting firmware execution on startup.
This discussion assumes that the reader is familiar with the following:
The distinction between a local and remote host
The relationship between the powerline device H1, M1 and PHY interfaces.
The structure of the following Atheros Management Message types: VS_HST_ACTION, VS_SET_SDRAM, VS_WR_MEM, VS_WR_MOD, VS_RS_DEV, VS_ST_MAC and VS_WRITE_AND_EXECUTE. Be aware that message types VS_SET_SDRAM, VS_WR_MEM, VS_WR_MOD and VS_ST_MAC are deprecated and will no longer be supported by the newest firmware.
Hardware architecture covered in the QCA Powerline Hardware Technical Reference Manual and the management message formats covered in the QCA Powerline Firmware Technical Reference Manual.
Boot from Host Configuration
The Boot from Host configuration requires a permanent connection between the powerline device and a local host having some type of persistent storage. In most cases, the powerline device and local host are co-located, possibly on the same board or same chip, and act together as an integral unit. Essentially, the local host provides persistent memory for the device.
The Boot from Host configuration lets the local host decide which runtime parameters and firmware to download on startup. This offers a considerable degree of product adaptability, allowing different parameter and firmware combinations to be downloaded based on external factors.
In a Boot from Host configuration, the processor must act as local host while the device is booting but it can also act as remote host when upgrading other devices. The former is a design requirement and latter is a design option.
Things to Remember
The Boot from Host configuration offers design flexibility but also increases the possibilities. Remember that the processes described here are based on simple rules that ultimately dictate why each process step is needed. Readers may find it helpful to review these rules.
The softloader and bootloader programs have limited vocabulary.
The INT6000 softloader recognizes only the VS_SW_VER, VS_ST_MAC, VS_RS_DEV, VS_WR_MOD requests. It does not recognize VS_WR_MEM.
The INT6300 bootloader recognizes only the VS_SW_VER, VS_WR_MEM, VS_ST_MAC, VS_RS_DEV and VS_SET_SDRAM requests. It does not recognize VS_WR_MOD.
The INT6400 bootloader recognizes only the VS_SW_VER, VS_WR_MEM, VS_ST_MAC, VS_RS_DEV requests. It recognizes VS_SET_SDRAM and responds to it but ignores it. It does not recognize VS_WR_MOD.
The AR7400 bootloader recognizes only VS_SW_VER, VS_WR_MEM, VS_ST_MAC, VS_RS_DEV requests. It recognizes VS_SET_SDRAM and responds to it but ignores it. It does not recognize VS_WR_MOD.
The AR7420 bootloader recognizes only VS_SW_VER, VS_RS_DEV, VS_WRITE_AND_EXECUTE and VS_RAND_MAC_ADDRESS requests. Early versions recognize VS_WRITE_MEM and VS_ST_MAC requests but they must not be used.
Softloader/Bootloader MMEs
MME
NAME
INT6000 Softloader
INT6300 Bootloader
INT6400 Bootloader
AR7400 Bootloader
AR7420 Bootloader
0xA000
VS_SW_VER
Yes
Yes
Yes
Yes
Yes
0xA008
VS_WR_MEM
No
Yes
Yes
Yes
Deprecated
0xA00C
VS_ST_MAC
Yes
Yes
Yes
Yes
Deprecated
0xA01C
VS_RS_DEV
Yes
Yes
Yes
Yes
Yes
0xA020
VS_WR_MOD
Yes
No
No
No
No
0xA05C
VS_SDRAM
No
Yes
Ignored
Ignored
No
0xA060
VS_HOST_ACTION
No
Yes
Yes
Yes
Yes
0xA098
VS_WRITE_AND_EXECUTE
No
No
No
Yes
Yes
0xA0D4
VS_RAND_MAC_ADDRESS
No
No
No
Yes
Yes
The Softloader, Bootloader and runtime firmware may treat the same MME differently because each is a different program. A notorious obvious example is the VS_SW_VER message type. This means that one may need to be aware of the device state when anticipating device behaviour or interpreting device response.
The local host is surrogate flash memory. When dedicated flash memory is not available to a device, the device will request firmware and parameter storage services from the local host using VS_HST_ACTION messages. The local host must be programmed to detect and respond to these messages or the firmware will appear to hang. See program int6khost, int64host, amphost or plchost to demonstrate and experiment with this interaction.
Only runtime firmware can write flash memory. Runtime firmware must be executing in order to write flash memory or upload to the local host. The Softloader and Bootloader cannot perform either operation.
All PIB changes must be written in flash memory. There are several things that can cause PIB changes. When a PIB change is needed, the Working PIB is copied to a scratch area and modified there. The Scratch PIB must then be written to flash memory or sent to the local host for storage. The device then resets causing the stored PIB to replace the Working PIB. If a freshly downloaded PIB changes for any reason then the cycle will repeat, automatically.
Runtime firmware updates the PIB after joining and before leaving an AVLN. This will cause a device reset in each case. If the device is using the local host for persistent storage, runtime firmware will send the associated VS_HST_ACTION messages to the host and the host will send the associated VS_RD_MOD and VS_RS_DEV messages as per Update Local Host.
Every Little Bit Hurts
With the addition of Push Button Encryption, and other planned features, runtime firmware can now modify the PIB. Consequently, host applications must not assume that the PIB has not changed since it was last downloaded. Atheros strongly recommends that applications always perform a read-modify-write when making PIB modifications. Failure to do so can result in infinite reset loops caused when a device modifies the PIB that has just been downloaded.
As one example, recent PIBs contain a network membership bit to indicate that the device has successfully joined the network associated with the current NMK. If the firmware detects the network and discovers that the membership bit is clear then it will join the network and set the bit. The firmware will then attempt to preserve the change by sending a VS_HOST_ACTION message to the local host. If the host application does not upload and store the changed PIB (as the device requested) before resetting the device then the original PIB will be downloaded again, after reset, and the process will repeat. Of course, a similar situation will occur when the device leaves the network and again when it joins another network.
Liar! Liar! Pants on Fire!
It is important to use the right Boot from Host sequence for each type of Atheros device. This means that you should query the device using a VS_SW_VER message beforehand to determine or confirm the device type. Although this should be a simple operation, there have been several changes that complicate matters.
The INT6300Bootloader incorrectly identifies the chipset as an INT6000 chipset in the MDEVICEID field of the VS_SW_VER message.
The AR7400Bootloader incorrectly identifies the chipset as an INT6400 chipset in the MDEVICEID field of the VS_SW_VER message.
The Bootloader, for INT6400 chipsets and later, returns two additional field, IDENT and STEP_NUMBER in the VS_SW_VER confirmation message. These fields, the hardware identifier and step number, are correct but are not returned in earlier chipsets.
The table below illustrates what is reported by various firmware, in the DEVICEID field of the VS_SW_VER message, on each type of hardware platform.
To properly detect the correct chipset perform the following steps.
Send a VS_SW_VER request message from the local host to the local device using the Atheros Local Management Address.
Read the VS_SW_VER confirm message returned to the host by the device.
Extract and save the MDEVICEID field (a small integer) and the MVERSION field (a string).
If the MVERSION string is SoftLoader then the MDEVICEID field is valid.
If the MVERSION string is not BootLoader then the MDEVICEID field is valid unless it is 0x07. In that case, set the stored DEVICEID to 0x04 to indicate an AR7400. Do not inspect the IDENT field because it does not exist in the firmware version of the VS_SW_VER message on any platform.
If the MDEVICEID field is 1, indicating an INT6000, then the chipset is actually an INT6300. Set the stored MDEVICEID to 2, indicating an INT6300. Do not inspect the IDENT field because it does not exist in the BootLoader version of the VS_SW_VER message for either of these two chipsets.
If the MDEVICEID field is 3, indicating an INT6400, then the chipset could be either an INT6300 or an AR7400. Inspect the IDENT field.
If the IDENT field is 0x6400, indicating an INT6400, then the stored MDEVICEID is valid.
If the IDENT field is 0x7400, indicating an AR7400, then set the stored MDEVICEID to 4, indicating an AR7400.
Having performed the previous conversions, the expression (1 << (DEVICEID - 1)) now indicates the proper IGNORE bit found in each NVM file header. Unfortunately, this only works for DeviceID values from 0x01 through 0x06. After that, the device identification scheme changes.
But wait! There's more ...
Starting with the AR7420, the DeviceID field in VS_SW_VER is now the DEVICE_CLASS field and identifies the Device Family, not the device type. Instead, the IDENT field in VS_SW_VER identifies the device type and the IDENT field is located at a variable offset within the message frame. Previously, the IDENT was located a fixed offset within the frame.