mediatek_optical/image/
chip.rs

1//! Chip generation and identity detection from image bytes.
2//!
3//! The authoritative signal for the chip generation (MT1959 vs MT1939) is the
4//! **boot loader banner** at image offset `0x3000` ([`layout::BANNER`], 16
5//! bytes), e.g. `"MT1959 Boot JB8 "` or `"MT1939 Boot Code"`. The family is
6//! decided by [`Chip::from_banner`] over that banner and by nothing else.
7//!
8//! Why the banner and not the `MTEKMT19xx` identity string: across a 119-image
9//! corpus of clean OEM images the banner agrees with the actual code generation
10//! 119/119, whereas the `MTEKMT19xx` descriptor tag is a *stale vendor label*
11//! that is wrong for 55 of them — the JB8/JBC6/JBP6/BUP1 builds (LG WH16NS58,
12//! WH16NS60, BH16NS40..NS50, …) carry the tag `MTEKMT1939` but ship an MT1959
13//! boot loader and MT1959 code. So the tag drives **no logic anywhere**: not the
14//! family, not a fallback, not a gate, not the family hash, not an engine
15//! choice. It is retained only as an optional display field ([`ChipInfo::identity_tag`])
16//! — a curiosity, never a decision.
17//!
18//! Two other things that *look* like family signals are also NOT used to gate
19//! the family:
20//!
21//! * the `MTEKMT19xx` identity string (see above) — display-only;
22//! * the descriptor **marker byte** at `+0x50` takes `0x78/0x58/0x18/0x38`
23//!   within a single family (a variant/region/downgrade flag beside the DE byte
24//!   at `+0x56`) — display-only, never a gate.
25//!
26//! Detection refuses cleanly on an image whose boot banner names no supported
27//! MT19xx generation ([`ChipError::Undetectable`]); the caller then aborts with
28//! a clear message rather than guessing.
29
30use crate::layout;
31use crate::Chip;
32
33const BANNER_OFFSET: usize = layout::BANNER.start;
34const BANNER_LEN: usize = layout::BANNER.len;
35const DESCRIPTOR_OFFSET: usize = layout::DESCRIPTOR.start;
36/// Bytes of the descriptor record consumed by parsing.
37const DESCRIPTOR_LEN: usize = 0x40;
38/// Offset of the descriptor's `MTEKMT19..` family tag within the record.
39const DESCRIPTOR_TAG_OFF: usize = 0x34;
40/// Offset of the display-only marker byte within the descriptor record.
41const DESCRIPTOR_MARKER_OFF: usize = 0x50;
42
43/// Everything the tools could read off the image about its chip identity. The
44/// `banner`, `vendor`, `model`, `rev`, `marker_0x50` and `identity_tag` fields
45/// are display / corroboration only — the `family` is decided by
46/// [`Chip::from_banner`] over the boot banner at [`layout::BANNER`] and nothing
47/// else.
48#[derive(Debug, Clone, PartialEq, Eq)]
49#[non_exhaustive]
50pub struct ChipInfo {
51    /// The chip family, decided by the boot banner ([`Chip::from_banner`]).
52    pub family: Chip,
53    /// The trimmed boot-banner string (e.g. `"MT1959 Boot BU5"`). The authoritative
54    /// source of `family`; also shown for display.
55    pub banner: String,
56    /// Trimmed vendor field from the descriptor (e.g. `"HL-DT-ST"`). May be empty
57    /// if the image has no well-formed identity page.
58    pub vendor: String,
59    /// Trimmed model field from the descriptor (e.g. `"BD-RE BU40N"`).
60    pub model: String,
61    /// Trimmed revision field from the descriptor (e.g. `"1.00"`).
62    pub rev: String,
63    /// Trimmed vendor-specific field from the descriptor (e.g. `"N003600"`) — the
64    /// region/SKU code MakeMKV/LibreDrive key on. Empty if no identity page.
65    pub vendor_specific: String,
66    /// The matched `MTEKMT19xx` identity string, if any. A **stale vendor label**:
67    /// display / audit only, it NEVER influences `family` (see module docs).
68    pub identity_tag: Option<String>,
69    /// The display-only marker byte at descriptor `+0x50`, if present. NEVER
70    /// gates the family (see module docs).
71    pub marker_0x50: Option<u8>,
72    /// Whether the image carries a well-formed MTEK identity page at
73    /// [`layout::DESCRIPTOR`] (tag `MTEKMT19..` present). Gates identity-page
74    /// edits such as the downgrade-enable byte.
75    pub descriptor_present: bool,
76}
77
78/// Trim NUL padding and surrounding whitespace from a lossily-decoded ASCII
79/// field.
80fn ascii_trim(bytes: &[u8]) -> String {
81    String::from_utf8_lossy(bytes)
82        .trim_matches(|c: char| c == '\0' || c.is_whitespace())
83        .to_string()
84}
85
86/// Scan `image` for the first `MTEKMT19` + two-ASCII-digit occurrence and return
87/// the matched 10-byte string (display / audit only — never used for `family`).
88fn first_mtek_tag(image: &[u8]) -> Option<String> {
89    const PREFIX: &[u8] = b"MTEKMT19";
90    if image.len() < PREFIX.len() + 2 {
91        return None;
92    }
93    let mut i = 0;
94    while i + PREFIX.len() + 2 <= image.len() {
95        if &image[i..i + PREFIX.len()] == PREFIX {
96            let d0 = image[i + PREFIX.len()];
97            let d1 = image[i + PREFIX.len() + 1];
98            if d0.is_ascii_digit() && d1.is_ascii_digit() {
99                return Some(String::from_utf8_lossy(&image[i..i + PREFIX.len() + 2]).into_owned());
100            }
101        }
102        i += 1;
103    }
104    None
105}
106
107/// Why [`detect_chip`] could not name a chip.
108#[derive(Debug, Clone, PartialEq, Eq)]
109#[non_exhaustive]
110pub enum ChipError {
111    /// The boot banner at [`layout::BANNER`] names no supported MT19xx
112    /// generation (MT1959 or MT1939). Unpack packed/truncated dumps first.
113    Undetectable,
114}
115
116impl std::fmt::Display for ChipError {
117    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
118        match self {
119            Self::Undetectable => f.write_str(
120                "undetectable — the boot loader banner at 0x3000 names no supported MT19xx \
121                 generation (only MT1959 and MT1939 are handled; unpack packed/truncated \
122                 dumps first)",
123            ),
124        }
125    }
126}
127
128impl std::error::Error for ChipError {}
129
130/// Detect the chip family + model/rev from `image`.
131///
132/// Family is decided by the boot loader banner at [`layout::BANNER`] via
133/// [`Chip::from_banner`], and by nothing else — the `MTEKMT19xx` identity string
134/// is a stale vendor label kept only in [`ChipInfo::identity_tag`] for display.
135/// Fails with [`ChipError::Undetectable`] only when the banner names no supported
136/// generation.
137pub fn detect_chip(image: &[u8]) -> Result<ChipInfo, ChipError> {
138    // --- Family: the boot loader banner is the single authoritative source. ---
139    let banner = read_banner(image);
140    let family = banner
141        .as_deref()
142        .and_then(|b: &str| Chip::from_banner(b.as_bytes()))
143        .ok_or(ChipError::Undetectable)?;
144
145    // --- Identity tag (stale vendor label): display / audit only. ---
146    let identity_tag = first_mtek_tag(image);
147
148    // --- Descriptor parse (display-only + DE anchor). ---
149    let (vendor, model, rev, vendor_specific, marker_0x50, descriptor_present) =
150        parse_descriptor(image);
151
152    Ok(ChipInfo {
153        family,
154        banner: banner.unwrap_or_default(),
155        vendor,
156        model,
157        rev,
158        vendor_specific,
159        identity_tag,
160        marker_0x50,
161        descriptor_present,
162    })
163}
164
165/// Read + trim the boot banner at [`layout::BANNER`], or `None` if the image is
166/// too small to contain it.
167fn read_banner(image: &[u8]) -> Option<String> {
168    if image.len() < BANNER_OFFSET + BANNER_LEN {
169        return None;
170    }
171    let banner_bytes = &image[BANNER_OFFSET..BANNER_OFFSET + BANNER_LEN];
172    let nul = banner_bytes
173        .iter()
174        .position(|&b| b == 0)
175        .unwrap_or(banner_bytes.len());
176    let s = ascii_trim(&banner_bytes[..nul]);
177    if s.is_empty() {
178        None
179    } else {
180        Some(s)
181    }
182}
183
184/// Parse the display-only descriptor fields and detect a well-formed identity
185/// page. Returns `(vendor, model, rev, vendor_specific, marker_0x50,
186/// descriptor_present)`; all strings empty and `descriptor_present == false` when
187/// no identity page exists.
188///
189/// Descriptor record layout (mirrors the drive's SCSI INQUIRY): vendor@0x00 (8),
190/// model@0x08 (16), rev@0x18 (4), `vendor_specific`@0x1C (8) — the region/SKU code
191/// MakeMKV/LibreDrive key on (e.g. `N003600`) — then a `UNIQUE<ts>` stamp and the
192/// `MTEKMT19xx` tag @0x34.
193fn parse_descriptor(image: &[u8]) -> (String, String, String, String, Option<u8>, bool) {
194    if image.len() < DESCRIPTOR_OFFSET + DESCRIPTOR_LEN {
195        return (
196            String::new(),
197            String::new(),
198            String::new(),
199            String::new(),
200            None,
201            false,
202        );
203    }
204    let desc = &image[DESCRIPTOR_OFFSET..DESCRIPTOR_OFFSET + DESCRIPTOR_LEN];
205    let tag_present = desc[DESCRIPTOR_TAG_OFF..].starts_with(b"MTEKMT19");
206    let vendor = ascii_trim(&desc[0x00..0x08]);
207    let model = ascii_trim(&desc[0x08..0x18]);
208    let rev = ascii_trim(&desc[0x18..0x1C]);
209    let vendor_specific = ascii_trim(&desc[0x1C..0x24]);
210    // The marker byte lives at descriptor `+0x50`, PAST the 0x40-byte record, so
211    // it is read from the image directly (with a bounds check), not the slice.
212    let marker = image
213        .get(DESCRIPTOR_OFFSET + DESCRIPTOR_MARKER_OFF)
214        .copied();
215    if tag_present {
216        (vendor, model, rev, vendor_specific, marker, true)
217    } else {
218        // No identity page: still expose the marker byte for audit, but report
219        // no descriptor and empty display fields (they'd be garbage).
220        (
221            String::new(),
222            String::new(),
223            String::new(),
224            String::new(),
225            marker,
226            false,
227        )
228    }
229}
230
231#[cfg(test)]
232#[path = "chip_tests.rs"]
233mod tests;
mediatek_optical/image/chip.rs

mediatek_optical/image/
chip.rs
