plcboot(1)

💖 plcboot — Qualcomm Atheros Panther/Lynx Powerline Device Bootstrapper 💖

okay bestie, welcome to plcboot(1) from the Qualcomm Atheros Open Powerline Toolkit. this is the glow-up-your-bricked-powerline-device page and i'm SO excited to walk you through it 🫶

✨ SYNOPSIS ✨

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

🌸 DESCRIPTION 🌸

so basically? this downloads and starts runtime firmware on a local powerline device when it's stuck in bootloader mode. a device ends up in bootloader mode if it has no flash memory at all, or if it just can't load firmware from flash for some reason. you can use this program to start the device and then, optionally, permanently write a softloader, parameters and firmware into flash memory. iconic behavior honestly.

Qualcomm Atheros introduced new boot methods with the Lightning chipset, and new file formats and flash methods with the Panther chipset. this program supports the newer formats and methods. it does not support the older formats and methods. if you need to initialize earlier chipsets, go see programs int6kboot or ampboot. not our problem, not our era 💅

this program is part of the Qualcomm Atheros Powerline Toolkit. see the plc man page for an overview and installation instructions.

👑 OPTIONS 👑

• -e — redirects stderr messages to stdout. normally, status and error messages go on stderr while the primary program output goes on stdout. this option prints everything on stdout in cases where that's what you want. one stream, one vibe ✨
• -F[F] — Flash or Force Flash NVRAM using either VS_MOD_NVM or VS_MODULE_OPERATION. adding a second F here, or another -F anywhere on the command line, will force-flash a blank or corrupted NVRAM. careful though bestie: firmware loaded from NVRAM may treat force-flash as an error, depending on the firmware version 😭
• -i interface — select the host Ethernet interface. all requests are sent via this host interface and only responses received via this host interface are recognized. the default interface is eth1 because most people use eth0 as their principle network connection. however, if the environment string "PLC" is defined then it takes precedence over the default interface. and this option takes precedence over either default. hierarchy, periodt 👑
• -N filename — the file containing the firmware chain used to boot and flash the device. this option and argument are required when booting or flashing a device, but may appear anywhere on the command line. invalid image files will be rejected. no assumptions are made about this file based on filename and no filename conventions are enforced. call it whatever you want, it's your life 🦋
• -P filename — the file containing the firmware chain used to boot and flash the device. this option and argument are required when booting or flashing a device, but may appear anywhere on the command line. invalid image files will be rejected. no assumptions are made about this file based on filename and no filename conventions are enforced. yes it reads the same as -N, they're both firmware chain files, that's just how it is 💀
• -q — suppresses status messages on stderr. quiet little icon, love that for you 🤫
• -S filename — the file containing the softloader chain used to flash the device. on prior versions of plcboot, the mere presence of this option meant flash memory should be programmed — that is no longer the case. you must now specify both this option and option -F in order to program flash memory. this option and argument are required when flashing a device, but may appear anywhere on the command line. invalid image files will be rejected. no assumptions are made about this file based on filename and no filename conventions are enforced.
• -t milliseconds — 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. in particular, this option dumps outgoing Ethernet packets on stdout. nosy in the best way 🔍
• -?,--help — print program help summary on stdout. this option takes precedence over other options on the command line. main character energy fr fr.
• -!,--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. receipts, bestie 🧾

💜 ARGUMENTS 💜

• device — the Ethernet hardware address of some powerline device. more than one address may be specified on the command line. if more than one address is specified then operations are performed on each device in turn. the default address is local, as explained in the DEVICES section. multi-task slay.

🎀 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 are not required. for example, "00b052000001", "00:b0:52:00:00:01" and "00b052:000001" are all valid and equivalent. the way that format is flexible?? we love a range 🌈

• 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. not one of ours, no thoughts.

common device addresses have symbolic names that can be used in place of the actual address value. the following symbolic addresses are recognized by this program and most other toolkit programs:

• 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 will not.

🦋 REFERENCES 🦋

