Module contributing 

Contributing

First build

From the workspace root:

cargo test -p rhdl_ed25519_model --release -j 1
cargo test -p rhdl_ed25519_core --release -j 1
RHDL_SKIP_IVERILOG_CHECK=1 cargo test --workspace --release -j 1
./tools/docs/build.sh

The single Cargo job is intentional on memory-constrained development hosts. Run narrow crate tests while iterating; reserve the workspace command for an integration gate.

Choosing a first issue

Good first hardware changes are narrow and independently testable:

• add a boundary vector to the field/scalar oracle tests;
• improve error/framing coverage in the top-level simulation;
• add a constant-pattern address assertion;
• document a state or intermediate bound next to its owning type;
• add a checksum/provenance check to a generated artifact.

Changes to point formulas, scalar reduction, canonical decoding, secret table selection, or top-level concurrency are high risk even when the diff is small.

Development loop

1. Identify the owning crate in crate::code_map.
2. Write or locate an independent oracle.
3. Add the failing narrow test.
4. Change one ownership boundary at a time.
5. Run the narrow Rust/RHDL test.
6. Run emitted RTL simulation if lowering or black boxes are involved.
7. Inspect counter/address traces for secret-independent behavior.
8. Run integration simulation.
9. Regenerate synthesis evidence before changing an area/timing claim.

Generated assets

Do not hand-edit basepoint .mem files or emitted Verilog. Use the generator, verify the pinned source checksum, and review the generated manifest. A table change should explain its logical dimensions, physical banking, constant-scan behavior, and synthesis impact.

RHDL style

• Keep Q (current registers) and D (next registers) conceptually separate.
• Make handshake conditions explicit.
• Use fixed-size arrays and bit widths in synthesizable paths.
• Keep child-engine protocols ready/busy/done or ready/valid consistently.
• Split very large kernels by responsibility; avoid opaque mega-tuples unless they materially reduce RHDL lowering cost.
• Comments should record bounds, timing assumptions, or protocol invariants, not restate assignments.

Security review questions

Before requesting review, answer:

1. Which inputs are secret or attacker-controlled?
2. Are loop counts, addresses, enables, and stalls independent of secrets?
3. Are untrusted encodings checked before reduction/use?
4. Which transient and cached values are cleared, and when?
5. Does any waveform, report, or host log contain a seed?

Performance review questions

1. Is the number a cycle model, OOC synthesis, post-route result, or board run?
2. What exact operation and message length does it cover?
3. Is it latency or steady-state initiation interval?
4. Does the resource count include the shell and data movers?
5. Are source and artifact checksums recorded?
6. Is comparison traffic and semantic work equivalent?

Updating these docs

The documentation crate uses ordinary Rustdoc Markdown through include_str!. Broken intra-doc links are denied. After an architecture or interface change, update the owning crate docs and this contributor guide in the same change.

Build locally with ./tools/docs/build.sh. The script creates a root redirect to this guide inside target/doc while preserving every workspace crate’s generated Rustdoc pages.