|
| 1 | +//! FLASH_LAYOUT extended-image parser for SAS2008 firmware. |
| 2 | +//! |
| 3 | +//! `FLASH_LAYOUT` is an MPI extended image (`MPI2_EXT_IMAGE_TYPE_FLASH_LAYOUT = 0x06`) |
| 4 | +//! embedded *inside* a firmware blob — NOT a config page. It is located by walking |
| 5 | +//! the extended-image linked list from the FW header's `NextImageHeaderOffset`, and |
| 6 | +//! defines the flash partition map (region offsets/sizes) for each candidate chip |
| 7 | +//! geometry. The bootloader selects the layout matching the detected physical chip. |
| 8 | +//! |
| 9 | +//! Cites: references/upstream/lsiutil/lsi/mpi2_ioc.h — |
| 10 | +//! `MPI2_FW_IMAGE_HEADER` (NextImageHeaderOffset@0x30), |
| 11 | +//! `MPI2_EXT_IMAGE_HEADER` (ImageType@0x00, ImageSize@0x08, NextImageHeaderOffset@0x0C), |
| 12 | +//! `MPI2_FLASH_LAYOUT_DATA` / `MPI2_FLASH_LAYOUT` / `MPI2_FLASH_REGION` (1469-1518). |
| 13 | +//! |
| 14 | +//! Validated against the lsi-flash-firmware corpus (2026-05-29): see |
| 15 | +//! lsi-flash-notes/02-hardware/flash-regions.md. |
| 16 | +
|
| 17 | +use crate::firmware::inspect::{FwError, MPI2_FW_HEADER_SIGNATURE}; |
| 18 | + |
| 19 | +/// `MPI2_FLASH_REGION_FIRMWARE` — the region a `fw` image lands in (mpi2_ioc.h:1507). |
| 20 | +pub const REGION_FIRMWARE: u8 = 0x01; |
| 21 | + |
| 22 | +const EXT_IMAGE_TYPE_FLASH_LAYOUT: u8 = 0x06; |
| 23 | +const FW_HDR_NEXT_IMAGE_OFFSET: usize = 0x30; // U32 in MPI2_FW_IMAGE_HEADER |
| 24 | + |
| 25 | +/// One flash region within a layout (`MPI2_FLASH_REGION`, 16 bytes). |
| 26 | +#[derive(Debug, Clone, Copy, PartialEq, Eq)] |
| 27 | +pub struct FlashRegion { |
| 28 | + pub region_type: u8, |
| 29 | + pub offset: u32, |
| 30 | + pub size: u32, |
| 31 | +} |
| 32 | + |
| 33 | +/// One candidate flash geometry, keyed by physical chip size (`MPI2_FLASH_LAYOUT`). |
| 34 | +#[derive(Debug, Clone, PartialEq, Eq)] |
| 35 | +pub struct Layout { |
| 36 | + pub flash_size: u32, |
| 37 | + pub regions: Vec<FlashRegion>, |
| 38 | +} |
| 39 | + |
| 40 | +/// Parsed FLASH_LAYOUT: all candidate geometries the firmware supports. |
| 41 | +#[derive(Debug, Clone, PartialEq, Eq)] |
| 42 | +pub struct FlashLayout { |
| 43 | + pub layouts: Vec<Layout>, |
| 44 | +} |
| 45 | + |
| 46 | +impl FlashLayout { |
| 47 | + /// Distinct FIRMWARE-region sizes across all candidate layouts, ascending. |
| 48 | + /// (1 MiB on >=4 MB chips, 640 KiB on the 2 MB chip layout — corpus 2026-05-29.) |
| 49 | + pub fn firmware_region_sizes(&self) -> Vec<u32> { |
| 50 | + let mut v: Vec<u32> = self |
| 51 | + .layouts |
| 52 | + .iter() |
| 53 | + .flat_map(|l| l.regions.iter()) |
| 54 | + .filter(|r| r.region_type == REGION_FIRMWARE) |
| 55 | + .map(|r| r.size) |
| 56 | + .collect(); |
| 57 | + v.sort_unstable(); |
| 58 | + v.dedup(); |
| 59 | + v |
| 60 | + } |
| 61 | +} |
| 62 | + |
| 63 | +fn rd_u16(d: &[u8], o: usize) -> u16 { |
| 64 | + u16::from_le_bytes([d[o], d[o + 1]]) |
| 65 | +} |
| 66 | +fn rd_u32(d: &[u8], o: usize) -> u32 { |
| 67 | + u32::from_le_bytes([d[o], d[o + 1], d[o + 2], d[o + 3]]) |
| 68 | +} |
| 69 | + |
| 70 | +/// Walk the extended-image chain and parse the embedded FLASH_LAYOUT. |
| 71 | +/// |
| 72 | +/// The ext-image offset is image-specific (a linked list), never hardcoded. |
| 73 | +pub fn parse_flash_layout(data: &[u8]) -> Result<FlashLayout, FwError> { |
| 74 | + if data.len() < 0x40 || rd_u32(data, 0) != MPI2_FW_HEADER_SIGNATURE { |
| 75 | + return Err(FwError::TooShort(data.len())); |
| 76 | + } |
| 77 | + |
| 78 | + // 1. Find the FLASH_LAYOUT ext-image by walking the chain. |
| 79 | + let mut off = rd_u32(data, FW_HDR_NEXT_IMAGE_OFFSET) as usize; |
| 80 | + let mut seen = std::collections::HashSet::new(); |
| 81 | + let mut base = None; |
| 82 | + while off != 0 && off + 0x10 <= data.len() && seen.insert(off) { |
| 83 | + let itype = data[off]; // MPI2_EXT_IMAGE_HEADER.ImageType @0x00 |
| 84 | + let next = rd_u32(data, off + 0x0C) as usize; // NextImageHeaderOffset @0x0C |
| 85 | + if itype == EXT_IMAGE_TYPE_FLASH_LAYOUT { |
| 86 | + base = Some(off); |
| 87 | + break; |
| 88 | + } |
| 89 | + if next == 0 || next == off { |
| 90 | + break; |
| 91 | + } |
| 92 | + off = next; |
| 93 | + } |
| 94 | + let base = base.ok_or(FwError::NoFlashLayout)?; |
| 95 | + |
| 96 | + // 2. Locate MPI2_FLASH_LAYOUT_DATA within the ext-image payload. A vendor |
| 97 | + // identify-string region precedes it; the struct begins where |
| 98 | + // SizeOfRegion==0x10 with sane NumberOfLayouts / RegionsPerLayout counts. |
| 99 | + let payload = base + 0x10; |
| 100 | + let scan_end = (payload + 0x40).min(data.len().saturating_sub(0x20)); |
| 101 | + let mut d = None; |
| 102 | + for c in payload..scan_end { |
| 103 | + let size_of_region = data[c + 0x02]; |
| 104 | + let n_layouts = rd_u16(data, c + 0x04); |
| 105 | + let regions_per = rd_u16(data, c + 0x06); |
| 106 | + if size_of_region == 0x10 |
| 107 | + && data[c] == 0x00 |
| 108 | + && (1..=16).contains(&n_layouts) |
| 109 | + && (1..=16).contains(®ions_per) |
| 110 | + { |
| 111 | + d = Some(c); |
| 112 | + break; |
| 113 | + } |
| 114 | + } |
| 115 | + let d = d.ok_or(FwError::NoFlashLayout)?; |
| 116 | + |
| 117 | + let size_of_region = data[d + 0x02] as usize; // 0x10 |
| 118 | + let n_layouts = rd_u16(data, d + 0x04) as usize; |
| 119 | + let regions_per = rd_u16(data, d + 0x06) as usize; |
| 120 | + let stride = 0x10 + regions_per * size_of_region; // MPI2_FLASH_LAYOUT size |
| 121 | + |
| 122 | + let mut layouts = Vec::with_capacity(n_layouts); |
| 123 | + for li in 0..n_layouts { |
| 124 | + let lp = d + 0x10 + li * stride; |
| 125 | + if lp + stride > data.len() { |
| 126 | + break; |
| 127 | + } |
| 128 | + let flash_size = rd_u32(data, lp); // MPI2_FLASH_LAYOUT.FlashSize @0x00 |
| 129 | + let mut regions = Vec::with_capacity(regions_per); |
| 130 | + for ri in 0..regions_per { |
| 131 | + let ro = lp + 0x10 + ri * size_of_region; |
| 132 | + regions.push(FlashRegion { |
| 133 | + region_type: data[ro], // @0x00 |
| 134 | + offset: rd_u32(data, ro + 0x04), // @0x04 |
| 135 | + size: rd_u32(data, ro + 0x08), // @0x08 |
| 136 | + }); |
| 137 | + } |
| 138 | + layouts.push(Layout { |
| 139 | + flash_size, |
| 140 | + regions, |
| 141 | + }); |
| 142 | + } |
| 143 | + if layouts.is_empty() { |
| 144 | + return Err(FwError::NoFlashLayout); |
| 145 | + } |
| 146 | + Ok(FlashLayout { layouts }) |
| 147 | +} |
| 148 | + |
| 149 | +#[cfg(test)] |
| 150 | +mod tests { |
| 151 | + use super::*; |
| 152 | + |
| 153 | + /// Parse FLASH_LAYOUT from the golden 2118it.bin (skips if fixture absent). |
| 154 | + /// Every SAS2008 layout must expose a 1 MiB FIRMWARE region; the geometry |
| 155 | + /// is corpus-validated in lsi-flash-notes/02-hardware/flash-regions.md. |
| 156 | + #[test] |
| 157 | + fn parses_2118it_flash_layout() { |
| 158 | + let base = std::env::var("LSI_FLASH_FIXTURES").unwrap_or_else(|_| { |
| 159 | + "/Users/mjackson/Developer/lsi-flash-notes/09-research-archive/upstream/lsi_sas_hba_crossflash_guide".to_string() |
| 160 | + }); |
| 161 | + let fixture = std::path::PathBuf::from(base).join("2118it.bin"); |
| 162 | + let Ok(data) = std::fs::read(&fixture) else { |
| 163 | + eprintln!("skipping: fixture {} not present", fixture.display()); |
| 164 | + return; |
| 165 | + }; |
| 166 | + let fl = parse_flash_layout(&data).expect("FLASH_LAYOUT should parse"); |
| 167 | + assert!(!fl.layouts.is_empty()); |
| 168 | + let fw_sizes = fl.firmware_region_sizes(); |
| 169 | + assert!( |
| 170 | + fw_sizes.contains(&0x100000), |
| 171 | + "expected a 1 MiB FW region, got {:X?}", |
| 172 | + fw_sizes |
| 173 | + ); |
| 174 | + // Every layout must contain exactly one FIRMWARE region. |
| 175 | + for l in &fl.layouts { |
| 176 | + let n = l |
| 177 | + .regions |
| 178 | + .iter() |
| 179 | + .filter(|r| r.region_type == REGION_FIRMWARE) |
| 180 | + .count(); |
| 181 | + assert_eq!(n, 1, "each layout has one FIRMWARE region"); |
| 182 | + } |
| 183 | + } |
| 184 | + |
| 185 | + #[test] |
| 186 | + fn rejects_non_firmware_blob() { |
| 187 | + assert!(matches!( |
| 188 | + parse_flash_layout(&[0u8; 0x80]), |
| 189 | + Err(FwError::TooShort(_)) |
| 190 | + )); |
| 191 | + } |
| 192 | +} |
0 commit comments