PLEX86 --- an x86 virtual machine
=================================

Welcome to plex86, the open-source x86 virtual machine.  This document
will get you started with running/testing plex86.  For more detailed
information, please consult the docs/ tree.

plex86 is distributed under the Lesser General Public License (LGPL).
Please check out the file COPYING in this directory for more details.

A list of all code contributors to plex86 can be found in the file
CONTRIBUTORS in this directory.  You can find all changes in each release
in the ChangeLog file.


,-----------------------------------------------------------------.
| IMPORTANT NOTICE                                                |
|-----------------------------------------------------------------|
| This code is EXTREMELY EXPERIMENTAL, and may well result in a   |
| SYSTEM CRASH, and who knows what other ill effects.  RUN THIS   |
| SOFTWARE AT YOUR OWN RISK.  As a precaution, do not attempt to  |
| run this software on a system with important data on it, and    |
| make liberal use of the sync command!  Expect to have to use    |
| the power button.                                               |
`-----------------------------------------------------------------'


The plex86 directory tree is structured as follows:

plex86                            root directory for plex86
    |
    |--- kernel                   contains the sources for the
    |      |                      plex86 kernel driver
    |      |
    |      `--- include           contains header files for the
    |                             plex86 kernel driver
    |
    |--- user                     contains the sources for the
    |      |                      user-level VM monitor
    |      |
    |      `--- plugins           contains the sources for the plugins
    |             |
    |             |--- bios       BIOS plugin; loads executable and init VGA
    |             |--- ice        ICE plugin; for using remote GDB
    |             `--- bochs      BOCHS plugin; contains emulated
    |                             hardware devices, and GUI code
    |
    |--- guest                    contains several simple kernels for
    |      |                      testing VM functionality as it is added
    |      |
    |      |--- virtcode          simple non-multitasking kernel (shell)
    |      |--- cooperative       simple cooperative multitasking kernel
    |      |--- preemptive        simple preemptive multitasking kernel
    |      |--- paging            same as preemptive, but with paging
    |      `--- test              small testkernel for scan-before-execute
    |
    |
    |--- bios                     system ROM BIOS
    |
    |--- misc                     contains miscellaneous files
    |      
    |
    `--- docs                     contains plex86 documentation
           |
           |--- sgml              documentation sources in SGML format
           |--- html              documentation sources in HTML format
           |--- txt               documentation sources in plain text
           `--- output            the compiled versions of the docs

Things have been kept modularized regarding the host OS.
Anything OS specific should be put in "kernel/host-xyz.c"
or "kernel/include/host-xyz.h".


====================================================================
Directions for installation:

   1.  Enter the plex86 root directory and type ./configure.
       The configure script will attempt to guess the settings
       for your system, such as host OS, location of libraries
       etc.

           user> cd plex86
           user> ./configure

   2.  When configure has completed, type make.  The whole tree
       will now be compiled.

           user> make

   3.  Load the kernel module into the system. This will also create the
       device node /dev/plex86.  Plex86 needs this device in order that the
       user-level VM monitor can communicate with the kernel driver.
       You will need to be root:

           user> su
           root> ./misc/load_module.sh
           root> exit

       You need to have the kernel module installed in order to
       use plex86.

   4.  You should use a configuration file to define many parameters
       relating to the desired VM environment and peripheral components
       setup.  There are sample ones in the conf/ directory.

   5.  If you do not have the VGA font installed, you will need
       to install it first (you can check this by skipping to
       step 6, and checking whether running the VM gives an error
       message).  You will only have to do this once.  The VGA font
       resides in misc/vga.pcf.  In order to install it, you'll need
       to be root.  Put it in the X fonts 'misc' directory and do
       what is necessary on your system to rebuild that font
       directory and let your system know about the update.

       For example, on Mandrake 7.1:
           user> su
           root> cp misc/vga.pcf /usr/X11R6/lib/X11/fonts/misc
           root> gzip            /usr/X11R6/lib/X11/fonts/misc/vga.pcf
           root> chmod ugo+r     /usr/X11R6/lib/X11/fonts/misc/vga.pcf.gz
           root> mkfontdir       /usr/X11R6/lib/X11/fonts/misc
           root> killall -HUP xfs   # notify font server of the change
           root> xset fp rehash
           root> exit

   6.  You can now start up the VM by invoking the user program:

           user> cd user
           user> ./plex86 -f ../conf/SOME-CONFIG-FILE-HERE

   7.  Whenever you recompile the kernel stuff, or want to get
       rid of the kernel module, remove the old kernel module first.
       As root:

           root> <...>/plex86/misc/unload_module.sh


====================================================================
Directions for compiling a BIOS (Optional)


  By default, there should be a precompiled BIOS in the 'bios'
  directory named 'BIOS-plex86-*'.  You only need to grab some
  extra tools if you want to compile/develop a new BIOS.  If so,
  here is what you should do:

  - You need 'bcc'.  I grabbed this from the Elks project, which
    seems to be rooted at http://www.elks.ecs.soton.ac.uk/.
    I Downloaded http://www.cix.co.uk/~mayday/Dev86src-0.15.1.tar.gz,
    which was labeled 'version 0.15.1 (710k)'.

      user-> tar xvfz Dev86src-0.15.1.tar.gz
      user-> cd linux-86
      user-> make bcc
      user-> strip bcc/bcc-cc1
      user-> cp bcc/bcc-cc1 ~/bin  # you can put it anywhere you want

    You can delelte the tarball and the linux-86 directory now
    if you want.  Only needed the 'bcc-cc1' phase of the compiler.

  - You need 'as86', and 'ld86'.  On my Mandrake 7.1 system, these
    files where provided by the 'bin86-*' RPM package, and
    were pre-installed for me given my package selections.  You
    may have them already on your distro.  If not, download
    and install packages for your system.


====================================================================
Special notes for using curses (text-mode VGA only) as a GUI.
If you use this in a terminal (like non-X based) which doesn't
load the VGA font, expect special characters to be displayed
as gargage.

1) Configure with curses:

  ./configure --with-gui=curses

2) Use an 80x24 terminal screen.  Use the VGA font if possible,
   otherwise some characters will be garbage.

  xterm -geometry 80x25 -fn vga

3) Send stderr to /dev/null.  In bash:

  ./plex86 -f ../conf/foo 2>/dev/null


====================================================================
Let us know whether plex86 works for you !!!  The address of the
plex86 mailing list is plex86@fastxs.net.  Have a look at the
webpage http://www.plex86.org/ for details.
