Parsers for the DSN 'Cache' stream and the 'Packages/<name>' streams: symbol definitions with graphics and pins, plus package/device pin-number maps. More...

#include <cstdint>
#include <map>
#include <optional>
#include <string>
#include <vector>
#include <sch_io/orcad/orcad_records.h>
#include <sch_io/orcad/orcad_stream.h>
#include <sch_io/orcad/orcad_structures.h>

Functions
std::optional< ORCAD_PRIMITIVE >	OrcadReadPrimitive (ORCAD_STREAM &aStream)
	Read one graphic primitive including its doubled u8 type-pair prefix, at the current cursor.

std::optional< ORCAD_SYMBOL_PIN >	OrcadReadSymbolPin (ORCAD_STRUCT_READER &aReader)
	Read one symbol pin.

ORCAD_SYMBOL_DEF	OrcadReadSymbolDef (ORCAD_STRUCT_READER &aReader, const ORCAD_PREFIXES &aPrefixes, bool aWithPins)
	Read a symbol definition body (LibraryPart / GlobalSymbol / PortSymbol / OffPageSymbol / TitleBlockSymbol / ERCSymbol / BookmarkSymbol / PinShapeSymbol).

ORCAD_SYMBOL_DEF	OrcadReadSthInPages0 (ORCAD_STRUCT_READER &aReader, const ORCAD_PREFIXES &aPrefixes)
	Structure type 2 (SthInPages0): nested symbol body inside Graphic*Inst structures on pages; carries the actual drawing primitives (e.g.

ORCAD_DRAWN_INSTANCE	OrcadReadDrawnInstance (ORCAD_STRUCT_READER &aReader, const ORCAD_PREFIXES &aPrefixes)
	Structure type 12 (DrawnInstance): hierarchical block instance.

ORCAD_DEVICE	OrcadReadDevice (ORCAD_STRUCT_READER &aReader)
	Read one Device structure (reads its own prefixes; type must be 32).

ORCAD_PACKAGE	OrcadReadPackage (ORCAD_STRUCT_READER &aReader, const ORCAD_PREFIXES &aPrefixes)
	Read a Package body (type 31); layout documented on ORCAD_PACKAGE.

std::optional< size_t >	OrcadFindStructureStart (const ORCAD_STREAM &aStream, size_t aPreamblePos)
	Given the absolute position of a preamble magic, backtrack to find a valid prefix chain ending right before it.

void	OrcadParseCache (const std::vector< char > &aData, const std::vector< std::string > &aStrings, const ORCAD_WARN_FN &aWarn, std::map< std::string, ORCAD_SYMBOL_DEF > &aSymbols, std::map< std::string, ORCAD_PACKAGE > &aPackages)
	Scan a Cache-framed stream (the 'Cache' stream itself, or any 'Packages/<name>' stream — they share the framing) and collect symbol definitions and packages.

void	OrcadMergeCacheStreams (std::map< std::string, ORCAD_SYMBOL_DEF > &aSymbols, std::map< std::string, ORCAD_PACKAGE > &aPackages, std::map< std::string, ORCAD_SYMBOL_DEF > &&aExtraSymbols, std::map< std::string, ORCAD_PACKAGE > &&aExtraPackages)
	Merge the results of a 'Packages/<name>' stream (locally modified parts) into the main cache maps: a symbol name already present gains the extra entries as variants (the main cache definition stays the default); a new name is inserted as-is.

Detailed Description

Parsers for the DSN 'Cache' stream and the 'Packages/<name>' streams: symbol definitions with graphics and pins, plus package/device pin-number maps.

The cache stream interleaves entry metadata (names, source library, dates) with prefix-framed structures. Rather than fragile sequential parsing, the walker scans for structure starts: every structure of interest begins with a chain of long prefixes (u8 type, u32 len, u32 zero) repeated with the same type byte, then a short prefix and the preamble magic FF E4 5C 39. Symbol and package structures embed their own name and source library, so the inter-structure metadata can be skipped entirely.

Implemented in orcad_cache.cpp.

Definition in file orcad_cache.h.

Function Documentation

◆ OrcadFindStructureStart()

std::optional< size_t > OrcadFindStructureStart	(	const ORCAD_STREAM &	aStream,
		size_t	aPreamblePos )

Given the absolute position of a preamble magic, backtrack to find a valid prefix chain ending right before it.

Tries short-prefix shapes with 0..39 property pairs (also accepting the i16 -1 marker with no pairs), requires the type byte to be in the known-structure whitelist, counts same-type long prefixes (u8 type, u32 len, u32 zero pad) going backwards, validates the chain with TryReadPrefixes(), and rejects chains whose claimed stop offsets run past the stream end.

Returns: the chain start offset, or std::nullopt when no valid chain ends at this preamble.

Definition at line 714 of file orcad_cache.cpp.

References ORCAD_PREFIXES::bodyLens, ORCAD_STREAM::Data(), ORCAD_STREAM::Seek(), ORCAD_STREAM::Size(), and ORCAD_STRUCT_READER::TryReadPrefixes().

Referenced by OrcadParseCache(), and OrcadReadHierarchyLinks().

◆ OrcadMergeCacheStreams()

void OrcadMergeCacheStreams	(	std::map< std::string, ORCAD_SYMBOL_DEF > &	aSymbols,
		std::map< std::string, ORCAD_PACKAGE > &	aPackages,
		std::map< std::string, ORCAD_SYMBOL_DEF > &&	aExtraSymbols,
		std::map< std::string, ORCAD_PACKAGE > &&	aExtraPackages )

Merge the results of a 'Packages/<name>' stream (locally modified parts) into the main cache maps: a symbol name already present gains the extra entries as variants (the main cache definition stays the default); a new name is inserted as-is.

Packages are inserted only when the name is not already present.

Definition at line 902 of file orcad_cache.cpp.

References name.

Referenced by SCH_IO_ORCAD::loadOlbSymbols(), and SCH_IO_ORCAD::LoadSchematicFile().

◆ OrcadParseCache()

void OrcadParseCache	(	const std::vector< char > &	aData,
		const std::vector< std::string > &	aStrings,
		const ORCAD_WARN_FN &	aWarn,
		std::map< std::string, ORCAD_SYMBOL_DEF > &	aSymbols,
		std::map< std::string, ORCAD_PACKAGE > &	aPackages )

Scan a Cache-framed stream (the 'Cache' stream itself, or any 'Packages/<name>' stream — they share the framing) and collect symbol definitions and packages.

Walk: find each preamble, backtrack via OrcadFindStructureStart(), parse symbol types (24, 33, 34, 35, 64, 75, 76, 98) with OrcadReadSymbolDef() and type 31 with OrcadReadPackage(); everything else is passed over. The cache may hold several stale library versions of one symbol name: the FIRST entry wins as the default and later same-name entries are appended to its variants list (see ORCAD_SYMBOL_DEF::variants). Packages: a later same-name entry replaces the earlier one. A parse failure inside one structure is warned and recovery continues at the structure's prefix end (or past the preamble when unknown).

Parameters

aSymbols	filled in-place, keyed by cache symbol name.
aPackages	filled in-place, keyed by package name.

Definition at line 805 of file orcad_cache.cpp.

References ORCAD_PREFIXES::end, ORCAD_STREAM::FindPreamble(), ORCAD_STREAM::GetOffset(), ORCAD_PACKAGE::name, ORCAD_SYMBOL_DEF::name, ORCAD_STREAM::npos, ORCAD_ST_PACKAGE, OrcadFindStructureStart(), OrcadReadPackage(), OrcadReadSymbolDef(), IO_ERROR::Problem(), ORCAD_STRUCT_READER::ReadPrefixes(), ORCAD_STREAM::Seek(), and ORCAD_PREFIXES::typeId.

Referenced by SCH_IO_ORCAD::loadOlbSymbols(), and SCH_IO_ORCAD::LoadSchematicFile().

◆ OrcadReadDevice()

ORCAD_DEVICE OrcadReadDevice ( ORCAD_STRUCT_READER & aReader )

Read one Device structure (reads its own prefixes; type must be 32).

Layout documented on ORCAD_DEVICE, including the FF FF empty-pin marker and the u8 config byte whose bit 7 flags an ignored pin.

Definition at line 651 of file orcad_cache.cpp.

References config, ORCAD_PREFIXES::end, ORCAD_STREAM::GetOffset(), ORCAD_ST_DEVICE, ORCAD_STREAM::PeekMatches(), ORCAD_DEVICE::pinIgnore, ORCAD_DEVICE::pinNumbers, ORCAD_STREAM::ReadLzt(), ORCAD_STRUCT_READER::ReadPrefixes(), ORCAD_STREAM::ReadU16(), ORCAD_STREAM::ReadU8(), ORCAD_DEVICE::refDes, ORCAD_STREAM::Seek(), ORCAD_STREAM::Skip(), ORCAD_STRUCT_READER::Stream(), THROW_IO_ERROR, ORCAD_PREFIXES::typeId, and ORCAD_DEVICE::unitRef.

Referenced by OrcadReadPackage().

◆ OrcadReadDrawnInstance()

ORCAD_DRAWN_INSTANCE OrcadReadDrawnInstance	(	ORCAD_STRUCT_READER &	aReader,
		const ORCAD_PREFIXES &	aPrefixes )

Structure type 12 (DrawnInstance): hierarchical block instance.

Layout documented on ORCAD_DRAWN_INSTANCE; the nested flag byte must equal 24 (LibraryPart) and the block reference starts at the second prefix stop. Called by the ORCAD_STRUCT_READER dispatcher; used for hierarchy DETECTION only in this importer.

Definition at line 563 of file orcad_cache.cpp.

References ORCAD_SYMBOL_DEF::bbox, ORCAD_DRAWN_INSTANCE::dbId, ORCAD_DRAWN_INSTANCE::displayProps, ORCAD_PREFIXES::end, flag, ORCAD_STREAM::GetOffset(), ORCAD_DRAWN_INSTANCE::h, ORCAD_BLOCK_PIN::name, ORCAD_ST_LIBRARY_PART, OrcadReadDisplayPropList(), OrcadReadSymbolDef(), pin, ORCAD_DRAWN_INSTANCE::pins, ORCAD_SYMBOL_DEF::pins, ORCAD_BLOCK_PIN::portType, ORCAD_STREAM::ReadI16(), ORCAD_STREAM::ReadLzt(), ORCAD_STRUCT_READER::ReadPrefixes(), ORCAD_STRUCT_READER::ReadStructure(), ORCAD_STREAM::ReadU16(), ORCAD_STREAM::ReadU32(), ORCAD_STREAM::ReadU8(), ORCAD_DRAWN_INSTANCE::reference, result, ORCAD_STREAM::Seek(), ORCAD_STREAM::Skip(), ORCAD_PREFIXES::stops, ORCAD_STRUCT_READER::Stream(), THROW_IO_ERROR, ORCAD_DRAWN_INSTANCE::w, ORCAD_BLOCK_PIN::x, ORCAD_BBOX::x1, ORCAD_DRAWN_INSTANCE::x1, ORCAD_BBOX::x2, ORCAD_BLOCK_PIN::y, ORCAD_BBOX::y1, ORCAD_DRAWN_INSTANCE::y1, and ORCAD_BBOX::y2.

Referenced by ORCAD_STRUCT_READER::ReadStructure().

◆ OrcadReadPackage()

ORCAD_PACKAGE OrcadReadPackage	(	ORCAD_STRUCT_READER &	aReader,
		const ORCAD_PREFIXES &	aPrefixes )

Read a Package body (type 31); layout documented on ORCAD_PACKAGE.

Definition at line 691 of file orcad_cache.cpp.

References ORCAD_PACKAGE::devices, ORCAD_PREFIXES::end, ORCAD_STREAM::GetOffset(), ORCAD_PACKAGE::name, OrcadReadDevice(), ORCAD_PACKAGE::pcbFootprint, ORCAD_STREAM::ReadLzt(), ORCAD_STREAM::ReadU16(), ORCAD_PACKAGE::refDes, ORCAD_STREAM::Seek(), ORCAD_PACKAGE::sourceLib, and ORCAD_STRUCT_READER::Stream().

Referenced by OrcadParseCache().

◆ OrcadReadPrimitive()

std::optional< ORCAD_PRIMITIVE > OrcadReadPrimitive ( ORCAD_STREAM & aStream )

Read one graphic primitive including its doubled u8 type-pair prefix, at the current cursor.

Handles both byteLength conventions per record (modern records have the preamble magic right at their claimed end; legacy records exclude the u32 size field + 4-byte pad, so end += 8 when no preamble sits at the claimed end; CommentText is exclusive in ALL eras). For polygon/polyline/bezier the point count is located deterministically by reconciling candidate offsets (16, 8, 0 for polygons; 8, 0 otherwise) with the stored size under one of the two conventions. Ends by seeking to the record end and skipping an optional trailing preamble block.

Returns: the primitive, or std::nullopt for SymbolVector records (parsed only to stay aligned) and for bitmap records whose payload exceeds the record.

Exceptions

IO_ERROR on a malformed prefix pair or an overrunning body.

Definition at line 394 of file orcad_cache.cpp.

References ORCAD_STREAM::GetOffset(), ORCAD_PRIM_SYMBOL_VECTOR, ORCAD_STREAM::ReadU8(), and THROW_IO_ERROR.

Referenced by BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), and OrcadReadSymbolDef().

