PC Emulator v1.01alpha (C) 1994 University of Bristol Please report comments, bugs etc to hedley@cs.bris.ac.uk This is David Hedley's PC Emulator. 0. Table of contents 0. Table of contents 1. How to get pcemu really running 2. Information about this FreeBSD port 3. David's original README 4. Copyright notice 1. This looks like PC, but where is DOS? How to get pcemu really running Pcemu is an emulator that emulates an 8086 CPU as well as a bunch of PC BIOS services, so it basically provides the functionality like an old PC/XT. Anyway, as with the XT too, the emulator requires something like an operating system to run with. Since we cannot ship MS-DOS or one of its variants along with this distribution (for legal reasons), you're now actually looking at a (sort of) "standalone operating system", just to get pcemu booted and running. All this system does is show you this introduction. You will have to replace this mini-system by a physical image of a DOS boot floppy. The "system" currently running is booted from the file /usr/local/lib/pcemu/DriveA. It pretends to be the image of a 720 KB diskette, which has been chosen as the default bootfile size. In order to obtain the image of a bootable DOS floppy, do the following: Prepare a 720 KB floppy with a DOS system as you'd like to run it later. Include all the good stuff you don't want to miss there. Don't forget to put a simple text editor there, so you can modify your configuration files later. Put a copy of the file /usr/local/lib/pcemu/C/emufs.sys onto this diskette, and include a line like device = a:\emufs.sys /usr/local/lib/pcemu/C into the config.sys file on this diskette. This will provide you with an interface to the BSD file system from within your DOS session. (It actually pretends to be a network drive.) According to David Hedley, you are also advised to include the line stacks = 9, 512 there to avoid stack overflow problems with the emulator. If you want to retain a copy of the standalone "system" you are currently looking at, move it away: # cd /usr/local/lib/pcemu; mv DriveA StandaloneA Now, make a copy of your disk by either: - under BSD, perform a # cp /dev/fd0.720 /usr/local/lib/pcemu/DriveA (the number after the fd may vary for drives other than the primary one), or - under DOS, copy the file /usr/local/lib/pcemu/C/dumpdisk.exe to your DOS system and execute it. This will dump the physical copy of either drive A or B to the file drivea in your current (DOS) working directory. You can then move this file to /usr/local/lib/pcemu/DriveA in your BSD system. Since pcemu needs to display the standard VGA font, you further need to tell your X server about the location of the font file. It has been put under /usr/local/lib/pcemu/font/ along with the necessary information for the X server. All you need to do is to tell your X server about it. This can either be done as a server default by including the directory into the FontPath section of your XF86Config file (this is for XFree86, refer to the documentation if you're using another X server). Alternatively, you can run the command $ xset fp+ /usr/local/lib/pcemu/font when X11 is running to instruct your X server to append this directory to the font path. Should you wish to run pcemu across the network, remember that the fonts must be physically available at the server side, or you need to provide an X11 font server (xfs). Refer to the X11 documentation on how to setup this. That's all, now you should be able to run pcemu. Add required device = a:\emufs.sys /... lines to your config.sys as you need them. It's not wise to make the whole BSD hierarchy available since DOS does not provide multiuser protection. Should you wish to override some of the emulator defaults like size and location of the bootfile, you can do this by settig up a $HOME/.pcemurc file. Refer to sections 2. and 3. below. 2. Information about this FreeBSD port This `port' of pcemu to FreeBSD has been prepared by Jörg Wunsch. It is a modified version of David's code, a few problems have been fixed for the BSD compilation environment, the location of the default boot file has been moved in order to get you started with just what you are reading now. Unfortunately David is no longer developing pcemu, so during the past years, a number of improvements have been added to the FreeBSD port. Thanks to Arne Henrik Juul who submitted a large patchset, among them fixes to make harddisk access work. The PostScript document David is mentioning under 3. below has been compressed and stored under /usr/local/lib/pcemu/doc/report.ps.gz. It is huge however, so if you don't care much for it you might wish to remove it later. Since i'm living in Germany with a German keyboard, i found the original X11 KeySym to PC scancode translation unacceptable. Several scancodes have been unreachable for me. Hence i decided to add another section to the .pcemurc file allowing to instruct pcemu of specific keyboard layout semantics. They consist of the keyword keymap, followed by the desired PC scancode, an equal sign, and the character that is generated for this key under X11 without any shift keys. (Note that no space is allowed on either side of the equal sign.) This way i won't get a German key mapping under DOS, but at least a valid keyboard layout where all the scan codes can actually be generated at all. The appropriate section of my .pcemurc file looks like: keymap 12=ß keymap 13=' keymap 21=z keymap 26=] keymap 27=+ keymap 39=\ keymap 40=[ keymap 41=^ keymap 43=# keymap 44=y keymap 53=- keymap 86=< Another recent addition to the .pcemurc file was the option to add floppy and hard disk defintions dynamically. (Previously, everything needed to be compiled into the emulator.) The syntax of those entries is: keyword filename sectors cylinders heads Examples: floppydisk /dev/rfd0 18 80 2 harddisk /dev/rad0 255 400 63 Drive letters are being assigned in ascending order, where drive A: is always reserved for the boot file. Write permission to the file in question is required by the time pcemu is being started (i. e. any floppy media need to be in the drive by that time). Be careful with letting DOS tools access your hard disks... Should you wish to contact me regarding this FreeBSD port, you can reach me as joerg_wunsch@uriah.heep.sax.de. 3. Here's David's original README file: PC Emulator for Unix and X Windows As the title suggests, this is a Unix/X windows program which is designed to emulate a standard 8086 based PC. In its current form it runs most text based programs. The programs I have tried and found to work are as follows: MSDOS 5.0 MSDOS 6.2 WordPerfect 5.1 Borland C++ 2.0 Turbo Debugger 2.51 Turbo Assembler 2.51 BBCBasic 4.61 MSDOS QBasic MSDOS GWBASIC Virtually all program that came with MSDOS 5 Hitchhiker's Guide to the Galaxy PC Magazine's ANSI.COM SemWare's QEdit 2.1 Norton Utils 4.50 Advanced Edition Norton Utils 6.0 Xtree Professional 1.1 PowerMeter Utils Autoroute (ancient version) Minitab 8.0 Microsoft Diagnostics This is all the programs I could lay my hands on which were text based and could run on an 8086 The emulator runs at about 8-10MHz 80286 speed on a Sun SparcStation 10/40 (without the -mviking flag) and at about 6MHz 8088 speed on a 33MHz 80486 box running Linux. I have included a Postscript representation of my project report. It's a bit out of date now, but it's the closest thing I've got to documentation! I'll do some kind of latex thing for the next release.... The program rather hogs the cpu but unmapping the window (iconifying it) will put it to sleep. The most recent version of this program will always be in ftp.cs.bris.ac.uk currently in the directory /users/hedley INSTALLING THE EMULATOR Edit the Makefile to change the OPTIONS, CFLAGS and XROOT to be appropriate for your system (I am assuming you are using GNU GCC, although any ANSI C compiler should work just as well). Ensure you are using the best (speed) optimisations possible (e.g. -O2 -fomit-frame-poiner) Edit the file mytypes.h and ensure that the types for INT8, UINT8, INT16, UINT16 etc are correct. Hopefully nothing need be changed in this file, but you never can tell... I have assumed that 'char's are 8 bit bytes, 'short's are 16 bit words and 'long's are 32 bit words. If your compiler treats these differently to the above then you will have to edit this header file. Type 'make' and go away and have a cup of tea! Compiling 'cpu.c' takes a while (and quite a bit of memory!). Get a floppy disk of the same size/type as you specified in the Makefile (i.e. if you chose -DBOOT720, then you'll need a 3.5" 720k disk). Install MSDOS on it. Copy the files 'config.sys', 'emufs.sys' and 'lredir.exe' from the 'programs' directory onto this floppy disk. Shove it in your Unix box and type cp /dev/fd0 DriveA This should create a 720k (or whatever) file which the emulator can boot from. If you do not have access to a Unix box with a floppy disk on it, then you can use the supplied 'dumpdisk' program to create a disk image. All you need is access to a PC. Simply put in a bootable MSDOS disk into the drive and type dumpdisk A (or dumpdisk B if in drive B). The program will copy the entire disk to a file called 'drivea'. You must then transfer it to your Unix box... You then need to convert the vga font (vga.bdf) into a font format your X server can understand (either SNF or PCF) using either 'bdftosnf' or 'bdftopcf' and install the resulting font file somewhere where your X server can find it. Then type 'mkfontdir' to rebuild the fonts.dir file and then type 'xset fp rehash' to tell your X server about the new font. If you type 'xlsfonts' you should see 'vga' as one of the fonts listed. If not, then something has gone wrong. I may or may not be able to help - it depends on your local setup. The emulator will run without the font as it uses the standard 8x16 X11 font - although most programs which use the extended character set will look pretty terrible. A warning will be displayed if the correct VGA font cannot be found. If you are using openwindows, you will have to type 'convertfont' and then 'bldfamily' You should now be in a position to run the emulator By default, the emulator requires the disk image called 'DriveA' to be in the current directory or else it will complain. If you don't like this, then you can change the file the emulator boots from by altering your .pcemurc file (see below) or by changing the default at compile time (by modifying the Makefile) Once run, the emulator should come up with the usual MSDOS banner and request the current date and time (which should already be correct). You can now run PC programs, mount Unix directories as drives etc. You will already have one drive redirection - drive C: is the Unix root directory. To mount further directories as drives, you must use the program 'lredir'. Consult the file 'lredir.readme' for instructions... The .pcemurc file At present this file allows a few things to be changed at run time. If this file is found (either in the current directory or in your home directory), then it is read and parsed and the values overwriting the equivalent compile time options. Currently the only options supported at present are: bootfile diskfile where diskfile is the disk image you want to boot from (no quotes or anything are needed and the filename must not contain white spaces). boottype type where type is either 360, 720, 144 or 12. This tells the emulator the type of disk the disk image file represents (360k, 720k, 1.44MB, 1.2MB respectively). updatespeed n where n is an integer > 0 This is the rate at which the screen memory gets checked for changes (and hence the update speed at which the screen gets updated for non-BIOS writes). n is measured in internal interrupt ticks of which there are ~72.8 per second (depends on the resolution of the system timer). cursorspeed n where n is an integer This specifies how fast the cursor should flash. Flashing the cursor can take a fair amount of bandwidth and so on slow/heavily loaded networks it may be best to slow down the cursor flashing. Setting n to 0 or less will disable cursor flashing - the cursor will be permanently on. An example .pcemurc file can be found in this directory. If you have problems compiling or running the emulator, then please contact me giving details of what went wrong (along with your computer type etc). Architectures tested: Computer OS Comments ----------------------------------------------------------------------------- PC 486/33 Linux 0.99.14w Runs quite well. A bit pointless though :) Sun 3/60 SunOS 4.1.x Takes an age to compile and not really worth the effort... SparcStation 10 SunOS 4.1.3 Runs well. Takes > 20MB RAM to compile though HP 755/99 HPUX Runs OK (>25MB RAM to compile...) Sun 4 Solaris 2.3 Runs OK RS6000 ??? Had a few problems getting it to compile. Getting there slowly though. SGI Indigo IRIX 4.?.? Doesn't work if compiled with optimisation using the standard compiler. Haven't tried it using gcc yet... As you can see this list is quite small. The main limiting factor is the range of machines I have access to. If anyone else can get it running on other architectures then please contact me! Warning: This program is not secure! Do not make is suid or sgid anything unless you wish to compromise the security of your system! EMULATOR LIMITATIONS etc Some parts of the PC architecture are emulated better than others. The BIOS has been partly implemented - enough to get MSDOS to boot and to allow most programs to run. Anyhow, most decent programs bypass the BIOS for screen access. BIOS Disk calls for drive A have been mostly emulated, although formatting doesn't work. Some of the hardware has been emulated but not much. Timer interrupts are generated by the system but there is now way (at present) to reprogram the timer. The Programmable Interrupt Controller has been emulated in part to respond to the End Of Interrupt command and reads from and writes to the mask register should work OK. None of the VGA hardware has been emulated at present (apart from screen updating) although this will change in the near future. Mode changes must therefore be done through the BIOS. The keyboard has been mostly emulated. The program converts X11 keysyms to raw PC scan codes and then generates an interrupt 9 as per usual. There is a BIOS routine which takes these scan codes and generates the correct BIOS ASCII/scan code pair. The keysyms used can be found in the module 'xstuff.c'. In the future these keysyms will be read in from a file at run time. THANKS Thanks go to the following: Andy Norman at HPLabs, Bristol (ange@hpl.hewlett-packard.co.uk) for the HP port. Dieter Becker (becker@med-in.uni-sb.de) for help with the Solaris port Klaas Esselink (esselin1@ksla.nl) for help with the RS6000 port Please report bugs/comments etc to me (hedley@cs.bris.ac.uk) and I'll do my best to sort them out (no guarantees though). After June 25th I will be leaving University and will not be able to check email very frequently - please be patient if you want a response - I will reply eventually. Have fun... David 4. And finally, the Copyright notice: All files, documentation etc with the exception of 'mfs.c', 'emufs.sys', 'emufs.S', 'lredir.exe', 'lredir.c' and 'lredir.readme' are Copyright (C) 1994 University of Bristol, England Permission is granted to use, copy, modify, and distribute this software and its documentation for any non-commercial purpose, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in the supporting documentation. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. --------------------------------------------------------------------- 'mfs.c', 'emufs.sys' and 'emufs.S' are covered by the following notice: Mach Operating System Copyright (c) 1993,1992,1991,1990 Carnegie Mellon University Copyright (c) 1991 IBM Corporation All Rights Reserved. Permission to use, copy, modify and distribute this software and its documentation is hereby granted, provided that both the copyright notice and this permission notice appear in all copies of the software, derivative works or modified versions, and any portions thereof, and that both notices appear in supporting documentation, and that the nema IBM not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. CARNEGIE MELLON AND IBM ALLOW FREE USE OF THIS SOFTWARE IN ITS "AS IS" CONDITION. CARNEGIE MELLON AND IBM DISCLAIM ANY LIABILITY OF ANY KIND FOR ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. Carnegie Mellon requests users of this software to return to Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU School of Computer Science Carnegie Mellon University Pittsburgh PA 15213-3890 any improvements or extensions that they make and grant Carnegie Mellon the rights to redistribute these changes. -------------------------------------------------------------------- 'lredir' was written by Tim Bird (Tim_R_Bird@Novell.COM)