Tool for programming Tock onto hardware boards.
pip3 install tockloader --user
If you want tab completions:
register-python-argcomplete tockloader >> ~/.bashrc
This tool installs a binary called tockloader
, which supports several commands.
These are the main commands for managing apps on a board.
Load Tock applications on to the board. Use --no-replace
to install
multiple copies of the same app.
Update an application that is already flashed to the board with a new binary.
Remove an application from flash by its name.
These query the board for its current state.
Print information about the apps currently loaded onto the board.
Show all properties of the board.
These provide other helpful features.
Listen to UART printf()
data from a board. Use the option --rtt
to use
Segger's RTT listener instead of using a serial port.
These provide more internal functionality.
Load binaries onto hardware platforms that are running a compatible bootloader.
This is used by the TockOS Make system
when kernel binaries are programmed to the board with make program
.
Show details about a compiled TAB file.
Enable an app so that the kernel will run it at boot.
Disable an app so that the kernel will not start it at boot.
Mark an app as sticky so that the --force
flag is required to uninstall it.
Remove the sticky flag from an app.
Show all of the attributes that are stored on the board.
Set a particular attribute key to the specified value. This will overwrite an existing attribute if the key matches.
Remove a particular attribute from the board.
Show the contents of a page of flash.
Read arbitrary flash memory from the board.
Print which boards tockloader has default settings for built-in.
For tockloader to know how to interface with a particular hardware board, it typically reads attributes from the bootloader to identify properties of the board. If those are unavailable, they can be specified as command line arguments.
tockloader [command] --arch [arch] --board [board]
arch
: The architecture of the board. Likelycortex-m0
orcortex-m4
.board
: The name of the board. This helps prevent incompatible applications from being flashed on the wrong board.
Tockloader also supports a JTAG interface using JLinkExe. JLinkExe requires knowing the device type of the MCU on the board.
tockloader [command] --jlink --arch [arch] --board [board] \
--jlink-cmd [jlink_cmd] --jlink-device [device] --jlink-speed [speed] --jlink-if [if]
jlink_cmd
: The JLink executable to invoke. Defaults toJLinkExe
on Mac/Linux, andJLink
on Windows.device
: The JLinkExe device identifier.speed
: The speed value to pass to JLink. Defaults to 1200.if
: The interface to pass to JLink.
Tockloader can also do JTAG using OpenOCD. OpenOCD needs to know which config
file to use. Note: you will likely need an up-to-date version of OpenOCD for
everything to work. On MacOS you can use brew install --HEAD openocd
to get
a version from git.
tockloader [command] --openocd --arch [arch] --board [board] --openocd-board [openocd_board] \
--openocd-cmd [openocd_cmd] --openocd-options [openocd_options] \
--openocd-commands [openocd_commands]
-
openocd_board
: The.cfg
file in the board folder in OpenOCD to use. -
openocd_cmd
: The OpenOCD executable to invoke. Defaults toopenocd
. -
openocd_options
: A list of Tock-specific flags used to customize how Tockloader calls OpenOCD based on experience with various boards and their quirks. Options include:noreset
: Removes the commandreset init;
from OpenOCD commands.nocmdprefix
: Removes the commandsinit; reset init; halt;
from OpenOCD commands.workareazero
: Adds the commandset WORKAREASIZE 0;
to OpenOCD commands.resume
: Adds the commandssoft_reset_halt; resume;
to OpenOCD commands.
-
openocd_commands
: This sets a custom OpenOCD command string to allow Tockloader to program arbitrary chips with OpenOCD before support for the board is officially include in Tockloader. The following main operations can be customized:program
: Operation used to write a binary to the chip.read
: Operation used to read arbitrary flash memory on the chip.erase
: Operation that erases arbitrary ranges of flash memory on the chip.
The custom values are specified as key=value pairs, for example,
--openocd_commands 'program=write_image; halt;' 'erase=flash fillb {address:#x} 0xff 512;'
. Operation strings can include wildcards which will get set with the correct value by Tockloader:{{binary}}
: The binary file path.{address:#x}
: The specified address for the binary to be programmed at.{length}
: The number of bytes. Only valid for theread
operation.
Install an app, make sure it's up to date, and make sure it's the only app on the board:
tockloader install --make --erase
Get all info from the board that can be used to help debugging:
tockloader info
Print additionally debugging information. This can be helpful when using JTAG.
tockloader install --debug
Get printf()
data from a board:
tockloader listen
There are additional flags that might be useful for customizing tockloader's operation based on the requirements of a particular hardware platform.
--app-address
: Manually specify the address at the beginning of where apps are stored. This can be in hex or decimal.--rewrite-apps
: This forces tockloader to re-write all apps anytime that any app changes in any way (e.g. its header changes or the app is updated or a new app is installed.). Additionally, tockloader will completely erase the app flash region between saving any existing apps from the board and then re-flashing the apps with any changes.
- Supported communication protocols
- Serial over USB
- Segger JLinkExe JTAG support
- OpenOCD JTAG support
- JLink RTT listener
Tockloader is a Python script that is installed as an executable. To use Tockloader, you need python3, a couple dependencies, and the Tockloader package.
-
Ubuntu
sudo apt install python3-pip pip3 install -U pip --user # update pip pip3 install tockloader --user
-
MacOS
brew install python3 pip3 install tockloader
-
Windows
- Download and Install Python 3
- Execute within CMD/PowerShell/...:
pip3 install tockloader
To test the code locally without installing as a package, from the top-level directory:
python3 -m tockloader.main <COMMANDS>
python3 setup.py sdist bdist_wheel
twine upload dist/*
pip3 install mkdocs
cd docs
./generate_docs.py
cd ..
mkdocs serve --dev-addr=0.0.0.0:8001