◆ OrcadReadSthInPages0()

ORCAD_SYMBOL_DEF OrcadReadSthInPages0	(	ORCAD_STRUCT_READER &	aReader,
		const ORCAD_PREFIXES &	aPrefixes )

Structure type 2 (SthInPages0): nested symbol body inside Graphic*Inst structures on pages; carries the actual drawing primitives (e.g.

the CommentText of a text object). Equals OrcadReadSymbolDef with aWithPins=false. Called by the ORCAD_STRUCT_READER dispatcher.

Definition at line 556 of file orcad_cache.cpp.

References OrcadReadSymbolDef().

Referenced by ORCAD_STRUCT_READER::ReadStructure().

◆ OrcadReadSymbolDef()

ORCAD_SYMBOL_DEF OrcadReadSymbolDef	(	ORCAD_STRUCT_READER &	aReader,
		const ORCAD_PREFIXES &	aPrefixes,
		bool	aWithPins )

Read a symbol definition body (LibraryPart / GlobalSymbol / PortSymbol / OffPageSymbol / TitleBlockSymbol / ERCSymbol / BookmarkSymbol / PinShapeSymbol).

Layout documented on ORCAD_SYMBOL_DEF, including the bbox rule: the box is the LAST 8 bytes before the next prefix stop (as 4 x i16), accepted only when x1 <= x2, y1 <= y2 and both spans are <= 4000 DBU.

