Files

1090 lines
68 KiB
Swift

// SPDX-License-Identifier: GPL-3.0-or-later
import Foundation
import CryptoKit
/// Verified mapping for one CMOC C translation unit, not a general C debugger.
/// LWASM object offsets are relocated using the matching LWLINK map. Every
/// initialized byte in the user object, including relocation operands, must
/// match the final DECB executable before any source breakpoint is exposed.
struct CMOCSourceMap: Sendable {
/// Bound public catalog arrays by their actual encoded JSON size, including
/// escaping. Private verified selectors retain every entry.
static func boundedJSONCatalog<T>(_ values: [T], maximumBytes: Int = 32 * 1024) -> (items: [T], total: Int, truncated: Bool) {
var items: [T] = [], bytes = 2 // array brackets
for value in values {
guard let encoded = try? JSONSerialization.data(withJSONObject: [value]) else { break }
let addition = encoded.count - 2 + (items.isEmpty ? 0 : 1)
guard bytes + addition <= maximumBytes else { break }
items.append(value); bytes += addition
}
return (items, values.count, items.count != values.count)
}
struct EvidenceAddress: Hashable {
let module: String?
let physical: UInt32
}
struct Instruction: Equatable, Sendable {
let sourceLine: Int // one-based C source line
let address: UInt16
let bytes: [UInt8] // final linked bytes, never unresolved listing bytes
let assembly: String
var moduleID: String? = nil
var physicalAddress: UInt32? = nil
}
struct Provenance: Equatable, Sendable {
let sourceSHA256: String
let binarySHA256: String
let objectSHA256: String
let listingSHA256: String
let linkMapSHA256: String
}
enum Failure: LocalizedError {
case invalid(String)
var errorDescription: String? {
switch self { case .invalid(let message): return "Cannot verify CMOC source mapping: " + message }
}
}
let sourceName: String
let entryPoint: UInt16
let provenance: Provenance
let instructions: [Instruction]
var executableLines: [Int] { Array(Set(instructions.map(\.sourceLine))).sorted() }
func addresses(forLine line: Int) -> [UInt16] { instructions.filter { $0.sourceLine == line }.map(\.address) }
func line(at address: UInt16) -> Int? { instructions.first { $0.address == address }?.sourceLine }
func matches(source: Data, binary: Data) -> Bool {
Self.sha256(source) == provenance.sourceSHA256 && Self.sha256(binary) == provenance.binarySHA256
}
static func sha256(_ data: Data) -> String { SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined() }
// Generated assembly may contain full compiler type records and data tables;
// it has a larger byte budget than object/listing/map/executable evidence.
// Banked verification retains one aggregate cap across unique files.
static let maximumVerificationBytes = 128 * 1024 * 1024
static func evidenceByteLimit(for path: String) -> Int {
(path as NSString).pathExtension.lowercased() == "s" ? 32 * 1024 * 1024 : 8 * 1024 * 1024
}
static func validateEvidenceSize(_ count: Int, path: String) throws {
let limit = evidenceByteLimit(for: path)
guard count <= limit else {
throw Failure.invalid("artifact \(path) is \(count) bytes; its verification limit is \(limit) bytes.")
}
}
static func decbEntryPoint(_ data: Data) throws -> UInt16 { try BinaryImage(data).entry }
/// The caller must build all artifacts together from an immutable source
/// snapshot in a fresh directory. C-source hashes are not present in LWOBJ.
static func parse(source: Data, sourceName: String, listing: Data, object: Data,
objectName: String, linkMap: Data, binary: Data,
sourceAliases: [String] = [], objectAliases: [String] = [],
strictIdentities: Bool = false, allowEmpty: Bool = false,
bankedLayout: CMOCBankedDebugLayout? = nil) throws -> Self {
for (name, data) in [(sourceName, source), (String(objectName.dropLast(2)) + ".lst", listing),
(objectName, object), ("linker map", linkMap), ("executable", binary)] {
try validateEvidenceSize(data.count, path: name)
}
guard let sourceText = String(data: source, encoding: .utf8), !sourceText.contains("\0"),
!sourceName.isEmpty, !objectName.isEmpty else { throw Failure.invalid("invalid source identity or encoding.") }
let verified = try verifiedSections(object: object, objectName: objectName, linkMap: linkMap, binary: binary,
objectAliases: objectAliases, strictIdentities: strictIdentities, bankedLayout: bankedLayout)
let sourceLines = sourceText.replacingOccurrences(of: "\r\n", with: "\n").replacingOccurrences(of: "\r", with: "\n").components(separatedBy: "\n").count
let listingLines = try textLines(listing)
let rowPattern = try NSRegularExpression(pattern: #"^\((.{0,17})\):([0-9]{5,}) (.*)$"#)
let sectionPattern = try NSRegularExpression(pattern: #"^\s*SECTION\s+([^\s,]+)(?:\s|,|$)"#, options: .caseInsensitive)
let linePattern = try NSRegularExpression(pattern: #"^\* Line (.+):([0-9]+)(?::.*)?$"#)
let functionPattern = try NSRegularExpression(pattern: #"^\* FUNCTION .+: defined at (.+):([0-9]+)$"#)
var sectionName: String?, sourceLine: Int?, instructions: [Instruction] = []
var seenAddresses = Set<EvidenceAddress>()
for text in listingLines {
let octets = Array(text.utf8)
guard octets.count >= 22, octets[21] == 32 else { continue }
let metadata = String(decoding: octets.dropFirst(22), as: UTF8.self)
guard let row = groups(rowPattern, metadata) else { continue }
let assembly = row[3], trimmed = assembly.trimmingCharacters(in: .whitespaces)
if let groups = groups(sectionPattern, assembly) {
guard sectionName == nil, verified.sections[groups[1]] != nil else { throw Failure.invalid("unknown or nested listing section.") }
sectionName = groups[1]; sourceLine = nil; continue
}
if trimmed.uppercased() == "ENDSECTION" { sectionName = nil; sourceLine = nil; continue }
if trimmed.hasPrefix("* END FUNCTION") { sourceLine = nil; continue }
if let location = groups(linePattern, trimmed) ?? groups(functionPattern, trimmed) {
sourceLine = nil
if ([sourceName] + sourceAliases).contains(where: { strictIdentities ? normalized(location[1]) == normalized($0) : matchesSource(location[1], $0) }), !trimmed.contains(": inline assembly") {
guard let number = Int(location[2]), number > 0, number <= sourceLines else {
throw Failure.invalid("a C source line is outside the source snapshot.")
}
sourceLine = number
}
continue
}
guard let sectionName, (bankedLayout != nil || sectionName == "code"), let sourceLine else { continue }
let digits = String(decoding: octets[5..<21], as: UTF8.self).trimmingCharacters(in: .whitespaces)
guard octets[4] == 32, !digits.isEmpty,
octets.prefix(4).allSatisfy({ (48...57).contains($0) || (65...70).contains($0) || (97...102).contains($0) }) else { continue }
guard digits.count % 2 == 0, digits.allSatisfy({ $0.isASCII && $0.isHexDigit }),
let offset = Int(String(decoding: octets.prefix(4), as: UTF8.self), radix: 16),
let section = verified.sections[sectionName], let final = section.final else { throw Failure.invalid("unsupported addressed listing row.") }
let chars = Array(digits)
let originalBytes = stride(from: 0, to: chars.count, by: 2).map { UInt8(String(chars[$0...($0 + 1)]), radix: 16)! }
guard offset + originalBytes.count <= final.count,
Array(section.original[offset..<(offset + originalBytes.count)]) == originalBytes else {
throw Failure.invalid("listing bytes do not match the object file.")
}
let opcode = trimmed.split(whereSeparator: \.isWhitespace).first?.uppercased() ?? ""
// Data in inline assembly is not an executable breakpoint location.
if ["FCB", "FDB", "FCC", "FCS", "FILL", "ZMB", "RMB", "RMD", "RMDQ", "FCQ"].contains(opcode) { continue }
if let bankedLayout {
guard bankedLayout.module(forSection: sectionName)?.codeSections.contains(sectionName) == true else {
throw Failure.invalid("a C instruction is outside the declared executable sections.")
}
}
let address = UInt16(section.base + offset)
let identity = bankedLayout?.module(forSection: sectionName)?.physicalAddress(Int(address)) ?? UInt32(address)
let qualified = EvidenceAddress(module: bankedLayout?.module(forSection: sectionName)?.id, physical: identity)
guard seenAddresses.insert(qualified).inserted else { throw Failure.invalid("duplicate instruction addresses in the listing module.") }
instructions.append(Instruction(sourceLine: sourceLine, address: address,
bytes: Array(final[offset..<(offset + originalBytes.count)]), assembly: trimmed,
moduleID: bankedLayout?.module(forSection: sectionName)?.id,
physicalAddress: bankedLayout?.module(forSection: sectionName)?.physicalAddress(Int(address))))
}
guard sectionName == nil, allowEmpty || !instructions.isEmpty else { throw Failure.invalid("no verified C instruction locations were found.") }
return Self(sourceName: sourceName, entryPoint: verified.entry,
provenance: Provenance(sourceSHA256: sha256(source), binarySHA256: sha256(binary), objectSHA256: sha256(object),
listingSHA256: sha256(listing), linkMapSHA256: sha256(linkMap)), instructions: instructions)
}
/// Resolve compiler debug labels from the object symbol table itself. The
/// map's section placements have been verified against the executable;
/// unused map symbols alone are not proof of a variable/scope address.
static func resolvedObjectSymbols(object: Data, objectName: String, objectAliases: [String] = [],
linkMap: Data) throws -> [String: Int] {
let objects = try ObjectSection.parse(object), map = try LinkMap(linkMap)
let names = Set(([objectName] + objectAliases).map(normalized))
let identities = Set(map.sections.filter { names.contains(normalized($0.object)) }.map(\.object))
guard identities.count == 1, let identity = identities.first else {
throw Failure.invalid("debug object identity is missing or ambiguous.")
}
let placements = map.sections.filter { $0.object == identity }
guard Set(placements.map(\.name)).count == placements.count,
Set(placements.map(\.name)) == Set(objects.map(\.name)) else {
throw Failure.invalid("debug object sections do not match the linker map.")
}
var result: [String: Int] = [:]
for section in objects {
guard let placement = placements.first(where: { $0.name == section.name }),
placement.length == section.length, placement.address + placement.length <= 65536 else {
throw Failure.invalid("debug object section has an invalid placement.")
}
for (name, offset) in section.locals {
let address = offset + (section.constant ? 0 : placement.address)
guard result[name] == nil, address < 65536 else {
throw Failure.invalid("debug object symbol is ambiguous or outside logical memory.")
}
result[name] = address
}
}
return result
}
/// Symbol ownership comes from the object's section table, never an address
/// guess: two overlay sections can legitimately have the same logical PC.
static func resolvedObjectSymbolModules(object: Data, layout: CMOCBankedDebugLayout) throws -> [String: String] {
var result: [String: String] = [:]
for section in try ObjectSection.parse(object) where !section.constant {
// Assemblers may retain empty default data/BSS sections. They own
// neither storage nor debug labels and need no bank declaration.
if section.length == 0 && section.locals.isEmpty { continue }
guard let module = layout.module(forSection: section.name) else {
throw Failure.invalid("debug symbol section has no banked module identity.")
}
for name in section.locals.keys {
guard result[name] == nil else { throw Failure.invalid("debug symbol has ambiguous module ownership.") }
result[name] = module.id
}
}
return result
}
/// A raw linker symbol is executable only when its own retained object
/// defines it inside initialized, declared executable bytes. A map label,
/// BSS address or another object's section boundary is not enough proof.
static func executableObjectSymbols(object: Data, objectName: String, objectAliases: [String] = [],
linkMap: Data, binary: Data, layout: CMOCBankedDebugLayout, sourcePaths: [String] = []) throws -> [CMOCProjectSourceMap.ExecutableSymbol] {
let verified = try verifiedSections(object: object, objectName: objectName, linkMap: linkMap, binary: binary,
objectAliases: objectAliases, strictIdentities: true, bankedLayout: layout)
let sections = try ObjectSection.parse(object), map = try LinkMap(linkMap)
let accepted = Set(([objectName] + objectAliases).map(normalized))
let identities = Set(map.sections.filter { accepted.contains(normalized($0.object)) }.map(\.object))
guard identities.count == 1, let identity = identities.first else { throw Failure.invalid("executable symbol object is missing or ambiguous.") }
let mappedSymbols = Dictionary(grouping: map.symbolRecords.filter { $0.object == identity }, by: \.name)
func entryLike(_ name: String, exported: Bool) -> Bool {
if exported { return true }
// CMOC's function-size EQU values can coincidentally fall inside
// code, and function-end labels are boundaries rather than entries.
// Retain deliberate assembly exports even with these spellings.
guard !name.hasPrefix("funcend_"), !name.hasPrefix("funcsize_"),
!name.hasPrefix(".vcc.debug.") else { return false }
let bytes = Array(name.utf8)
guard let first = bytes.first, (65...90).contains(first) || (97...122).contains(first) || first == 95,
bytes.allSatisfy({ (65...90).contains($0) || (97...122).contains($0) || (48...57).contains($0) || [95, 46, 36, 64].contains($0) }) else { return false }
// Compiler instruction/debug labels are not a function catalog.
// An explicitly exported assembly label remains selectable.
return !(first == 76 && bytes.count > 1 && bytes.dropFirst().allSatisfy { (48...57).contains($0) })
}
var result: [CMOCProjectSourceMap.ExecutableSymbol] = []
for section in sections where !section.bss && !section.constant && section.length > 0 {
guard let module = layout.module(forSection: section.name), module.codeSections.contains(section.name),
let placed = verified.sections[section.name], let linked = placed.final,
placed.base >= 0, placed.base + linked.count <= 0xfe00 else { continue }
// Match the guards to independently relocated object bytes, not
// merely to a self-declared symbol address or image hash.
for (offset, byte) in linked.enumerated() {
let address = placed.base + offset
guard let guardRange = module.codeGuards.first(where: {
address >= Int($0.address) && address - Int($0.address) < $0.bytes.count
}), guardRange.bytes[address - Int(guardRange.address)] == byte else {
throw Failure.invalid("executable object section is not covered by matching code guards.")
}
}
for (name, offset) in section.locals where offset < section.length && entryLike(name, exported: section.exportedNames.contains(name)) {
let address = placed.base + offset
let matches = mappedSymbols[name] ?? []
guard matches.count == 1, matches[0].address == address, let physical = module.physicalAddress(address),
!name.isEmpty, name.utf8.count <= 1024 else { continue }
result.append(.init(name: name, objectPath: objectName, sectionName: section.name,
address: UInt16(address), moduleID: module.id, physicalAddress: physical, sourcePaths: sourcePaths))
}
}
return result
}
struct VerifiedSection {
let base: Int
let original: [UInt8]
let final: [UInt8]?
}
/// Apply every supported object relocation and compare the result with the
/// actual linked DECB bytes before interpreting either C or assembly lines.
static func verifiedSections(object: Data, objectName: String, linkMap: Data, binary: Data,
objectAliases: [String] = [], strictIdentities: Bool = true,
bankedLayout: CMOCBankedDebugLayout? = nil) throws
-> (entry: UInt16, sections: [String: VerifiedSection]) {
let image = try bankedLayout == nil ? BinaryImage(binary) : nil
let objects = try ObjectSection.parse(object)
let map = try LinkMap(linkMap)
let acceptedObjects = Set(([objectName] + objectAliases).map(normalized))
let exactObjects = Set(map.sections.filter { acceptedObjects.contains(normalized($0.object)) }.map(\.object))
let matchingObjects = !exactObjects.isEmpty || strictIdentities ? exactObjects : Set(map.sections.filter {
URL(fileURLWithPath: $0.object).lastPathComponent == URL(fileURLWithPath: objectName).lastPathComponent
}.map(\.object))
guard matchingObjects.count == 1, let mappedObject = matchingObjects.first else {
throw Failure.invalid("the object filename is missing or ambiguous in the linker map.")
}
let placements = map.sections.filter { $0.object == mappedObject }
guard Set(placements.map(\.name)).count == placements.count,
Set(placements.map(\.name)) == Set(objects.map(\.name)) else {
throw Failure.invalid("object sections do not uniquely match the linker map.")
}
var bases: [String: Int] = [:]
for section in objects {
guard let placement = placements.first(where: { $0.name == section.name }),
placement.length == section.length, placement.address + placement.length <= 65536 else {
throw Failure.invalid("section size or address differs from the linker map.")
}
bases[section.name] = placement.address
if let bankedLayout, !section.constant, section.length > 0 {
guard let module = bankedLayout.module(forSection: section.name),
(placement.address / 8192...((placement.address + placement.length - 1) / 8192)).allSatisfy({ page in
module.pages.contains { $0.logicalPage == page }
}) else {
throw Failure.invalid("object section has no complete physical placement.")
}
}
}
func local(_ name: String, in section: ObjectSection) throws -> Int {
if let offset = section.locals[name] { return offset + (section.constant ? 0 : bases[section.name]!) }
let matches = objects.filter { $0.locals[name] != nil }
guard matches.count == 1, let target = matches.first, let offset = target.locals[name] else {
throw Failure.invalid("a local relocation symbol is missing or ambiguous.")
}
return offset + (target.constant ? 0 : bases[target.name]!)
}
var linkedSections: [String: [UInt8]] = [:]
for section in objects {
guard !section.bss && !section.constant else { continue }
var linked = section.bytes
var touched = Set<Int>()
for relocation in section.relocations {
let width = relocation.width
// Zero-width references express linker dependencies only.
if width == 0 { continue }
guard relocation.offset + width <= linked.count else { throw Failure.invalid("relocation leaves its section.") }
let value = try relocation.evaluate(base: bases[section.name]!, local: { try local($0, in: section) }, external: { symbol in
let values = map.symbols[symbol] ?? []
guard values.count == 1, let value = values.first else {
throw Failure.invalid("an external relocation symbol is missing or ambiguous.")
}
return value
})
for index in 0..<width {
let position = relocation.offset + index
guard touched.insert(position).inserted else { throw Failure.invalid("overlapping relocations.") }
linked[position] = UInt8(truncatingIfNeeded: value >> (8 * (width - 1 - index)))
}
}
for (offset, byte) in linked.enumerated() {
let address = bases[section.name]! + offset
let actual: UInt8?
if let bankedLayout {
guard let module = bankedLayout.module(forSection: section.name) else { throw Failure.invalid("section has no banked module identity.") }
let index = address - module.logicalAddress
actual = module.bytes.indices.contains(index) ? module.bytes[index] : nil
} else { actual = image?.bytes[address] }
guard actual == byte else {
throw Failure.invalid("object/linker-map bytes do not match the executable. Rebuild before debugging.")
}
}
linkedSections[section.name] = linked
}
var sections: [String: VerifiedSection] = [:]
for section in objects {
sections[section.name] = VerifiedSection(base: bases[section.name]!, original: section.bytes,
final: linkedSections[section.name])
}
return (bankedLayout?.entryPoint ?? image!.entry, sections)
}
private static func matchesSource(_ candidate: String, _ expected: String) -> Bool {
let candidate = normalized(candidate), expected = normalized(expected)
if candidate == expected { return true }
// The caller knows the immutable build snapshot path. Some bundled
// preprocessors emit it absolutely, others retain the bare input name.
return expected.hasPrefix("/") && candidate == URL(fileURLWithPath: expected).lastPathComponent
}
private static func normalized(_ name: String) -> String {
var value = name
while value.hasPrefix("./") { value.removeFirst(2) }
return value
}
private static func textLines(_ data: Data) throws -> [String] {
guard let text = String(data: data, encoding: .utf8), !text.contains("\0") else { throw Failure.invalid("invalid text encoding.") }
let lines = text.replacingOccurrences(of: "\r\n", with: "\n").components(separatedBy: "\n")
guard lines.count <= 100_000, lines.allSatisfy({ $0.utf8.count <= 8192 }) else { throw Failure.invalid("text exceeds mapping limits.") }
return lines
}
private static func groups(_ regex: NSRegularExpression, _ text: String) -> [String]? {
let ns = text as NSString
guard let match = regex.firstMatch(in: text, range: NSRange(location: 0, length: ns.length)) else { return nil }
return (0..<match.numberOfRanges).map { match.range(at: $0).location == NSNotFound ? "" : ns.substring(with: match.range(at: $0)) }
}
private struct BinaryImage {
let bytes: [Int: UInt8]
let entry: UInt16
init(_ data: Data) throws {
var reader = Reader(data), bytes: [Int: UInt8] = [:]
var entry: UInt16?
while !reader.finished {
let type = try reader.byte(), length = try reader.word(), address = try reader.word()
if type == 255 {
guard length == 0, reader.finished, entry == nil else { throw Failure.invalid("invalid DECB entry record.") }
entry = UInt16(address); break
}
guard type == 0, address + length <= 65536 else { throw Failure.invalid("invalid DECB data record.") }
for offset in 0..<length {
guard bytes[address + offset] == nil else { throw Failure.invalid("overlapping DECB blocks.") }
bytes[address + offset] = try reader.byte()
}
}
guard let entry, bytes[Int(entry)] != nil else { throw Failure.invalid("missing executable entry point.") }
self.bytes = bytes; self.entry = entry
}
}
private struct LinkMap {
struct Section { let name: String; let object: String; let address: Int; let length: Int }
struct Symbol { let name: String; let object: String; let address: Int }
let sections: [Section]
let symbols: [String: [Int]]
let symbolRecords: [Symbol]
init(_ data: Data) throws {
let sectionPattern = try NSRegularExpression(pattern: #"^Section: ([^\s]+) \((.+)\) load at ([0-9A-Fa-f]{4}), length ([0-9A-Fa-f]{4})$"#)
let symbolPattern = try NSRegularExpression(pattern: #"^Symbol: ([^\s]+) \((.+)\) = ([0-9A-Fa-f]{4})$"#)
var sections: [Section] = [], symbols: [String: [Int]] = [:], symbolRecords: [Symbol] = []
for line in try textLines(data) {
if let item = groups(sectionPattern, line) {
sections.append(Section(name: item[1], object: item[2], address: Int(item[3], radix: 16)!, length: Int(item[4], radix: 16)!))
} else if let item = groups(symbolPattern, line) {
let address = Int(item[3], radix: 16)!
symbols[item[1], default: []].append(address)
symbolRecords.append(Symbol(name: item[1], object: item[2], address: address))
}
else if line.hasPrefix("Section:") || line.hasPrefix("Symbol:") { throw Failure.invalid("unsupported linker-map record.") }
}
guard !sections.isEmpty else { throw Failure.invalid("empty linker map.") }
self.sections = sections; self.symbols = symbols; self.symbolRecords = symbolRecords
}
}
private struct Reader {
let bytes: [UInt8]
var offset = 0
init(_ data: Data) { bytes = Array(data) }
var finished: Bool { offset == bytes.count }
mutating func byte() throws -> UInt8 {
guard offset < bytes.count else { throw Failure.invalid("truncated binary artifact.") }
defer { offset += 1 }; return bytes[offset]
}
mutating func word() throws -> Int { Int(try byte()) * 256 + Int(try byte()) }
mutating func string() throws -> String {
var result: [UInt8] = []
while true {
let next = try byte(); if next == 0 { break }; result.append(next)
guard result.count <= 4096 else { throw Failure.invalid("oversized object symbol.") }
}
guard let value = String(bytes: result, encoding: .utf8) else { throw Failure.invalid("invalid object symbol encoding.") }
return value
}
}
private struct Relocation {
enum Term { case integer(Int), external(String), local(String), base, operation(UInt8) }
let offset: Int, width: Int
let terms: [Term]
func evaluate(base: Int, local: (String) throws -> Int, external: (String) throws -> Int) throws -> Int {
var stack: [Int] = []
for term in terms {
switch term {
case .integer(let n): stack.append(n)
case .external(let name): stack.append(try external(name))
case .local(let name): stack.append(try local(name))
case .base: stack.append(base)
case .operation(let operation):
guard let rhs = stack.popLast() else { throw Failure.invalid("invalid relocation expression.") }
if [12, 13, 14].contains(operation) {
stack.append(operation == 12 ? -rhs : operation == 13 ? ~rhs : (~rhs & 255)); continue
}
guard let lhs = stack.popLast() else { throw Failure.invalid("invalid relocation expression.") }
let result: Int
switch operation {
case 1: result = lhs + rhs
case 2: result = lhs - rhs
case 3: result = lhs * rhs
case 4, 6: guard rhs != 0 else { throw Failure.invalid("division by zero in relocation.") }; result = lhs / rhs
case 5: guard rhs != 0 else { throw Failure.invalid("division by zero in relocation.") }; result = lhs % rhs
case 7: result = lhs & rhs
case 8: result = lhs | rhs
case 9: result = lhs ^ rhs
case 10: result = lhs != 0 && rhs != 0 ? 1 : 0
case 11: result = lhs != 0 || rhs != 0 ? 1 : 0
case 15: result = lhs == rhs ? 1 : 0
case 16: result = lhs != rhs ? 1 : 0
case 17: result = lhs < rhs ? 1 : 0
case 18: result = lhs <= rhs ? 1 : 0
case 19: result = lhs > rhs ? 1 : 0
case 20: result = lhs >= rhs ? 1 : 0
default: throw Failure.invalid("unsupported relocation operator.")
}
// Bound malicious expressions before Swift arithmetic can overflow.
guard (-0x7fff_ffff...0x7fff_ffff).contains(result) else { throw Failure.invalid("relocation arithmetic overflow.") }
stack.append(result)
}
}
guard stack.count == 1, let result = stack.first else { throw Failure.invalid("unresolved relocation expression.") }
return result
}
}
private struct ObjectSection {
let name: String, flags: Set<UInt8>, length: Int, bytes: [UInt8]
let locals: [String: Int]
let exportedNames: Set<String>
let relocations: [Relocation]
var bss: Bool { flags.contains(1) }
var constant: Bool { flags.contains(2) }
static func parse(_ data: Data) throws -> [Self] {
var reader = Reader(data)
for expected in Array("LWOBJ16".utf8) + [0] { guard try reader.byte() == expected else { throw Failure.invalid("unsupported LWASM object format.") } }
var sections: [Self] = []
while !reader.finished {
let name = try reader.string()
if name.isEmpty { guard reader.finished else { throw Failure.invalid("trailing object bytes.") }; break }
guard !sections.contains(where: { $0.name == name }), sections.count < 256 else { throw Failure.invalid("duplicate or excessive object sections.") }
var flags = Set<UInt8>()
while true { let flag = try reader.byte(); if flag == 0 { break }; guard [1, 2].contains(flag) else { throw Failure.invalid("unsupported section flags.") }; flags.insert(flag) }
var locals: [String: Int] = [:], exportedNames = Set<String>()
for table in 0..<2 {
while true {
let symbol = try reader.string(); if symbol.isEmpty { break }
let value = try reader.word()
if table == 0 { guard locals[symbol] == nil else { throw Failure.invalid("duplicate local symbol.") }; locals[symbol] = value }
else { exportedNames.insert(symbol) }
}
}
var relocations: [Relocation] = []
while true {
var type = try reader.byte(); if type == 0 { break }
var terms: [Relocation.Term] = [], width = 2
while type != 0 {
switch type {
case 255:
guard terms.isEmpty else { throw Failure.invalid("relocation flags follow expression terms.") }
switch try reader.byte() { case 1: width = 1; case 2: width = 0; default: throw Failure.invalid("unsupported relocation flags.") }
case 1: terms.append(.integer(Int(Int16(bitPattern: UInt16(try reader.word())))))
case 2: terms.append(.external(try reader.string()))
case 3: terms.append(.local(try reader.string()))
case 4: terms.append(.operation(try reader.byte()))
case 5: terms.append(.base)
default: throw Failure.invalid("unsupported relocation term.")
}
guard terms.count <= 4096 else { throw Failure.invalid("oversized relocation expression.") }
type = try reader.byte()
}
relocations.append(Relocation(offset: try reader.word(), width: width, terms: terms))
}
let length = try reader.word()
var bytes: [UInt8] = []
if !flags.contains(1) { for _ in 0..<length { bytes.append(try reader.byte()) } }
sections.append(Self(name: name, flags: flags, length: length, bytes: bytes, locals: locals, exportedNames: exportedNames, relocations: relocations))
}
guard !sections.isEmpty else { throw Failure.invalid("empty object file.") }
return sections
}
}
}
/// One linked program, with stable project-relative source identities. A header
/// or generated source can contribute instructions to several translation units.
/// Every contributed object is verified independently against the final image.
struct CMOCProjectSourceMap: Sendable {
struct CodeGuard: Equatable, Sendable {
let address: UInt16
let bytes: [UInt8]
var workerFields: [String: Any] {
["address": Int(address), "bytes_base64": Data(bytes).base64EncodedString()]
}
}
struct TranslationUnit: Sendable {
let sourcePath: String
let sourceName: String
let objectName: String
let listing: Data
let object: Data
}
struct Instruction: Equatable, Sendable {
let sourcePath: String
let sourceLine: Int
let address: UInt16
let bytes: [UInt8]
let assembly: String
var moduleID: String? = nil
var physicalAddress: UInt32? = nil
}
struct ExecutableSymbol: Equatable, Sendable {
let name: String
let objectPath: String
let sectionName: String
let address: UInt16
let moduleID: String
let physicalAddress: UInt32
var sourcePaths: [String] = [] // contributing object sources, never a symbol declaration
}
struct ExecutableLocation: Equatable, Sendable {
let address: UInt16
let moduleID: String
let physicalAddress: UInt32
let codeRange: Range<Int>
}
struct Location: Equatable, Hashable, Sendable {
let path: String
let line: Int
}
let entryPoint: UInt16
let binarySHA256: String
let sourceHashes: [String: String]
let instructions: [Instruction]
let objectHashes: [String: String]
let listingHashes: [String: String]
let linkMapSHA256: String
var bankedLayout: CMOCBankedDebugLayout? = nil
var activeModuleIDs: Set<String>? = nil
var executableSymbols: [ExecutableSymbol] = []
/// Complete relocated executable sections for ordinary flat programs. The
/// worker binds these logical bytes to its actual runtime mapping through
/// the native flat debugger path; no stock physical pages are assumed.
var flatCodeGuards: [CodeGuard] = []
var sourcePaths: [String] { Array(Set(instructions.map(\.sourcePath))).sorted() }
private static func cSymbolAlias(_ name: String) -> String? {
guard name.hasPrefix("_"), name.utf8.count > 1 else { return nil }
let alias = String(name.dropFirst())
guard let first = alias.utf8.first, (65...90).contains(first) || (97...122).contains(first) || first == 95,
alias.utf8.allSatisfy({ (65...90).contains($0) || (97...122).contains($0) || (48...57).contains($0) || $0 == 95 }) else { return nil }
return alias
}
/// Symbol selection names one proven executable address, not a C function
/// range, source line or frame layout. Raw names and unique C aliases work.
func executableSymbol(named name: String) -> ExecutableSymbol? {
let matches = executableSymbols.filter { $0.name == name || Self.cSymbolAlias($0.name) == name }
return matches.count == 1 ? matches.first : nil
}
var executableSymbolNames: [String] {
var counts: [String: Int] = [:]
for symbol in executableSymbols {
for name in Set([symbol.name] + [Self.cSymbolAlias(symbol.name)].compactMap { $0 }) {
counts[name, default: 0] += 1
}
}
return counts.filter { $0.value == 1 }.map(\.key).sorted()
}
/// Runtime identity for code without C statements or typed function ranges.
/// Requires a bank projection and rechecks all code against this snapshot.
func executableLocation(at address: UInt16, memory: Data, available: Data, sharedPaths: Set<String>? = nil) -> ExecutableLocation? {
guard address < 0xfe00, let layout = bankedLayout, let active = activeModuleIDs,
verifiesRuntime(memory: memory, available: available) else { return nil }
let permitted = sharedPaths.map { sharedExecutableModuleIDs(paths: $0) } ?? active
let matches: [ExecutableLocation] = layout.modules.filter { active.contains($0.id) && permitted.contains($0.id) }.flatMap { module in
module.codeGuards.compactMap { code in
let start = Int(code.address), end = start + code.bytes.count
guard Int(address) >= start, Int(address) < end, end <= 0xfe00,
let physical = module.physicalAddress(Int(address)) else { return nil }
return .init(address: address, moduleID: module.id, physicalAddress: physical, codeRange: start..<end)
}
}
return matches.count == 1 ? matches.first : nil
}
/// A module needs actual contributing shared source evidence. A linked
/// object with no C markers never acquires an invented source association.
func sharedExecutableModuleIDs(paths: Set<String>) -> Set<String> {
let mapped = instructions.filter { paths.contains($0.sourcePath) }.compactMap(\.moduleID)
let symbols = executableSymbols.filter { !paths.isDisjoint(with: $0.sourcePaths) }.map(\.moduleID)
return Set(mapped + symbols).intersection(activeModuleIDs ?? [])
}
func executableCodeRanges(sharedPaths: Set<String>) -> [Range<Int>] {
guard let layout = bankedLayout else { return [] }
let permitted = sharedExecutableModuleIDs(paths: sharedPaths)
return layout.modules.filter { permitted.contains($0.id) }.flatMap { module in
module.codeGuards.compactMap { code in
let start = Int(code.address), end = start + code.bytes.count
return !code.bytes.isEmpty && end <= 0xfe00 ? start..<end : nil
}
}
}
/// Only declared executable code from selected modules is readable through
/// the source-only interface. Call verifiesRuntime on the same capture first.
var executableCodeRanges: [Range<Int>] {
guard let layout = bankedLayout, let active = activeModuleIDs else { return [] }
return layout.modules.filter { active.contains($0.id) }.flatMap { module in
module.codeGuards.compactMap { code in
let start = Int(code.address), end = start + code.bytes.count
return !code.bytes.isEmpty && end <= 0xfe00 ? start..<end : nil
}
}
}
/// Validate one immutable logical-memory snapshot. Banked callers must
/// project to its physical mapping first and check the stopped PC's module.
func verifiesRuntime(memory: Data, available: Data) -> Bool {
guard memory.count == 65536, available.count == 65536 else { return false }
func matches(_ address: UInt16, _ bytes: [UInt8]) -> Bool {
let start = Int(address), end = start + bytes.count
return end <= memory.count && available[start..<end].allSatisfy { $0 != 0 } &&
Array(memory[start..<end]) == bytes
}
if let bankedLayout {
guard let activeModuleIDs, !activeModuleIDs.isEmpty else { return false }
return bankedLayout.modules.filter { activeModuleIDs.contains($0.id) }.allSatisfy { module in
module.codeGuards.allSatisfy { matches($0.address, $0.bytes) }
}
}
if !flatCodeGuards.isEmpty { return flatCodeGuards.allSatisfy { matches($0.address, $0.bytes) } }
return instructions.allSatisfy { matches($0.address, $0.bytes) }
}
func executableLines(in path: String) -> [Int] {
Array(Set(instructions.filter { $0.sourcePath == path }.map(\.sourceLine))).sorted()
}
func addresses(forLine line: Int, in path: String) -> [UInt16] {
instructions.filter { $0.sourcePath == path && $0.sourceLine == line }.map(\.address)
}
func location(at address: UInt16) -> Location? {
let matches = instructions.filter { $0.address == address }
return matches.count == 1 ? matches.first.map { Location(path: $0.sourcePath, line: $0.sourceLine) } : nil
}
func matches(sources: [String: Data], binary: Data) -> Bool {
sources.mapValues(CMOCSourceMap.sha256) == sourceHashes && CMOCSourceMap.sha256(binary) == binarySHA256
}
static func parse(sources: [String: Data], compilationDirectory: URL,
units: [TranslationUnit], linkMap: Data, binary: Data,
bankedLayout: CMOCBankedDebugLayout? = nil) throws -> Self {
guard !units.isEmpty, units.count <= 1024, !sources.isEmpty, sources.count <= 4096 else {
throw CMOCSourceMap.Failure.invalid("no supported compilation units or too many project sources.")
}
if let bankedLayout {
guard bankedLayout.binarySHA256 == CMOCSourceMap.sha256(binary),
bankedLayout.sourceHashes == sources.mapValues(CMOCSourceMap.sha256),
bankedLayout.linkMap == linkMap else { throw CMOCSourceMap.Failure.invalid("banked build identities disagree.") }
}
let paths = sources.keys.sorted()
for path in paths {
guard !path.isEmpty, !path.hasPrefix("/"), !path.split(separator: "/").contains(".."),
(path as NSString).standardizingPath == path else {
throw CMOCSourceMap.Failure.invalid("source identities must be canonical project-relative paths.")
}
}
var instructions: [Instruction] = [], addresses = Set<CMOCSourceMap.EvidenceAddress>(), occupied = Set<CMOCSourceMap.EvidenceAddress>()
var entry: UInt16?, objectHashes: [String: String] = [:], listingHashes: [String: String] = [:]
var executableSymbols: [ExecutableSymbol] = [], flatCodeGuards: [CodeGuard] = []
let marker = try NSRegularExpression(pattern: #"\* (?:Line (.+):([0-9]+)(?::.*)?|FUNCTION .+: defined at (.+):([0-9]+))$"#)
func normalize(_ value: String) -> String {
var value = value
while value.hasPrefix("./") { value.removeFirst(2) }
return (value as NSString).standardizingPath
}
for unit in units {
guard sources[unit.sourcePath] != nil, objectHashes[unit.objectName] == nil else {
throw CMOCSourceMap.Failure.invalid("a translation unit is missing its source or repeats an object identity.")
}
if let bankedLayout {
let listingPath = String(unit.objectName.dropLast(2)) + ".lst"
guard bankedLayout.artifactHashes[unit.objectName] == CMOCSourceMap.sha256(unit.object),
unit.listing.isEmpty || bankedLayout.artifactHashes[listingPath] == CMOCSourceMap.sha256(unit.listing) else {
throw CMOCSourceMap.Failure.invalid("object/listing is absent from the banked build manifest.")
}
}
guard let listingText = String(data: unit.listing, encoding: .utf8) else {
throw CMOCSourceMap.Failure.invalid("invalid listing encoding.")
}
var mentioned = Set<String>()
for line in listingText.components(separatedBy: .newlines) {
let ns = line as NSString
guard let match = marker.firstMatch(in: line, range: NSRange(location: 0, length: ns.length)) else { continue }
let index = match.range(at: 1).location == NSNotFound ? 3 : 1
mentioned.insert(normalize(ns.substring(with: match.range(at: index))))
}
let candidates = paths.filter { path in
let absolute = compilationDirectory.appendingPathComponent(path).path
return mentioned.contains(normalize(path)) || mentioned.contains(normalize(absolute)) ||
(path == unit.sourcePath && mentioned.contains(normalize(unit.sourceName)))
}
// Even an assembly-only/optimized-away C unit must have its object
// bytes checked. It simply contributes no source breakpoint locations.
for path in candidates.isEmpty ? [unit.sourcePath] : candidates {
let absolute = compilationDirectory.appendingPathComponent(path).path
let sourceName = path == unit.sourcePath ? unit.sourceName : absolute
let map = try CMOCSourceMap.parse(source: sources[path]!, sourceName: sourceName,
listing: unit.listing, object: unit.object, objectName: unit.objectName,
linkMap: linkMap, binary: binary, sourceAliases: [path, absolute],
objectAliases: [compilationDirectory.appendingPathComponent(unit.objectName).path],
strictIdentities: true, allowEmpty: true, bankedLayout: bankedLayout)
if let entry, entry != map.entryPoint { throw CMOCSourceMap.Failure.invalid("inconsistent entry points.") }
entry = map.entryPoint
for item in map.instructions {
let startIdentity = CMOCSourceMap.EvidenceAddress(module: item.moduleID, physical: item.physicalAddress ?? UInt32(item.address))
guard addresses.insert(startIdentity).inserted else {
throw CMOCSourceMap.Failure.invalid("two source locations claim the same instruction address.")
}
for index in item.bytes.indices {
let address = Int(item.address) + index
let identity = item.moduleID.flatMap { bankedLayout?.module(id: $0)?.physicalAddress(address) } ?? UInt32(address)
let qualified = CMOCSourceMap.EvidenceAddress(module: item.moduleID, physical: identity)
guard address < 65536, occupied.insert(qualified).inserted else {
throw CMOCSourceMap.Failure.invalid("overlapping source instruction ranges.")
}
}
instructions.append(Instruction(sourcePath: path, sourceLine: item.sourceLine,
address: item.address, bytes: item.bytes, assembly: item.assembly,
moduleID: item.moduleID, physicalAddress: item.physicalAddress))
}
}
if let bankedLayout {
executableSymbols += try CMOCSourceMap.executableObjectSymbols(object: unit.object, objectName: unit.objectName,
objectAliases: [compilationDirectory.appendingPathComponent(unit.objectName).path], linkMap: linkMap,
binary: binary, layout: bankedLayout, sourcePaths: candidates)
guard executableSymbols.count <= 8192 else { throw CMOCSourceMap.Failure.invalid("executable symbol catalog exceeds its limit.") }
} else {
let verified = try CMOCSourceMap.verifiedSections(object: unit.object, objectName: unit.objectName,
linkMap: linkMap, binary: binary,
objectAliases: [compilationDirectory.appendingPathComponent(unit.objectName).path], strictIdentities: true)
if let code = verified.sections["code"], let bytes = code.final, !bytes.isEmpty {
guard code.base >= 0, code.base + bytes.count <= 0xfe00 else {
throw CMOCSourceMap.Failure.invalid("flat executable code is outside supported RAM.")
}
flatCodeGuards.append(.init(address: UInt16(code.base), bytes: bytes))
}
}
objectHashes[unit.objectName] = CMOCSourceMap.sha256(unit.object)
if !unit.listing.isEmpty { listingHashes[unit.objectName] = CMOCSourceMap.sha256(unit.listing) }
}
guard let entry, !instructions.isEmpty || !executableSymbols.isEmpty || !flatCodeGuards.isEmpty else { throw CMOCSourceMap.Failure.invalid("no verified C locations or executable evidence were found.") }
var guarded = IndexSet()
for guardRange in flatCodeGuards {
let range = Int(guardRange.address)..<(Int(guardRange.address) + guardRange.bytes.count)
guard !guarded.intersects(integersIn: range) else { throw CMOCSourceMap.Failure.invalid("flat executable sections overlap.") }
guarded.insert(integersIn: range)
}
return Self(entryPoint: entry, binarySHA256: CMOCSourceMap.sha256(binary),
sourceHashes: sources.mapValues(CMOCSourceMap.sha256), instructions: instructions.sorted { $0.address < $1.address },
objectHashes: objectHashes, listingHashes: listingHashes, linkMapSHA256: CMOCSourceMap.sha256(linkMap), bankedLayout: bankedLayout,
executableSymbols: executableSymbols.sorted { ($0.name, $0.objectPath, $0.address) < ($1.name, $1.objectPath, $1.address) },
flatCodeGuards: flatCodeGuards.sorted { $0.address < $1.address })
}
}
extension CMOCProjectSourceMap {
func addresses(file: String, line: Int) -> [UInt16] { addresses(forLine: line, in: file) }
func instruction(at address: UInt16) -> Instruction? {
let matches = instructions.filter { $0.address == address }
return matches.count == 1 ? matches.first : nil
}
/// Select only modules whose complete page contract matches the current
/// snapshot. The caller must additionally verify live bytes before using it.
func projected(physicalPages: [Int: Int]) -> Self {
guard let bankedLayout else { return self }
let active = Set(bankedLayout.modules.filter { module in
module.overlay == nil && module.pages.allSatisfy { physicalPages[$0.logicalPage] == $0.physicalPage }
}.map(\.id))
return projected(activeModuleIDs: active)
}
/// Mapped code can still belong to a loader or an overlay not installed
/// yet. Such modules contribute no source or variable identities until all
/// their executable bytes match this same immutable memory snapshot.
func projected(physicalPages: [Int: Int], memory: Data, available: Data) -> Self {
guard let bankedLayout else { return self }
guard memory.count == 65536, available.count == 65536 else { return projected(activeModuleIDs: []) }
func mapped(_ module: CMOCBankedDebugLayout.Module) -> Bool {
module.pages.allSatisfy { physicalPages[$0.logicalPage] == $0.physicalPage }
}
func codeMatches(_ module: CMOCBankedDebugLayout.Module) -> Bool {
mapped(module) && module.codeGuards.allSatisfy { guardRange in
let start = Int(guardRange.address), end = start + guardRange.bytes.count
return end <= memory.count && available[start..<end].allSatisfy { $0 != 0 } &&
Array(memory[start..<end]) == guardRange.bytes
}
}
var selectedOwners = Set<CMOCBankedDebugLayout.OverlayIdentity>()
for group in bankedLayout.overlayGroups {
let matches = group.owners.filter { owner in
let identity = CMOCBankedDebugLayout.OverlayIdentity(group: group.id, owner: owner)
let code = bankedLayout.modules.filter { $0.overlay == identity && !$0.codeGuards.isEmpty }
return !code.isEmpty && code.allSatisfy(codeMatches)
}
if matches.count == 1 {
selectedOwners.insert(.init(group: group.id, owner: matches[0]))
}
}
let active = Set(bankedLayout.modules.filter { module in
if let overlay = module.overlay { return selectedOwners.contains(overlay) && mapped(module) }
return codeMatches(module)
}.map(\.id))
return projected(activeModuleIDs: active)
}
private func projected(activeModuleIDs active: Set<String>) -> Self {
return Self(entryPoint: entryPoint, binarySHA256: binarySHA256, sourceHashes: sourceHashes,
instructions: instructions.filter { $0.moduleID.map(active.contains) == true },
objectHashes: objectHashes, listingHashes: listingHashes, linkMapSHA256: linkMapSHA256,
bankedLayout: bankedLayout, activeModuleIDs: active,
executableSymbols: executableSymbols.filter { active.contains($0.moduleID) })
}
/// Compatibility projection for the existing editor. Object/listing hashes
/// identify the complete contributing project set, not a single object file.
func map(forFile path: String) -> CMOCSourceMap? {
let selected = instructions.filter { $0.sourcePath == path }
guard let hash = sourceHashes[path], !selected.isEmpty else { return nil }
func aggregate(_ values: [String: String]) -> String {
CMOCSourceMap.sha256(Data(values.keys.sorted().map { $0 + "\0" + values[$0]! }.joined(separator: "\n").utf8))
}
return CMOCSourceMap(sourceName: path, entryPoint: entryPoint,
provenance: .init(sourceSHA256: hash, binarySHA256: binarySHA256,
objectSHA256: aggregate(objectHashes), listingSHA256: aggregate(listingHashes), linkMapSHA256: linkMapSHA256),
instructions: selected.map { .init(sourceLine: $0.sourceLine, address: $0.address, bytes: $0.bytes, assembly: $0.assembly,
moduleID: $0.moduleID, physicalAddress: $0.physicalAddress) })
}
static func parse(artifact: CMOCBuildArtifact, bankedLayout: CMOCBankedDebugLayout? = nil) throws -> Self {
guard artifact.hasBinary else { throw CMOCSourceMap.Failure.invalid("this target did not produce an executable binary.") }
let retainedBinary = try Data(contentsOf: artifact.binaryURL)
guard retainedBinary == artifact.binaryData else {
throw CMOCSourceMap.Failure.invalid("retained executable bytes differ from this build's binary identity.")
}
let bankedLayout = try bankedLayout ?? artifact.bankedDebugLayout()
let linkMap = try bankedLayout?.linkMap ?? Data(contentsOf: artifact.mapURL)
guard let mapText = String(data: linkMap, encoding: .utf8) else { throw CMOCSourceMap.Failure.invalid("invalid linker-map encoding.") }
let objectPattern = try NSRegularExpression(pattern: #"^Section: [^\s]+ \((.+)\) load at [0-9A-Fa-f]{4}, length [0-9A-Fa-f]{4}$"#)
var linked = Set<String>()
for row in mapText.components(separatedBy: .newlines) {
let ns = row as NSString
if let match = objectPattern.firstMatch(in: row, range: NSRange(location: 0, length: ns.length)) {
var path = ns.substring(with: match.range(at: 1))
while path.hasPrefix("./") { path.removeFirst(2) }
let prefix = artifact.compilationDirectory.path + "/"
if path.hasPrefix(prefix) { path.removeFirst(prefix.count) }
linked.insert(path)
}
}
let marker = try NSRegularExpression(pattern: #"\* (?:Line (.+):[0-9]+(?::.*)?|FUNCTION .+: defined at (.+):[0-9]+)$"#)
var aliases: [String: String] = [:]
for path in artifact.sources.keys {
aliases[path] = path
aliases[artifact.compilationDirectory.appendingPathComponent(path).path] = path
}
var units: [TranslationUnit] = []
let outputs = Set(artifact.outputPaths.isEmpty ? [artifact.entrySourcePath.replacingOccurrences(of: ".c", with: ".o"), artifact.entrySourcePath.replacingOccurrences(of: ".c", with: ".lst")] : artifact.outputPaths)
for path in outputs.sorted() where path.hasSuffix(".o") && linked.contains(path) {
let listingPath = String(path.dropLast(2)) + ".lst"
guard outputs.contains(listingPath) || bankedLayout != nil else { continue }
// Assembly-only objects still replay every relocation even when
// their recipe did not request a source listing.
let listing = try outputs.contains(listingPath) ? Data(contentsOf: artifact.fileURL(listingPath)) : Data()
guard let text = String(data: listing, encoding: .utf8) else { throw CMOCSourceMap.Failure.invalid("invalid listing encoding.") }
var referenced: [String] = []
for row in text.components(separatedBy: .newlines) {
let ns = row as NSString
guard let match = marker.firstMatch(in: row, range: NSRange(location: 0, length: ns.length)) else { continue }
let index = match.range(at: 1).location == NSNotFound ? 2 : 1
var name = ns.substring(with: match.range(at: index))
while name.hasPrefix("./") { name.removeFirst(2) }
if let source = aliases[name], !referenced.contains(source) { referenced.append(source) }
}
guard let source = referenced.first(where: { $0.hasSuffix(".c") }) ?? referenced.first ?? (bankedLayout == nil ? nil : artifact.entrySourcePath) else { continue }
units.append(TranslationUnit(sourcePath: source,
sourceName: artifact.compilationDirectory.appendingPathComponent(source).path,
objectName: path, listing: listing, object: try Data(contentsOf: artifact.fileURL(path))))
}
return try parse(sources: artifact.sources, compilationDirectory: artifact.compilationDirectory,
units: units, linkMap: linkMap, binary: artifact.binaryData, bankedLayout: bankedLayout)
}
}
/// The same verified source/type evidence serves build receipts and stopped
/// observations. Catalogs contain only shared declarations and bounded metadata;
/// they confer no permission to read arbitrary guest addresses.
struct CMOCPublicDebugEvidence {
static func fields(artifact: CMOCBuildArtifact, sharedPaths: Set<String>) -> [String: Any] {
do {
let map = try CMOCProjectSourceMap.parse(artifact: artifact)
do {
return fields(map: map, metadata: try CMOCVariableDebug.parse(artifact: artifact, verifiedMap: map),
variableError: nil, sharedPaths: sharedPaths)
} catch {
return fields(map: map, metadata: nil, variableError: reason(error, artifact: artifact), sharedPaths: sharedPaths)
}
} catch {
return ["status": "unavailable", "source_map": "unavailable", "variables": "unavailable",
"reason": reason(error, artifact: artifact), "reason_code": "debug_evidence_not_verified",
"binary_sha256": CMOCSourceMap.sha256(artifact.binaryData),
"requirements": "Retain the matching executable, linker map, linked project objects and listings. Packed/banked builds also need the declared debug manifest."]
}
}
private static func reason(_ error: Error, artifact: CMOCBuildArtifact) -> String {
var text = error.localizedDescription
for root in [artifact.directory.path, artifact.compilationDirectory.path].sorted(by: { $0.count > $1.count }) {
text = text.replacingOccurrences(of: root, with: "<build>")
}
return String(text.prefix(2000))
}
static func fields(map: CMOCProjectSourceMap, metadata: CMOCVariableDebug?, variableError: String?,
sharedPaths: Set<String>) -> [String: Any] {
var fields: [String: Any] = ["status": metadata == nil ? "source_only" : "verified",
"source_map": "verified", "variables": metadata == nil ? "unavailable" : "verified",
"banked": map.bankedLayout != nil, "binary_sha256": map.binarySHA256,
"supported_manifest_versions": [1, 2], "module_catalog_scope": "verified_static_declarations_not_residency",
"entry_point": Int(map.entryPoint), "link_map_sha256": map.linkMapSHA256,
"c_frame_locals": "unavailable", "c_frame_locals_reason": "Owned entry/instruction stops do not establish a C frame; optimized-out or unknown layouts are not guessed.",
"owned_stop_evidence": map.bankedLayout != nil ? "declared_banked_modules" : map.flatCodeGuards.isEmpty ? "unavailable" : "verified_flat_code"]
if let variableError { fields["reason"] = variableError; fields["reason_code"] = "typed_metadata_unavailable" }
func catalog(_ name: String, _ rows: [Any]) {
let result = CMOCSourceMap.boundedJSONCatalog(rows, maximumBytes: 16 * 1024)
fields[name] = result.items; fields[name + "_total"] = result.total; fields[name + "_truncated"] = result.truncated
}
let instructions = map.instructions.filter { sharedPaths.contains($0.sourcePath) }
catalog("c_line_stops", instructions.map { point in
["path": point.sourcePath, "line": point.sourceLine, "address": Int(point.address),
"module_id": point.moduleID as Any? ?? NSNull(),
"physical_address": point.physicalAddress as Any? ?? NSNull()] as [String: Any]
})
let functions = metadata?.functions.filter { sharedPaths.contains($0.sourcePath) } ?? []
let functionNames = (metadata?.breakpointFunctionNames ?? []).filter { name in functions.contains { $0.name == name } }
let symbols = map.executableSymbolNames.filter { name in
map.executableSymbol(named: name).map { !sharedPaths.isDisjoint(with: $0.sourcePaths) } == true
}
let entries = Set((metadata?.functionEntryNames ?? []).filter { name in functions.contains { $0.name == name } } + symbols).sorted()
catalog("functions", functionNames)
catalog("function_entries", entries)
catalog("executable_symbols", symbols)
catalog("function_details", functions.map { function in
var row: [String: Any] = ["name": function.name, "path": function.sourcePath,
"entry_address": function.entry, "module_id": function.moduleID as Any? ?? NSNull(),
"function_entry_available": metadata?.entryFunction(named: function.name) != nil]
if let point = metadata?.breakpointInstruction(named: function.name) {
row["c_line_stop"] = ["path": point.sourcePath, "line": point.sourceLine, "address": Int(point.address)]
} else { row["c_line_unavailable"] = "No unique compiler-mapped C statement in this function's verified body." }
if let line = function.sourceLine { row["declaration_line"] = line }
return row
})
catalog("globals", globalDeclarations(metadata: metadata, sharedPaths: sharedPaths))
catalog("modules", map.bankedLayout?.modules.map(\.id) ?? [])
catalog("module_details", map.bankedLayout?.modules.map { module in
var row: [String: Any] = ["id": module.id, "pages": module.pages.map { ["logical_page": $0.logicalPage, "physical_page": $0.physicalPage] }]
if let overlay = module.overlay { row["overlay"] = ["group": overlay.group, "owner": overlay.owner] }
return row
} ?? [])
catalog("overlay_groups", map.bankedLayout?.overlayGroups.map { ["id": $0.id, "owners": $0.owners] as [String: Any] } ?? [])
catalog("framebuffers", map.bankedLayout?.framebuffers.map(\.workerFields) ?? [])
fields["function_metadata_count"] = functions.count
return fields
}
static func globalDeclarations(metadata: CMOCVariableDebug?, sharedPaths: Set<String>) -> [[String: Any]] {
(metadata?.variables ?? []).filter { $0.scope == nil && $0.offset == nil && sharedPaths.contains($0.sourcePath) }
.sorted { ($0.sourcePath, $0.line, $0.name) < ($1.sourcePath, $1.line, $1.name) }.map { variable in
var row: [String: Any] = ["name": variable.name, "path": variable.sourcePath, "line": variable.line,
"type": variable.type.name, "byte_count": variable.type.size,
"module_id": variable.moduleID as Any? ?? NSNull(), "is_static": variable.isStatic,
"status": "runtime_required"]
if let address = variable.address, address >= 0, variable.type.size > 0, address + variable.type.size <= 0xfe00 {
row["address"] = address
} else { row["status"] = "unavailable"; row["unavailable"] = "No supported verified RAM storage for this declaration." }
if variable.type.kind == "unsupported" {
row["status"] = "unavailable"; row["unavailable"] = "The compiler emitted an unsupported or optimized-out type/storage layout."
}
return row
}
}
/// Values come from the same frozen safe-memory capture as registers and
/// permitted ranges. Each declaration is resolved independently so a local
/// shadow cannot cause a global's address/value to be mislabeled.
static func globals(metadata: CMOCVariableDebug?, sharedPaths: Set<String>, context: CMOCWatchEvaluator.Context,
permittedRanges: [Range<Int>], physicalPages: [Int: Int]) -> (items: [[String: Any]], total: Int, truncated: Bool) {
let definitions = (metadata?.variables ?? []).filter { $0.scope == nil && $0.offset == nil && sharedPaths.contains($0.sourcePath) }
.sorted { ($0.sourcePath, $0.line, $0.name) < ($1.sourcePath, $1.line, $1.name) }
var rows = globalDeclarations(metadata: metadata, sharedPaths: sharedPaths)
// Bound evaluation work independently of the encoded catalog size.
rows = Array(rows.prefix(128))
for index in rows.indices {
let variable = definitions[index]
guard let metadata, let address = variable.address,
permittedRanges.contains(where: { $0.contains(address) && address + variable.type.size <= $0.upperBound }),
variable.type.size > 0 else {
rows[index]["status"] = "unavailable"; rows[index]["unavailable"] = "Storage is not readable in this verified stopped mapping."; continue
}
let selected = CMOCVariableDebug(functions: metadata.functions, variables: [variable], sourceMap: metadata.sourceMap)
let value = CMOCWatchEvaluator(metadata: selected, context: context, frameLocalsAvailable: false).evaluate(variable.name)
if let error = value.error { rows[index]["status"] = "unavailable"; rows[index]["unavailable"] = error }
else { rows[index]["status"] = "available"; rows[index]["value"] = value.value }
if let page = physicalPages[address / 8192] { rows[index]["physical_address"] = page * 8192 + address % 8192 }
}
let catalog = CMOCSourceMap.boundedJSONCatalog(rows, maximumBytes: 32 * 1024)
return (catalog.items, definitions.count, catalog.truncated || catalog.items.count != definitions.count)
}
}