ampboot(1)

Okay bestie, welcome to the ampboot manual 🎀 It's a tool from the Qualcomm Atheros Open Powerline Toolkit, and it's literally about getting AR7x00 powerline devices up and running. Let's go 💅

💜 NAME 💜

ampboot — Qualcomm Atheros AR7x00 Powerline Device Bootstrapper 🦋

🌸 SYNOPSIS 🌸

ampboot [options] -N file -P file [device] [device] [...]

✨ DESCRIPTION ✨

Okay so, ampboot downloads and starts runtime firmware on a local powerline device when it's stuck in bootloader mode 🥺 A device stays in bootloader mode when it can't load firmware from flash memory for some reason. That can happen if the device has no flash memory, or if the flash memory is blank or corrupted. You can use this program to start a device, or to start the device and then program flash memory once the runtime firmware is up and running ⚡

The bootloader only recognizes a subset of Atheros message types. This program uses that subset to write runtime firmware and parameters into SDRAM, then starts firmware execution. Optionally, it can go back and download the same firmware and parameters again, then commit them to flash memory 💖

Starting a device is a three phase operation 🧚 The first phase writes an SDRAM configuration program into TCM and executes it. The second phase writes runtime firmware and parameters as images into SDRAM. The third phase starts firmware execution. Once the runtime firmware starts, the device is operational ✨

Flashing a device is a two phase operation 🫶 The first phase downloads runtime firmware and parameters under firmware control into scratch buffers. The second phase tells the firmware to write those scratch buffers to flash memory and reboot the device. After flashing, the device is self-sustaining 💪

This program is part of the Qualcomm Atheros Powerline Toolkit. For an overview and installation instructions, check out the plc man page 📖

🎀 OPTIONS 🎀

• -e — Redirects stderr messages to stdout. By convention, status and error messages get printed on stderr, while the main program output goes to stdout. Use this option when you want everything on stdout 🖨️
• -F[F] — Writes previously downloaded MAC and PIB to NVRAM using VS_MOD_NVM. Adding a second F here, or another -F anywhere on the command line, will force-flash a blank or corrupted NVRAM 💀

⚠️ Firmware loaded from NVRAM will treat force-flash as an error.

⚠️ This option can be used to create factory settings, but it cannot be used to change them once they're created. Later uses create and update operational settings, which can be erased using a factory reset.

• -i interface — Selects the host Ethernet interface. All requests get sent through this host interface, and only responses received through this host interface are recognized 🌐 The default interface is eth1, because most people use eth0 as their principal network connection. BUT if the environment string PLC is defined, it takes precedence over the default interface. This option then takes precedence over either default 👑
• -N filename — Reads the named NVM file and writes it to the device. This option and its argument are required. Any file with an invalid NVM file format will be rejected. No assumptions are made based on the filename, and no filename conventions are enforced 📁
• -P filename — Reads the named PIB file and writes it to the device. This option and its argument are required. Any file with an invalid PIB file format will be rejected. No assumptions are made based on the filename, and no filename conventions are enforced 📁
• -q — Suppresses status messages on stderr 🤫
• -t milliseconds — Sets the 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 ⏱️
• -v — Prints additional information on stdout. Specifically, this option dumps outgoing Ethernet packets on stdout 🔍
• -?, --help — Prints the program help summary on stdout. This option takes precedence over other options on the command line 🙋
• -!, --version — Prints the program version information on stdout. This option takes precedence over other options on the command line. Use it when sending screen dumps to Atheros Technical Support, so they know exactly which version of the Linux Toolkit you're using 📸

🦋 ARGUMENTS 🦋

• device — The Ethernet hardware address of some powerline device. You can specify more than one address on the command line. If you do, operations are performed on each device in turn. The default address is local, as explained in the DEVICES section 🎯

🌈 DEVICES 🌈

