Skip to content

Update readme with dependencies and updated build instructions #211

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mfield4 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Update readme with dependencies and updated build instructions #211

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
71a3b50
Update readme with dependencies and updated build instructions
mfield4 Feb 17, 2026
bc2a0ba
Appended remaining options and fixed htool output examples
mfield4 Feb 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
164 changes: 149 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,62 +3,178 @@
This repository contains a libraries and example programs for interacting with
a hoth-class root of trust.

# Build via meson
## Prerequisites

To build libhoth, you will need `meson`, `ninja`, and several development libraries. On Ubuntu/Debian, you can install them with:

```bash
sudo apt-get update
sudo apt-get install meson libusb-1.0-0-dev libsystemd-dev libcap-dev libgtest-dev
```

## Build via Meson

```bash
meson build
ninja -C build
./build/examples/htool
```

### Running Tests (Meson)

```bash
meson test -C build
```

### Optional: D-Bus Backend (Meson)

To enable the D-Bus backend:

```bash
meson build -Ddbus_backend=true
ninja -C build
```
$ meson build
$ (cd build && ninja)
$ build/examples/htool

## Build via Bazel

```bash
bazel build //...
./bazel-bin/examples/htool
```

# Build via Bazel
### Running Tests (Bazel)

```bash
bazel test //...
```
$ bazel build ...
$ bazel-bin/examples/htool

### Optional: D-Bus Backend (Bazel)

To enable the D-Bus backend:

```bash
bazel build --define dbus_backend=true //examples:htool
```

# examples/htool
## examples/htool

htool is a command line tool for performing basic actions against a hoth RoT.

```
$ htool
Unknown subcommand
Available subcommands: (append --help to subcommand for details)
usb list - List all RoTs connected via USB.
reboot - Reboot the RoT.
show firmware_version - Get the version of the RoT firmware.
show chipinfo - Return details about this specific RoT chip.
spi read - Read from SPI flash into a file
spi update - Write a file to SPI flash (erase + program).
spi passthrough off - Disable SPS->SPI passthrough
spi passthrough on - Enable SPS->SPI passthrough
target reset on - Put the target device into reset.
target reset off - Take the target device out of reset
target reset pulse - Quickly put the target device in and out of reset
console - Open a console for communicating with the RoT or devices attached to the RoT.
payload getstatus - Show the current payload update status
payload status - Show payload status
payload update - Perform payload update protocol for Titan images.
payload read - Read content of staging flash for Titan images.
payload info - Display payload info for a Titan image.
firmware_update update_from_flash_and_reset - Installs a firmware update from a bundle staged in the external flash.
dfu update - Directly install a PIE-RoT fwupdate.
dfu check - Check that the device is running firmware matching a fwupdate bundle.
flash_spi_info - Get SPI NOR flash info.
statistics - Show statistics
get_panic - Retrieve or clear the stored panic record.
authz_record read - Read the current authorization record
authz_record erase - Erase the current authorization record
authz_record build - Build an empty authorization record for the chip
authz_record set - Upload an authorization record to the chip
authz_host_command build - Build an authorized host command
authz_host_command send - Send an authorized host command
arm_coordinated_reset - Arms the coordinated reset to hard reset when it receives a trigger.
srtm - Pushes a measurement into PCR0.
sbs_single get - Get status of SBS mux select
sbs_single connect_flash_to_rot - Set mux to connect flash to RoT
sbs_single connect_flash_to_target - Set mux to connect flash to target
sbs_dual get - Get status of SBS mux select
sbs_dual connect_target_to_spi_flash_0 - Set mux select pin to connect target to spi flash 0 (SBS Dual)
sbs_dual connect_target_to_spi_flash_1 - Set mux select pin to connect target to spi flash 1 (SBS Dual)
i2c detect - Detect I2C devices on bus
i2c read - Perform I2C transaction
i2c write - Perform I2C transaction
i2c mux_ctrl get - Get status of I2C Mux sel (if present)
i2c mux_ctrl select_rot - Change I2C Mux sel (if present) to select RoT as controller
i2c mux_ctrl select_host - Change I2C Mux sel (if present) to select Host as controller
rot_usb mux_ctrl get - Get status of USB mux select (if present)
rot_usb mux_ctrl connect_rot_to_host - Change USB mux select (if present) so that RoT is connected to Host
rot_usb mux_ctrl connect_rot_to_front_panel - Change USB mux select (if present) so that RoT is connected to Front panel
raw_host_command - Stream raw host commands via stdin/stdout
jtag read_idcode - Read IDCODE for a device over JTAG. Assumes only a single device in chain
jtag test_bypass - Send test pattern of 64 bytes to JTAG device in BYPASS mode. Assumes only a single device in chain
external_usb_host check_presence - Check presence of an External USB host connected to the system containing RoT
jtag program_and_verify_pld - Program and verify a PLD over JTAG. Assumes only a single device in chain
jtag verify_pld - Verify a PLD over JTAG. Assumes only a single device in chain
storage read - Read from the controlled storage
storage write - Write to the controlled storage
storage delete - Delete from the controlled storage
hello - A test function to send and receive an integer
opentitan_version - Get OpenTitan version
extract_ot_bundle - Get OpenTitan version
key_rotation get status - Reads info from key rotation record and validation method and data.
key_rotation get version - Gets key rotation header version.
key_rotation payload status - Gets status regarding payload validation method and validation data.
key_rotation update - Writes the key rotation record.
key_rotation read - Read size bytes from key rotation record.
key_rotation read_chunk - Read chunk of given type from the key rotation record.
key_rotation chunk_type_count - Get the number of chunks of a given type in the key rotation record.
key_rotation erase record - Erase the key rotation record from both halves of the flash if the mauv allows
key_rotation set mauv - Set Key Rotation Record MAUV
key_rotation get mauv - Get Key Rotation Record MAUV
secure_boot get_enforcement - Get the current state of target secure boot enforcement.
secure_boot enable_enforcement - Enable secure boot enforcement.
security info - Retrieve the Info from firmware
tpm_spi probe - Probe the TPM_SPI interface (DID/VID) over a spidev interface
provisioning read - Get Provisioning Log
provisioning validate_and_sign - Validate and Sign the provisioning log
security get_alias_key_cert - Get the Alias Key Cert
security get_device_id_cert - Get the Device ID Cert
security get_attestation_pub_cert - Get the Attestation Public Cert
security get_signed_attestation_pub_cert - Get the Signed Attestation Public Cert
security attestation - Fetch attestation information, including tokens and certificates.

Global flags:
--transport (default: "")
The method of connecting to the RoT; for example 'spidev'/'usb'/'mtd'
The method of connecting to the RoT; for example 'spidev'/'usb'/'mtd'/'dbus'
--usb_loc (default: "")
The full bus-portlist location of the RoT; for example '1-10.4.4.1'.
--usb_product (default: "")
If there is a single USB RoT with this substring in the USB product string, use it.
--spidev_path (default: "")
The full SPIDEV path of the RoT; for example '/dev/spidev0.0'.
--spidev_atomic (default: "false")
If true, force spidev to send the request and receive the corresponding response with a single atomic ioctl. This is required on some systems for correctness.
--spidev_speed_hz (default: "0")
Clock speed (in Hz) to use when using spidev transport. Default behavior (with input 0) is to not change the clock speed
--spidev_device_busy_wait_timeout (default: "180000000")
Maximum duration (in microseconds) to wait when SPI device indicates that it is busy
--spidev_device_busy_wait_check_interval (default: "100")
Interval duration (in microseconds) to wait before checking SPI device status again when it indicates that the device is busy
--quadmode (default: "auto")
Enable Quad SPI mode (auto|on|force|off). Default: auto
--mtddev_path (default: "")
The full MTD path of the RoT mailbox; for example '/dev/mtd0'. If unspecified, will attempt to detect the correct device automatically
--mtddev_name (default: "hoth-mailbox")
The MTD name of the RoT mailbox; for example 'hoth-mailbox'.
The MTD name of the RoT mailbox; for example 'hoth-mailbox'.
--mailbox_location (default: "0")
The location of the mailbox on the RoT, for 'spidev' or 'mtd' transports; for example '0x900000'.
--dbus_hoth_id (default: "")
The hoth ID associated with the RoT's hothd service.
--connect_timeout (default: "10s")
Maximum duration to retry opening a busy libhoth transport (e.g., '1s', '1500ms').
--version (default: "false")
Print htool version.
```