see the Qualcomm Atheros HomePlug AV Firmware Technical Reference Manual for technical information. see the Qualcomm Atheros Powerline Toolkit Online Documentation for practical information and examples. reading is fundamental, bestie 📚

🔥 EXAMPLES 🔥

this example boots a powerline device by downloading runtime parameters and firmware then starting firmware execution. the actual boot method used will depend on the file formats and powerline device type detected by the program. the output shown here is typical for panther and lynx chipsets. options -P and -N are required but their order is not important. the MAC address may be omitted because it will default to 00:B0:52:00:00:01, which is also the default bootloader device address. on completion, runtime firmware is executing in SDRAM but flash memory has not been programmed. this operation is common for flash-less devices. if we reset the device at this point then it will return to bootloader mode. no cap.

# plcboot -P AR7420.pib -N AR7400.nvm
eth1 00:B0:52:00:00:01 BootLoader is running
eth1 00:B0:52:00:00:01 Write AR7420.nvm (1) (0x00000040:6212)
eth1 00:B0:52:00:00:01 Start AR7420.nvm (1) (0x000000C0)
eth1 00:B0:52:00:00:01 Write AR7420.pib (1) (0x00200000:10904)
eth1 00:B0:52:00:00:01 Write AR7420.nvm (5) (0x002B610C:281252)
eth1 00:B0:52:00:00:01 Start AR7420.nvm (5) (0x002B64FC)
eth1 00:B0:52:BA:BE:88 MAC-QCA7420ES-0.9.0.278-0-20110914-INTERNAL is
running

the next example boots a device, as before, then flashes the same parameters and firmware into non-volatile memory attached to the device. observe that a softloader is required and will be written to flash memory before runtime parameters and firmware. the softloader need only be written once when first programming a blank flash memory. option -FF is optional but permitted for backward compatibility with programs ampboot and int6kboot. nostalgic and cute 🎀

# plcboot -P AR7420.pib -N AR7400.nvm -S AR7420-softloader.nvm -FF
eth1 00:B0:52:00:00:01 Write AR7420.nvm (1) (00000040:6212)
eth1 00:B0:52:00:00:01 Start AR7420.nvm (1) (000000C0)
eth1 00:B0:52:00:00:01 Write AR7420.pib (1) (00200000:11692)
eth1 00:B0:52:00:00:01 Write AR7420.nvm (5) (002B6A4C:282444)
eth1 00:B0:52:00:00:01 Start AR7420.nvm (5) (002B6E3C)
eth1 00:B0:52:00:00:06 MAC-QCA7420ES-1.0.0.280-00-20110923-ALPHA is
running
eth1 00:B0:52:00:00:06 Start Session
eth1 00:B0:52:00:00:06 Flash AR7420-softloader.nvm
eth1 00:B0:52:00:00:06 Close Session
eth1 00:B0:52:00:00:06 Start Session
eth1 00:B0:52:00:00:06 Flash AR7420.pib
eth1 00:B0:52:00:00:06 Flash AR7420.nvm
eth1 00:B0:52:00:00:06 Close Session

😭 DISCLAIMER 😭

okay bestie, legal voice time. Qualcomm Atheros firmware file structure and content is proprietary to Qualcomm Atheros, Ocala FL USA. consequently, public information is not available. Qualcomm Atheros reserves the right to change firmware file structure or content, or change the name or behavior of any program that inspects or changes firmware files, in future software releases without any obligation to notify or compensate users of such programs. Qualcomm Atheros HomePlug AV Vendor Specific Management Message 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. they said what they said 💀

🌟 SEE ALSO 🌟

ampboot(1), amptool(1), chknvm(1), chkpib(1), int6kboot(1), modpib(1), plctool(1)

go read those next, the whole friend group is iconic 🫶

💖 CREDITS 💖

Charles Maier

and that's the whole page!! this cutie came from open-plc-utils-0.0.3, dated November 2013 — yes it's a vintage icon and yes it still eats. bye bestie, go boot something 👑✨💅