$Id: README 513 2006-10-27 12:08:29Z brandt_h $

Copyright (c)1994-2002 Begemot Computer Associates. All rights reserved.
See the file COPYRIGHT for details of redistribution and use.

	p11-2.10
	-------

This is my pdp-11 emulator. It currently runs under the following platforms:

	- FreeBSD [45]
	- Spars-Solatis 2.[5678]
	- RedHat Linux
	- Slackware 7.1 Linux
	- MacOS-X 10.1

It may also run (and has previously) on:

	- BSD/OS
	- SunOS 4.1
	- OSF/1 Alpha

To compile it you need gcc 2.x and a non-bsd make (GNU-make will do it)
and the Begemot-library (available at the same place as the emulator).

This release has been tested with gcc version 2.95.3 and GNU make 3.79.1.

P11 currently emulates the following configuration:
	- a KDJ11A processor (including fpp)
	- one or more RL-controllers (RLV12) with up to 4 RL02 each
	- one or more RHV?? controllers with up to 8 RP06 each
	- an RK11-controller with 22-bit addressing (hey ever saw one?)
	- a MRV12 option (boot-rom/maintenance and display register)
	- one or more KL11A controllers with up to 4 serial lines each
	- a standard printer interface
	- a read only TM11 tape
	- a DEQNA ethernet adapter
	- a toy clock

On a 900MHz Athlon under FreeBSD 5.0 a 'make build; make installsrc' of
2.11BSD takes around 2:24 hours - this is several times faster than
a real KDJ11A (if /usr is mounted async,noaccesstime).
Floating point speed is in the order of 10 times the original.

P11 successfully runs RSX11M-PLUS, UN*X Version 5/6/7, 2.11BSD, RT-4 and XXDP.
No success so far with RSTS/E, but I'm an RSTS/E dummy.

Because I don't have any processor diagnostics there may be emulation bugs
left. Some of the decisions to emulate a specific command in a specific way
where made by writing a test program and run it on a real machine. This is
especially true for the fpp commands. (btw., the fpp documentation is _very_
bad. The documentation bugs once made in the very early versions are
simply copied up to the KDJ11A documentation). If you have processor diags and
could manage it to run them on p11, please let me know about the results.

1. Getting started
------------------

Get, build and install libbegemot-1.8 or higher.

Make sure you have at least 15 MBytes of free disk space (excluding disk
images). If you have a binary distribution read section 2 below. If you have
the source distribution unpack the tar file.

The source tree is organized as follows:

p11-2.10/		- emulator source
p11-2.10/Utils		- support programs
p11-2.10/IOProgs	- satellite programs for TTY and LP support
p11-2.10/Misc		- real misc, look there
p11-2.10/Tests		- sources for various test programs
p11-2.10/libutil	- utility library, used by other programs
p11-2.10/Boot		- boot PROM sources and binary


2. Compilation
--------------

Well this is easy:

	./configure [--with-begemot=DIR] [--with-as11=PATH_TO_AS11]

other options are available. You should specify --with-float=qlib on
sparcs if you need correct behaviour of the MODF instruction for big
integers.

	gmake
	gmake install # if everything wents ok.

In order to use the QNA adapter you need either bpf (Berkley Packet
Filter), an IP tunnel driver or an Ethernet tunnel driver.  Bpf let's
you share the real ethernet interface between the host and the
emulator, but puts you interface in promiscous mode (unless you have a
spare ethernet adaptor in your machine). Under FreeBSD and Linux the
tunnel driver is part of the kernel source. The tunnel driver for 
Solaris is available at http://vtun.sourceforge.net/tun, but be warned, that
it happens to crash quit often (at least Version 1.1).

Configuring the tunnel driver is done on the host (after starting the
emulator):

	ifconfig tun0 [plumb] <host-ip> <emulator-ip> up

The 'plumb' keyword is used on Solaris. This can be done directly from the
p11 configuration file.

The tap driver (or ethernet tunnel) is configured via:

	ifconfig tap0 <host-ip> up

I recommend using the tap driver under FreeBSD and Linux, because this
driver supports ARP. If you use the tun driver you must issue a arp
command after booting 2.11BSD:

arp -s <host-ip> <host-ethernet>

where host-ethernet is the ethernet you have given to epp_tun in the
configuration file (the second of these).

3. Running
----------

It is possible to run p11 not installed with:

	./p11 -Siodir=IOProgs

To tailor p11 to your environment make a local copy of PREFIX/share/p11/p11conf
and edit it to mount the right disk images. (You can also change the default
one, but the next install will clobber it).

The subdirectory test contains a lot of test programs which can be
started with:

	p11 prog.11
	@0g

In order to use the QNA interface you will need a ROM image of the onboard
ROM. If you don't have one, create just a file with at least 4k bytes and
use that. In this case you can't run the good citizenship test and can't
use MOPR/MOPDL to boot over the QNA (do you really want to do this? :-).

Don't forget to start a 'telnet localhost 10000' (if you didn't change the
default configuration) to see actual console output.

The emulator can use the disk images provided for Bob Supnik's
emulator (but read the licenses careful). Tape images cannot be used
directly. The Utils subdirectory contains the mktape program, that can
be used to build tape images from files.

Enjoy.


4. Wishes
---------

This is a unsorted list that comes into mind at the time of this writing.

1. It would be nice to have processor/controller/device/... diagnostics

2. wouldn't it be nice to have rx01/02 emulated?

3. a tap driver for Solaris.


5. License restrictions
-----------------------

Please look at the file COPYRIGHT or feel free to contact me if you have any
questions regarding reusage of the source.

6. Acknowledgements
-------------------

I would like to thank Bob Supnik for giving me insight into the internals
of the KDJ11A and Steven M. Schultz for a number of bug fixes. Thanks to Robin Birch and Eric Moret for bug-fixes and suggestions.

7. Known problems
-----------------

- gcc-3.1 on i386 generates bad code for MTPI/MTPD when compiling with global
  registers (the compiler does not spot, that F26() changes the global register
  containings src). Use configure --disable-regs in this case.

8. How to contact me
---------------------

Please send suggestions, bugs, bug-fixes, code, OS-sources, flying saucers to:

	'harti@freebsd.org'


harti brandt
