Add Toad, the USB micro dev companion.

This utility prefers to use the newer libftdi1 (not the 0.x version being
distributed currently), due to its (meagre) asynchronous transfer support.
This will still compile using libftdi 0.x, but console mode and the initialize
commands will be disabled.

The output of the Toad commands is designed to be very shell-script-friendly;
querying commands (status, getmode, etc) can be wrapped in "eval" to set a few
shell variables.

There is a hacky workaround to initialize the CBUS bit-bang mode when the
command is run on a Toad that has just been plugged in. The FTDI chip does not
seem to expose any better way to work around the issue, unfortunately.

When compiled with libftdi1, Toad includes a completely self-contained console
mode with some bonus keyboard escapes, so no ftdi_sio module or serial console
software is necessary.  Of course, on machines with ftdi_sio, this utility is
unnecessary for simple AP and EC console access. For machines with both,
libftdi1 will automatically disable the ftdi_sio module when you run the

Even libftdi1 does not fully support the FT230X in use, so the initialize
command has its own EEPROM modification and checksumming code.

TEST=Play with the hardware:

1) Compile with the old libftdi 0.x; plug in one programmed Toad
Get the serial number: ./toad list
This should do the same thing: ./toad --serialname=$THE_SERIAL list
This should do the same thing, with more messages: ./toad --serialname= list
This should again do the same thing, with more messages: ./toad -s all list
Play with LEDs: ./toad ecap toggle
Spit out a file as boot code (don't do this plugged in): ./toad boot toad.c
Get the current mode: ./toad getmode
Turn the LEDs off: ./toad vbus off
Turn them back on: ./toad setmode boot
Go back to normal: ./toad boot off
Make sure the status is sane: ./toad status
This won't find any devices: ./toad initialize
This will find one, but won't work under the old libftdi: ./toad -f initialize
This still won't work under the old libftdi: ./toad initialize -f

2) Compile with the new libftdi 1.x; plug in one programmed Toad
Try everything in #1, up until the initialize commands.
This won't find any devices: ./toad initialize
This should work, though: ./toad -f initialize
But this shouldn't: ./toad -s $THE_SERIAL initialize
But this should: ./toad -s $THE_SERIAL initialize -f
Enter console mode: ./toad console
Switch between AP and EC in console mode: ^X^A, ^X^E
Forgot the escapes!: ^Xh
Cancel out: ^X^C. If you check the return code ($?) it should be non-zero.
Enter console mode again, this time start on the AP: ./toad ap
End console mode: ^X^D. The return code should be zero (success).
Enter console mode once more, on the EC: ./toad ec
Background console mode: ^X^Z. The terminal should be OK (not in raw mode).
Return using "fg". We should be in raw mode again.
If you can get something that echos (like a DUT or a loopback), see if you get
echos. Note that a straight loopback will not convert carriage returns (the
enter key) into linefeeds, so you won't get any newlines.
Unplug Toad. Console mode should error out.

3) Keep the new libftdi 1.x version; plug in a bunch of unprogrammed Toads
Program ALL the Toads!: ./toad -s all initialize
Make sure they're all programmed: ./toad -s all list
Unplug and plug them back in and make sure they're sane: ./toad -s all list

Change-Id: Ibf190dda8d45cb27e40dd19ef2fa21a87a1cd8b7
Reviewed-by: Todd Broch <>
Commit-Ready: David Schneider <>
Tested-by: David Schneider <>
5 files changed