//! Deterministic GDS object review without the normalization performed by the //! Arrow reader. Raw payloads borrow the file; only polygon keys are copied. use crate::{ basic::{ErrType, decode_name, decode_real8, encode_real8, unpad_ascii}, record::{Record as _, RecordFrame}, records::*, }; use std::{ borrow::Cow, collections::{BTreeMap, BTreeSet}, fmt::{self, Write}, }; pub mod changes; mod hierarchy; pub mod names; mod pair; pub mod report; pub mod selection; mod text; use changes::Replacement; use pair::CellReuse; pub use pair::RevisionPair; use selection::{DisplayFilter, Scope}; pub use text::{TextReport, TextReportOptions, TextStyle}; /// Input revision associated with a diagnostic. #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub enum Side { Old, New, } impl fmt::Display for Side { fn fmt(&self, out: &mut fmt::Formatter<'_>) -> fmt::Result { out.write_str(match self { Self::Old => "old", Self::New => "new", }) } } /// A review error or comparison limitation, with structured source context. #[derive(Clone, Debug)] pub struct Diagnostic { pub code: &'static str, pub message: String, pub side: Option, pub offset: Option, pub cell: Option, pub layer: Option, pub target: Option, } impl Diagnostic { pub fn new(code: &'static str, message: impl Into, side: Option) -> Self { Self { code, message: message.into(), side, offset: None, cell: None, layer: None, target: None, } } fn at(code: &'static str, offset: usize, message: String) -> Self { Self { offset: Some(offset), ..Self::new(code, error(offset, message), None) } } } impl fmt::Display for Diagnostic { fn fmt(&self, out: &mut fmt::Formatter<'_>) -> fmt::Result { if let Some(side) = self.side { write!(out, "{side}: ")?; } out.write_str(&self.message) } } /// The five meaningful combinations of completeness and comparison result. #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub enum Outcome { Equal, Different, Incomplete { different: bool }, Failed, } impl Outcome { pub fn status(self) -> &'static str { match self { Self::Equal | Self::Different => "complete", Self::Incomplete { .. } => "incomplete", Self::Failed => "failed", } } pub fn result(self) -> &'static str { match self { Self::Equal => "equal", Self::Different | Self::Incomplete { different: true } => "different", Self::Incomplete { different: false } | Self::Failed => "unknown", } } pub fn exit_code(self) -> u8 { match self { Self::Equal => 0, Self::Different => 1, _ => 2, } } pub fn is_equal(self) -> bool { self == Self::Equal } pub fn is_complete(self) -> bool { matches!(self, Self::Equal | Self::Different) } } pub const PROFILE: &str = "pheon-structural-v1"; pub type Layer = (u16, u16); pub type Bounds = [i32; 4]; #[derive(Clone, Debug)] pub struct Record<'a> { pub offset: usize, pub tag: u16, pub data: &'a [u8], } #[derive(Clone, Debug, Eq, PartialEq, Ord, PartialOrd)] struct Key<'a> { kind: u16, fields: Vec<(u16, Cow<'a, [u8]>)>, properties: Vec<(u16, &'a [u8])>, } #[derive(Clone, Debug)] pub struct Object<'a> { pub offset: usize, pub end_offset: usize, pub kind: u16, pub layer: Option, pub bounds: Option, pub target: Option, pub multiplicity: u64, key: Key<'a>, metadata: bool, issues: Vec, } impl Object<'_> { fn field(&self, tag: u16) -> Option<&[u8]> { self.key .fields .iter() .find(|(t, _)| *t == tag) .map(|(_, v)| v.as_ref()) } } fn format_object<'a, W: fmt::Write>( out: &mut W, kind: u16, layer: Option, fields: impl Iterator + Clone, properties: impl IntoIterator, heading: impl FnOnce(&mut W, &'static str) -> fmt::Result, ) -> fmt::Result { let field = |tag| { fields .clone() .find_map(|(t, data)| (t == tag).then_some(data)) }; let rectangle = if is_polygon(kind) { field(RTAG_XY).and_then(XY::closed_rectangle) } else { None }; let target = if matches!(kind, RTAG_SREF | RTAG_AREF) { field(RTAG_SNAME) } else { None }; let dimensions = if kind == RTAG_AREF { field(RTAG_COLROW).and_then(array_dimensions) } else { None }; heading(out, object_name(kind, rectangle.is_some()))?; if let Some(target) = target { write!(out, " {}", quoted(target))?; } if let Some([columns, rows]) = dimensions { write!(out, " ({columns} × {rows})")?; } for (tag, value) in fields { if (layer.is_some() && matches_layer_field(kind, tag)) || (tag == RTAG_SNAME && target.is_some()) || (tag == RTAG_COLROW && dimensions.is_some()) { continue; } if tag == RTAG_XY && value.len().is_multiple_of(8) { if let Some([xmin, ymin, xmax, ymax]) = rectangle { write!(out, " ({xmin}, {ymin}) to ({xmax}, {ymax})")?; } else { write_points(out, value)?; } } else { write!(out, " {}={}", tag_name(tag), format_exact_value(tag, value))?; } } for (attribute, value) in properties { write!(out, " property[{attribute}]={}", quoted(value))?; } Ok(()) } fn array_dimensions(data: &[u8]) -> Option<[u16; 2]> { let [column_hi, column_lo, row_hi, row_lo]: [u8; 4] = data.try_into().ok()?; Some([ u16::from_be_bytes([column_hi, column_lo]), u16::from_be_bytes([row_hi, row_lo]), ]) } const POINTS_PER_LINE: usize = 4; fn write_points(out: &mut impl fmt::Write, data: &[u8]) -> fmt::Result { let mut points = XY::points(data); if points.len() == 1 { let [x, y] = points.next().unwrap(); return write!(out, " xy=({x}, {y})"); } out.write_str(" xy=[")?; for (index, [x, y]) in points.enumerate() { if index != 0 { out.write_str(if index % POINTS_PER_LINE == 0 { ",\n " } else { ", " })?; } write!(out, "({x}, {y})")?; } out.write_str("]") } impl fmt::Display for Object<'_> { fn fmt(&self, out: &mut fmt::Formatter<'_>) -> fmt::Result { self.format_with_heading(out, |out, name| write_object_heading(out, self.layer, name)) } } fn write_object_heading( out: &mut impl fmt::Write, layer: Option, name: &str, ) -> fmt::Result { if let Some((layer, datatype)) = layer { write!(out, "{layer}/{datatype}: ")?; } out.write_str(name) } impl Object<'_> { fn format_with_heading( &self, out: &mut W, heading: impl FnOnce(&mut W, &'static str) -> fmt::Result, ) -> fmt::Result { format_object( out, self.kind, self.layer, self.key .fields .iter() .map(|(tag, data)| (*tag, data.as_ref())), self.key.properties.iter().copied(), heading, ) } } #[derive(Debug)] pub struct Cell<'a> { pub offset: usize, /// Start of ENDSTR, for inserting records without rewriting the cell. pub end_offset: usize, pub objects: Vec>, attributes: Vec<(u16, &'a [u8])>, issues: Vec, } #[derive(Debug)] pub struct Document<'a> { pub records: Vec>, pub cells: BTreeMap>, pub layer_names: BTreeMap, /// Unsupported features or invalid reference graphs prevent an equality claim. pub diagnostics: Vec, header: Vec<(u16, &'a [u8])>, global_issues: Vec, known_cells: BTreeSet, pub scope: Scope, present: bool, } fn error(offset: usize, message: impl std::fmt::Display) -> String { format!("at byte {offset}: {message}") } fn decoded_string(data: &[u8], offset: usize) -> Result { if data.contains(&0) { return Err(error(offset, "name or metadata contains an embedded NUL")); } std::str::from_utf8(data) .map(str::to_owned) .map_err(|_| error(offset, "name or metadata is not UTF-8")) } fn integer(data: &[u8]) -> u16 { u16::from_be_bytes(data.try_into().unwrap()) } fn coordinate_bounds(points: impl IntoIterator) -> Bounds { let mut points = points.into_iter(); let [x, y] = points.next().unwrap(); points.fold([x, y, x, y], |[xmin, ymin, xmax, ymax], [x, y]| { [xmin.min(x), ymin.min(y), xmax.max(x), ymax.max(y)] }) } // Booth's least-rotation algorithm avoids quadratic work on repeated vertices. fn least_rotation(n: usize, point: impl Fn(usize) -> [i32; 2]) -> usize { let (mut i, mut j, mut k) = (0, 1, 0); while i < n && j < n && k < n { match point((i + k) % n).cmp(&point((j + k) % n)) { std::cmp::Ordering::Equal => k += 1, std::cmp::Ordering::Greater => { i += k + 1; if i <= j { i = j + 1; } k = 0; } std::cmp::Ordering::Less => { j += k + 1; if j <= i { j = i + 1; } k = 0; } } } i.min(j) } fn canonical_ring(data: &[u8]) -> Option> { let (points, _) = data.as_chunks::<8>(); let (last, ring) = points.split_last()?; if ring.len() < 3 || ring.first() != Some(last) { return None; } let n = ring.len(); let first = least_rotation(n, |index| XY::point(ring[index])); let split = n - least_rotation(n, |index| XY::point(ring[n - 1 - index])); let forward = ring[first..].iter().chain(&ring[..first]); let backward = ring[..split].iter().rev().chain(ring[split..].iter().rev()); let decode = |point: &[u8; 8]| XY::point(*point); let use_forward = forward .clone() .map(decode) .cmp(backward.clone().map(decode)) .is_le(); if use_forward && first == 0 { return Some(Cow::Borrowed(data)); } let mut result = Vec::with_capacity(data.len()); if use_forward { result.extend(forward.flatten().copied()); } else { result.extend(backward.flatten().copied()); } result.extend_from_within(..8); Some(Cow::Owned(result)) } fn validate_payload(record: &Record<'_>) -> Result<(), String> { let size = record.data.len() as u16; check_payload_size(record.tag, size).map_err(|message| { error( record.offset, format!( "invalid payload size {size} for {}: {message}", tag_name(record.tag) ), ) })?; if record.tag == RTAG_UNITS { UNITS::read_data(record.data, size) .map_err(|(_, reason)| payload_error(record.offset, reason))?; } Ok(()) } fn payload_error(offset: usize, reason: ErrType) -> String { match reason { ErrType::Failed(message) => error(offset, message), ErrType::Incomplete(_) => error(offset, "truncated record payload"), } } fn is_element(tag: u16) -> bool { matches!( tag, RTAG_BOUNDARY | RTAG_PATH | RTAG_SREF | RTAG_AREF | RTAG_TEXT | RTAG_NODE | RTAG_BOX ) } fn is_polygon(kind: u16) -> bool { matches!(kind, RTAG_BOUNDARY | RTAG_BOX) } fn layer_type_tag(kind: u16) -> u16 { match kind { RTAG_TEXT => RTAG_TEXTTYPE, RTAG_NODE => RTAG_NODETYPE, RTAG_BOX => RTAG_BOXTYPE, _ => RTAG_DATATYPE, } } fn matches_layer_field(kind: u16, tag: u16) -> bool { tag == RTAG_LAYER || tag == layer_type_tag(kind) } fn allowed_field(kind: u16, tag: u16) -> bool { if matches!(tag, RTAG_ELFLAGS | RTAG_PLEX | RTAG_XY) { return true; } match kind { RTAG_BOUNDARY => matches!(tag, RTAG_LAYER | RTAG_DATATYPE), RTAG_BOX => matches!(tag, RTAG_LAYER | RTAG_BOXTYPE), RTAG_NODE => matches!(tag, RTAG_LAYER | RTAG_NODETYPE), RTAG_PATH => matches!( tag, RTAG_LAYER | RTAG_DATATYPE | RTAG_WIDTH | RTAG_PATHTYPE | RTAG_BGNEXTN | RTAG_ENDEXTN ), RTAG_SREF => matches!(tag, RTAG_SNAME | RTAG_STRANS | RTAG_MAG | RTAG_ANGLE), RTAG_AREF => matches!( tag, RTAG_SNAME | RTAG_STRANS | RTAG_MAG | RTAG_ANGLE | RTAG_COLROW ), RTAG_TEXT => matches!( tag, RTAG_LAYER | RTAG_TEXTTYPE | RTAG_STRING | RTAG_STRANS | RTAG_MAG | RTAG_ANGLE | RTAG_PRESENTATION | RTAG_PATHTYPE | RTAG_WIDTH ), _ => false, } } fn object<'a>(records: &[Record<'a>], issues: &mut Vec) -> Result, String> { let first = &records[0]; let mut fields = Vec::new(); let mut properties = Vec::new(); let mut target = None; let mut seen = BTreeSet::new(); let mut i = 1; while i + 1 < records.len() { let record = &records[i]; if record.tag == RTAG_PROPATTR { let value = records .get(i + 1) .filter(|r| r.tag == RTAG_PROPVALUE) .ok_or_else(|| error(record.offset, "PROPATTR without PROPVALUE"))?; properties.push((integer(record.data), unpad_ascii(value.data))); i += 2; continue; } if !allowed_field(first.tag, record.tag) { issues.push(Diagnostic::at( "unsupported_record", record.offset, format!( "unsupported record 0x{:04x} in {}", record.tag, kind_name(first.tag) ), )); } if !seen.insert(record.tag) { return Err(error(record.offset, "duplicate element field")); } let mut data = Cow::Borrowed(record.data); if record.tag == RTAG_SNAME && matches!(first.tag, RTAG_SREF | RTAG_AREF) { let name = decode_name(record.data).map_err(|message| error(record.offset, message))?; target = Some(name.to_owned()); data = Cow::Borrowed(name.as_bytes()); } else if record.tag & 0xff == 6 { data = Cow::Borrowed(unpad_ascii(record.data)); } if record.tag == RTAG_XY && is_polygon(first.tag) { data = canonical_ring(record.data).ok_or_else(|| { error( record.offset, "polygon must have at least three vertices and be closed", ) })?; } fields.push((record.tag, data)); i += 1; } fields.sort(); properties.sort(); let mut object = Object { offset: first.offset, end_offset: records.last().unwrap().offset + 4, kind: first.tag, layer: None, bounds: None, target, multiplicity: 1, key: Key { kind: first.tag, fields, properties, }, metadata: false, issues: Vec::new(), }; let xy = object .field(RTAG_XY) .ok_or_else(|| error(first.offset, "element has no XY record"))?; object.bounds = Some(if first.tag == RTAG_AREF { let counts = object .field(RTAG_COLROW) .ok_or_else(|| error(first.offset, "array has no COLROW"))?; let placement = ArrayPlacement::decode(counts, xy) .map_err(|(_, reason)| payload_error(first.offset, reason))?; let [columns, rows] = placement.counts; object.multiplicity = u64::from(columns) * u64::from(rows); coordinate_bounds(placement.points) } else { let points = XY::points(xy); let valid_count = match first.tag { RTAG_TEXT | RTAG_SREF => points.len() == 1, RTAG_PATH => points.len() >= 2, RTAG_NODE => points.len() > 0, RTAG_BOX => points.len() == 5, _ => true, }; if !valid_count { return Err(error(first.offset, "invalid coordinate count")); } coordinate_bounds(points) }); if matches!(first.tag, RTAG_SREF | RTAG_AREF) { if object.target.is_none() { return Err(error(first.offset, "reference has no SNAME")); } } else { let dtype = layer_type_tag(first.tag); object.layer = Some(( integer( object .field(RTAG_LAYER) .ok_or_else(|| error(first.offset, "element has no LAYER"))?, ), integer( object .field(dtype) .ok_or_else(|| error(first.offset, "element has no datatype/texttype"))?, ), )); if first.tag == RTAG_TEXT && object.field(RTAG_STRING).is_none() { return Err(error(first.offset, "text has no STRING")); } } Ok(object) } fn read_records(input: &[u8]) -> Result>, String> { read_records_with(input, |_, _| {}) } fn read_records_with<'a>( input: &'a [u8], mut observe: impl FnMut(usize, &Record<'a>), ) -> Result>, String> { if input.starts_with(b"\x1f\x8b") { return Err(error( 0, "gzip-compressed input. Decompress it before reading GDSII", )); } if input.starts_with(b"%SEMI-OASIS\r\n") { return Err(error(0, "OASIS input. Export the layout as GDSII")); } let mut records = Vec::new(); let mut remaining = input; while !remaining.is_empty() { let offset = input.len() - remaining.len(); let (next, frame) = RecordFrame::read(remaining).map_err(|(_, reason)| match reason { ErrType::Incomplete(_) => error(offset, "truncated record header"), ErrType::Failed(message) => error(offset, message), })?; let record = Record { offset, tag: frame.tag, data: frame.data, }; observe(records.len(), &record); records.push(record); remaining = next; if frame.tag == RTAG_ENDLIB { if remaining.iter().any(|b| *b != 0) { return Err(error( input.len() - remaining.len(), "nonzero data after ENDLIB", )); } break; } } Ok(records) } impl<'a> Document<'a> { pub fn parse(input: &'a [u8]) -> Result { let records = read_records(input)?; let mut doc = Self::parse_records(&records, None)?; doc.records = records; Ok(doc) } fn parse_records( records: &[Record<'a>], reuse: Option>, ) -> Result { for record in records { validate_payload(record)?; } if records.first().map(|r| r.tag) != Some(RTAG_HEADER) || records.get(1).map(|r| r.tag) != Some(RTAG_BGNLIB) || records.last().map(|r| r.tag) != Some(RTAG_ENDLIB) { return Err("expected HEADER, BGNLIB, and a final ENDLIB".to_string()); } let mut doc = Self { records: Vec::new(), cells: BTreeMap::new(), layer_names: BTreeMap::new(), diagnostics: Vec::new(), header: Vec::new(), global_issues: Vec::new(), known_cells: BTreeSet::new(), scope: Scope::default(), present: true, }; let mut i = 2; let mut global_seen = BTreeSet::new(); let mut cells_started = false; doc.header.push((RTAG_HEADER, records[0].data)); while i + 1 < records.len() { let record = &records[i]; if record.tag != RTAG_BGNSTR { if cells_started { return Err(error( record.offset, "library field outside the library header", )); } if record.tag != RTAG_MASK && !global_seen.insert(record.tag) { return Err(error(record.offset, "duplicate library field")); } if !matches!( record.tag, RTAG_LIBNAME | RTAG_UNITS | RTAG_REFLIBS | RTAG_FONTS | RTAG_GENERATIONS | RTAG_ATTRTABLE | RTAG_FORMAT | RTAG_MASK | RTAG_ENDMASKS | RTAG_LIBDIRSIZE | RTAG_SRFNAME | RTAG_LIBSECUR ) { doc.global_issues.push(Diagnostic::at( "unsupported_record", record.offset, format!("unsupported library record 0x{:04x}", record.tag), )); } doc.header.push(( record.tag, if record.tag == RTAG_LIBNAME { decode_name(record.data) .map_err(|message| error(record.offset, message))? .as_bytes() } else if record.tag & 0xff == 6 { unpad_ascii(record.data) } else { record.data }, )); i += 1; continue; } if !global_seen.contains(&RTAG_LIBNAME) || !global_seen.contains(&RTAG_UNITS) { return Err(error(record.offset, "LIBNAME and UNITS must precede cells")); } cells_started = true; let offset = record.offset; i += 1; let name_record = records .get(i) .filter(|r| r.tag == RTAG_STRNAME) .ok_or_else(|| error(offset, "BGNSTR must be followed by STRNAME"))?; let name = decode_name(name_record.data) .map_err(|message| error(name_record.offset, message))? .to_owned(); if name.is_empty() { return Err(error(name_record.offset, "empty cell name")); } if let Some(reuse) = &reuse && let Some((cell, end)) = reuse.cell(&name, offset, records) { if doc.cells.insert(name.clone(), cell).is_some() { return Err(error(offset, format!("duplicate cell name {name:?}"))); } i = end + 1; continue; } i += 1; let mut cell = Cell { offset, end_offset: 0, objects: Vec::new(), attributes: Vec::new(), issues: Vec::new(), }; loop { let record = records .get(i) .ok_or_else(|| error(offset, "missing ENDSTR"))?; if record.tag == RTAG_ENDSTR { cell.end_offset = record.offset; i += 1; break; } if is_element(record.tag) { let start = i; i += 1; while records.get(i).is_some_and(|r| r.tag != RTAG_ENDEL) { if matches!(records[i].tag, RTAG_ENDSTR | RTAG_ENDLIB | RTAG_BGNSTR) || is_element(records[i].tag) { return Err(error(records[i].offset, "missing ENDEL")); } i += 1; } if i == records.len() { return Err(error(offset, "missing ENDEL")); } let mut issues = Vec::new(); let mut parsed = object(&records[start..=i], &mut issues)?; parsed.issues = issues; cell.objects.push(parsed); i += 1; } else { if matches!(record.tag, RTAG_ENDLIB | RTAG_BGNSTR) { return Err(error(record.offset, "missing ENDSTR")); } if record.tag != RTAG_STRCLASS { cell.issues.push(Diagnostic::at( "unsupported_record", record.offset, format!("unsupported cell record 0x{:04x}", record.tag), )); } else if !cell.objects.is_empty() || cell.attributes.iter().any(|(tag, _)| *tag == RTAG_STRCLASS) { return Err(error( record.offset, "STRCLASS must occur once before elements", )); } cell.attributes.push((record.tag, record.data)); i += 1; } } cell.attributes.sort(); cell.objects.sort_by(|a, b| a.key.cmp(&b.key)); if doc.cells.insert(name.clone(), cell).is_some() { return Err(error(offset, format!("duplicate cell name {name:?}"))); } } if !global_seen.contains(&RTAG_LIBNAME) || !global_seen.contains(&RTAG_UNITS) { return Err("library must contain LIBNAME and UNITS".to_string()); } doc.header.sort(); doc.read_metadata()?; doc.known_cells = doc.cells.keys().cloned().collect(); doc.refresh_diagnostics(); Ok(doc) } fn check_graph(&mut self) { let mut unresolved = BTreeMap::new(); for (parent, cell) in &self.cells { for object in &cell.objects { if let Some(target) = &object.target && !self.known_cells.contains(target) { unresolved.entry((parent, target)).or_insert(object.offset); } } } for ((parent, target), offset) in unresolved { self.diagnostics.push(Diagnostic { code: "unresolved_reference", side: None, message: format!("cell {parent:?}: unresolved reference {target:?}"), offset: Some(offset), cell: Some(parent.clone()), layer: None, target: Some(target.clone()), }); } let mut state = BTreeMap::<&str, u8>::new(); for root in self.cells.keys() { let mut stack = vec![(root.as_str(), false)]; while let Some((name, leaving)) = stack.pop() { if leaving { state.insert(name, 2); continue; } match state.get(name) { Some(2) => continue, Some(1) => { self.diagnostics.push(Diagnostic { code: "hierarchy_cycle", side: None, message: format!("cyclic hierarchy involving {name:?}"), offset: self.cells.get(name).map(|c| c.offset), cell: Some(name.to_string()), layer: None, target: None, }); continue; } _ => (), } state.insert(name, 1); stack.push((name, true)); if let Some(cell) = self.cells.get(name) { for object in &cell.objects { if let Some(target) = &object.target { stack.push((target, false)); } } } } } } pub fn edges(&self) -> BTreeMap<(String, String), u64> { self.cells .iter() .flat_map(|(name, cell)| { let mut counts = BTreeMap::new(); for object in &cell.objects { if let Some(target) = object.target.as_deref() { let count = counts.entry(target).or_insert(0_u64); *count = count.saturating_add(object.multiplicity); } } counts .into_iter() .map(|(target, count)| ((name.clone(), target.to_owned()), count)) }) .collect() } pub fn hierarchy(&self, mermaid: bool, max_depth: usize) -> String { let revision = Revision::from_document(self); hierarchy::render_hierarchy(&revision, &revision, None, mermaid, max_depth) } pub fn canonical_dump(&self) -> String { let mut out = TextReport::default(); self.write_canonical_dump(&mut out); out.into_string() } /// Append the canonical object dump and its presentation roles. pub fn write_canonical_dump(&self, out: &mut TextReport) { if !self.present { out.write_styled(TextStyle::Heading, format_args!("library absent")); out.push('\n'); return; } let version_index = self .header .iter() .position(|(tag, _)| *tag == RTAG_HEADER) .unwrap(); let header = |tag| self.header.iter().find(|(t, _)| *t == tag).unwrap().1; let (user, meters) = header(RTAG_UNITS).split_at(8); let version = i16::from_be_bytes(self.header[version_index].1.try_into().unwrap()); out.write_styled( TextStyle::Heading, format_args!( "library {} (GDSII {version}, {} user units/dbu, {} m/dbu)", quoted(header(RTAG_LIBNAME)), format_exact_value(RTAG_UNITS, user), format_exact_value(RTAG_UNITS, meters) ), ); out.push('\n'); self.scope.write_restrictions(out); for (index, (tag, data)) in self.header.iter().enumerate() { if index != version_index && !matches!(*tag, RTAG_LIBNAME | RTAG_UNITS) { writeln!(out, "{}={}", tag_name(*tag), format_exact_value(*tag, data)).unwrap(); } } for ((layer, dtype), name) in &self.layer_names { out.write_styled(TextStyle::Layer, format_args!("{layer}/{dtype}")); writeln!(out, ": name {name:?}").unwrap(); } for (name, cell) in &self.cells { out.write_styled(TextStyle::Heading, format_args!("cell {name:?}")); out.push('\n'); for (tag, data) in &cell.attributes { writeln!( out, " {}={}", tag_name(*tag), format_exact_value(*tag, data) ) .unwrap(); } let mut objects = cell .objects .iter() .filter(|object| !object.metadata) .peekable(); while let Some(object) = objects.next() { let mut count = 1; while objects.next_if(|next| next.key == object.key).is_some() { count += 1; } out.push_str(" "); if count != 1 { write!(out, "{count}x ").unwrap(); } object .format_with_heading(out, |out, name| { if let Some((layer, datatype)) = object.layer { out.write_styled(TextStyle::Layer, format_args!("{layer}/{datatype}")); out.push_str(": "); } if matches!(object.kind, RTAG_SREF | RTAG_AREF) && object.layer.is_none() { out.write_styled(TextStyle::Layer, format_args!("{name}")); } else { out.push_str(name); } Ok(()) }) .unwrap(); out.push('\n'); } } for diagnostic in &self.diagnostics { out.write_styled( TextStyle::Warning, format_args!("INCOMPLETE: {}", diagnostic.message), ); out.push('\n'); } } pub fn record_dump(&self) -> String { format_records(&self.records) } } /// Inspect record boundaries even when object grammar or metadata is invalid. pub fn dump_records(input: &[u8]) -> Result { let mut out = TextReport::default(); write_record_dump(&mut out, input)?; Ok(out.into_string()) } /// Append the raw record dump and its presentation roles. pub fn write_record_dump(out: &mut TextReport, input: &[u8]) -> Result<(), String> { write_records(out, &read_records(input)?); Ok(()) } fn format_records(records: &[Record<'_>]) -> String { let mut out = TextReport::default(); write_records(&mut out, records); out.into_string() } fn write_records(out: &mut TextReport, records: &[Record<'_>]) { for record in records { write!(out, "{:010} {:04x} ", record.offset, record.tag).unwrap(); out.write_styled(TextStyle::Layer, format_args!("{}", tag_name(record.tag))); writeln!( out, " size={} {}", record.data.len() + 4, format_data( record.tag, if record.tag & 0xff == 6 { unpad_ascii(record.data) } else { record.data } ) ) .unwrap(); } } /// A retained comparison field. Polygon coordinates and string padding follow /// the comparison profile; REAL encodings and unsupported payloads are exact. #[derive(Clone, Debug, Eq, PartialEq)] pub struct FieldValue { pub tag: u16, pub data: Vec, } fn owned_fields<'a>(fields: impl IntoIterator) -> Vec { fields .into_iter() .map(|(tag, data)| FieldValue { tag, data: data.to_vec(), }) .collect() } #[derive(Debug)] pub struct ObjectChange { pub offset: usize, pub end_offset: usize, pub kind: u16, pub layer: Option, pub bounds: Option, pub target: Option, pub origin: Option<[i32; 2]>, pub width: Option, pub counts: Option<[u16; 2]>, pub fields: Vec, pub properties: Vec<(u16, Vec)>, } impl fmt::Display for ObjectChange { fn fmt(&self, out: &mut fmt::Formatter<'_>) -> fmt::Result { self.format_with_heading(out, |out, name| write_object_heading(out, self.layer, name)) } } impl ObjectChange { fn format_with_heading( &self, out: &mut W, heading: impl FnOnce(&mut W, &'static str) -> fmt::Result, ) -> fmt::Result { format_object( out, self.kind, self.layer, self.fields .iter() .map(|field| (field.tag, field.data.as_slice())), self.properties .iter() .map(|(attribute, data)| (*attribute, data.as_slice())), heading, ) } } impl From<&Object<'_>> for ObjectChange { fn from(object: &Object<'_>) -> Self { Self { offset: object.offset, end_offset: object.end_offset, kind: object.kind, layer: object.layer, bounds: object.bounds, target: object.target.clone(), origin: object .field(RTAG_XY) .and_then(|data| XY::points(data).next()), width: object .field(RTAG_WIDTH) .map(|data| i32::from_be_bytes(data.try_into().unwrap())), counts: object.target.as_ref().and_then(|_| { if object.kind == RTAG_AREF { object.field(RTAG_COLROW).and_then(array_dimensions) } else { Some([1, 1]) } }), fields: owned_fields( object .key .fields .iter() .map(|(tag, data)| (*tag, data.as_ref())), ), properties: object .key .properties .iter() .map(|(a, v)| (*a, v.to_vec())) .collect(), } } } /// An existing cell's source location and retained attributes. #[derive(Debug)] pub struct CellRevision { pub offset: usize, pub attributes: Vec, } impl From<&Cell<'_>> for CellRevision { fn from(cell: &Cell<'_>) -> Self { Self { offset: cell.offset, attributes: owned_fields(cell.attributes.iter().copied()), } } } #[derive(Debug)] pub struct CellChange { pub name: String, pub old: Option, pub new: Option, pub removed: Vec, pub added: Vec, pub replacements: Vec, } impl CellChange { pub fn attributes_changed(&self) -> bool { self.old.as_ref().map(|cell| &cell.attributes) != self.new.as_ref().map(|cell| &cell.attributes) } } #[derive(Debug)] pub struct LayerNameChange { pub layer: Layer, pub old: Option, pub new: Option, } /// Library presence or exact record payloads, formatted only when rendered. #[derive(Debug)] pub enum LibraryChange { Presence { old: bool, new: bool, }, Record { tag: u16, old: Vec>, new: Vec>, }, } impl fmt::Display for LibraryChange { fn fmt(&self, out: &mut fmt::Formatter<'_>) -> fmt::Result { match self { Self::Presence { old, new } => out.write_str(match (old, new) { (false, true) => "added", (true, false) => "removed", (true, true) => "present", (false, false) => "absent", }), Self::Record { tag, old, new } => { let values = if old.len() <= 1 && new.len() <= 1 { format_field_change( *tag, old.first().map(Vec::as_slice), new.first().map(Vec::as_slice), ) } else { let list = |items: &[Vec]| { if items.is_empty() { return "absent".to_string(); } let values = items .iter() .map(|data| format_exact_value(*tag, data)) .collect::>() .join(", "); format!("[{values}]") }; format!("{} -> {}", list(old), list(new)) }; write!(out, "{} {values}", tag_name(*tag)) } } } } /// Owned revision metadata and reference counts captured before documents are dropped. #[derive(Debug)] pub struct Revision { pub scope: Scope, pub present: bool, pub units: Option>, cells: BTreeSet, known_cells: BTreeSet, edges: BTreeMap<(String, String), u64>, } impl Revision { fn from_document(doc: &Document<'_>) -> Self { Self { scope: doc.scope.clone(), present: doc.present, units: doc .header .iter() .find(|(tag, _)| *tag == RTAG_UNITS && doc.present) .map(|(_, data)| data.to_vec()), cells: doc.cells.keys().cloned().collect(), known_cells: doc.known_cells.clone(), edges: doc.edges(), } } } #[derive(Debug)] pub struct Comparison { pub old: Revision, pub new: Revision, /// Unchanged layer names available to the text report. pub layer_legend: BTreeMap, pub library_changes: Vec, pub layer_names: Vec, pub cells: Vec, pub diagnostics: Vec, } /// A comparison for text and hierarchy reports. #[derive(Debug)] pub struct TextComparison { comparison: Comparison, } impl TextComparison { pub fn between(old: &Document<'_>, new: &Document<'_>) -> Self { Self::collect(old, new, &BTreeSet::new()) } fn collect(old: &Document<'_>, new: &Document<'_>, reused_cells: &BTreeSet<&str>) -> Self { Self { comparison: Comparison::collect(old, new, reused_cells, false), } } pub fn outcome(&self) -> Outcome { self.comparison.outcome() } pub fn hierarchy(&self, mermaid: bool, max_depth: usize) -> String { self.comparison.hierarchy(mermaid, max_depth) } } impl Comparison { pub fn between(old: &Document<'_>, new: &Document<'_>) -> Self { Self::collect(old, new, &BTreeSet::new(), true) } fn collect( old: &Document<'_>, new: &Document<'_>, reused_cells: &BTreeSet<&str>, include_whole_cell_objects: bool, ) -> Self { let mut result = Self { old: Revision::from_document(old), new: Revision::from_document(new), layer_legend: old .layer_names .iter() .filter(|(pair, name)| new.layer_names.get(pair) == Some(*name)) .map(|(pair, name)| (*pair, name.clone())) .collect(), library_changes: Vec::new(), layer_names: Vec::new(), cells: Vec::new(), diagnostics: Vec::new(), }; if old.present != new.present { result.library_changes.push(LibraryChange::Presence { old: old.present, new: new.present, }); } for (side, doc) in [(Side::Old, old), (Side::New, new)] { result .diagnostics .extend(doc.diagnostics.iter().cloned().map(|mut diagnostic| { diagnostic.side = Some(side); diagnostic })); } if old.scope != new.scope { result.diagnostics.push(Diagnostic::new( "scope_mismatch", "comparison scopes differ", None, )); } let header_tags: BTreeSet<_> = old .header .iter() .chain(&new.header) .map(|(tag, _)| *tag) .collect(); for tag in header_tags { let a: Vec<_> = old .header .iter() .filter(|(t, _)| *t == tag) .map(|(_, value)| *value) .collect(); let b: Vec<_> = new .header .iter() .filter(|(t, _)| *t == tag) .map(|(_, value)| *value) .collect(); if a != b { result.library_changes.push(LibraryChange::Record { tag, old: a.into_iter().map(<[u8]>::to_vec).collect(), new: b.into_iter().map(<[u8]>::to_vec).collect(), }); } } let layers: BTreeSet<_> = old .layer_names .keys() .chain(new.layer_names.keys()) .copied() .collect(); for layer in layers { if old.layer_names.get(&layer) != new.layer_names.get(&layer) { result.layer_names.push(LayerNameChange { layer, old: old.layer_names.get(&layer).cloned(), new: new.layer_names.get(&layer).cloned(), }); } } let names: BTreeSet<_> = old.cells.keys().chain(new.cells.keys()).collect(); for name in names { if reused_cells.contains(name.as_str()) { continue; } let a = old.cells.get(name); let b = new.cells.get(name); let mut change = CellChange { name: name.clone(), old: a.map(CellRevision::from), new: b.map(CellRevision::from), removed: Vec::new(), added: Vec::new(), replacements: Vec::new(), }; if !include_whole_cell_objects && (a.is_none() || b.is_none()) { let details = if a.is_some() { &mut change.removed } else { &mut change.added }; // The hierarchy uses the changed reference targets. details.extend( a.or(b) .into_iter() .flat_map(|cell| &cell.objects) .filter(|object| !object.metadata && object.target.is_some()) .map(ObjectChange::from), ); result.cells.push(change); continue; } let a: Vec<_> = a .into_iter() .flat_map(|c| &c.objects) .filter(|o| !o.metadata) .collect(); let b: Vec<_> = b .into_iter() .flat_map(|c| &c.objects) .filter(|o| !o.metadata) .collect(); let (mut i, mut j) = (0, 0); while i < a.len() || j < b.len() { let order = match (a.get(i), b.get(j)) { (Some(a), Some(b)) => a.key.cmp(&b.key), (Some(_), None) => std::cmp::Ordering::Less, _ => std::cmp::Ordering::Greater, }; match order { std::cmp::Ordering::Equal => { i += 1; j += 1; } std::cmp::Ordering::Less => { change.removed.push(a[i].into()); i += 1; } std::cmp::Ordering::Greater => { change.added.push(b[j].into()); j += 1; } } } if change.attributes_changed() || !change.removed.is_empty() || !change.added.is_empty() { change.replacements = changes::replacements(&change.removed, &change.added); result.cells.push(change); } } result } pub fn outcome(&self) -> Outcome { let different = !self.library_changes.is_empty() || !self.layer_names.is_empty() || !self.cells.is_empty(); if !self.diagnostics.is_empty() { Outcome::Incomplete { different } } else if different { Outcome::Different } else { Outcome::Equal } } /// Render the affected hierarchy. ASCII output shows relationships between cells. pub fn hierarchy(&self, mermaid: bool, max_depth: usize) -> String { hierarchy::render_hierarchy(&self.old, &self.new, Some(&self.cells), mermaid, max_depth) } } fn cell_marker(old: bool, new: bool) -> char { match (old, new) { (true, false) => '-', (false, true) => '+', _ => '*', } } fn cell_label(name: &str) -> Cow<'_, str> { if name .bytes() .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'_' | b'$' | b'?' | b'.' | b'-')) { Cow::Borrowed(name) } else { Cow::Owned(format!("{name:?}")) } } fn quoted(data: &[u8]) -> String { let mut out = "\"".to_string(); for byte in data { for escaped in std::ascii::escape_default(*byte) { out.push(escaped as char); } } out.push('"'); out } fn real8_words(data: &[u8]) -> impl ExactSizeIterator + '_ { data.as_chunks::<8>() .0 .iter() .copied() .map(u64::from_be_bytes) } fn format_real8(data: &[u8], show_bytes: bool) -> String { let mut values = real8_words(data).map(decode_real8); let mut out = if values.len() == 1 { format!("{:?}", values.next().unwrap()) } else { format!("{:?}", values.collect::>()) }; if show_bytes { write!(out, " raw={}", hex(data)).unwrap(); } out } fn is_real8(tag: u16, data: &[u8]) -> bool { tag & 0xff == 5 && data.len().is_multiple_of(8) } fn format_exact_value(tag: u16, data: &[u8]) -> String { if is_real8(tag, data) { let show_bytes = real8_words(data).any(|bits| encode_real8(decode_real8(bits)).ok() != Some(bits)); format_real8(data, show_bytes) } else { format_data(tag, data) } } fn format_field_change(tag: u16, before: Option<&[u8]>, after: Option<&[u8]>) -> String { let show_bytes = before.zip(after).is_some_and(|(a, b)| { is_real8(tag, a) && is_real8(tag, b) && real8_words(a) .zip(real8_words(b)) .any(|(a, b)| a != b && decode_real8(a).to_bits() == decode_real8(b).to_bits()) }); let format_value = |data: Option<&[u8]>| match data { Some(data) if is_real8(tag, data) => format_real8(data, show_bytes), Some(data) => format_data(tag, data), None => "absent".to_string(), }; format!("{} -> {}", format_value(before), format_value(after)) } fn format_data(tag: u16, data: &[u8]) -> String { if matches!( tag, RTAG_LAYER | RTAG_DATATYPE | RTAG_TEXTTYPE | RTAG_BOXTYPE | RTAG_NODETYPE ) && data.len() == 2 { return integer(data).to_string(); } match tag & 0xff { 0 if data.is_empty() => String::new(), 2 if data.len().is_multiple_of(2) => format!( "{:?}", data.as_chunks::<2>() .0 .iter() .copied() .map(i16::from_be_bytes) .collect::>() ), 3 if data.len().is_multiple_of(4) => format!( "{:?}", data.as_chunks::<4>() .0 .iter() .copied() .map(i32::from_be_bytes) .collect::>() ), 5 if data.len().is_multiple_of(8) => format!( "{:?} raw={}", real8_words(data).map(decode_real8).collect::>(), hex(data) ), 6 => quoted(data), _ => hex(data), } } fn object_name(kind: u16, rectangular: bool) -> &'static str { match kind { RTAG_BOUNDARY if rectangular => "rectangle", RTAG_BOUNDARY => "polygon", RTAG_BOX => "box", RTAG_PATH => "path", RTAG_SREF => "reference", RTAG_AREF => "array reference", RTAG_TEXT => "label", RTAG_NODE => "node", _ => kind_name(kind), } } fn hex(data: &[u8]) -> String { let mut out = "0x".to_string(); for byte in data { write!(out, "{byte:02x}").unwrap(); } out } fn kind_name(tag: u16) -> &'static str { match tag { RTAG_BOUNDARY => "BOUNDARY", RTAG_PATH => "PATH", RTAG_SREF => "SREF", RTAG_AREF => "AREF", RTAG_TEXT => "TEXT", RTAG_NODE => "NODE", RTAG_BOX => "BOX", _ => "UNKNOWN", } } fn tag_name(tag: u16) -> String { let name = match tag { RTAG_HEADER => "HEADER", RTAG_BGNLIB => "BGNLIB", RTAG_LIBNAME => "LIBNAME", RTAG_UNITS => "UNITS", RTAG_ENDLIB => "ENDLIB", RTAG_BGNSTR => "BGNSTR", RTAG_STRNAME => "STRNAME", RTAG_ENDSTR => "ENDSTR", RTAG_ENDEL => "ENDEL", RTAG_LAYER => "layer", RTAG_DATATYPE => "datatype", RTAG_TEXTTYPE => "texttype", RTAG_XY => "xy", RTAG_SNAME => "target", RTAG_COLROW => "counts", RTAG_STRANS => "strans", RTAG_MAG => "mag", RTAG_ANGLE => "angle", RTAG_WIDTH => "width", RTAG_PATHTYPE => "pathtype", RTAG_STRING => "string", RTAG_PROPATTR => "PROPATTR", RTAG_PROPVALUE => "PROPVALUE", RTAG_PRESENTATION => "presentation", RTAG_BGNEXTN => "bgnextn", RTAG_ENDEXTN => "endextn", RTAG_BOXTYPE => "boxtype", RTAG_NODETYPE => "nodetype", RTAG_ELFLAGS => "elflags", RTAG_PLEX => "plex", RTAG_STRCLASS => "STRCLASS", tag if is_element(tag) => kind_name(tag), _ => return format!("record_{tag:04x}"), }; name.to_string() }