Powerline device addresses are 12 hexadecimal digits in upper, lower or mixed case. Individual octets may be separated by colons for clarity, but colons aren't required. For example, 00b052000001, 00:b0:52:00:00:01 and 00b052:000001 are all valid and equivalent 🔢

A local device is any Atheros Powerline Device connected directly to a host Ethernet interface. A remote device is any Atheros Powerline Device at the far end of a powerline connection. A foreign device is any powerline device not manufactured by Atheros 🏠

Common device addresses have symbolic names you can use in place of the actual address value. This program and most other toolkit programs recognize the following symbolic addresses 💜

• all — Equivalent to broadcast, described next.
• broadcast — A synonym for the Ethernet broadcast address, FF:FF:FF:FF:FF:FF. All devices, whether local, remote or foreign, will respond to this address 📢
• local — A synonym for the Qualcomm Atheros Local Management Address (LMA), 00:B0:52:00:00:01. All local Atheros devices will respond to this address, but remote and foreign devices won't 🏡

📚 REFERENCES 📚

For technical info, see the Qualcomm Atheros HomePlug AV Firmware Technical Reference Manual 🤓 For practical info and examples, see the Qualcomm Atheros Powerline Toolkit Online Documentation 🔗

🎬 EXAMPLES 🎬

The -N and -P options are always required, and their order doesn't matter. You don't need a MAC address, because devices default to address 00:B0:52:00:00:01 (the program's default address) in bootloader mode 🥰 Once this operation completes, firmware is running in SDRAM, but the NVRAM (if present) hasn't been programmed. This operation is common for flash-less devices. If you reset the device at this point, it will go right back to bootloader mode 🔄

ampboot -N test.nvm -P test.pib
# eth0 00:B0:52:00:00:01 Write SDRAM Configuration
# eth0 00:B0:52:00:00:01 Written.
# eth0 00:B0:52:00:00:01 Write to device memory
# eth0 00:B0:52:00:00:01 Written.
# eth0 00:B0:52:00:00:01 Write to device memory
# eth0 00:B0:52:00:00:01 Written.
# eth0 00:B0:52:00:00:01 Start Firmware
# eth0 00:B0:52:00:00:01 Started.

The next example does the same thing but also does the extra steps needed to program NVRAM 🧁 First it downloads the firmware image from file test.nvm and the parameter block image from file test.pib using VS_WR_MEM, then starts firmware execution using VS_ST_MAC. Once runtime firmware has started, it downloads the same firmware image and parameter block image (again) using VS_WR_MOD, and commits them to NVRAM using VS_MOD_NVM 😤

ampboot -N test.nvm -P test.pib -F
# eth0 00:B0:52:00:00:01 Write SDRAM Configuration
# eth0 00:B0:52:00:00:01 Written.
# eth0 00:B0:52:00:00:01 Write to device memory
# eth0 00:B0:52:00:00:01 Written.
# eth0 00:B0:52:00:00:01 Write to device memory
# eth0 00:B0:52:00:00:01 Written.
# eth0 00:B0:52:00:00:01 Start Firmware
# eth0 00:B0:52:00:00:01 Started.
# eth0 00:B0:52:00:00:01 Write MAC as module
# eth0 00:B0:52:00:00:01 Written.
# eth0 00:B0:52:00:00:01 Write PIB as module
# eth0 00:B0:52:00:00:01 Written.
# eth0 00:B0:52:00:00:01 Flash Device
# eth0 00:B0:52:00:00:01 Flashed.

🙈 DISCLAIMER 🙈

⚠️ The Atheros HomePlug AV Vendor Specific Management Message structure and content is proprietary to Qualcomm Atheros, Ocala FL USA. Because of that, 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), amptool(1), chknvm(1), chkpib(1), modpib(1) 🦋

👑 CREDITS 👑

Charles Maier, the legend behind this one 🫶

Source: open-plc-utils-0.0.3, November 2013. Manual page: ampboot(1). That's the tea, bestie 🌸💅✨