Files
VCCPlusOSS/platforms/macos/App/CMOCVariableDebug.swift
T

360 lines
21 KiB
Swift

// 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<Int>?
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[..<colon]))
guard let source = artifact.sources[path], let text = String(data: source, encoding: .utf8),
line <= text.components(separatedBy: .newlines).count else { throw fail("compiler location is outside the verified source snapshot.") }
return (path, line)
}
func validate(_ type: CType, depth: Int = 0) throws {
guard depth <= 12, type.name.count <= 4096, (0...65535).contains(type.size) else { throw fail("invalid type metadata.") }
switch type.kind {
case "integer": guard [1, 2, 4].contains(type.size), type.signed != nil else { throw fail("unsupported integer layout.") }
case "pointer": guard type.size == 2, let element = type.element else { throw fail("unsupported pointer layout.") }; try validate(element, depth: depth + 1)
case "array":
guard let count = type.count, (0...65535).contains(count), let element = type.element else { throw fail("invalid array layout.") }
try validate(element, depth: depth + 1)
guard count * element.size == type.size else { throw fail("invalid array size.") }
case "aggregate":
guard let members = type.members, members.count <= 1024, Set(members.map(\.name)).count == members.count else { throw fail("invalid aggregate layout.") }
for member in members {
try validate(member.type, depth: depth + 1)
guard member.offset >= 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[..<marker.upperBound].utf8.count)
}
}
let listedRows = metadataRows(text)
var payloads = listedRows.map(\.payload)
let assemblyPath = String(object.dropLast(2)) + ".s"
if let expected = verifiedMap.sourceHashes[assemblyPath] {
guard let frozen = artifact.sources[assemblyPath], CMOCSourceMap.sha256(frozen) == expected else {
throw fail("\(assemblyPath): compiler assembly is outside the verified source snapshot.")
}
let assembly = try CMOCProject.readText(artifact.fileURL(assemblyPath), maximumBytes: CMOCProject.maximumFileBytes)
guard CMOCSourceMap.sha256(Data(assembly.utf8)) == expected else {
throw fail("\(assemblyPath): compiler assembly changed since verification.")
}
let completeRows = metadataRows(assembly)
guard completeRows.count == listedRows.count else {
throw fail("\(assemblyPath): compiler metadata record count differs from the verified listing.")
}
for (complete, listed) in zip(completeRows, listedRows) {
let exact = complete.payload == listed.payload
let truncated = complete.prefixBytes < 2048 &&
listed.payload.utf8.count == 2048 - complete.prefixBytes &&
complete.payload.utf8.count > 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<Int>?
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..<end
} else if record.offset != nil { throw fail("local variable has no lexical scope.") }
if visible(identity) && (scopeIdentity == nil || visible(scopeIdentity)) {
variables.append(Variable(name: record.name, sourcePath: path, line: line, type: type, address: storage,
offset: record.offset, scope: scope, isStatic: record.static == true,
moduleID: identity, scopeModuleID: scopeIdentity))
}
} else { throw fail("unknown compiler metadata record.") }
}
}
guard !functions.isEmpty else { throw fail("rebuild with the VCC Plus compiler to include C debug metadata.") }
return Self(functions: functions, variables: variables, sourceMap: verifiedMap)
}
}