Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: tock/tockloader
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: v1.8.0
Choose a base ref
...
head repository: tock/tockloader
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: master
Choose a head ref

Commits on Aug 30, 2021

  1. start on 1.9.0

    bradjc committed Aug 30, 2021
    Copy the full SHA
    021f440 View commit details

Commits on Feb 9, 2022

  1. Add SMA Q3 board

    dcz committed Feb 9, 2022
    Copy the full SHA
    d1f3b2f View commit details

Commits on Feb 17, 2022

  1. Add OpenOCD support for RTT

    dcz committed Feb 17, 2022
    Copy the full SHA
    e502a44 View commit details

Commits on Mar 7, 2022

  1. Merge pull request #78 from dcz-self/master

    Add RTT support for OpenOCD
    bradjc authored Mar 7, 2022
    Copy the full SHA
    0abc5d3 View commit details

Commits on Mar 8, 2022

  1. Copy the full SHA
    de88a22 View commit details
  2. Merge pull request #80 from tock/app-position-scenario

    Detect fixed vs. position independent vs. mixed apps case
    bradjc authored Mar 8, 2022
    Copy the full SHA
    e3f03cf View commit details

Commits on Mar 16, 2022

  1. RTT: Don't fail on corrupted output

    dcz committed Mar 16, 2022
    Copy the full SHA
    d58df88 View commit details

Commits on May 2, 2022

  1. deps: Use toml instead pytoml

    pytoml has been abandoned.
    dcz committed May 2, 2022
    Copy the full SHA
    d0172e9 View commit details

Commits on May 9, 2022

  1. Merge pull request #81 from dcz-self/corrupt

    RTT: Don't fail on corrupted output
    hudson-ayers authored May 9, 2022
    Copy the full SHA
    fb8254b View commit details

Commits on May 19, 2022

  1. Merge pull request #83 from dcz-self/toml

    deps: Use toml instead pytoml
    bradjc authored May 19, 2022
    Copy the full SHA
    32d438c View commit details

Commits on May 25, 2022

  1. openocd: Fix cleanup after exceptions

    This fixes unwinding resources after an exception. The old version would exit if the creation of the socket failed, raising an exception when trying to close the socket.
    
    The new version makes sure that only objects successfully created are cleaned up.
    
    Instead of nesting try..finally multiple times, this appends handlers onto an explicit list.
    dcz committed May 25, 2022
    Copy the full SHA
    ea06cc0 View commit details
  2. Merge pull request #84 from dcz-self/ooc

    openocd: Fix cleanup after exceptions
    bradjc authored May 25, 2022
    Copy the full SHA
    9d0f22c View commit details

Commits on May 26, 2022

  1. openocd: Check for a connection several times

    OpenOCD can start slowly under system load. Instead of trying once and giving up, this tries a couple times for a few seconds. In the best case, there's no extra time spent waiting. In the worst case, we can still connect to a delayed OpenOCD.
    dcz committed May 26, 2022
    Copy the full SHA
    2ac38af View commit details

Commits on Jul 21, 2022

  1. Merge pull request #85 from dcz-self/wait

    openocd: Check for a connection several times
    bradjc authored Jul 21, 2022
    Copy the full SHA
    7271ae1 View commit details

Commits on Aug 31, 2022

  1. docs: update openocd docs

    bradjc committed Aug 31, 2022
    Copy the full SHA
    e873c16 View commit details
  2. Copy the full SHA
    315f2f4 View commit details

Commits on Sep 1, 2022

  1. add display module

    add json format to installed apps and tbfh
    bradjc committed Sep 1, 2022
    Copy the full SHA
    9a8e1e4 View commit details
  2. Copy the full SHA
    a8c06dd View commit details
  3. Copy the full SHA
    a064e75 View commit details
  4. add json output for info cmd

    bradjc committed Sep 1, 2022
    Copy the full SHA
    410ab7c View commit details
  5. print attr moved to display

    bradjc committed Sep 1, 2022
    Copy the full SHA
    3f094b7 View commit details
  6. updated docs with new display

    bradjc committed Sep 1, 2022
    Copy the full SHA
    03e60f3 View commit details

