1use std::collections::HashMap;
14
15const PAGE_HEADER: usize = 20;
16const PAGE_MAGIC: u16 = 0xb29a;
17const MIN_PAGE: usize = 512;
18const COUNTER_BITS: u32 = 27;
19const COUNTER_MASK: u32 = (1 << COUNTER_BITS) - 1;
20const KEY_SHIFT: u32 = 7;
21const KEY_MASK: u32 = (1 << 20) - 1;
22const TYPE_MASK: u32 = 0x7f;
23const LARGE_LEN_MASK: u32 = (1 << 26) - 1;
24const COUNTER_SMALL_SIZE: usize = 204;
25
26pub const APPLICATION_SIZE_700: usize = 0x3000;
28pub const IMAGE_SIZE_700: usize = 0xc000;
30pub const IMAGE_SIZE_800: usize = 0xa000;
32
33pub const PROTOCOL_VERSION_FILE: u32 = 0x50000;
35pub const CONTROLLER_INFO_FILE: u32 = 0x50004;
37pub const APPLICATION_VERSION_FILE_700: u32 = 0x51000;
39pub const APPLICATION_VERSION_FILE_800: u32 = 0x41000;
41
42#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
44#[error("NVM3 at {offset:#x}: {message}")]
45pub struct Nvm3Error {
46 pub offset: usize,
48 pub message: &'static str,
50}
51
52fn bad(offset: usize, message: &'static str) -> Nvm3Error {
53 Nvm3Error { offset, message }
54}
55
56fn berger(word: u32, bits: u32) -> u32 {
58 let w = if bits < 32 {
59 word & ((1 << bits) - 1)
60 } else {
61 word
62 };
63 bits - w.count_ones()
64}
65
66fn u32le(b: &[u8], at: usize) -> Option<u32> {
67 Some(u32::from_le_bytes(b.get(at..at + 4)?.try_into().ok()?))
68}
69
70#[derive(Debug, Clone, Copy, PartialEq, Eq)]
71enum Frag {
72 None,
73 First,
74 Next,
75 Last,
76}
77
78#[derive(Debug, Clone)]
79struct Object {
80 key: u32,
81 deleted: bool,
82 frag: Frag,
83 data: std::ops::Range<usize>,
84}
85
86#[derive(Debug, Clone)]
87struct Page {
88 erase_count: u32,
89 objects: Vec<Object>,
90}
91
92#[derive(Debug, Clone)]
94pub struct Nvm3 {
95 volumes: Vec<Vec<Page>>,
96 pub shared: bool,
98 pub page_size: usize,
100 files: HashMap<u32, Vec<u8>>,
101}
102
103fn parse_page(image: &[u8], offset: usize) -> Result<(Page, usize), Nvm3Error> {
104 let h = image
105 .get(offset..offset + PAGE_HEADER)
106 .ok_or(bad(offset, "incomplete page header"))?;
107 let version = u16::from_le_bytes([h[0], h[1]]);
108 let magic = u16::from_le_bytes([h[2], h[3]]);
109 if magic != PAGE_MAGIC {
110 return Err(bad(offset, "not an NVM3 page"));
111 }
112 if version != 1 {
113 return Err(bad(offset, "unsupported NVM3 page version"));
114 }
115 let ec = u32le(h, 4).expect("in header");
116 let eci = u32le(h, 8).expect("in header");
117 let (count, inv) = (ec & COUNTER_MASK, eci & COUNTER_MASK);
118 if berger(count, COUNTER_BITS) != ec >> COUNTER_BITS
119 || berger(inv, COUNTER_BITS) != eci >> COUNTER_BITS
120 || count != (!inv & COUNTER_MASK)
121 {
122 return Err(bad(offset, "invalid erase count"));
123 }
124 let dev_info = u16::from_le_bytes([h[16], h[17]]);
125 let mut size = MIN_PAGE << ((dev_info >> 13) & 0b111);
126 if (dev_info >> 13) & 0b111 == 0b111 {
128 size = (0..7)
129 .map(|e| MIN_PAGE << e)
130 .find(|&s| offset + s == image.len() || parse_header_ok(image, offset + s))
131 .ok_or(bad(offset, "cannot determine the page size"))?;
132 }
133 if offset + size > image.len() {
134 return Err(bad(offset, "incomplete page"));
135 }
136 let mut objects = Vec::new();
137 let mut at = offset + PAGE_HEADER;
138 let end = offset + size;
139 while at + 4 <= end {
140 let hdr1 = u32le(image, at).expect("bounded");
141 if hdr1 == u32::MAX {
142 break;
143 }
144 let key = (hdr1 >> KEY_SHIFT) & KEY_MASK;
145 let mut typ = hdr1 & TYPE_MASK;
146 let large = typ == 0 || typ == 1;
147 let (header, len, frag) = if large {
148 let hdr2 = u32le(image, at + 4).ok_or(bad(at, "incomplete object header"))?;
149 let code = berger(hdr1, 32) + berger(hdr2, 26);
150 if code != hdr2 >> 26 {
151 return Err(bad(at, "object header check failed"));
152 }
153 let frag = match (hdr1 >> 27) & 0b11 {
154 0 => Frag::None,
155 1 => Frag::First,
156 2 => Frag::Next,
157 _ => Frag::Last,
158 };
159 (8, (hdr2 & LARGE_LEN_MASK) as usize, frag)
160 } else {
161 if berger(hdr1, 27) != hdr1 >> 27 {
162 return Err(bad(at, "object header check failed"));
163 }
164 let len = if typ > 7 {
165 let l = (typ - 7) as usize;
166 typ = 7;
167 l
168 } else if typ == 2 {
169 COUNTER_SMALL_SIZE
170 } else {
171 0
172 };
173 (4, len, Frag::None)
174 };
175 let data = at + header..at + header + len;
176 if data.end > end {
177 return Err(bad(at, "object runs past its page"));
178 }
179 objects.push(Object {
180 key,
181 deleted: typ == 3,
182 frag,
183 data,
184 });
185 at += header + len.div_ceil(4) * 4;
186 }
187 Ok((
188 Page {
189 erase_count: count,
190 objects,
191 },
192 size,
193 ))
194}
195
196fn parse_header_ok(image: &[u8], offset: usize) -> bool {
197 let Some(h) = image.get(offset..offset + PAGE_HEADER) else {
198 return false;
199 };
200 u16::from_le_bytes([h[2], h[3]]) == PAGE_MAGIC && u16::from_le_bytes([h[0], h[1]]) == 1
201}
202
203fn find(image: &[u8], pages: &[Page], key: u32) -> Option<Vec<u8>> {
206 if pages.is_empty() {
207 return None;
208 }
209 let max = pages.iter().map(|p| p.erase_count).max()?;
210 let current = pages
211 .iter()
212 .rposition(|p| p.erase_count == max && !p.objects.is_empty())
213 .or_else(|| pages.iter().rposition(|p| !p.objects.is_empty()))
214 .unwrap_or(0);
215 let mut parts: Vec<&[u8]> = Vec::new();
216 for k in 0..pages.len() {
217 let page = &pages[(current + pages.len() - k) % pages.len()];
218 for o in page.objects.iter().rev() {
219 if o.key != key {
220 parts.clear();
221 continue;
222 }
223 if o.deleted {
224 return None;
225 }
226 let d = &image[o.data.clone()];
227 match o.frag {
228 Frag::None => return Some(d.to_vec()),
229 Frag::Last => parts = vec![d],
230 Frag::Next if !parts.is_empty() => parts.insert(0, d),
231 Frag::First if !parts.is_empty() => {
232 parts.insert(0, d);
233 return Some(parts.concat());
234 }
235 _ => parts.clear(),
236 }
237 }
238 }
239 None
240}
241
242impl Nvm3 {
243 pub fn parse(image: &[u8]) -> Result<Nvm3, Nvm3Error> {
245 let mut pages = Vec::new();
246 let mut offsets = Vec::new();
247 let mut at = 0;
248 let mut page_size = 0;
249 while at < image.len() {
250 let (p, size) = parse_page(image, at)?;
251 page_size = page_size.max(size);
252 offsets.push(at);
253 pages.push(p);
254 at += size;
255 }
256 let shared = pages.iter().any(|p| {
257 p.objects
258 .iter()
259 .any(|o| o.key == APPLICATION_VERSION_FILE_800)
260 });
261 let volumes = if shared {
262 vec![pages]
263 } else {
264 let (app, proto): (Vec<_>, Vec<_>) = pages
265 .into_iter()
266 .zip(offsets)
267 .partition(|(_, o)| *o < APPLICATION_SIZE_700);
268 vec![
269 app.into_iter().map(|x| x.0).collect(),
270 proto.into_iter().map(|x| x.0).collect(),
271 ]
272 };
273 let mut keys: Vec<u32> = volumes
274 .iter()
275 .flatten()
276 .flat_map(|p| p.objects.iter().map(|o| o.key))
277 .collect();
278 keys.sort_unstable();
279 keys.dedup();
280 let mut files = HashMap::new();
281 for k in keys {
282 for v in &volumes {
283 if let Some(d) = find(image, v, k) {
284 files.insert(k, d);
285 break;
286 }
287 }
288 }
289 Ok(Nvm3 {
290 volumes,
291 shared,
292 page_size,
293 files,
294 })
295 }
296
297 pub fn file(&self, key: u32) -> Option<&[u8]> {
299 self.files.get(&key).map(Vec::as_slice)
300 }
301
302 pub fn keys(&self) -> Vec<u32> {
304 let mut k: Vec<u32> = self.files.keys().copied().collect();
305 k.sort_unstable();
306 k
307 }
308
309 pub fn pages(&self) -> Vec<usize> {
311 self.volumes.iter().map(Vec::len).collect()
312 }
313}
314
315#[derive(Debug, Clone, Copy, PartialEq, Eq)]
317pub struct Version {
318 pub major: u8,
320 pub minor: u8,
322 pub patch: u8,
324 pub format: u8,
326}
327
328impl std::fmt::Display for Version {
329 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
330 write!(f, "{}.{}.{}", self.major, self.minor, self.patch)
331 }
332}
333
334fn version(d: &[u8]) -> Option<Version> {
335 (d.len() >= 4).then(|| Version {
336 patch: d[0],
337 minor: d[1],
338 major: d[2],
339 format: d[3],
340 })
341}
342
343#[derive(Debug, Clone, PartialEq, Eq)]
345pub struct NvmInfo {
346 pub shared: bool,
348 pub size: usize,
350 pub protocol: Option<Version>,
352 pub application: Option<Version>,
354 pub home_id: Option<u32>,
356 pub node_id: Option<u16>,
358}
359
360impl NvmInfo {
361 pub fn read(image: &[u8]) -> Result<NvmInfo, Nvm3Error> {
363 let n = Nvm3::parse(image)?;
364 let ci = n.file(CONTROLLER_INFO_FILE);
365 let protocol = n.file(PROTOCOL_VERSION_FILE).and_then(version);
367 let lr_format = n.shared || protocol.is_some_and(|p| p.format >= 5);
368 Ok(NvmInfo {
369 shared: n.shared,
370 size: image.len(),
371 protocol,
372 application: n
373 .file(APPLICATION_VERSION_FILE_800)
374 .or(n.file(APPLICATION_VERSION_FILE_700))
375 .and_then(version),
376 home_id: ci
377 .and_then(|c| c.get(0..4))
378 .map(|b| u32::from_be_bytes([b[0], b[1], b[2], b[3]])),
379 node_id: ci.and_then(|c| {
380 if lr_format {
381 c.get(4..6).map(|b| u16::from_le_bytes([b[0], b[1]]))
382 } else {
383 c.get(4).map(|&b| u16::from(b))
384 }
385 }),
386 })
387 }
388
389 pub fn restorable_onto(&self, target: &NvmInfo) -> Result<(), String> {
391 if self.size != target.size || self.shared != target.shared {
392 return Err(format!(
393 "the backup is a {} image of {} bytes, the controller a {} image of {} bytes; that needs conversion between series",
394 if self.shared { "800 series" } else { "700 series" },
395 self.size,
396 if target.shared { "800 series" } else { "700 series" },
397 target.size
398 ));
399 }
400 if self.shared {
401 return match (self.application, target.application) {
403 (Some(a), Some(b)) if a == b => Ok(()),
404 (Some(a), Some(b)) => Err(format!("the backup is from controller firmware {a}, the controller runs {b}; that needs conversion")),
405 _ => Err("an image has no application version file".into()),
406 };
407 }
408 match (self.protocol, target.protocol) {
409 (Some(a), Some(b)) if a.format != b.format || (a.major, a.minor) != (b.major, b.minor) => Err(format!(
410 "the backup is from protocol {a} (format {}), the controller runs {b} (format {}); that needs conversion",
411 a.format, b.format
412 )),
413 (None, _) | (_, None) => Err("an image has no protocol version file".into()),
414 _ => Ok(()),
415 }
416 }
417}
418
419fn page_header(erase_count: u32, page_size: usize) -> [u8; PAGE_HEADER] {
422 let mut h = [0u8; PAGE_HEADER];
423 h[0..2].copy_from_slice(&1u16.to_le_bytes());
424 h[2..4].copy_from_slice(&PAGE_MAGIC.to_le_bytes());
425 let ec = erase_count & COUNTER_MASK;
426 let inv = !erase_count & COUNTER_MASK;
427 h[4..8].copy_from_slice(&(ec | berger(ec, COUNTER_BITS) << COUNTER_BITS).to_le_bytes());
428 h[8..12].copy_from_slice(&(inv | berger(inv, COUNTER_BITS) << COUNTER_BITS).to_le_bytes());
429 h[12..16].copy_from_slice(&u32::MAX.to_le_bytes());
430 let bits = (page_size / MIN_PAGE).trailing_zeros() as u16;
431 h[16..18].copy_from_slice(&((bits << 13) | (1 << 12)).to_le_bytes());
432 h[18..20].copy_from_slice(&0xffffu16.to_le_bytes());
433 h
434}
435
436fn object(key: u32, data: &[u8]) -> Vec<u8> {
437 let mut v = Vec::new();
438 if data.len() <= 120 {
439 let hdr = ((7 + data.len() as u32) & TYPE_MASK) | ((key & KEY_MASK) << KEY_SHIFT);
440 v.extend_from_slice(&(hdr | berger(hdr, 27) << 27).to_le_bytes());
441 } else {
442 let hdr1 = (key & KEY_MASK) << KEY_SHIFT;
443 let hdr2 = data.len() as u32 & LARGE_LEN_MASK;
444 let code = berger(hdr1, 32) + berger(hdr2, 26);
445 v.extend_from_slice(&hdr1.to_le_bytes());
446 v.extend_from_slice(&(hdr2 | code << 26).to_le_bytes());
447 }
448 v.extend_from_slice(data);
449 v.resize(v.len().div_ceil(4) * 4, 0xff);
450 v
451}
452
453pub const RF_CONFIG_FILE: u32 = 104;
455
456fn protocol_format_for_sdk(v: Version) -> u8 {
459 let v = (v.major, v.minor, v.patch);
460 match v {
461 _ if v >= (7, 19, 0) => 5,
462 _ if v >= (7, 17, 0) => 4,
463 _ if v >= (7, 15, 3) => 3,
464 _ if v >= (7, 12, 0) => 2,
465 _ if v >= (7, 11, 0) => 1,
466 _ => 0,
467 }
468}
469
470fn application_file(key: u32) -> bool {
472 key < PROTOCOL_VERSION_FILE || key == APPLICATION_VERSION_FILE_700
473}
474
475pub fn convert(backup: &[u8], target: &[u8]) -> Result<Vec<u8>, String> {
485 let from = NvmInfo::read(backup).map_err(|e| format!("backup: {e}"))?;
486 let to = NvmInfo::read(target).map_err(|e| format!("controller: {e}"))?;
487 if from.restorable_onto(&to).is_ok() {
488 return Ok(backup.to_vec());
489 }
490 let src = Nvm3::parse(backup).map_err(|e| format!("backup: {e}"))?;
491 let tgt = Nvm3::parse(target).map_err(|e| format!("controller: {e}"))?;
492 let format = from
493 .protocol
494 .ok_or("the backup has no protocol version file, so its format cannot be told")?
495 .format;
496 let reads = match (to.protocol, to.application) {
497 (Some(p), _) => p.format.max(protocol_format_for_sdk(p)),
498 (None, Some(a)) => protocol_format_for_sdk(a),
499 (None, None) => {
500 return Err(
501 "the controller's image has no version files, so its SDK cannot be told".into(),
502 )
503 }
504 };
505 if format > reads {
506 return Err(format!(
507 "the backup's protocol format {format} is newer than this controller's SDK reads ({reads}); update the controller's firmware first"
508 ));
509 }
510 let app_key = if tgt.shared {
511 APPLICATION_VERSION_FILE_800
512 } else {
513 APPLICATION_VERSION_FILE_700
514 };
515 let app_version = tgt
516 .file(app_key)
517 .ok_or("the controller's image has no application version file")?;
518 let mut files: Vec<(u32, Vec<u8>)> = src
519 .keys()
520 .into_iter()
521 .filter(|k| {
522 ![
523 APPLICATION_VERSION_FILE_700,
524 APPLICATION_VERSION_FILE_800,
525 RF_CONFIG_FILE,
526 ]
527 .contains(k)
528 })
529 .filter_map(|k| src.file(k).map(|d| (k, d.to_vec())))
530 .collect();
531 files.push((app_key, app_version.to_vec()));
532 if let Some(rf) = tgt.file(RF_CONFIG_FILE).or(src.file(RF_CONFIG_FILE)) {
533 files.push((RF_CONFIG_FILE, rf.to_vec()));
534 }
535 files.sort_by_key(|f| f.0);
536 let page = tgt.page_size;
537 let image = if tgt.shared {
538 write_volume(target.len(), page, &files)?
539 } else {
540 if target.len() <= APPLICATION_SIZE_700 {
541 return Err("the controller's 700 series image is too small".into());
542 }
543 let (app, proto): (Vec<_>, Vec<_>) = files.into_iter().partition(|f| application_file(f.0));
544 [
545 write_volume(APPLICATION_SIZE_700, page, &app)?,
546 write_volume(target.len() - APPLICATION_SIZE_700, page, &proto)?,
547 ]
548 .concat()
549 };
550 let check = NvmInfo::read(&image).map_err(|e| format!("converted image: {e}"))?;
551 if check.home_id != from.home_id || check.shared != tgt.shared {
552 return Err("the converted image does not read back".into());
553 }
554 Ok(image)
555}
556
557pub fn write_volume(
560 size: usize,
561 page_size: usize,
562 files: &[(u32, Vec<u8>)],
563) -> Result<Vec<u8>, &'static str> {
564 if page_size < MIN_PAGE || !size.is_multiple_of(page_size) {
565 return Err("bad volume geometry");
566 }
567 let mut out = vec![0xffu8; size];
568 let mut page = 0;
569 let mut at = PAGE_HEADER;
570 for (key, data) in files {
571 let obj = object(*key, data);
572 if at + obj.len() > page_size {
573 page += 1;
574 at = PAGE_HEADER;
575 if (page + 1) * page_size > size || obj.len() + PAGE_HEADER > page_size {
576 return Err("files do not fit the volume");
577 }
578 }
579 out[page * page_size + at..page * page_size + at + obj.len()].copy_from_slice(&obj);
580 at += obj.len();
581 }
582 for p in 0..size / page_size {
583 out[p * page_size..p * page_size + PAGE_HEADER].copy_from_slice(&page_header(1, page_size));
584 }
585 Ok(out)
586}
587
588#[cfg(test)]
589mod tests {
590 use super::*;
591
592 fn ver(major: u8, minor: u8, patch: u8, format: u8) -> Vec<u8> {
593 vec![patch, minor, major, format]
594 }
595
596 #[test]
597 fn write_then_read_700_and_800() {
598 let mut ci = vec![0xc0, 0xff, 0xee, 0x01, 1];
599 ci.resize(13, 0);
600 let big: Vec<u8> = (0..300u32).map(|i| i as u8).collect();
601 let app = write_volume(
602 APPLICATION_SIZE_700,
603 2048,
604 &[(APPLICATION_VERSION_FILE_700, ver(7, 18, 1, 0))],
605 )
606 .unwrap();
607 let proto = write_volume(
608 IMAGE_SIZE_700 - APPLICATION_SIZE_700,
609 2048,
610 &[
611 (PROTOCOL_VERSION_FILE, ver(7, 17, 0, 3)),
612 (CONTROLLER_INFO_FILE, ci),
613 (0x50005, big.clone()),
614 ],
615 )
616 .unwrap();
617 let image = [app, proto].concat();
618 let n = Nvm3::parse(&image).unwrap();
619 assert!(!n.shared);
620 assert_eq!(n.file(0x50005), Some(&big[..]));
621 let info = NvmInfo::read(&image).unwrap();
622 assert_eq!(info.home_id, Some(0xc0ffee01));
623 assert_eq!(info.node_id, Some(1));
624 assert_eq!(info.protocol.unwrap().to_string(), "7.17.0");
625
626 let mut ci = vec![0xc0, 0xff, 0xee, 0x02, 1, 0];
627 ci.resize(22, 0);
628 let shared = write_volume(
629 IMAGE_SIZE_800,
630 8192,
631 &[
632 (APPLICATION_VERSION_FILE_800, ver(7, 23, 0, 0)),
633 (PROTOCOL_VERSION_FILE, ver(7, 23, 0, 5)),
634 (CONTROLLER_INFO_FILE, ci),
635 ],
636 )
637 .unwrap();
638 let info8 = NvmInfo::read(&shared).unwrap();
639 assert!(info8.shared);
640 assert_eq!((info8.home_id, info8.node_id), (Some(0xc0ffee02), Some(1)));
641 assert!(info.restorable_onto(&info).is_ok());
642 assert!(info
643 .restorable_onto(&info8)
644 .unwrap_err()
645 .contains("conversion"));
646 }
647
648 #[test]
649 fn corrupt_images_are_refused() {
650 let mut v = write_volume(4096, 2048, &[(PROTOCOL_VERSION_FILE, ver(7, 17, 0, 3))]).unwrap();
651 assert!(Nvm3::parse(&v).is_ok());
652 v[PAGE_HEADER] ^= 0x01;
653 assert!(Nvm3::parse(&v).is_err(), "object header check");
654 assert!(Nvm3::parse(&[0u8; 100]).is_err());
655 assert!(Nvm3::parse(&[]).is_ok_and(|n| n.keys().is_empty()));
656 }
657}