From 5b98362bf468a93cb70f7423c5eae0b572896696 Mon Sep 17 00:00:00 2001 From: p-x9 <50244599+p-x9@users.noreply.github.com> Date: Thu, 11 Apr 2024 01:06:15 +0900 Subject: [PATCH] Add doc comment about `DyldCache` --- Sources/MachOKit/DyldCache.swift | 17 +++++++++++- .../DyldCacheHeader/DyldCacheHeader.swift | 10 +++++++ .../Model/DyldCache/DyldCacheImageInfo.swift | 3 +++ .../DyldCache/DyldCacheImageTextInfo.swift | 4 +++ .../DyldCache/DyldCacheLocalSymbolsInfo.swift | 26 ++++++++++++++++--- .../DyldCacheMappingAndSlideInfo.swift | 3 +++ .../DyldCache/DyldCacheMappingInfo.swift | 2 ++ .../Model/DyldCache/DyldSubCacheEntry.swift | 10 +++++++ .../DyldCacheLocalSymbolsEntryProtocol.swift | 5 ++++ 9 files changed, 75 insertions(+), 5 deletions(-) diff --git a/Sources/MachOKit/DyldCache.swift b/Sources/MachOKit/DyldCache.swift index 3bd1433..6432c91 100644 --- a/Sources/MachOKit/DyldCache.swift +++ b/Sources/MachOKit/DyldCache.swift @@ -9,6 +9,7 @@ import Foundation public class DyldCache { + /// URL of loaded dyld cache file public let url: URL let fileHandle: FileHandle @@ -16,7 +17,12 @@ public class DyldCache { DyldCacheHeader.layoutSize } + /// Header for dyld cache public let header: DyldCacheHeader + + /// Target CPU info. + /// + /// It is obtained based on magic. public let cpu: CPU public init(url: URL) throws { @@ -46,6 +52,7 @@ public class DyldCache { } extension DyldCache { + /// Sequence of mapping infos public var mappingInfos: DataSequence? { guard header.mappingCount > 0 else { return nil } return fileHandle.readDataSequence( @@ -54,6 +61,7 @@ extension DyldCache { ) } + /// Sequence of mapping and slide infos public var mappingAndSlideInfos: DataSequence? { guard header.mappingWithSlideCount > 0 else { return nil } return fileHandle.readDataSequence( @@ -62,6 +70,7 @@ extension DyldCache { ) } + /// Sequence of image infos. public var imageInfos: DataSequence? { guard header.imagesCount > 0 else { return nil } return fileHandle.readDataSequence( @@ -70,6 +79,7 @@ extension DyldCache { ) } + /// Sequence of image text infos. public var imageTextInfos: DataSequence? { guard header.imagesTextCount > 0 else { return nil } return fileHandle.readDataSequence( @@ -78,7 +88,9 @@ extension DyldCache { ) } - /// check if entry type is `dyld_subcache_entry_v1` or `dyld_subcache_entry` + /// Sub cache type + /// + /// Check if entry type is `dyld_subcache_entry_v1` or `dyld_subcache_entry` public var subCacheEntryType: DyldSubCacheEntryType? { guard header.subCacheArrayCount > 0 else { return nil @@ -95,6 +107,7 @@ extension DyldCache { } } + /// Local symbol info public var localSymbolsInfo: DyldCacheLocalSymbolsInfo? { guard header.localSymbolsSize > 0 else { return nil } return fileHandle.read( @@ -102,6 +115,7 @@ extension DyldCache { ) } + /// Sequence of sub caches public var subCaches: SubCaches? { guard let subCacheEntryType else { return nil } fileHandle.seek(toFileOffset: numericCast(header.subCacheArrayOffset)) @@ -117,6 +131,7 @@ extension DyldCache { } extension DyldCache { + /// Sequence of MachO information contained in this cache public func machOFiles() -> AnySequence { guard let imageInfos = imageInfos else { return AnySequence([]) diff --git a/Sources/MachOKit/Header/DyldCacheHeader/DyldCacheHeader.swift b/Sources/MachOKit/Header/DyldCacheHeader/DyldCacheHeader.swift index 18aaa37..3ae5025 100644 --- a/Sources/MachOKit/Header/DyldCacheHeader/DyldCacheHeader.swift +++ b/Sources/MachOKit/Header/DyldCacheHeader/DyldCacheHeader.swift @@ -15,43 +15,53 @@ public struct DyldCacheHeader: LayoutWrapper { } extension DyldCacheHeader { + /// dyld_cache magic number identifier public var magic: String { .init(tuple: layout.magic) } + /// Unique value for each shared cache file public var uuid: UUID { .init(uuid: layout.uuid) } + /// Type of dyld cache. public var cacheType: DyldCacheType { .init(rawValue: layout.cacheType)! } + /// Sub type of dyld cache for a multi-cache, nil otherwise. public var cacheSubType: DyldCacheSubType? { guard cacheType == .multiCache else { return nil } return .init(rawValue: layout.cacheSubType) } + /// Target Platform public var platform: Platform { .init(rawValue: layout.platform) ?? .unknown } + /// A boolean value that indicates whether this cache targets simulator public var isSimulator: Bool { layout.simulator != 0 } + /// Target OS version public var osVersion: Version { .init(layout.osVersion) } + /// Alternative target platform. public var altPlatform: Platform { .init(rawValue: layout.altPlatform) ?? .unknown } + /// Alternative target OS version public var altOsVersion: Version { .init(layout.altOsVersion) } + /// UUID of the associated symbol file. public var symbolFileUUID: UUID { .init(uuid: layout.symbolFileUUID) } diff --git a/Sources/MachOKit/Model/DyldCache/DyldCacheImageInfo.swift b/Sources/MachOKit/Model/DyldCache/DyldCacheImageInfo.swift index fdadf46..172af47 100644 --- a/Sources/MachOKit/Model/DyldCache/DyldCacheImageInfo.swift +++ b/Sources/MachOKit/Model/DyldCache/DyldCacheImageInfo.swift @@ -15,6 +15,9 @@ public struct DyldCacheImageInfo: LayoutWrapper { } extension DyldCacheImageInfo { + /// Path for image + /// - Parameter cache: DyldCache to which this image belongs + /// - Returns: Path for image public func path(in cache: DyldCache) -> String? { cache.fileHandle.readString( offset: numericCast(layout.pathFileOffset), diff --git a/Sources/MachOKit/Model/DyldCache/DyldCacheImageTextInfo.swift b/Sources/MachOKit/Model/DyldCache/DyldCacheImageTextInfo.swift index 9c3a750..5f7ae3f 100644 --- a/Sources/MachOKit/Model/DyldCache/DyldCacheImageTextInfo.swift +++ b/Sources/MachOKit/Model/DyldCache/DyldCacheImageTextInfo.swift @@ -15,10 +15,14 @@ public struct DyldCacheImageTextInfo: LayoutWrapper { } extension DyldCacheImageTextInfo { + /// UUID of this image text public var uuid: UUID { .init(uuid: layout.uuid) } + /// Path for image text + /// - Parameter cache: DyldCache to which this image belongs + /// - Returns: Path for image text public func path(in cache: DyldCache) -> String? { cache.fileHandle.readString( offset: numericCast(layout.pathOffset), diff --git a/Sources/MachOKit/Model/DyldCache/DyldCacheLocalSymbolsInfo.swift b/Sources/MachOKit/Model/DyldCache/DyldCacheLocalSymbolsInfo.swift index 5b075bf..dec5d7c 100644 --- a/Sources/MachOKit/Model/DyldCache/DyldCacheLocalSymbolsInfo.swift +++ b/Sources/MachOKit/Model/DyldCache/DyldCacheLocalSymbolsInfo.swift @@ -15,6 +15,9 @@ public struct DyldCacheLocalSymbolsInfo: LayoutWrapper { } extension DyldCacheLocalSymbolsInfo { + /// Sequence of 64-bit architecture symbols + /// - Parameter cache: DyldCache to which `self` belongs + /// - Returns: Sequence of symbols public func symbols64(in cache: DyldCache) -> MachOFile.Symbols64? { guard cache.cpu.is64Bit else { return nil } @@ -36,6 +39,9 @@ extension DyldCacheLocalSymbolsInfo { ) } + /// Sequence of 32-bit architecture symbols + /// - Parameter cache: DyldCache to which `self` belongs + /// - Returns: Sequence of symbols public func symbols32(in cache: DyldCache) -> MachOFile.Symbols? { guard !cache.cpu.is64Bit else { return nil } @@ -57,18 +63,24 @@ extension DyldCacheLocalSymbolsInfo { ) } - public func symbols(in cache: DyldCache) -> AnySequence { + /// Sequence of symbols + /// - Parameter cache: DyldCache to which `self` belongs + /// - Returns: Sequence of symbols + public func symbols(in cache: DyldCache) -> AnyRandomAccessCollection { if let symbols64 = symbols64(in: cache) { - return AnySequence(symbols64) + return AnyRandomAccessCollection(symbols64) } else if let symbols32 = symbols32(in: cache) { - return AnySequence(symbols32) + return AnyRandomAccessCollection(symbols32) } else { - return AnySequence([]) + return AnyRandomAccessCollection([]) } } } extension DyldCacheLocalSymbolsInfo { + /// Sequence of 64-bit architecture symbols entries + /// - Parameter cache: DyldCache to which `self` belongs + /// - Returns: Sequence of symbols entries public func entries64( in cache: DyldCache ) -> DataSequence? { @@ -81,6 +93,9 @@ extension DyldCacheLocalSymbolsInfo { ) } + /// Sequence of 32-bit architecture symbols entries + /// - Parameter cache: DyldCache to which `self` belongs + /// - Returns: Sequence of symbols entries public func entries32( in cache: DyldCache ) -> DataSequence? { @@ -94,6 +109,9 @@ extension DyldCacheLocalSymbolsInfo { ) } + /// Sequence of symbols entries + /// - Parameter cache: DyldCache to which `self` belongs + /// - Returns: Sequence of symbols entries public func entries( in cache: DyldCache ) -> AnySequence { diff --git a/Sources/MachOKit/Model/DyldCache/DyldCacheMappingAndSlideInfo.swift b/Sources/MachOKit/Model/DyldCache/DyldCacheMappingAndSlideInfo.swift index 8953540..435a15f 100644 --- a/Sources/MachOKit/Model/DyldCache/DyldCacheMappingAndSlideInfo.swift +++ b/Sources/MachOKit/Model/DyldCache/DyldCacheMappingAndSlideInfo.swift @@ -15,14 +15,17 @@ public struct DyldCacheMappingAndSlideInfo: LayoutWrapper { } extension DyldCacheMappingAndSlideInfo { + /// Flags of mapping public var flags: DyldCacheMappingFlags { .init(rawValue: layout.flags) } + /// Max vm protection of this mapping public var maxProtection: VMProtection { .init(rawValue: VMProtection.RawValue(bitPattern: layout.maxProt)) } + /// Initial vm protection of this mapping public var initialProtection: VMProtection { .init(rawValue: VMProtection.RawValue(bitPattern: layout.maxProt)) } diff --git a/Sources/MachOKit/Model/DyldCache/DyldCacheMappingInfo.swift b/Sources/MachOKit/Model/DyldCache/DyldCacheMappingInfo.swift index 356add6..3d14575 100644 --- a/Sources/MachOKit/Model/DyldCache/DyldCacheMappingInfo.swift +++ b/Sources/MachOKit/Model/DyldCache/DyldCacheMappingInfo.swift @@ -15,10 +15,12 @@ public struct DyldCacheMappingInfo: LayoutWrapper { } extension DyldCacheMappingInfo { + /// Max vm protection of this mapping public var maxProtection: VMProtection { .init(rawValue: VMProtection.RawValue(bitPattern: layout.maxProt)) } + /// Initial vm protection of this mapping public var initialProtection: VMProtection { .init(rawValue: VMProtection.RawValue(bitPattern: layout.maxProt)) } diff --git a/Sources/MachOKit/Model/DyldCache/DyldSubCacheEntry.swift b/Sources/MachOKit/Model/DyldCache/DyldSubCacheEntry.swift index b591ef9..2356a92 100644 --- a/Sources/MachOKit/Model/DyldCache/DyldSubCacheEntry.swift +++ b/Sources/MachOKit/Model/DyldCache/DyldSubCacheEntry.swift @@ -33,6 +33,7 @@ public enum DyldSubCacheEntry { } } + /// UUID of sub cache public var uuid: UUID { switch self { case let .general(info): info.uuid @@ -40,6 +41,7 @@ public enum DyldSubCacheEntry { } } + /// Offset of this subcache from the main cache base address public var cacheVMOffset: UInt64 { switch self { case let .general(info): info.cacheVMOffset @@ -47,6 +49,9 @@ public enum DyldSubCacheEntry { } } + /// File name suffix of the subCache file + /// + /// e.g. ".25.data", ".03.development" public var fileSuffix: String? { switch self { case let .general(info): info.fileSuffix @@ -62,6 +67,7 @@ public struct DyldSubCacheEntryV1: LayoutWrapper { } extension DyldSubCacheEntryV1 { + /// UUID of sub cache public var uuid: UUID { .init(uuid: layout.uuid) } @@ -74,10 +80,14 @@ public struct DyldSubCacheEntryGeneral: LayoutWrapper { } extension DyldSubCacheEntryGeneral { + /// UUID of sub cache public var uuid: UUID { .init(uuid: layout.uuid) } + /// File name suffix of the subCache file + /// + /// e.g. ".25.data", ".03.development" public var fileSuffix: String { .init(tuple: layout.fileSuffix) } diff --git a/Sources/MachOKit/Protocol/DyldCacheLocalSymbolsEntryProtocol.swift b/Sources/MachOKit/Protocol/DyldCacheLocalSymbolsEntryProtocol.swift index d1a2c3b..52cac87 100644 --- a/Sources/MachOKit/Protocol/DyldCacheLocalSymbolsEntryProtocol.swift +++ b/Sources/MachOKit/Protocol/DyldCacheLocalSymbolsEntryProtocol.swift @@ -9,7 +9,12 @@ import Foundation public protocol DyldCacheLocalSymbolsEntryProtocol { + /// Offset in cache file of start of dylib var dylibOffset: Int { get } + + /// Start index of locals for this dylib var nlistStartIndex: Int { get } + + /// Number of local symbols for this dylib var nlistCount: Int { get } }