Files

384 lines
33 KiB
Objective-C
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// SPDX-License-Identifier: GPL-3.0-or-later
#import <Foundation/Foundation.h>
#import <CoreGraphics/CoreGraphics.h>
NS_ASSUME_NONNULL_BEGIN
typedef NS_ENUM(NSInteger, VCCMachineState) {
VCCMachineStateEmpty, VCCMachineStatePaused, VCCMachineStateRunning, VCCMachineStateClosed
};
typedef NS_ENUM(NSInteger, VCCFloppyFormat) {
VCCFloppyFormatStandard, VCCFloppyFormatTrackDMK, VCCFloppyFormatSectorVDK
};
typedef NS_ENUM(NSInteger, VCCDiskInsertionReset) {
VCCDiskInsertionResetNone, VCCDiskInsertionResetSoftReset, VCCDiskInsertionResetColdRestart
};
// Immutable copies only; no borrowed RAM or rendering pointers cross the queue.
@interface VCCDiskSnapshot : NSObject
@property(nonatomic, readonly) BOOL mounted, dirty, writeProtected, sourceReadOnly;
@property(nonatomic, readonly) NSString *name;
@property(nonatomic, readonly, nullable) NSString *floppyExtension;
@property(nonatomic, readonly) BOOL formatWriteProtected;
@property(nonatomic, readonly) NSUInteger tracks, sides, byteCount;
@property(nonatomic, readonly) uint64_t readEvents, writeEvents;
@end
// Immutable mounted-image snapshot held by one controller-owned edit lease.
@interface VCCDiskEditCapture : NSObject
@property(nonatomic, readonly) NSData *data;
@property(nonatomic, readonly) NSString *name;
@property(nonatomic, readonly) uint64_t token;
@property(nonatomic, readonly) NSInteger drive;
@property(nonatomic, readonly) BOOL canApply;
@end
@interface VCCHardDiskSave : NSObject
@property(nonatomic, readonly) NSData *data; // full export, or packed [LSN little-endian UInt32, 256 bytes] records
@property(nonatomic, readonly) uint64_t token;
@property(nonatomic, readonly) NSUInteger byteCount;
@end
// Raw, immutable printer bytes captured at one emulation-queue boundary.
@interface VCCPrinterOutput : NSObject
@property(nonatomic, readonly) NSData *bytes;
@property(nonatomic, readonly) uint64_t revision, droppedBytes;
@property(nonatomic, readonly) NSUInteger capacity;
@property(nonatomic, readonly) BOOL enabled;
@end
// A native grant can invalidate its owner while an emulator operation is queued.
@interface VCCCompiledRunLease : NSObject
@property(nonatomic, readonly, getter=isValid) BOOL valid;
- (void)invalidate;
@end
// Immutable input values copied from the same core snapshot as state/frame identity.
// Ports are ordered right (0), left (1); no hardware identities or typed keys.
@interface VCCJoystickInputSnapshot : NSObject
@property(nonatomic, readonly) NSUInteger x, y, buttons, mode;
@end
@interface VCCMachineSnapshot : NSObject
@property(nonatomic, readonly) VCCMachineState state;
@property(nonatomic, readonly) uint64_t generation;
@property(nonatomic, readonly) uint64_t debuggerProgramRevision, debuggerMappingFingerprint, debuggerResidencyFingerprint, assistantMediaRevision;
@property(nonatomic, readonly) BOOL debuggerDevelopmentAttached, debuggerAssemblyAttached, debuggerSourceStepping;
@property(nonatomic, readonly) BOOL debuggerBankedDevelopment;
@property(nonatomic, readonly) BOOL basicDebugAttached, assistantCompiledReturned;
@property(nonatomic, readonly) NSArray<NSString *> *assistantDeviceBlockers;
@property(nonatomic, readonly, nullable) NSNumber *assistantDirectPrompt, *assistantEmptyBASIC; // On-demand readiness observation.
@property(nonatomic, readonly, nullable) NSString *assistantLoadedSource; // Only the guarded transfer completion.
@property(nonatomic, readonly) NSInteger basicStoppedLine; // -1 unless stopped before a BASIC statement
@property(nonatomic, readonly) NSInteger basicSourceOffset;
@property(nonatomic, readonly) NSUInteger basicSourceLength;
@property(nonatomic, readonly) BOOL basicStepping, basicCanStepOut;
@property(nonatomic, readonly) NSInteger basicErrorLine;
@property(nonatomic, readonly) NSString *basicErrorCode;
@property(nonatomic, readonly) NSString *basicDebugStatus;
@property(nonatomic, readonly) uint64_t frames;
@property(nonatomic, readonly, copy) NSArray<VCCJoystickInputSnapshot *> *joystickInputs;
@property(nonatomic, readonly) BOOL keyboardInputHeld;
@property(nonatomic, readonly) NSUInteger pasteRemaining;
@property(nonatomic, readonly) BOOL printerEnabled;
@property(nonatomic, readonly) uint64_t printerRevision, printerDroppedBytes;
@property(nonatomic, readonly) NSUInteger printerByteCount;
@property(nonatomic, readonly) uint64_t cycles;
@property(nonatomic, readonly) uint16_t programCounter;
@property(nonatomic, readonly) CGRect activeVideoRect; // Bounds belonging to pixels, not the latest register state.
@property(nonatomic, readonly, nullable) NSData *pixels; // 640x480, little-endian 0x00RRGGBB
@property(nonatomic, readonly, nullable) NSString *errorMessage;
@property(nonatomic, readonly) BOOL use6309, fastForward;
@property(nonatomic, readonly) NSUInteger ramConfiguration, cpuOverclock, frameInterval;
@property(nonatomic, readonly) uint64_t presentedFrame; // Completed guest rasters at publication.
@property(nonatomic, readonly) uint64_t pixelRevision; // Includes redraws between rasters at a BASIC stop.
@property(nonatomic, readonly) NSInteger videoOutput; // 0 RGB, 1 composite, 2 alternate composite phase
@property(nonatomic, readonly) BOOL audioEnabled;
@property(nonatomic, readonly) BOOL driveWireEnabled;
@property(nonatomic, readonly, copy) NSString *macShellStatus;
@property(nonatomic, readonly) uint64_t macShellRequestID;
@property(nonatomic, readonly) uint64_t audioUnderruns, audioOverruns, audioConsumed;
// Lifetime totals except current occupancy (audioBuffered) and maximum fields.
// Nonzero signal is counted before gain; reset/pause do not clear diagnostics.
@property(nonatomic, readonly) uint64_t audioSubmitted, audioSignalSamples, audioBuffered, audioStarts;
@property(nonatomic, readonly) uint64_t audioMaximumRequest, audioMaximumRefillGapNanoseconds;
@property(nonatomic, readonly) BOOL tapeMounted, tapeMotor, tapeDirty, tapeFast, tapeWAV;
@property(nonatomic, readonly) NSInteger tapeMode;
@property(nonatomic, readonly) uint64_t tapePosition, tapeLength;
@property(nonatomic, readonly) uint64_t tapeReadEvents, tapeWriteEvents;
@property(nonatomic, readonly) BOOL diskEnabled, diskBusy, diskMotor, diskConnected, diskEditorLocked;
@property(nonatomic, readonly) BOOL hardDiskConnected, hardClockEnabled, hardClockReadOnly;
@property(nonatomic, readonly) NSUInteger hardSelectedDrive, hardSector, hardStatus;
@property(nonatomic, readonly) uint64_t hardFlushRequests;
@property(nonatomic, readonly) NSArray<VCCDiskSnapshot *> *hardDisks; // two drives
@property(nonatomic, readonly) BOOL sdcReadOnly;
@property(nonatomic, readonly) NSArray<NSString *> *sdcDriveNames;
@property(nonatomic, readonly) NSString *sdcDirectory;
@property(nonatomic, readonly, nullable) NSString *sdcError;
@property(nonatomic, readonly) uint64_t sdcReadCount, sdcWriteCount;
@property(nonatomic, readonly) BOOL multiPakEnabled;
@property(nonatomic, readonly) NSUInteger physicalSlot, romSlot, ioSlot;
@property(nonatomic, readonly) NSArray<NSNumber *> *cartridgeKinds;
@property(nonatomic, readonly) NSArray<NSString *> *cartridgeNames; // single then slots 1...4
@property(nonatomic, readonly) NSString *diskROMName;
@property(nonatomic, readonly) NSInteger diskSelectedDrive;
@property(nonatomic, readonly) NSUInteger diskTrack, diskSector, diskSide;
@property(nonatomic, readonly) NSArray<VCCDiskSnapshot *> *disks; // always four drives
@end
// Owned, validated payload for a complete profile switch. Image indices 0...3
// are floppies and 4...5 are hard disks; empty image data denotes no medium.
@interface VCCMachineProfile : NSObject <NSCopying>
@property(nonatomic) BOOL use6309, fastForward, sound, multiPak, clockEnabled, clockReadOnly, cassetteWAV, fastCassette;
@property(nonatomic) NSInteger ram, overclock, frameInterval, videoOutput, physicalSlot;
@property(nonatomic) float volume;
@property(nonatomic, copy, nullable) NSData *systemROM, *diskROM, *cassette;
@property(nonatomic, copy) NSString *diskROMName;
@property(nonatomic, copy) NSArray<NSNumber*> *kinds, *readOnly, *protectedImages;
@property(nonatomic, copy) NSArray<NSData*> *cartridgeROMs, *images;
@property(nonatomic, copy) NSArray<NSString*> *cartridgeNames, *imageNames;
@property(nonatomic, copy) NSArray<NSString*> *sdcFolders;
@property(nonatomic, copy) NSArray<NSNumber*> *sdcReadOnly;
@end
typedef void (^VCCMachineCompletion)(VCCMachineSnapshot *snapshot);
// Debugger data is captured on the same queue and at the same boundary as
// machine state. Unavailable I/O bytes are marked separately, never read.
@interface VCCDebugInstruction : NSObject
@property(nonatomic, readonly) uint16_t address;
@property(nonatomic, readonly) NSData *bytes;
@property(nonatomic, readonly) NSString *mnemonic, *operand;
@property(nonatomic, readonly) BOOL valid;
@end
@interface VCCDebugMemoryCapture : NSObject
@property(nonatomic, readonly) VCCMachineSnapshot *machine;
@property(nonatomic, readonly) uint32_t address, capacity;
@property(nonatomic, readonly) NSData *bytes, *available;
@property(nonatomic, readonly) NSArray<VCCDebugInstruction *> *instructions;
// Parallel offsets distinguish physical locations from assumed logical PCs.
@property(nonatomic, readonly) NSArray<NSNumber *> *instructionOffsets;
@end
// Pixel coordinates use the captured source resolution, before display zoom.
// Addresses are in the same space as the enclosing capture.
@interface VCCDebugGraphicsPixel : NSObject
@property(nonatomic, readonly) uint32_t address;
@property(nonatomic, readonly) uint8_t value, mask;
@property(nonatomic, readonly, nullable) NSNumber *attributeAddress, *attributeValue; // attributed text cells
@property(nonatomic, readonly) BOOL available;
@end
@interface VCCDebugGraphicsCapture : NSObject
@property(nonatomic, readonly) VCCMachineSnapshot *machine;
@property(nonatomic, readonly, nullable) NSString *errorMessage;
@property(nonatomic, readonly) NSString *modeName;
@property(nonatomic, readonly) NSInteger width, height;
@property(nonatomic, readonly) uint32_t address;
@property(nonatomic, readonly) BOOL physical;
@property(nonatomic, readonly) NSData *rgba; // R, G, B, A; four bytes per pixel, rows top-down.
- (nullable VCCDebugGraphicsPixel *)pixelAtX:(NSInteger)x y:(NSInteger)y NS_SWIFT_NAME(pixel(x:y:));
- (BOOL)hasSameLayoutAs:(VCCDebugGraphicsCapture *)other NS_SWIFT_NAME(hasSameLayout(as:));
@end
@interface VCCMemoryMapping : NSObject
@property(nonatomic, readonly) uint16_t page;
@property(nonatomic, readonly) uint32_t ramAddress, sourceAddress;
@property(nonatomic, readonly) NSInteger source; // 0 RAM, 1 internal ROM, 2 cartridge ROM
@end
@interface VCCMMUSnapshot : NSObject
@property(nonatomic, readonly) BOOL enabled, ramVectors, allRAM;
@property(nonatomic, readonly) NSUInteger activeTask, romMap, prefix;
@property(nonatomic, readonly) uint32_t ramByteCount, vectorRAMAddress;
@property(nonatomic, readonly) NSArray<NSNumber *> *task0, *task1;
// Eight logical 8 KiB banks, before FE00/vector and FF00/I/O overrides.
@property(nonatomic, readonly) NSArray<VCCMemoryMapping *> *effective;
@end
@interface VCCDebuggerSnapshot : NSObject
@property(nonatomic, readonly) VCCMachineSnapshot *machine;
@property(nonatomic, readonly) NSDictionary<NSString *, NSNumber *> *registers;
@property(nonatomic, readonly) NSArray<VCCDebugInstruction *> *instructions;
@property(nonatomic, readonly) NSArray<NSNumber *> *breakpoints, *disabledBreakpoints;
@property(nonatomic, readonly) uint16_t memoryAddress;
@property(nonatomic, readonly) NSData *memory, *memoryAvailable;
// Full logical memory and availability captured atomically with registers.
@property(nonatomic, readonly) NSData *logicalMemory, *logicalMemoryAvailable;
@property(nonatomic, readonly) NSString *stopReason;
@property(nonatomic, readonly) VCCMMUSnapshot *mmu;
@property(nonatomic, readonly) uint32_t physicalAddress;
@property(nonatomic, readonly) NSData *physicalMemory; // Raw RAM, never overlaid ROM/I/O; read-only.
@end
// Commands are asynchronous and ordered on a private serial queue. Completions
// are delivered on the main queue. One process-wide machine may be loaded.
// Shutdown is terminal; deallocation also drains work and releases the core.
@interface VCCTraceRecord : NSObject
@property(nonatomic, readonly) NSUInteger index;
@property(nonatomic, readonly) uint64_t clock, frame;
@property(nonatomic, readonly) NSInteger cycles;
@property(nonatomic, readonly) uint16_t address;
@property(nonatomic, readonly) NSString *kind, *instruction, *detail, *before, *after;
@end
@interface VCCTraceSnapshot : NSObject
@property(nonatomic, readonly) BOOL armed, capturing;
@property(nonatomic, readonly) uint64_t identifier;
@property(nonatomic, readonly) NSUInteger total, limit, offset;
@property(nonatomic, readonly) NSString *status;
@property(nonatomic, readonly) NSArray<VCCTraceRecord *> *records;
@end
// Guest-only immutable recording input. Each audio frame is Float32 stereo at
// 44.1 kHz. The offset is a monotonic recording timeline, not a CPU cycle count.
@interface VCCVideoPacket : NSObject
@property(nonatomic, readonly) NSData *pixels, *samples;
@property(nonatomic, readonly) CGRect activeArea;
@property(nonatomic, readonly) uint64_t sampleOffset;
@end
@interface VCCMachineController : NSObject
- (void)beginVideoCaptureWithCompletion:(VCCMachineCompletion)completion NS_SWIFT_NAME(beginVideoCapture(completion:));
- (void)takeVideoCapturePackets:(BOOL)finish completion:(void (^)(NSArray<VCCVideoPacket *> *, NSString * _Nullable))completion NS_SWIFT_NAME(takeVideoCapture(finish:completion:));
// Recording data must continue draining while a native modal loop owns the UI.
// Ordinary callers retain the main-queue completion methods above.
- (void)beginVideoCaptureOnQueue:(dispatch_queue_t)replyQueue completion:(VCCMachineCompletion)completion NS_SWIFT_NAME(beginVideoCapture(replyQueue:completion:));
- (void)takeVideoCapturePackets:(BOOL)finish replyQueue:(dispatch_queue_t)replyQueue completion:(void (^)(NSArray<VCCVideoPacket *> *, NSString * _Nullable))completion NS_SWIFT_NAME(takeVideoCapture(finish:replyQueue:completion:));
// Capture starts disabled. Toggling or clearing never pauses/resets the machine.
// Closing a UI window has no effect; reset/profile replacement retain output.
- (void)setPrinterEnabled:(BOOL)enabled completion:(VCCMachineCompletion)completion;
- (void)clearPrinterOutputWithCompletion:(VCCMachineCompletion)completion;
- (void)printerOutputWithCompletion:(void (^)(VCCPrinterOutput *, VCCMachineSnapshot *))completion;
- (void)debuggerSnapshotAtAddress:(uint16_t)address followPC:(BOOL)followPC memoryAddress:(uint16_t)memoryAddress completion:(void (^)(VCCDebuggerSnapshot *))completion NS_SWIFT_NAME(debuggerSnapshot(address:followPC:memoryAddress:completion:));
- (void)debuggerSnapshotAtAddress:(uint16_t)address followPC:(BOOL)followPC memoryAddress:(uint16_t)memoryAddress physicalAddress:(uint32_t)physicalAddress physicalMemory:(BOOL)physicalMemory completion:(void (^)(VCCDebuggerSnapshot *))completion NS_SWIFT_NAME(debuggerSnapshot(address:followPC:memoryAddress:physicalAddress:physicalMemory:completion:));
// Mode for an address preview: SG4, PMODE 0–4, then HSCREEN 1–4 (0–9).
// Current page derives the interpretation, palette and physical address from the machine.
- (void)debuggerGraphicsCurrentPage:(BOOL)currentPage address:(uint32_t)address physical:(BOOL)physical mode:(NSInteger)mode alternatePalette:(BOOL)alternatePalette completion:(void (^)(VCCDebugGraphicsCapture *))completion NS_SWIFT_NAME(debuggerGraphics(currentPage:address:physical:mode:alternatePalette:completion:));
- (void)debuggerStepWithCompletion:(VCCMachineCompletion)completion;
// mode: 0 into, 1 over, 2 out. Completion acknowledges start; poll machine state
// for the eventual pause. pauseWithCompletion cancels a pending source step.
- (void)debuggerStepSource:(NSInteger)mode addresses:(NSArray<NSNumber *> *)addresses locations:(NSArray<NSNumber *> *)locations bytes:(NSArray<NSData *> *)bytes generation:(uint64_t)generation programRevision:(uint64_t)programRevision mappingFingerprint:(uint64_t)mappingFingerprint programCounter:(uint16_t)programCounter completion:(VCCMachineCompletion)completion NS_SWIFT_NAME(debuggerStepSource(mode:addresses:locations:bytes:generation:programRevision:mappingFingerprint:programCounter:completion:));
- (void)debuggerStepBankedSource:(NSInteger)mode addresses:(NSArray<NSNumber *> *)addresses locations:(NSArray<NSNumber *> *)locations bytes:(NSArray<NSData *> *)bytes moduleIdentifiers:(NSArray<NSString *> *)moduleIdentifiers generation:(uint64_t)generation programRevision:(uint64_t)programRevision mappingFingerprint:(uint64_t)mappingFingerprint residencyFingerprint:(uint64_t)residencyFingerprint programCounter:(uint16_t)programCounter completion:(VCCMachineCompletion)completion NS_SWIFT_NAME(debuggerStepBankedSource(mode:addresses:locations:bytes:moduleIdentifiers:generation:programRevision:mappingFingerprint:residencyFingerprint:programCounter:completion:));
- (void)debuggerMemoryAtAddress:(uint32_t)address count:(uint32_t)count physical:(BOOL)physical logicalAddress:(uint16_t)logicalAddress os9:(BOOL)os9 decode:(BOOL)decode completion:(void (^)(VCCDebugMemoryCapture *))completion NS_SWIFT_NAME(debuggerMemory(address:count:physical:logicalAddress:os9:decode:completion:));
- (void)debuggerSetPC:(uint16_t)address completion:(VCCMachineCompletion)completion;
- (void)debuggerSetBreakpoints:(NSArray<NSNumber *> *)addresses completion:(VCCMachineCompletion)completion;
- (void)debuggerConfigureBreakpoints:(NSArray<NSNumber *> *)enabled disabled:(NSArray<NSNumber *> *)disabled completion:(VCCMachineCompletion)completion;
- (void)debuggerStartTrace:(NSUInteger)maximum starts:(NSArray<NSNumber *> *)starts stops:(NSArray<NSNumber *> *)stops screen:(BOOL)screen scheduler:(BOOL)scheduler completion:(VCCMachineCompletion)completion;
- (void)debuggerStopTraceWithCompletion:(VCCMachineCompletion)completion;
- (void)debuggerClearTraceWithCompletion:(VCCMachineCompletion)completion;
- (void)debuggerTraceAtOffset:(NSUInteger)offset completion:(void (^)(VCCTraceSnapshot *, VCCMachineSnapshot *))completion NS_SWIFT_NAME(debuggerTrace(offset:completion:));
- (void)debuggerExportTraceFrom:(NSUInteger)first count:(NSUInteger)count completion:(void (^)(NSString * _Nullable, VCCMachineSnapshot *))completion NS_SWIFT_NAME(debuggerExportTrace(first:count:completion:));
// Direct BASIC transfers are serialized with emulation; no synthetic key events.
// Scoped BASIC operations validate machine identity, mounted devices and guest program on its owner queue.
- (void)assistantReadinessWithCompletion:(VCCMachineCompletion)completion NS_SWIFT_NAME(assistantReadiness(completion:));
- (void)assistantLoadSource:(NSString *)source breakpoints:(NSArray<NSNumber *> *)lines expected:(VCCMachineSnapshot *)expected existing:(NSString *)existing completion:(VCCMachineCompletion)completion NS_SWIFT_NAME(assistantLoad(source:breakpoints:expected:existing:completion:));
- (void)assistantPaste:(NSArray<NSNumber *> *)chords runID:(NSString *)runID direct:(BOOL)direct expected:(VCCMachineSnapshot *)expected source:(NSString *)source completion:(VCCMachineCompletion)completion NS_SWIFT_NAME(assistantPaste(chords:runID:direct:expected:source:completion:));
- (void)cancelAssistantPaste:(NSString *)runID;
- (void)compiledGuest:(VCCCompiledRunLease *)lease runID:(NSString *)runID expected:(VCCMachineSnapshot *)expected assembly:(BOOL)assembly key:(nullable NSNumber *)key readScreen:(BOOL)readScreen finalScreen:(BOOL)finalScreen completion:(void (^)(NSString * _Nullable, VCCMachineSnapshot *))completion NS_SWIFT_NAME(compiledGuest(lease:runID:expected:assembly:key:readScreen:finalScreen:completion:));
- (void)checkReviewedBASIC:(VCCMachineSnapshot *)expected source:(NSString *)source completion:(VCCMachineCompletion)completion;
- (void)assistantScreen:(VCCMachineSnapshot *)expected source:(NSString *)source completion:(void (^)(NSDictionary<NSString *,id> * _Nullable, VCCMachineSnapshot *))completion NS_SWIFT_NAME(assistantScreen(expected:source:completion:));
- (void)basicLoadSource:(NSString *)source run:(BOOL)run completion:(VCCMachineCompletion)completion NS_SWIFT_NAME(basicLoadSource(_:run:completion:));
- (void)basicLoadSource:(NSString *)source run:(BOOL)run breakpoints:(NSArray<NSNumber *> *)lines completion:(VCCMachineCompletion)completion NS_SWIFT_NAME(basicLoadSource(_:run:breakpoints:completion:));
- (void)basicSetBreakpoints:(NSArray<NSNumber *> *)lines source:(NSString *)source completion:(VCCMachineCompletion)completion NS_SWIFT_NAME(basicSetBreakpoints(_:source:completion:));
- (void)basicContinueSource:(NSString *)source completion:(VCCMachineCompletion)completion NS_SWIFT_NAME(basicContinue(source:completion:));
- (void)basicStepSource:(NSString *)source over:(BOOL)over completion:(VCCMachineCompletion)completion NS_SWIFT_NAME(basicStep(source:over:completion:));
- (void)basicStepOutSource:(NSString *)source completion:(VCCMachineCompletion)completion NS_SWIFT_NAME(basicStepOut(source:completion:));
- (void)basicClearDebugWithCompletion:(VCCMachineCompletion)completion;
- (void)basicExportSource:(NSString *)source name:(NSString *)name cassette:(BOOL)cassette completion:(void (^)(NSData * _Nullable, VCCMachineSnapshot *))completion NS_SWIFT_NAME(basicExportSource(_:name:cassette:completion:));
- (void)basicInspectSource:(NSString *)source completion:(void (^)(NSArray<NSDictionary<NSString *, id> *> * _Nullable, VCCMachineSnapshot *))completion NS_SWIFT_NAME(basicInspect(source:completion:));
- (void)basicReadSourceWithCompletion:(void (^)(NSString * _Nullable, VCCMachineSnapshot *))completion NS_SWIFT_NAME(basicReadSource(completion:));
- (void)debuggerWriteMemoryAtAddress:(uint16_t)address data:(NSData *)data completion:(VCCMachineCompletion)completion NS_SWIFT_NAME(debuggerWriteMemory(address:data:completion:));
// Stages/validates all devices first, rejects dirty media, then cold-loads paused.
// applied distinguishes a committed setup from a preflight rejection, including
// the unlikely case of a core allocation failure after media installation.
- (void)applyProfile:(VCCMachineProfile*)profile completion:(void (^)(BOOL applied, VCCMachineSnapshot *snapshot))completion NS_SWIFT_NAME(applyProfile(_:completion:));
- (void)configureMachineWith6309:(BOOL)use6309 ram:(NSInteger)ram overclock:(NSInteger)overclock frameInterval:(NSInteger)interval fastForward:(BOOL)fastForward completion:(VCCMachineCompletion)completion NS_SWIFT_NAME(configureMachine(use6309:ram:overclock:frameInterval:fastForward:completion:));
- (void)setVideoOutput:(NSInteger)output completion:(VCCMachineCompletion)completion;
- (void)loadDiagnosticWithCompletion:(VCCMachineCompletion)completion;
- (void)loadDiagnosticWith6309:(BOOL)use6309 completion:(VCCMachineCompletion)completion NS_SWIFT_NAME(loadDiagnostic(use6309:completion:));
- (void)loadROM:(NSData *)rom use6309:(BOOL)use6309 completion:(VCCMachineCompletion)completion;
// Fire-and-forget input shares the command queue; no frame copy per key event.
- (void)setJoystick:(NSUInteger)port x:(NSUInteger)x y:(NSUInteger)y buttons:(NSUInteger)buttons mode:(NSUInteger)mode;
- (void)pasteChords:(NSArray<NSNumber*> *)chords completion:(VCCMachineCompletion)completion;
- (void)cancelPasteWithCompletion:(VCCMachineCompletion)completion;
- (void)copyScreenTextWithCompletion:(void (^)(NSString * _Nullable, VCCMachineSnapshot *))completion;
// Read-only discovery for loading automation; graphics screens return nil without setting a user-visible error.
- (void)inspectScreenTextWithCompletion:(void (^)(NSString * _Nullable, VCCMachineSnapshot *))completion;
- (void)setKeyboardMask:(uint64_t)keys;
- (void)launchAssembly:(NSData *)binary points:(NSArray<NSNumber *> *)points addresses:(NSArray<NSNumber *> *)addresses bytes:(NSArray<NSData *> *)bytes pauseAtEntry:(BOOL)pauseAtEntry requires6309:(BOOL)requires6309 generation:(uint64_t)generation revision:(uint64_t)revision mapping:(uint64_t)mapping completion:(VCCMachineCompletion)completion;
- (void)launchAssembly:(NSData *)binary points:(NSArray<NSNumber *> *)points addresses:(NSArray<NSNumber *> *)addresses bytes:(NSArray<NSData *> *)bytes pauseAtEntry:(BOOL)pauseAtEntry requires6309:(BOOL)requires6309 generation:(uint64_t)generation revision:(uint64_t)revision mapping:(uint64_t)mapping shared:(BOOL)shared completion:(VCCMachineCompletion)completion;
- (void)pauseAssembly:(VCCMachineSnapshot *)expected completion:(VCCMachineCompletion)completion;
- (void)controlAssembly:(BOOL)step expected:(VCCMachineSnapshot *)expected completion:(VCCMachineCompletion)completion;
- (void)updateAssembly:(NSArray<NSNumber *> *)points expected:(VCCMachineSnapshot *)expected completion:(VCCMachineCompletion)completion;
- (void)clearAssembly:(VCCMachineSnapshot *)expected completion:(VCCMachineCompletion)completion;
- (void)startReviewedC:(NSData *)binary disk:(nullable NSData *)disk name:(NSString *)name stop:(uint16_t)stop expected:(VCCMachineSnapshot *)expected completion:(VCCMachineCompletion)completion;
- (void)continueReviewedC:(VCCMachineSnapshot *)expected name:(NSString *)name stop:(uint16_t)stop bytes:(NSData *)bytes completion:(VCCMachineCompletion)completion;
- (void)ejectReviewedCDisk:(NSString *)name completion:(VCCMachineCompletion)completion;
- (void)debuggerLoadBinary:(NSData *)binary breakpoint:(uint16_t)breakpoint completion:(VCCMachineCompletion)completion;
- (void)debuggerLoadBinary:(NSData *)binary breakpoints:(NSArray<NSNumber *> *)breakpoints completion:(VCCMachineCompletion)completion;
- (void)debuggerArmDevelopmentBreakpoints:(NSArray<NSNumber *> *)breakpoints guardAddresses:(NSArray<NSNumber *> *)guardAddresses guardBytes:(NSArray<NSData *> *)guardBytes completion:(VCCMachineCompletion)completion;
// Module dictionaries: id:String, pages:[{logicalPage:Number,physicalPage:Number}],
// addresses:[Number], bytes:[Data], optional breakpoints:[Number]. An explicit
// breakpoint array qualifies stops to this module; empty retains only code evidence.
// Pages identify actual installed 8 KiB RAM.
- (void)debuggerArmBankedDevelopmentBreakpoints:(NSArray<NSNumber *> *)breakpoints modules:(NSArray<NSDictionary<NSString *, id> *> *)modules completion:(VCCMachineCompletion)completion;
- (void)debuggerClearDevelopmentBreakpointsWithCompletion:(VCCMachineCompletion)completion;
- (void)quickLoadBinary:(NSData *)binary completion:(VCCMachineCompletion)completion;
- (void)requestNitros9BootWithCompletion:(VCCMachineCompletion)completion;
- (void)resumeWithCompletion:(VCCMachineCompletion)completion;
- (void)pauseWithCompletion:(VCCMachineCompletion)completion;
- (void)softResetWithCompletion:(VCCMachineCompletion)completion;
- (void)resetWithCompletion:(VCCMachineCompletion)completion;
- (void)startMacShellWithCompletion:(VCCMachineCompletion)completion NS_SWIFT_NAME(startMacShell(completion:));
- (void)stopMacShellWithCompletion:(VCCMachineCompletion)completion NS_SWIFT_NAME(stopMacShell(completion:));
- (void)decideMacShellRequest:(uint64_t)requestID allow:(BOOL)allow completion:(VCCMachineCompletion)completion NS_SWIFT_NAME(decideMacShellRequest(_:allow:completion:));
- (void)setDriveWireEnabled:(BOOL)enabled completion:(VCCMachineCompletion)completion;
- (void)setAudioEnabled:(BOOL)enabled volume:(float)volume completion:(VCCMachineCompletion)completion;
- (void)mountTape:(NSData *)data wav:(BOOL)wav completion:(VCCMachineCompletion)completion;
// 0 stop, 1 play, 2 rewind, 3 eject, 4 record CAS, 5 record WAV.
- (void)tapeAction:(NSInteger)action completion:(VCCMachineCompletion)completion;
- (void)seekTape:(uint64_t)position completion:(VCCMachineCompletion)completion;
- (void)setTapeFast:(BOOL)enabled completion:(VCCMachineCompletion)completion;
- (void)exportTapeWithCompletion:(void (^)(NSData * _Nullable, VCCMachineSnapshot *))completion;
- (void)discardTapeWithCompletion:(VCCMachineCompletion)completion;
- (void)markTapeSavedWithCompletion:(VCCMachineCompletion)completion;
// Atomic layout change; kinds: 0 empty, 1 raw ROM, 2 FD-502, 3 virtual hard disk, 4 RAM disk, 5 Orchestra-90 (optional 8 KiB ROM), 6 Speech/Sound (PIC + speech payload, or empty), 7 CoCo SDC (8/16 KiB ROM).
// Empty ROM data for kind 1 represents an unavailable remembered file.
// Changes pause and cold reset; disk contents and save acknowledgements survive.
- (void)configureCartridges:(NSArray<NSNumber *> *)kinds roms:(NSArray<NSData *> *)roms names:(NSArray<NSString *> *)names multiPak:(BOOL)enabled physicalSlot:(NSInteger)slot completion:(VCCMachineCompletion)completion;
// SDC folders are explicit host roots, never guest paths. Writes are opt-in.
- (void)configureCartridges:(NSArray<NSNumber *> *)kinds roms:(NSArray<NSData *> *)roms names:(NSArray<NSString *> *)names multiPak:(BOOL)enabled physicalSlot:(NSInteger)slot sdcFolders:(NSArray<NSString *> *)folders sdcReadOnly:(NSArray<NSNumber *> *)readOnly completion:(VCCMachineCompletion)completion;
// Disk changes pause execution and reject in-progress controller commands.
- (void)pauseForDiskChangeWithCompletion:(VCCMachineCompletion)completion;
- (void)loadDiskROM:(NSData *)rom name:(NSString *)name completion:(VCCMachineCompletion)completion;
- (void)disableDisksWithCompletion:(VCCMachineCompletion)completion;
- (void)mountDisk:(NSData *)data drive:(NSInteger)drive name:(NSString *)name readOnly:(BOOL)readOnly completion:(VCCMachineCompletion)completion;
// Validate the complete replacement and media guards before resetting; reset and
// mount share one serialized transaction. Reset does not execute the new disk.
- (void)mountDisk:(NSData *)data drive:(NSInteger)drive name:(NSString *)name readOnly:(BOOL)readOnly reset:(VCCDiskInsertionReset)reset completion:(VCCMachineCompletion)completion;
- (void)createDiskInDrive:(NSInteger)drive completion:(VCCMachineCompletion)completion;
- (void)createDiskInDrive:(NSInteger)drive format:(VCCFloppyFormat)format completion:(VCCMachineCompletion)completion;
- (void)ejectDiskInDrive:(NSInteger)drive discard:(BOOL)discard completion:(VCCMachineCompletion)completion;
- (void)setDiskWriteProtected:(BOOL)enabled drive:(NSInteger)drive completion:(VCCMachineCompletion)completion;
// Export freezes execution and returns immutable bytes and a one-use token.
// Acknowledge only after a successful host write; stale tokens never clear dirty state.
- (void)exportDiskInDrive:(NSInteger)drive completion:(void (^)(NSData * _Nullable, uint64_t, VCCMachineSnapshot *))completion;
// Copy completed in-memory bytes on the worker queue without pausing execution,
// changing media/dirty state, or consuming an export/save acknowledgement token.
- (void)snapshotDiskCopyInDrive:(NSInteger)drive completion:(void (^)(NSData * _Nullable, VCCMachineSnapshot *))completion NS_SWIFT_NAME(snapshotDiskCopy(inDrive:completion:));
- (void)markDiskSavedInDrive:(NSInteger)drive token:(uint64_t)token name:(NSString *)name completion:(VCCMachineCompletion)completion;
// Acquiring a lease pauses at an idle disk boundary. All execution/media
// mutations are refused until cancel or a confirmed edited-image commit.
- (void)beginDiskEditorInDrive:(NSInteger)drive completion:(void (^)(VCCDiskEditCapture * _Nullable, VCCMachineSnapshot *))completion NS_SWIFT_NAME(beginDiskEditor(inDrive:completion:));
- (void)beginHardDiskEditorInDrive:(NSInteger)drive completion:(void (^)(VCCDiskEditCapture * _Nullable, VCCMachineSnapshot *))completion NS_SWIFT_NAME(beginHardDiskEditor(inDrive:completion:));
- (void)prepareDiskEditorToken:(uint64_t)token data:(NSData *)data completion:(void (^)(BOOL, VCCMachineSnapshot *))completion NS_SWIFT_NAME(prepareDiskEditor(token:data:completion:));
- (void)commitDiskEditorToken:(uint64_t)token restartConfirmed:(BOOL)restartConfirmed sourceSaved:(BOOL)sourceSaved completion:(void (^)(BOOL, VCCMachineSnapshot *))completion NS_SWIFT_NAME(commitDiskEditor(token:restartConfirmed:sourceSaved:completion:));
- (void)cancelDiskEditorToken:(uint64_t)token completion:(VCCMachineCompletion)completion NS_SWIFT_NAME(cancelDiskEditor(token:completion:));
- (void)snapshotWithCompletion:(VCCMachineCompletion)completion;
// Background saving neither pauses the CPU nor restarts audio. Nil means no
// eligible completed write. A stale acknowledgement leaves newer writes dirty.
- (void)captureDiskForSavingInDrive:(NSInteger)drive completion:(void (^)(NSData * _Nullable, uint64_t, VCCMachineSnapshot *))completion;
- (void)acknowledgeDiskSaveInDrive:(NSInteger)drive token:(uint64_t)token completion:(VCCMachineCompletion)completion;
- (void)mountHardDisk:(NSData *)data drive:(NSInteger)drive name:(NSString *)name readOnly:(BOOL)readOnly completion:(VCCMachineCompletion)completion;
- (void)createHardDiskInDrive:(NSInteger)drive size:(NSUInteger)size completion:(VCCMachineCompletion)completion;
// 0 eject, 1 discard/eject, 2 protect, 3 allow writes.
- (void)hardDiskAction:(NSInteger)action drive:(NSInteger)drive completion:(VCCMachineCompletion)completion;
- (void)configureHardClock:(BOOL)enabled readOnly:(BOOL)readOnly completion:(VCCMachineCompletion)completion;
- (void)captureHardDiskInDrive:(NSInteger)drive full:(BOOL)full completion:(void (^)(VCCHardDiskSave * _Nullable, VCCMachineSnapshot *))completion;
- (void)acknowledgeHardDiskInDrive:(NSInteger)drive token:(uint64_t)token name:(NSString * _Nullable)name completion:(VCCMachineCompletion)completion;
- (void)shutdownWithCompletion:(VCCMachineCompletion)completion;
@end
NS_ASSUME_NONNULL_END