Parameters

aWithPins read the trailing u16 pin-count pin list and u16 property list (true for cache symbols, false for nested SthInPages0 bodies).

Definition at line 449 of file orcad_cache.cpp.

References ORCAD_SYMBOL_DEF::bbox, ORCAD_SYMBOL_DEF::color, ORCAD_PREFIXES::end, ORCAD_SYMBOL_DEF::generalFlags, ORCAD_STREAM::GetOffset(), ORCAD_SYMBOL_DEF::name, ORCAD_ST_LIBRARY_PART, OrcadReadPrimitive(), OrcadReadSymbolPin(), ORCAD_STREAM::PeekU8(), pin, ORCAD_SYMBOL_DEF::pins, ORCAD_SYMBOL_DEF::primitives, ORCAD_SYMBOL_DEF::props, ORCAD_STRUCT_READER::PropsDict(), ORCAD_STREAM::ReadI16(), ORCAD_STREAM::ReadLzt(), ORCAD_STRUCT_READER::ReadStructure(), ORCAD_STREAM::ReadU16(), ORCAD_STREAM::ReadU32(), save, ORCAD_STREAM::Seek(), ORCAD_STREAM::Skip(), ORCAD_SYMBOL_DEF::sourceLib, ORCAD_PREFIXES::stops, ORCAD_STRUCT_READER::Stream(), ORCAD_PREFIXES::typeId, ORCAD_SYMBOL_DEF::typeId, ORCAD_BBOX::x1, ORCAD_BBOX::x2, ORCAD_BBOX::y1, and ORCAD_BBOX::y2.

