PDPTubeDoc for !PDPTube - PDP-11 Emulator, Version 0.29 ======================================================= J.G.Harston, 70 Camm Street, Walkley, Sheffield, S6 3TR http://mdfs.net/Apps/Emulators/PDPTube/ Date: 28-Jul-2018 !PDPTube emulates a PDP-11 coprocessor attached to a RISC OS computer, in the same way that !65Tube emulates a 6502 coprocessor. PDP11Em will also run on any system that can run BBC BASIC programs, such as BBC, DOS, UNIX and Windows. PDP11Em.exe is a precompiled Windows binary. Opening a filer window containing !PDPTube sets up an alias command *PDP11 to start PDP-11 emulation, and a pathname PDPTube: pointing to the resources inside !PDPTube. Double-clicking on !PDPTube starts the emulator with default settings. These can be altered with a Choices:PDPTube.Choices file. On running, various command line options can be given: *PDP11 [-debug] [file [params]] -debug If given, after every opcode executed, a register dump is displayed at the top of the screen. This also slows the emulator down considerably. If a file is given, it is loaded into the PDP-11's memory according to its filetype. Any extra parameters are copied to the PDP-11 stack as a vector of zero-terminated strings for the loaded program to collect and deal with. An example command line would be: *PDP11 TestProg This is a command line This would start the emulator, load the file TestProg into memory, copy the text "This is a command line" to the stack at the top of memory, and enter the code at the relevant entry point. If a BASIC file is specified, with filetype &FFB (BASIC) or &1C7 (Basic8) the emulator looks for a file specified by , and passes the pathname of the BASIC file to it. In effect, it alters the command line from: *PDP11 basicfile Parameters to *PDP11 basicfile Parameters Filetypes Recognised ~~~~~~~~~~~~~~~~~~~~ Filetype: &1C5, &FE6 Name: PDP-11, UnixEx Description: A PDP-11 file or a Unix executable file. Run Action: Loaded into memory according to any header. If there is a Unix header, then the specified code and data segments from byte 16 onwards in the file are loaded to location zero in PDP-11 memory. Any uninitialised data segment is zeroed immediately after the initialised data. A stack frame is built at the top of memory containing the command line parameters and is pointed to with SP, and the code is entered at location zero. The stack does not contain a return address, the code must exit with a call to exit() with TRAP 1. If there is no header, the file is loaded at the first available address and entered at the first location. A stack is placed at the top of memory with a return address of &0000 pushed onto it. The command line tail is found with OSARGS 1 and can be read with OSWORD 5. Code is entered with R5=&0BBC to indicate it is running in a BBC environment and the BBC EMT calls are available, R6=stack (and any stack frame) and R7=entry point. EMT 0 can be used to exit. Filetype: &1C7, &FFB Name: Basic8, BASIC Description: BBC BASIC program in Russell or Acorn/Wilson format. Load Action: If passed as a parameter to *PDP, the file specified with is loaded to memory and executed according to any filetype and header, and any parameters are copied to memory according to the filetype and header. The emulator also recognises untyped files with load address < &10000 and execution address < &10000, ie a code file intended to load into language processor memory. If this type of file is given as a parameter to *PDP11, or is *Run from inside the PDP-11 environment, it is loaded into PDP-11 memory at the load address, parameters are copied to the stack, and it is entered at its execution address. When within !PDPTube, attempting a *command that runs a file from disk will first check to see if it can be recognised as a PDP-11 file. If so, it is loaded into the PDP-11's memory and executed there. Otherwise, it is passed on to the MOS to deal with. The PDP-11 Environment ====================== Error Handling ~~~~~~~~~~~~~~ If an error occurs on the host, the error message and the low byte of the error number is copied to the error buffer with an EMT 15 instruction before it, and then the EMT 15 is jumped to. The form of an error is as follows: EMT 15 EQUB error_number EQUM "Error string" EQUB 0 PDP-11 File Header ~~~~~~~~~~~~~~~~~~ EQUW &0107 ; Magic number &o000407, also branch to CodeStart EQUW CodeEnd-CodeStart ; size of text (code) EQUW DataEnd-CodeEnd ; size of initialised data EQUW ZeroEnd-DataEnd ; size of uninitialised data EQUW &0000 ; size of symbol data EQUW CodeEntry-CodeStart ; entry point EQUW &0000 ; not used EQUW &0001 ; no relocation info ; .CodeStart .CodeEntry .CodeEnd .DataEnd .ZeroEnd CPU Implementation ================== PDPTube emulates a single 64K bank of memory. All PDP-11 opcodes detailed on the "PDP-11 Programming Card", in "Assembly Language for the PDP-11", Kapps & Stafford and in "Introduction to the PDP-11 And Its Assembly Language", Frank are implmented. HALT returns to the PDPTube command prompt. Opcodes 1 to 7 (WAIT, RTI, BPT, IOT, RESET, RTT, MFPT) are executed as NOPs. Host Interface ============== EMT 0 to EMT 15 are used to control the emulator and to communicate with the host. On return from an EMT call if V is set, then R0 points to an error block. If an error handler has been registered, errors may return via the handler. EMT 0 - QUIT Executing this will terminate the emulator. Standard MOS interface calls: EMT 1 - CLI Passes the command line pointed to by R0 to the host. If the command results in a file being run from disk that can be recognised as a PDP-11 file, it is loaded directly into the PDP-11 memory and entered. EMT 2 - BYTE Does OSBYTE R0,R1,R2; returning results in R0, R1, R2 and Carry. The memory value request OSBYTEs &82, &83 and &84 are trapped and returned with values appropriate to the PDP-11 environment. &82 (High order address) returns &0000, &83 returns the lowest usable address, &84 returns the address after the last usable address. EMT 3 - WORD Does OSWORD R0 with R1 pointing to the parameter block. OSWORD 0 (read line) returns values in R2 and Carry. EMT 4 - WRCH Outputs character in R0. EMT 5 - NEWL Outputs LF,CR and returns R0=13. EMT 6 - RDCH Read character to R0 and Carry. EMT 7 - FILE R0=function, R1=>control block. EMT 8 - ARGS R0=function, R1=channel, R2=>control block. EMT 9 - BGET R1=channel, returns character in R0 and Carry. If R1=0, then reads from OSRDCH input stream. EMT 10 - BPUT R0=character, R1=channel. If R1=0, then writes to OSWRCH output stream. EMT 11 - GBPB R0=function, R1=control block. If (R1)=0 then reads or writes to OSWRCH or OSRDCH. EMT 12 - FIND R0=0 and R1=channel or R0<>0 and R1=>filename EMT 13 - SYST Various system control functions: R0=0 - loads and enters BBC BASIC, R1=0 or R1=>parameters. R0=1 - Set up new program environment - default environment handlers only. EMT 14 - CTRL If R0>=0, reads or writes EMT dispatch address: R0=EMT number R1=address of EMT code, or zero to read If R0<0, reads or writes environment handler: R0=Environment handler number R1=address of environment handler or zero to read R2=address of environment data block or zero to read On exit, R0 is preserved, R1 and R2 hold the previous values. Environment handler numbers are: R0 R1 R2 &FFFF Exit handler ignored &FFFE Escape handler Escape flag &FFFD Error handler Error buffer &FFFC Event handler ignored &FFFB Unknown IRQ handler ignored &FFFA ignored EMT dispatch table The Exit handler is entered with R0=return value. The Escape handler is entered with R0=new escape state in b6, and must be returned from with RTS PC. If no Escape handler is set up, the system sets and clears b7 of the Escape flag. The Error handler is entered with R0=>error block. The error block will usually be stored in the Error buffer. The Event handler is entered with R0,R1,R2 holding the event parameters and must be returned from with RTS PC. The Unknown IRQ handler must be returned from with RTI. All other registers must be preserved. Note: the emulator does not support setting an Escape handler, just an Escape flag address. EMT 15 - ERROR Error block follows EMT opcode in the following manner: EMT 15 EQUB errornumber EQUS "error message" EQUB 0 ALIGN EMT 15 enters the current error handler with R0 pointing to the error block after the EMT 15. Memory Addresses ~~~~~~~~~~~~~~~~ MOS calls to OSWORD, OSFILE and OSGBPB whose control blocks contain addresses that refer to memory have these addresses checked before passing them on to the host, and on return. If the address is < &10000, it is translated to the PDP-11 address before being passed on. If it is > &FFFF, it is left unchanged to refer to ARM memory. Unix Interface ============== PDP-11 UNIX TRAPS are implemented and are translated to appropriate calls to the host system. TRAP 0 indir TRAP 16 chown TRAP 32 gtty TRAP 48 signal TRAP 1 exit TRAP 17 brk TRAP 33 TRAP 49 TRAP 2 fork TRAP 18 stat TRAP 34 nice TRAP 50 TRAP 3 read TRAP 19 lseek TRAP 35 ftime TRAP 51 acct TRAP 4 write TRAP 20 getpid TRAP 36 sync TRAP 52 phys TRAP 5 open TRAP 21 mount TRAP 37 kill TRAP 53 lock TRAP 6 close TRAP 22 umount TRAP 38 switch TRAP 54 ioctl TRAP 7 wait TRAP 23 setuid TRAP 39 TRAP 55 TRAP 8 creat TRAP 24 getuid TRAP 40 TRAP 56 mpxchan TRAP 9 link TRAP 25 stime TRAP 41 dup2 TRAP 57 TRAP 10 unlink TRAP 26 ptrace TRAP 42 pipe TRAP 58 TRAP 11 exec TRAP 27 TRAP 43 times TRAP 59 exece TRAP 12 chdir TRAP 28 fstat TRAP 44 profil TRAP 60 umask TRAP 13 time TRAP 29 pause TRAP 45 tui TRAP 61 chroot TRAP 14 mknod TRAP 30 utime TRAP 46 setgid TRAP 62 TRAP 15 chmod TRAP 31 stty TRAP 47 getgid TRAP 63 PDPTube Information =================== PDPTube:!Boot contains PDPTube's default startup settings. If a file Choices:PDPTube.Choices exists it can override the default settings. The Choices file should be an Obey file containing commands similar to the contents of PDPTube:!Boot. The simplest way to create a Choices file is to copy the !Boot file to Choices:PDPTube.Choices and edit the contents. !PDPTube can be run from a read-only media (eg CD-ROM), as long as the files have the appropriate Read attributes. !PDPTube is 26/32bit clean, and should operate on any system that can run BBC BASIC, such as BBC, RISC OS, DOS, Windows and UNIX. PDP11Em/exe is a precompiled binary for Windows. Version History =============== v0.12 2004 Some more work. v0.13 2005 *Commands, RTS, EMT, TRAP. v0.14 01-Sep-2005 More EMTs and TRAPs, mode 7(pc) seems to work, works on PC/Windows TRAP 3 and 4 work for STD*, FNsrc() sets address of source. v0.15 04-Mar-2006 Split out UNIX traps, allocated startup memory, branches fixed, errors caught, flags change. v0.16 20-May-2006 Uses new Make system. v0.17 18-Mar-2007 prog% at &0000 as per Unix expectations - means hardware vectors must be somewhere else, stack frame created for files with headers. v0.18 13-Jan-2008 Uses updated disassembly API. v0.19 03-Feb-2008 Checks for odd addressed word accesses. v0.20 02-Sep-2008 Tightened up filename extensions. v0.21 18-Feb-2009 Escape checked for in background. v0.22 27-Sep-2009 OSBYTE 160 translated to appropriate host calls. v0.23 17-Jun-2010 Indirect TRAP dispatch fixed, errors can return via errvec. v0.25 20-Jan-2012 TRAP brk() correctly fetches inline parameter, paths can contain quoted spaces, added OSWORD 190. v0.26 27-Aug-2015 Added *RESET command. v0.27 29-Sep-2015 Added TUBE/NOTUBE parameter to *RESET, *GO searches Client for EXECUTE routine. v0.28 24-Oct-2015 *RUN uses Client EXECUTE routine, better checking of code header, added more OSBYTE 160 translations. v0.29 28-Jul-2018 Rewrote MUL, shifts and rotates use << and >>, V fixed on CMP/SUB. v0.30 11-Mar-2021 Added *SAVE, start/len/exec/load address general parser