6502 Emulator Trap Opcodes ========================== File: Docs.Comp.6502.EmulatorOp - Update: 0.10 Author: J.G.Harston - Date: 15-09-2016 Applications that emulate a 6502 environment often use normally unused opcodes to make a call to the emulator to access the host system. Most 6502 emulators have chosen &x3 as the opcodes to communicate with the host system, ie the extra (zp,X) addressing mode instructions. Usually the emulator only executes emulator traps if they are in high memory, above the top of normal RAM - so in sideways ROM on a BBC host or within the Tube Client code in a 6502 CoPro. Otherwise, the emulator executes them as undocumented opcodes. This protects against code running in RAM from accidently executing emulator traps. Acorn emulator traps use the 16 one-byte &x3 opcodes. The &x3 opcode makes a MOS call, passing the parameters as per the usual MOS calling convention. The emulated 6502 continues after the one-byte &x3 opcode. Warm Silence emulator traps use a single-byte &23 opcode to call MOS_RDCH, and a two-byte &03 Emulator Trap opcode with the immediate value being the emulator call to make. After the call is made the emulated 6502 continues as though a RTS has been executed. Both emulators implement &07 to issue a SWI call to the RISC OS host. Acorn WSS Action Notes --------------------------------------------------------------------------- &03 nn MOS_EMT &03 MOS_CLI XY=>command line &13 &03 &41 MOS_BYTE Acorn AXY=parameters, WSS &EF,&F0,&F1=parameters &23 &03 &40 MOS_WORD Acorn AXY=parameters, WSS &EF,&F0,&F1=parameters &33 MOS_WRCH A=char &43 &23 MOS_RDCH A=char, Cy=flag &53 &03 &06 MOS_FILE AXY=parameters &63 &03 &05 MOS_ARGS AXY=parameters &73 &03 &04 MOS_BGET AXY=parameters &83 &03 &03 MOS_BPUT AXY=parameters &93 &03 &02 MOS_GBPB AXY=parameters &A3 &03 &01 MOS_FIND AXY=parameters The WSS OSGBPB 9 call has the contents of the control block the wrong way around from the standard layout: On entry: On exit: XY?0 = count XY?0 = count returned XY!1 = address XY!1 = address not updated XY!5 = buffer length at address XY!5 = bufflen not updated XY!9 = offset XY!9 = updated offset The 65Tube OSGBPB call allows additional parameters to be passed with A>9: On entry: On exit: XY?0 = ignored XY?0 = directory cycle XY!1 = address, uses length=256 XY!1 = updated address XY!5 = count XY!5 = count returned XY!9 = offset XY!9 = updated offset XY!13=>directory name XY!13= preserved XY!17=>wildcard to match XY!17= preserved &B3 &03 &FF MOS_QUIT Quit the emulator or put it into a dormant state. &C3 MOS_LANG X=OSBYTE 142 parameter. After calling, OSBYTE &A3,&F3,4 should be called to find out execution address in XY. &03 &00 MOS_FSC AXY=parameters Normally returns A=preserved When calling with A=8 (*command warning) the emulator may return A=3 to indicate that the emulator can implement the command itself without generating a 'Bad command' error. Otherwise the caller can chose not to pass the command with A=3. When calling with A=2 (*/filename), A=3 (*command) or A=4 (*RUN filename) an action is returned in A that the caller can chose to respond to. On return, A=action, XY=address with A=%1xxxxxxx - enter CoPro address, A=ID A=%01xxxxxx - enter I/O address A=%001xxxxx - print text A=%0001xxxx - reserved A=%0000xxxx - all done (usually preserved) &03 &80 EMT &80 Read CMOS low level location X, return in Y and A &03 &81 EMT &81 Write Y to CMOS low level location X &03 &82 EMT &82 Read EPROM low level location X, return in Y and A &03 &83 EMT &83 Write Y to EPROM low level location X &03 &D0 EMT &D0 *SRLOAD, (&F2)=>command line &03 &D1 EMT &D1 *SRWRITE, (&F2)=>command line &03 &D2 EMT &D2 *DRIVE, (&F2)=>command line &03 &D3 EMT &D3 Load/Run/Exec !BOOT &03 &D4 EMT &D4 Does nothing &03 &D5 EMT &D5 *BACK &03 &D6 EMT &D6 *MOUNT, (&F2)=>command line The calling code can work out which emulator traps are available with the following code: Acorn effect WSS effect .WhatTraps LDA #130 LDX #nullstr AND 255 LDY #nullstr DIV 256 DEFB &03 ; OSCLI "" EMT DEFW &0041 ; EOR (&00,X) OSBYTE 130 and RTS LDA #0 RTS .nullstr EQUB 13 With Acorn emulator traps a null OSCLI call is made, and A=0 is returned. With Warm Silence emulator traps OSBYTE 130 reads the bottom of user memory and returns with A=130. When implementing emulator traps, the Warm Silence 6502Em should be taken as the reference model for WSS Emulator Traps, and the Acorn 65Tube should be taken as the reference model for Acorn Emulator Traps. The defined Emulator Traps must work correctly and any extensions must be transparently ignored. Virtual DFS ----------- VDFS is a filing system for the BBC/Master intended to be used on emulators that use WSS Emulator Traps to communicate with the host. It implements the following commands: *VDFS - select VDFS filing system (filing system number 17) *FSCLAIM (ON|OFF) - claim DISC and ADFS, defaults to OFF *QUIT or *DESKTOP - return to the desktop *SRLOAD - load to sideways RAM *SRWRITE - write to sideways RAM Filing system commands are passed to the emulator, for most of them if the emulator does not implement them the commands are silently ignored. If FSCLAIM is ON than *DISK, *DISC, *ADFS, *FADFS and the equivalent service calls select VDFS. See also -------- mdfs.net/Apps/Emulators/BBC/BeebEm mdfs.net/Apps/Emulators/BBC/6502Em/VirtualDFS www.borcherds.co.uk/murklesoft/riscos/6502em/virtualdfs.html