1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
//! Command-line surface: global flags + subcommands. Parsing only.
use std::path::PathBuf;
use clap::{Parser, Subcommand};
#[derive(Parser)]
#[command(
name = "norbert",
about = "A patient SPI-NOR flasher",
disable_version_flag = true,
arg_required_else_help = true
)]
/// Parsed command line: global flags shared by every subcommand, plus the
/// selected [`Cmd`]. Built by [`clap`] from the process arguments.
pub struct Cli {
/// Pick a specific Pico de Gallo by USB serial number.
#[arg(long, global = true)]
pub serial: Option<String>,
/// SPI clock in Hz (USB-FS bound; 10 MHz is plenty).
#[arg(long, global = true, default_value_t = 10_000_000)]
pub freq: u32,
/// Hold a shared bus master off the SPI while programming, then release it so it
/// boots. Wire the target's CRESET to User GPIO 3 (header pin 14). Omit for a
/// bare chip or any flash with no other bus master on the SPI.
#[arg(long, global = true)]
pub reset: bool,
/// Machine-friendly output: drop the commentary, print IDs/addresses/OK/FAIL only.
#[arg(long, global = true)]
pub quiet: bool,
/// Print version.
#[arg(short = 'V', long = "version", global = true)]
pub version: bool,
#[command(subcommand)]
pub cmd: Option<Cmd>,
}
#[derive(Subcommand)]
/// The subcommand to run. Each variant maps to one handler in
/// [`crate::commands`].
pub enum Cmd {
/// Read the raw 3-byte JEDEC ID.
Jedec,
/// Erase + program + verify a bitstream at an offset, then boot it.
Program {
/// Path to the bitstream/image file to write.
bitstream: PathBuf,
/// Byte offset in flash to program at (default 0).
#[arg(long, default_value_t = 0)]
offset: usize,
/// Skip read-back verification.
#[arg(long)]
no_verify: bool,
/// Full chip erase instead of just the covered 64 KiB blocks.
#[arg(long)]
chip_erase: bool,
/// Clear status-register block-protection (BP) bits before erase/program.
#[arg(long)]
unprotect: bool,
},
/// Dump `length` bytes from `offset` to a file.
Read {
/// Destination file for the dumped bytes.
out: PathBuf,
/// Number of bytes to read.
#[arg(long)]
length: usize,
/// Byte offset in flash to start reading from (default 0).
#[arg(long, default_value_t = 0)]
offset: usize,
},
/// Compare flash contents against a file.
Verify {
/// Path to the file to compare flash contents against.
bitstream: PathBuf,
/// Byte offset in flash where the comparison starts (default 0).
#[arg(long, default_value_t = 0)]
offset: usize,
},
/// Erase (covered blocks for a size, or the whole chip).
Erase {
/// Byte offset in flash where the erase region starts (default 0).
#[arg(long, default_value_t = 0)]
offset: usize,
/// Region length in bytes; erases every block overlapping it.
#[arg(long)]
length: Option<usize>,
/// Erase the entire chip instead of a region.
#[arg(long)]
chip: bool,
},
/// Detect and print the flash profile the tool will use (SFDP or fallback table).
#[command(alias = "discover")]
Detect,
/// Read + print JEDEC ID and SFDP/profile info.
Info,
/// Dump raw SFDP and the decoded BFPT.
Sfdp,
/// List the chips Norbert knows without SFDP (the fallback table).
List,
/// Set status-register block-protection bits.
Protect,
/// Clear status-register block-protection bits.
Unprotect,
/// Flash soft-reset (0x66/0x99); also reboots a held master.
Reset,
/// Wiring/power/speed check-up (read-only).
Doctor,
/// Read-back consistency check; with --sector N, a destructive sector self-test.
Test {
/// Destructively test sector N (backup, erase, pattern, verify, restore).
#[arg(long)]
sector: Option<usize>,
},
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn reset_defaults_off_and_parses_when_set() {
let cli = Cli::try_parse_from(["norbert", "jedec"]).expect("bare subcommand parses");
assert!(!cli.reset, "--reset must default to false");
let cli = Cli::try_parse_from(["norbert", "--reset", "jedec"]).expect("--reset parses");
assert!(cli.reset, "--reset must set the flag");
}
#[test]
fn removed_gpio_flags_are_rejected() {
use clap::error::ErrorKind;
for bad in ["--cs", "--hold-gpio", "--hold-active", "--hold-release"] {
let err = Cli::try_parse_from(["norbert", bad, "jedec"])
.err()
.unwrap_or_else(|| panic!("{bad} should no longer be a valid flag"));
assert_eq!(
err.kind(),
ErrorKind::UnknownArgument,
"{bad} should be rejected as an unknown argument"
);
}
}
}