Referenced by OrcadParseCache(), OrcadReadDrawnInstance(), and OrcadReadSthInPages0().

◆ OrcadReadSymbolPin()

std::optional< ORCAD_SYMBOL_PIN > OrcadReadSymbolPin ( ORCAD_STRUCT_READER & aReader )

Read one symbol pin.

A single 0x00 byte instead of a prefix chain marks a skipped pin slot and yields std::nullopt. Otherwise the prefixes must be of type 26 or 27; layout documented on ORCAD_SYMBOL_PIN. The pin body's trailing junk bytes are consumed by seeking to the pin's outer prefix stop.

Definition at line 412 of file orcad_cache.cpp.

References ORCAD_PREFIXES::end, ORCAD_STREAM::GetOffset(), ORCAD_ST_SYMBOL_PIN_BUS, ORCAD_ST_SYMBOL_PIN_SCALAR, PASSIVE, ORCAD_STREAM::PeekU8(), pin, ORCAD_STREAM::ReadI32(), ORCAD_STREAM::ReadLzt(), ORCAD_STRUCT_READER::ReadPrefixes(), ORCAD_STREAM::ReadU16(), ORCAD_STREAM::ReadU32(), ORCAD_STREAM::Seek(), ORCAD_STREAM::Skip(), ORCAD_STRUCT_READER::Stream(), THROW_IO_ERROR, and ORCAD_PREFIXES::typeId.

Referenced by OrcadReadSymbolDef().

Functions