Skip to content

Commit 2ce8aac

Browse files
0xEthamin0xEthamin
committed
add documentation ci & fix links
1 parent 8fa22d9 commit 2ce8aac

12 files changed

Lines changed: 474 additions & 11 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
name: 'Documentation'
2+
3+
# Build and publish rustdoc to GitHub Pages.
4+
#
5+
# The workspace splits into two compilation targets:
6+
# - host (x86_64-unknown-linux-gnu) for every crate except hsm-firmware.
7+
# `cargo doc` picks them up via `default-members` in the root Cargo.toml.
8+
# - thumbv6m-none-eabi for hsm-firmware, which depends on embassy-rp and
9+
# cortex-m and only compiles for Cortex-M0.
10+
#
11+
# Each target lands in its own subdirectory under `site/`. A custom
12+
# landing page at `site/index.html` points users to either tree.
13+
14+
on:
15+
push:
16+
branches:
17+
- main
18+
pull_request:
19+
workflow_dispatch:
20+
21+
env:
22+
CARGO_TERM_COLOR: always
23+
24+
jobs:
25+
build:
26+
name: Build documentation
27+
runs-on: ubuntu-latest
28+
29+
steps:
30+
- name: Checkout repository
31+
uses: actions/checkout@v4
32+
33+
- name: Install system dependencies
34+
run: |
35+
sudo apt-get update
36+
sudo apt-get install -y \
37+
libudev-dev \
38+
pkg-config
39+
40+
- name: Install Rust toolchain
41+
uses: dtolnay/rust-toolchain@stable
42+
with:
43+
targets: thumbv6m-none-eabi
44+
45+
- name: Cache cargo registry
46+
uses: actions/cache@v4
47+
with:
48+
path: ~/.cargo/registry
49+
key: ${{ runner.os }}-cargo-doc-${{ hashFiles('**/Cargo.lock') }}
50+
51+
- name: Build host documentation
52+
run: |
53+
cargo doc \
54+
--no-deps \
55+
--document-private-items \
56+
--target-dir target/doc-host
57+
58+
- name: Build firmware documentation
59+
run: |
60+
cargo doc \
61+
-p hsm-firmware \
62+
--no-deps \
63+
--document-private-items \
64+
--target thumbv6m-none-eabi \
65+
--target-dir target/doc-firmware
66+
67+
- name: Generate host index page
68+
run: |
69+
mkdir -p doc-build/host
70+
cat > doc-build/host-index.html << 'EOF'
71+
<!DOCTYPE html>
72+
<html lang="en">
73+
<head>
74+
<meta charset="UTF-8">
75+
<title>mini-hsm - host crates</title>
76+
<style>
77+
body { font-family: -apple-system, "Segoe UI", sans-serif; max-width: 720px; margin: 2rem auto; padding: 0 1rem; color: #2b2b2b; line-height: 1.6; }
78+
h1 { color: #3d6b3c; border-bottom: 1px solid #ddd; padding-bottom: 0.4rem; }
79+
ul { padding-left: 1.2rem; }
80+
li { margin: 0.3rem 0; }
81+
a { color: #3d6b3c; text-decoration: none; }
82+
a:hover { text-decoration: underline; }
83+
.target { font-family: "Source Code Pro", monospace; background: #eaeaea; padding: 0.1rem 0.4rem; border-radius: 3px; font-size: 0.85rem; }
84+
.back { font-size: 0.9rem; }
85+
@media (prefers-color-scheme: dark) {
86+
body { background: #1a1a1a; color: #e6e6e6; }
87+
h1 { color: #b3dcb2; border-bottom-color: #3a3a3a; }
88+
a { color: #b3dcb2; }
89+
.target { background: #2e2e2e; }
90+
}
91+
</style>
92+
</head>
93+
<body>
94+
<p class="back"><a href="../">&larr; back to index</a></p>
95+
<h1>Host crates</h1>
96+
<p>Target: <span class="target">x86_64-unknown-linux-gnu</span></p>
97+
<ul>
98+
<li><a href="atecc608b/index.html">atecc608b</a> : no_std driver for the ATECC608B</li>
99+
<li><a href="hsm_crypto_service/index.html">hsm_crypto_service</a> : business logic (PIN, PUK, sign workflow)</li>
100+
<li><a href="hsm_usb_protocol/index.html">hsm_usb_protocol</a> : HID command and response encoding</li>
101+
<li><a href="hsm_firmware_logic/index.html">hsm_firmware_logic</a> : host-testable firmware logic (state machine, debouncer)</li>
102+
<li><a href="hsm_host/index.html">hsm_host</a> : CLI client over USB-HID</li>
103+
<li><a href="config_generator/index.html">config_generator</a> : ATECC608B configuration zone blob generator</li>
104+
</ul>
105+
</body>
106+
</html>
107+
EOF
108+
109+
- name: Generate firmware index page
110+
run: |
111+
cat > doc-build/firmware-index.html << 'EOF'
112+
<!DOCTYPE html>
113+
<html lang="en">
114+
<head>
115+
<meta charset="UTF-8">
116+
<title>mini-hsm - firmware</title>
117+
<style>
118+
body { font-family: -apple-system, "Segoe UI", sans-serif; max-width: 720px; margin: 2rem auto; padding: 0 1rem; color: #2b2b2b; line-height: 1.6; }
119+
h1 { color: #3d6b3c; border-bottom: 1px solid #ddd; padding-bottom: 0.4rem; }
120+
ul { padding-left: 1.2rem; }
121+
li { margin: 0.3rem 0; }
122+
a { color: #3d6b3c; text-decoration: none; }
123+
a:hover { text-decoration: underline; }
124+
.target { font-family: "Source Code Pro", monospace; background: #eaeaea; padding: 0.1rem 0.4rem; border-radius: 3px; font-size: 0.85rem; }
125+
.back { font-size: 0.9rem; }
126+
@media (prefers-color-scheme: dark) {
127+
body { background: #1a1a1a; color: #e6e6e6; }
128+
h1 { color: #b3dcb2; border-bottom-color: #3a3a3a; }
129+
a { color: #b3dcb2; }
130+
.target { background: #2e2e2e; }
131+
}
132+
</style>
133+
</head>
134+
<body>
135+
<p class="back"><a href="../">&larr; back to index</a></p>
136+
<h1>Firmware</h1>
137+
<p>Target: <span class="target">thumbv6m-none-eabi</span></p>
138+
<p>The RP2040 binary. Cross-compiled because it depends on embassy-rp and cortex-m.</p>
139+
<ul>
140+
<li><a href="hsm_firmware/index.html">hsm_firmware</a> : main binary, tasks, RP2040 HAL implementation</li>
141+
</ul>
142+
</body>
143+
</html>
144+
EOF
145+
146+
- name: Assemble documentation site
147+
run: |
148+
mkdir -p site/host site/firmware
149+
cp -r target/doc-host/doc/. site/host/
150+
cp -r target/doc-firmware/thumbv6m-none-eabi/doc/. site/firmware/
151+
cp doc-extras/index.html site/index.html
152+
cp doc-build/host-index.html site/host/index.html
153+
cp doc-build/firmware-index.html site/firmware/index.html
154+
155+
- name: Upload site artifact
156+
uses: actions/upload-pages-artifact@v3
157+
with:
158+
path: site
159+
160+
deploy:
161+
name: Deploy to GitHub Pages
162+
runs-on: ubuntu-latest
163+
needs: build
164+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
165+
166+
permissions:
167+
contents: read
168+
pages: write
169+
id-token: write
170+
171+
environment:
172+
name: github-pages
173+
url: ${{ steps.deployment.outputs.page_url }}
174+
175+
steps:
176+
- name: Deploy
177+
id: deployment
178+
uses: actions/deploy-pages@v4

‎crates/atecc608b/src/command/gendig.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
//!
2323
//! In this project's provisioning flow:
2424
//!
25-
//! 1. The host calls [`crate::command::nonce::AteccChannel::nonce_random`] to
25+
//! 1. The host calls [`crate::AteccChannel::nonce_random`] to
2626
//! establish a shared `TempKey` value between host and chip.
2727
//! 2. The host calls [`AteccChannel::gendig`] with the I/O Protection Key slot
2828
//! (slot 8). The chip computes

‎crates/atecc608b/src/command/privwrite.rs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
//!
2222
//! **This command is intentionally NOT used for the user identity key.**
2323
//! User identity keys (slots 0..=4 in this project) are generated on-chip
24-
//! via [`crate::command::genkey::AteccChannel::genkey_create`] so that the private
24+
//! via [`crate::AteccChannel::genkey_create`] so that the private
2525
//! material never traverses the host or the USB bus. `PrivWrite` exists
2626
//! here for bring-up and for the V3 attestation slot (slot 7) only, both
2727
//! controlled by a privileged path in `tools/hsm-host`.
@@ -36,8 +36,8 @@
3636
//! data field carries ciphertext plus a 32-byte MAC. The driver does not
3737
//! currently expose the encrypted path: the orchestration is
3838
//! service-layer work that depends on
39-
//! [`crate::command::nonce::AteccChannel::nonce_random`] +
40-
//! [`crate::command::gendig::AteccChannel::gendig`] and the matching host-side
39+
//! [`crate::AteccChannel::nonce_random`] +
40+
//! [`crate::AteccChannel::gendig`] and the matching host-side
4141
//! key derivation. It will be added when that orchestration lands.
4242
//!
4343
//! Reference: `CryptoAuthLib` `lib/calib/calib_priv_write.c`, constants

‎crates/atecc608b/src/error.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -262,7 +262,7 @@ impl ChipError
262262
/// Return the raw status byte this variant came from.
263263
///
264264
/// Inverse of [`Self::from_status_byte`]. For
265-
/// [`ChipError::Unknown(byte)`] returns the preserved raw byte.
265+
/// [`ChipError::Unknown`] returns the preserved raw byte.
266266
#[must_use]
267267
pub const fn as_status_byte(self) -> u8
268268
{

‎crates/atecc608b/src/lib.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@
4747
#![deny(missing_docs)]
4848
#![deny(unsafe_code)]
4949
#![warn(clippy::pedantic)]
50+
#![allow(rustdoc::private_intra_doc_links)]
5051

5152
pub mod command;
5253
pub mod crc;

‎crates/hsm-crypto-service/src/lib.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@
2424
#![deny(missing_docs)]
2525
#![deny(unsafe_code)]
2626
#![warn(clippy::pedantic)]
27+
#![allow(rustdoc::private_intra_doc_links)]
2728

2829
pub(crate) mod encrypted_write;
2930
pub mod error;

‎crates/hsm-crypto-service/src/pin.rs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,8 @@
2424
//! The `CheckMac` verification on slot 5 / 6 mirrors what the chip itself
2525
//! computes. The byte layout below is taken **verbatim** from
2626
//! `CryptoAuthLib`'s `atcah_check_mac` (`lib/host/atca_host.c`), which is
27-
//! the authoritative reference, and validated against it by
28-
//! [`tests::checkmac_response_matches_cryptoauthlib_oracle`].
27+
//! the authoritative reference, and validated against it by
28+
//! `checkmac_response_matches_cryptoauthlib_oracle_*` tests.
2929
//!
3030
//! ```text
3131
//! msg[0..32] = slot_value (32)

‎crates/hsm-crypto-service/src/slots.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
//! could be programmed differently. Putting the convention in one place keeps
2020
//! it visible and reviewable.
2121
//!
22-
//! The authoritative reference is [`docs/config-zone-layout.md`]. This module
22+
//! The authoritative reference is docs/config-zone-layout.md. This module
2323
//! exposes named constants for the slots the service code references; it
2424
//! must stay in sync with the configuration zone the chip is provisioned
2525
//! with.

‎crates/hsm-firmware/src/hal_rp2040.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@
4040
//! intermittent `0x04` HAL errors on subsequent reads. The CryptoAuthLib
4141
//! method keeps the I2C controller in continuous control of the line
4242
//! and matches the reference implementation byte-for-byte. Restoring the
43-
//! bus to 400 kHz is automatic on the next [`Self::build_i2c`] call.
43+
//! bus to 400 kHz is automatic on the next [`Rp2040Hal::build_i2c`] call.
4444
//!
4545
//! The post-pulse wait (`tHTSU`, ~4.5 ms before the chip responds to
4646
//! I2C) is the **driver's** responsibility, not the HAL's:

‎crates/hsm-firmware/src/usb.rs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,8 @@
1818
//! Initialises an embassy-usb device that exposes one vendor-defined HID
1919
//! interface, per the project's USB protocol (see crate `hsm-usb-protocol`).
2020
//!
21-
//! The two endpoints are split into a [`HidReader`] (host -> token) and a
22-
//! [`HidWriter`] (token -> host). They are owned by separate async tasks
21+
//! The two endpoints are split into a [`embassy_usb::class::hid::HidReader`] (host -> token) and a
22+
//! [`embassy_usb::class::hid::HidWriter`] (token -> host). They are owned by separate async tasks
2323
//! in [`crate::tasks`] so reads and writes proceed independently.
2424
//!
2525
//! # Lifetime model

0 commit comments

Comments
 (0)