# 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 INT6000 Bootloader nor the INT6300 Bootloader can write to flash memory.

On startup, the INT6000 Bootloader 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 INT6000 Bootloader cannot continue so the device cannot function.

On startup, the INT6300 Bootloader 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 INT6300 Bootloader now performs similar functions. The Softloader cannot write to flash memory.

On startup, the INT6000 Bootloader 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 INT6300 Bootloader 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:

1. The distinction between a local and remote host

2. The relationship between the powerline device H1, M1 and PHY interfaces.

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

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

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

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

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

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

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

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

1. The INT6300 Bootloader incorrectly identifies the chipset as an INT6000 chipset in the `MDEVICEID` field of the `VS_SW_VER` message.

2. The AR7400 Bootloader incorrectly identifies the chipset as an INT6400 chipset in the `MDEVICEID` field of the `VS_SW_VER` message.

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

### Legacy Device Identification

Chipset | DEVICEID/IDENT (Bootloader) | MVERSION (Bootloader) | DEVICEID/IDENT (Firmware) | MVERSION (Firmware)
--- | --- | --- | --- | ---
INT6000 | 0x01 / 0x00000042 | BootLoader | 0x01 / na | INT6000-MAC-0-0-3213-1206-20071224-FINAL
INT6300 | 0x02 / 0x00006300 | BootLoader | 0x02 / na | INT6300-MAC-0-0-4203-00-4089-20091105-FINAL
INT6400 | 0x03 / 0x00006400 | BootLoader | 0x03 / na | INT6400-MAC-4-3-4304-01-4397-20100924-FINAL
INT7400 | 0x03 / 0x00007400 | BootLoader | 0x04 / na | INT7400-MAC-5-2-5213-01-1027-20110428-FINAL
INT7450 | 0x03 / 0x0F001D1A | BootLoader | 0x20 / 0x00001D1A | QCA7450-MAC-5-2-5213-01-1027-20110428-FINAL
INT7451 | 0x03 / 0x00007400 | BootLoader | 0x20 / 0x0E001D1A | QCA7451-MAC-5-2-5213-01-1027-20110428-FINAL
AR6405 | 0x03 / 0x00006400 | BootLoader | 0x05 / na | INT6405-MAC-4-3-4304-01-4397-20100924-FINAL
AR7420 | 0x05 / 0x001CFCFC | BootLoader | 0x20 / 0x001CFCFC | MAC-QCA7420-2.5.14.2259-23-20110621-FINAL
QCA6410 | 0x05 / 0x001B58EC | BootLoader | 0x21 / 0x001B58EC | MAC-QCA6410-2.5.14.2259-23-20110621-FINAL
QCA6411 | 0x05 / 0x001B58BC | BootLoader | 0x21 / 0x001B58BC | MAC-QCA6411-2.5.14.2259-23-20110621-FINAL
QCA7000 | 0x05 / 0x001B589C | BootLoader | 0x22 / 0x001B589C | MAC-QCA7000-1.4.13.3259-43-20110621-FINAL

To properly detect the correct chipset perform the following steps.

1. Send a `VS_SW_VER` request message from the local host to the local device using the Atheros Local Management Address.

2. Read the `VS_SW_VER` confirm message returned to the host by the device.

3. Extract and save the `MDEVICEID` field (a small integer) and the `MVERSION` field (a string).

4. If the `MVERSION` string is SoftLoader then the `MDEVICEID` field is valid.

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

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

7. If the `MDEVICEID` field is `3`, indicating an INT6400, then the chipset could be either an INT6300 or an AR7400. Inspect the `IDENT` field.

8. If the `IDENT` field is `0x6400`, indicating an INT6400, then the stored `MDEVICEID` is valid.

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

### Device Identification

Chipset | Softloader | Bootloader | Firmware | Identity
--- | --- | --- | --- | ---
INT6000 | 0x01 |  | 0x01 | 0x00000042
INT6300 |  | 0x01 | 0x02 | 0x00006300
INT6400 |  | 0x03 | 0x03 | 0x00006400
AR7400 |  | 0x03 | 0x04 | 0x00007400
AR6405 |  | 0x03 | 0x05 | 0x00006400
AR7420 |  | 0x05 | 0x20 | 0x001CFCFC
QCA6410 |  | 0x05 | 0x21 | 0x001B58EC
QCA7000 |  | 0x05 | 0x22 | 0x001B589C

&firmware-6000-flash; &firmware-6000-upload; &firmware-6000-boot; &firmware-6300-boot; &firmware-6400-boot; &firmware-7400-boot; &firmware-7420-boot; &firmware-7420-flash;