// SPDX-License-Identifier: GPL-3.0-or-later import Foundation /// Types and storage locations emitted by the compiler, bound to the exact /// source/object/listing/link-map/executable set already verified by the IDE. struct CMOCVariableDebug: Sendable { final class CType: Decodable, Sendable { struct Member: Decodable, Sendable { let name: String let offset: Int let type: CType } let name: String let kind: String let size: Int let signed: Bool? let count: Int? let element: CType? let members: [Member]? let floatingFormat: String? init(name: String, kind: String, size: Int, signed: Bool? = nil, count: Int? = nil, element: CType? = nil, members: [Member]? = nil, floatingFormat: String? = nil) { self.name = name; self.kind = kind; self.size = size; self.signed = signed self.count = count; self.element = element; self.members = members self.floatingFormat = floatingFormat } static var integer: CType { CType(name: "int", kind: "integer", size: 2, signed: true) } } struct Function: Sendable { let name: String let sourcePath: String let entry: Int let body: Int let end: Int let frame: Bool var moduleID: String? = nil var sourceLine: Int? = nil } struct Variable: Sendable { let name: String let sourcePath: String let line: Int let type: CType let address: Int? let offset: Int? let scope: Range? let isStatic: Bool var moduleID: String? = nil var scopeModuleID: String? = nil } let functions: [Function] let variables: [Variable] let sourceMap: CMOCProjectSourceMap /// A compiler function record alone is not a C breakpoint location: pure /// assembly functions can have type metadata without any mapped C statement. /// Keep the advertised names and the actual stop selection on one path. func breakpointInstruction(named name: String) -> CMOCProjectSourceMap.Instruction? { let matches = functions.filter { $0.name == name } guard matches.count == 1, let function = matches.first else { return nil } return sourceMap.instructions.lazy.filter { $0.moduleID == function.moduleID && Int($0.address) >= function.body && Int($0.address) < function.end }.min { $0.address < $1.address } } var breakpointFunctionNames: [String] { Set(functions.map(\.name)).filter { breakpointInstruction(named: $0) != nil }.sorted() } /// Function-entry stops describe a verified executable symbol, including /// assembly functions and C prologues. They never imply a mapped C line. func entryFunction(named name: String) -> Function? { let matches = functions.filter { $0.name == name } guard matches.count == 1, let function = matches.first, verifiesEntry(function) else { return nil } return function } var functionEntryNames: [String] { Set(functions.map(\.name)).filter { entryFunction(named: $0) != nil }.sorted() } /// A live containing-function claim requires an explicit bank projection. /// PC may be in a verified prologue before the first mapped C statement. func entryFunction(containing address: UInt16) -> Function? { guard sourceMap.activeModuleIDs != nil || (sourceMap.bankedLayout == nil && !sourceMap.flatCodeGuards.isEmpty) else { return nil } let matches = functions.filter { Int(address) >= $0.entry && Int(address) < $0.end && verifiesEntry($0) } return matches.count == 1 ? matches.first : nil } private func verifiesEntry(_ function: Function) -> Bool { guard !function.name.isEmpty, !function.sourcePath.isEmpty, function.entry >= 0, function.end > function.entry, function.end <= 0xfe00 else { return false } if sourceMap.bankedLayout == nil { guard function.moduleID == nil else { return false } var covered = function.entry for code in sourceMap.flatCodeGuards.sorted(by: { $0.address < $1.address }) { let begin = Int(code.address), end = begin + code.bytes.count if end <= covered { continue } guard begin <= covered else { return false } covered = end if covered >= function.end { return true } } return false } guard let identity = function.moduleID, let module = sourceMap.bankedLayout?.module(id: identity), !module.codeSections.isEmpty, !module.pages.isEmpty, module.pages.count <= 8, Set(module.pages.map(\.logicalPage)).count == module.pages.count, module.pages.allSatisfy({ (0..<8).contains($0.logicalPage) && (0..<1024).contains($0.physicalPage) }) else { return false } if let active = sourceMap.activeModuleIDs, !active.contains(identity) { return false } for page in function.entry / 8192...(function.end - 1) / 8192 { guard module.pages.contains(where: { $0.logicalPage == page }) else { return false } } var covered = function.entry for code in module.codeGuards.sorted(by: { $0.address < $1.address }) { let begin = Int(code.address), end = begin + code.bytes.count if end <= covered { continue } guard begin <= covered else { return false } covered = end if covered >= function.end { return true } } return false } func projected(physicalPages: [Int: Int]) -> Self { projected(sourceMap: sourceMap.projected(physicalPages: physicalPages)) } func projected(physicalPages: [Int: Int], memory: Data, available: Data) -> Self { projected(sourceMap: sourceMap.projected(physicalPages: physicalPages, memory: memory, available: available)) } private func projected(sourceMap selected: CMOCProjectSourceMap) -> Self { guard let active = selected.activeModuleIDs else { return self } return Self(functions: functions.filter { $0.moduleID.map(active.contains) == true }, variables: variables.filter { variable in variable.moduleID.map(active.contains) == true && (variable.scopeModuleID == nil || variable.scopeModuleID.map(active.contains) == true) }, sourceMap: selected) } enum Failure: LocalizedError { case invalid(String) var errorDescription: String? { if case .invalid(let text) = self { return "C variables unavailable: " + text }; return nil } } private struct Record: Decodable { let kind: String let name: String let location: String let type: CType? let symbol: String? let begin: String let end: String let frame: Bool? let offset: Int? let `static`: Bool? } static func parse(artifact: CMOCBuildArtifact, verifiedMap: CMOCProjectSourceMap) throws -> Self { func fail(_ message: String) -> Failure { .invalid(message) } guard verifiedMap.matches(sources: artifact.sources, binary: artifact.binaryData) else { throw fail("source or executable changed since verification. Rebuild before debugging.") } let linkData = try verifiedMap.bankedLayout?.linkMap ?? Data(contentsOf: artifact.mapURL) guard CMOCSourceMap.sha256(linkData) == verifiedMap.linkMapSHA256, let linkText = String(data: linkData, encoding: .utf8) else { throw fail("linker map changed since verification.") } func canonical(_ name: String) -> String { // NSString standardization can collapse /private/var to /var only // while the path exists. Strip the frozen physical build prefix // first, so keeping/reusing/deleting the incremental cache cannot // change the identity of the same retained compiler location. let physicalPrefix = artifact.compilationDirectory.path + "/" var name = name if name.hasPrefix(physicalPrefix) { name.removeFirst(physicalPrefix.count) } else { name = (name as NSString).standardizingPath let aliasPrefix = (artifact.compilationDirectory.path as NSString).standardizingPath + "/" if name.hasPrefix(aliasPrefix) { name.removeFirst(aliasPrefix.count) } } while name.hasPrefix("./") { name.removeFirst(2) } return name } let symbolPattern = try NSRegularExpression(pattern: #"^Symbol: (.+) \((.+)\) = ([0-9A-Fa-f]{4})$"#) var symbols: [String: [String: Int]] = [:] for line in linkText.components(separatedBy: .newlines) { let ns = line as NSString guard let match = symbolPattern.firstMatch(in: line, range: NSRange(location: 0, length: ns.length)) else { continue } let name = ns.substring(with: match.range(at: 1)), object = canonical(ns.substring(with: match.range(at: 2))) guard let address = Int(ns.substring(with: match.range(at: 3)), radix: 16), symbols[object]?[name] == nil else { throw fail("duplicate or malformed linker symbol.") } symbols[object, default: [:]][name] = address } func location(_ raw: String) throws -> (String, Int) { guard let colon = raw.lastIndex(of: ":"), let line = Int(raw[raw.index(after: colon)...]), line > 0 else { throw fail("invalid compiler source location.") } let path = canonical(String(raw[..= 0, member.offset <= type.size, member.type.size <= type.size - member.offset else { throw fail("member leaves its aggregate.") } } case "floating": guard (type.floatingFormat?.count ?? 0) <= 128 else { throw fail("invalid floating-point format metadata.") } // Unknown or legacy formats remain individually unavailable. // Known tags must agree with the declared storage layout. if let format = type.floatingFormat, let size = ["coco-basic-40": 5, "ieee754-binary32-be": 4][format], size != type.size { throw fail("floating-point format disagrees with its storage size.") } case "unsupported": break default: throw fail("unknown type metadata version.") } } var functions: [Function] = [], variables: [Variable] = [] for object in verifiedMap.objectHashes.keys.sorted() { guard let listingHash = verifiedMap.listingHashes[object], listingHash != CMOCSourceMap.sha256(Data()) else { continue } let listingPath = String(object.dropLast(2)) + ".lst" let listing = try Data(contentsOf: artifact.fileURL(listingPath)) let bytes = try Data(contentsOf: artifact.fileURL(object)) guard CMOCSourceMap.sha256(listing) == verifiedMap.listingHashes[object], CMOCSourceMap.sha256(bytes) == verifiedMap.objectHashes[object], let text = String(data: listing, encoding: .utf8) else { throw fail("compiler artifacts changed since verification.") } // LWASM retains at most 2,048 input bytes per line. Large compiler // type records therefore lose their tail in the listing. Recover // only from the immutable, source-hashed assembly from this build, // and bind every recovered record to the corresponding listing row. func metadataRows(_ text: String) -> [(payload: String, prefixBytes: Int)] { text.components(separatedBy: .newlines).compactMap { row in guard let marker = row.range(of: "* VCCDBG1 ") else { return nil } return (String(row[marker.upperBound...]), row[.. listed.payload.utf8.count && complete.payload.hasPrefix(listed.payload) guard exact || truncated else { throw fail("\(assemblyPath): compiler metadata record differs from the verified listing.") } } payloads = completeRows.map(\.payload) } let objectSymbols = try CMOCSourceMap.resolvedObjectSymbols(object: bytes, objectName: object, objectAliases: [artifact.compilationDirectory.appendingPathComponent(object).path], linkMap: linkData) let symbolModules = try verifiedMap.bankedLayout.map { try CMOCSourceMap.resolvedObjectSymbolModules(object: bytes, layout: $0) } ?? [:] func module(_ symbol: String) throws -> String? { guard verifiedMap.bankedLayout != nil else { return nil } guard let id = symbolModules[symbol] else { throw fail("compiler storage label has no verified banked placement.") } return id } func visible(_ id: String?) -> Bool { guard let active = verifiedMap.activeModuleIDs else { return true } return id.map(active.contains) == true } func address(_ name: String) throws -> Int { guard let result = symbols[canonical(object)]?[name], objectSymbols[name] == result else { throw fail("compiler storage label disagrees with its object symbol table.") } return result } for (recordIndex, payload) in payloads.enumerated() { guard payload.utf8.count < 512 * 1024, functions.count + variables.count < 20000 else { throw fail("debug metadata exceeds its limits.") } let payloadData = Data(payload.utf8) // Bound nesting before recursive Decodable type construction. let decodedJSON: Any do { decodedJSON = try JSONSerialization.jsonObject(with: payloadData) } catch { throw fail("\(listingPath), metadata record \(recordIndex + 1): invalid or truncated JSON; retain hash-verified compiler assembly for complete type records.") } var pending: [(Any, Int)] = [(decodedJSON, 0)] var nodes = 0 while let (node, depth) = pending.popLast() { nodes += 1 guard depth <= 24, nodes <= 10000 else { throw fail("debug type nesting exceeds its limits.") } if let dictionary = node as? [String: Any] { pending += dictionary.values.map { ($0, depth + 1) } } else if let array = node as? [Any] { pending += array.map { ($0, depth + 1) } } } let record: Record do { record = try JSONDecoder().decode(Record.self, from: payloadData) } catch { throw fail("\(listingPath), metadata record \(recordIndex + 1): unsupported compiler metadata format (\(String(describing: error))).") } let (path, line) = try location(record.location) guard !record.name.isEmpty, record.name.count < 1024 else { throw fail("invalid variable or function name.") } if record.kind == "function" { guard let symbol = record.symbol else { throw fail("function has no entry symbol.") } let entry = try address(symbol), body = try address(record.begin), end = try address(record.end) guard entry <= body, body <= end else { throw fail("invalid function range.") } let identity = try module(symbol) guard try module(record.begin) == identity, try module(record.end) == identity else { throw fail("function spans incompatible module placements.") } if visible(identity) { functions.append(Function(name: record.name, sourcePath: path, entry: entry, body: body, end: end, frame: record.frame == true, moduleID: identity, sourceLine: line)) } } else if record.kind == "variable" { guard let type = record.type, (record.offset == nil) != (record.symbol == nil) else { throw fail("variable has ambiguous storage.") } try validate(type) let storage = try record.symbol.map(address) if let storage, storage + type.size > 65536 { throw fail("variable leaves logical memory.") } if let offset = record.offset, !(-32768...32767).contains(offset) { throw fail("invalid stack offset.") } var scope: Range? let identity = try record.symbol.map(module) ?? (record.begin.isEmpty ? nil : module(record.begin)) var scopeIdentity: String? if !record.begin.isEmpty || !record.end.isEmpty { let begin = try address(record.begin), end = try address(record.end) guard begin <= end else { throw fail("invalid lexical scope.") } guard try module(record.begin) == module(record.end) else { throw fail("lexical scope spans incompatible module placements.") } scopeIdentity = try module(record.begin) scope = begin..