```
Expand All @@ -67,11 +183,15 @@ $ htool usb list
```

```
htool spi update --help
Usage: spi update <source-file>
$ htool spi update --help
Usage: spi update <source-file>
-s --start (default: "0")
start address
-v --verify (default: "true")
-a --address_mode (default: "3B/4B")
3B: 3 byte mode no enter/exit 4B supported
3B/4B: 3 Byte current but enter 4B for SPI operation
4B: 4 byte mode only, no enter/exit 4B supported

$ echo "Hello world" > /tmp/hello
$ htool spi update -s 0x5000 /tmp/hello
Expand All @@ -81,10 +201,15 @@ Verifying: 100% - 0kB / 0kB 503 kB/sec; 0.0 s remaining

```
$ htool spi read --help
Usage: spi read <dest-file>
Usage: spi read <dest-file>
-s --start (default: "0")
start address
-n --length
the number of bytes to read
-a --address_mode (default: "3B/4B")
3B: 3 byte mode no enter/exit 4B supported
3B/4B: 3 Byte current but enter 4B for SPI operation
4B: 4 byte mode only, no enter/exit 4B supported

$ htool spi read -s 0x5000 -n 16 /dev/stdout | hexdump -C
Reading: 100% - 0kB / 0kB 514 kB/sec; 0.0 s remaining
Expand All @@ -94,12 +219,21 @@ Reading: 100% - 0kB / 0kB 514 kB/sec; 0.0 s remaining

```
$ htool console --help
Usage: console
Usage: console
-c --channel
Which channel to talk to. Typically a fourcc code.
-f --force_drive_tx (default: "0")
Drive the UART's TX net even if Hoth isn't sure whether some other device else is driving it. Only use this option if you are CERTAIN there is no debugging hardware attached.
Drive the UART's TX net even if the RoT isn't sure whether some other device else is driving it. Only use this option if you are CERTAIN there is no debugging hardware attached.
-h --history (default: "false")
Include data bufferred before the current time.
-n --onlcr (default: "false")
Translate received "\n" to "\r\n".
-b --baud_rate (default: "0")
-s --snapshot (default: "false")
Print a snapshot of most recent console messages.
--claim_timeout_secs (default: "60")
How long we should attempt to claim the device before returning a fatal error.
--yield_ms (default: "50")
After releasing the device, how long we should wait before claiming it again. Decrease to reduce console latency. Increase to reduce contention between concurrent clients.
```