Commits on Sep 2, 2022

  1. board_interface: update litex_sim architecture to rv32imc

    This is in line with changes to the LiteX simulation command line
    invocation as documented in Tock, changes to the Tock board
    configuration and changes to libtock-c's app configuration.
    
    Signed-off-by: Leon Schuermann <leon@is.currently.online>
    lschuermann committed Sep 2, 2022
    Copy the full SHA
    ae5f684 View commit details
  2. Merge pull request #89 from lschuermann/dev/litex_sim-rv32imc

    board_interface: update litex_sim architecture to rv32imc
    bradjc authored Sep 2, 2022
    Copy the full SHA
    913929b View commit details
  3. Copy the full SHA
    67be589 View commit details
  4. Add support for the QEMU RISC-V 32 bit "virt" Platform

    This adds support for the `qemu_rv32_virt` board as supported by Tock.
    
    Signed-off-by: Leon Schuermann <leon@is.currently.online>
    lschuermann committed Sep 2, 2022
    Copy the full SHA
    e845fdb View commit details
  5. add missing logging import

    fixes #90
    bradjc committed Sep 2, 2022
    Copy the full SHA
    eace386 View commit details
  6. Merge pull request #91 from lschuermann/dev/qemu-rv32-virt-support

    Add support for the QEMU RISC-V 32 bit "virt" Platform
    bradjc authored Sep 2, 2022
    Copy the full SHA
    a5eaf4f View commit details

Commits on Sep 5, 2022

  1. update docs

    bradjc committed Sep 5, 2022
    Copy the full SHA
    f6c125a View commit details
  2. release 1.9.0

    bradjc committed Sep 5, 2022
    Copy the full SHA
    a85821f View commit details
  3. start on 1.10.0

    bradjc committed Sep 5, 2022
    Copy the full SHA
    0aa97ab View commit details
  4. Initial hacky support for credentials. Because Tockloader queries the

    board it needs to support both main and program headers; this
    commit cuts out main support so I could be sure program was working.
    Will re-incorporate main headers next.
    phil-levis authored and bradjc committed Sep 5, 2022
    Copy the full SHA
    456e5bb View commit details
  5. Copy the full SHA
    9d5fb79 View commit details
  6. Copy the full SHA
    36b940f View commit details
  7. Add support for printing out footers.

    phil-levis authored and bradjc committed Sep 5, 2022
    Copy the full SHA
    1dbeb91 View commit details
  8. Fix output of footers.

    phil-levis authored and bradjc committed Sep 5, 2022
    Copy the full SHA
    2852812 View commit details
  9. fixup: Format Python code with Black

    autoblack authored and bradjc committed Sep 5, 2022
    Copy the full SHA
    f76b518 View commit details
  10. fixup: Format Python code with Black

    autoblack authored and bradjc committed Sep 5, 2022
    Copy the full SHA
    1f4389f View commit details
  11. Fix error message.

    phil-levis authored and bradjc committed Sep 5, 2022
    Copy the full SHA
    437009c View commit details
  12. Copy the full SHA
    3034ba4 View commit details
  13. Copy the full SHA
    fc2aed0 View commit details
  14. remove extra print

    bradjc committed Sep 5, 2022
    Copy the full SHA
    22df584 View commit details
  15. make tlvs consistent

    bradjc committed Sep 5, 2022
    Copy the full SHA
    d9a818a View commit details
  16. Copy the full SHA
    21eb01e View commit details
  17. working on delete tlv

    bradjc committed Sep 5, 2022
    Copy the full SHA
    e4b3056 View commit details
  18. Copy the full SHA
    6656a4d View commit details
  19. Copy the full SHA
    4891861 View commit details
  20. padding length could be 0

    bradjc committed Sep 5, 2022
    Copy the full SHA
    d0b6e80 View commit details
  21. Copy the full SHA
    21c94d4 View commit details
  22. Copy the full SHA
    79535a4 View commit details
1 change: 1 addition & 0 deletions MANIFEST.in
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
include tockloader/static/*.bit
144 changes: 127 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
@@ -6,7 +6,8 @@ Install
-------

```
pip3 install tockloader --user
pip3 install pipx
pipx install tockloader
```

If you want tab completions:
@@ -125,40 +126,90 @@ Print which boards tockloader has default settings for built-in.

Set the jump address the bootloader uses for the location of the kernel.

#### `tockloader tbf tlv add|modify|delete [TLVNAME]`

Interact with TLV structures within a TBF.

#### `tockloader tbf credential add|delete [credential type]`

Add and remove credentials in the TBF footer.

#### `tockloader tickv get|append|invalidate|dump|cleanup|reset [key] [value]`

Interact with a TicKV key-value database.


Specifying the Board
--------------------

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. Tockloader also attempts to automatically discover boards using JLink and
OpenOCD as well. If those are unavailable, they can be specified as command line
arguments.
For tockloader to know how to interface with a particular hardware board,
it tries several options:

tockloader [command] --arch [arch] --board [board]
1. Read the parameters from the bootloader. Tockloader assumes it can open a
serial connection to a
[tock-bootloader](https://github.com/tock/tock-bootloader/) on the board.

2. Use `JLinkExe` and `OpenOCD` to discover known boards.

3. Use the `--board` command line flag and a list of known boards.

4. Use individual command line flags that specify how to interact with the
board.

If command line flags are passed they take priority over any automatically
discovered options.

Tockloader has hardcoded parameters for a variety of boards. You can list these
with:

tockloader list-known-boards

To use a known board, if it is not automatically discovered, you can:

tockloader [command] --board [board]

If your board is not a known board, you can specify the required parameters
via command line options. Note, you also need to provide a name for the board.

tockloader [command] --board [board] --arch [arch] --page-size [page_size]

- `arch`: The architecture of the board. Likely `cortex-m0` or `cortex-m4`.
- `board`: The name of the board. This helps prevent incompatible applications
from being flashed on the wrong board.
- `arch`: The architecture of the board. Likely `cortex-m0` or `cortex-m4`.
- `page_size`: The size in bytes of the smallest erasable unit in flash.

Specifying the Communication Channel
------------------------------------

Tockloader defaults to using a serial connection to an on-chip bootloader to
program and interact with a board. If you need to use a different communication
mechanism, you can specify what Tockloader should use with command line
arguments. Note, Tockloader's board autodiscovery process also selects different
communication channels based on which board it finds.

Tockloader also supports a JTAG interface using JLinkExe. JLinkExe requires
To use a JTAG interface using JLinkExe, specify `--jlink`. 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]
tockloader [command] --board [board] --arch [arch] --page-size [page_size] \
--jlink --jlink-cmd [jlink_cmd] --jlink-device [device] \
--jlink-speed [speed] --jlink-if [if] \
--jlink-serial-number [serial_number]

- `jlink_cmd`: The JLink executable to invoke. Defaults to `JLinkExe` on
Mac/Linux, and `JLink` 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.
- `serial-number`: The serial number of the target board to use with JLink.

Tockloader can also do JTAG using OpenOCD. OpenOCD needs to know which config
file to use.

tockloader [command] --openocd --arch [arch] --board [board] --openocd-board [openocd_board] \
--openocd-cmd [openocd_cmd] --openocd-options [openocd_options] \
--openocd-commands [openocd_commands]
tockloader [command] --board [board] --arch [arch] --page-size [page_size] \
--openocd --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 to `openocd`.
@@ -167,13 +218,13 @@ file to use.
quirks. Options include:
- `noreset`: Removes the command `reset init;` from OpenOCD commands.
- `nocmdprefix`: Removes the commands `init; reset init; halt;` from OpenOCD
commands.
commands.
- `workareazero`: Adds the command `set WORKAREASIZE 0;` to OpenOCD commands.
- `resume`: Adds the commands `soft_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:
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.
@@ -186,6 +237,17 @@ file to use.
- `{address:#x}`: The specified address for the binary to be programmed at.
- `{length}`: The number of bytes. Only valid for the `read` operation.

For STM32 boards, Tockloader supports
[STLINK](https://github.com/stlink-org/stlink). The stlink tool knows how to
interface with the boards, so there are not many flags.

tockloader [command] --board [board] --arch [arch] --page-size [page_size] \
--stlink \
--stinfo-cmd [stinfo_cmd] --stflash-cmd [stflash_cmd]

- `stinfo_cmd`: The st-info executable to invoke. Defaults to `st-info`.
- `stflash_cmd`: The st-flash executable to invoke. Defaults to `st-flash`.

Finally, Tockloader can treat a local file as though it were the flash contents
of a board. The file can then be loaded separately onto a board.

@@ -194,6 +256,7 @@ of a board. The file can then be loaded separately onto a board.
- `filepath`: The file to use as the flash contents. Will be created if it
doesn't exist.


Example Usage
-------------

@@ -226,6 +289,47 @@ operation based on the requirements of a particular hardware platform.
bundle using only a single flash command. This will require that anytime any
app changes in any way (e.g. its header changes or the app is updated or a new
app is installed) all apps are re-written.
- `--layout`: Specify exactly how apps and padding apps should be written to the
board. This implies `--erase` and `--force` as all existing (even sticky) apps
will be removed.

The layout is specified as a string of how apps from TBFs and padding apps
should be written to the board. The syntax for the layout uses the following
identifiers:

- `T`: indicates to install a TBF app.
- `p<size>`: indicates to install a padding app of `<size>` bytes.

For example `--layout Tp1024TT` specifies to install the first app at the
`app-address`, then install a 1024 byte padding app, then install the second
app, then install the third app. No board-specific alignment or sizing will
be used; the apps will be installed exactly as described. It can be helpful
to use `tockloader list --map` to view how the apps were actually installed.

Credentials and Integrity Support
---------------------------------

Tockloader supports working with credentials stored in the TBF footer.
Tockloader will attempt to verify that stored credentials are valid for the
given TBF. For credentials that require keys to verify, Tockloader can check the
credential using:

$ tockloader inspect-tab --verify-credentials [list of key files]
example:
$ tockloader inspect-tab --verify-credentials tockkey.public.der

Tockloader can also add credentials. To add a hash:

$ tockloader tbf credential add sha256

To add an RSA signature:

$ tockloader tbf credential add rsa2048 --private-key tockkey2048.private.der --public-key tockkey2048.public.der

To remove credentials:

$ tockloader tbf credential delete sha256


Features
--------
@@ -235,6 +339,7 @@ Features
- Segger JLinkExe JTAG support
- OpenOCD JTAG support
- JLink RTT listener
- JSON output using `--output-format json` for certain commands.


Complete Install Instructions
@@ -288,3 +393,8 @@ directory:
./generate_docs.py
cd ..
mkdocs serve --dev-addr=0.0.0.0:8001
### Create requirements.txt
pip3 install pipreqs
pipreqs . --force
102 changes: 102 additions & 0 deletions default.nix
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
# Nix expression for building Tockloader

{ pkgs ? import <nixpkgs> {}, withUnfreePkgs ? true }:

with builtins;
let
inherit (pkgs) stdenv stdenvNoCC lib;

nrf-command-line-tools = stdenvNoCC.mkDerivation {
pname = "nrf-command-line-tools";
version = "10.22.1";

src = builtins.fetchurl {
url = "https://nsscprodmedia.blob.core.windows.net/prod/software-and-other-downloads/desktop-software/nrf-command-line-tools/sw/versions-10-x-x/10-22-1/nrf-command-line-tools-10.22.1_linux-amd64.tar.gz";
sha256 = "sha256:0i3dfhp75rizs7kxyfka166k3zy5hmb28c25377pgnzk6w1yx383";
};

nativeBuildInputs = with pkgs; [
autoPatchelfHook
];

propagatedBuildInputs = with pkgs; [
segger-jlink libusb
];

installPhase = ''
mkdir -p $out/
cp -r * $out/
'';

meta.license = lib.licenses.unfree;
};

python3Packages = lib.fix' (self: with self; pkgs.python3Packages //
{
siphash = buildPythonPackage rec {
pname = "siphash";
version = "0.0.1";

src = fetchPypi {
inherit pname version;
sha256 = "sha256-rul/6V4JoplYGcBYpeSsbZZmGomNf+CtVeO3LJox1GE=";
};
};

pynrfjprog = buildPythonPackage {
pname = "pynrfjprog";
version = nrf-command-line-tools.version;

src = nrf-command-line-tools.src;

preConfigure = ''
cd ./python
'';

format = "pyproject";

nativeBuildInputs = [
setuptools
pkgs.autoPatchelfHook
];

buildInputs = [
nrf-command-line-tools
];

propagatedBuildInputs = [
tomli-w
future
];

meta.license = lib.licenses.unfree;
};
});
in pkgs.python3Packages.buildPythonPackage rec {
pname = "tockloader";
version = "1.10.0";
name = "${pname}-${version}";

propagatedBuildInputs = with python3Packages; [
argcomplete
colorama
crcmod
pyserial
toml
tqdm
questionary
pycrypto
siphash
] ++ (lib.optional withUnfreePkgs pynrfjprog);

src = ./.;

# Dependency checks require unfree software
doCheck = withUnfreePkgs;

# Make other dependencies explicitly available as passthru attributes
passthru = {
inherit nrf-command-line-tools;
pynrfjprog = python3Packages.pynrfjprog;
};
}
Loading