Instructions for using PC-Choices

(Version 0.5, SIMTEL20 distribution, 11 Mar 92)

This document explains how to install and run PC-Choices.  If you
encounter any problems, please contact Lup at lup@cs.uiuc.edu.

What is PC-Choices

    PC-Choices is a version of Choices for 386/486 PCs.  Choices is a
    portable object-oriented operating system developed by the University
    of Illinois' Systems Research Group, headed by Prof. Roy Campbell.
    The PC-Choices kernel runs in 32-bit protected mode and calls
    DOS/BIOS in 16-bit virtual-8086 mode for input/output operations.
    Because it uses DOS/BIOS instead of working with I/O hardware
    directly, PC-Choices will run on many PCs.  PC-Choices is written
    mainly in C++ and the source code is available free-of-charge to
    people who sign the educational/research license.  PC-Choices contains
    no proprietary code.

System requirements

    A 386/486 PC running DOS version 3.0 or higher; EGA or VGA display;
    at least 3 Meg extended memory.  PC-Choices does not swap out memory
    so it may not run properly without lots of extended memory (say 5 Meg).
    3 Meg of disk space is required for storing the Choices kernel and
    application files.

What does it do

    PC-Choices runs 32-bit Choices applications and supports multitasking.
    The PC-Choices package has a command shell, some file utilities,
    a kernel browsing tool, a kernel visualization monitor and some
    simple applications.  Users can compile PC-Choices applications
    with DJGPP, the DOS port of g++.  Applications are written using
    the Choices object-oriented application programming interface.

Who should use PC-Choices

    People interested in object-oriented operating systems; people
    who want to build 32-bit applications and run them in a multitasking
    PC environment; people who want to learn how protected-mode PC
    operating systems can be implemented in C++.  PC-Choices is
    currently available for beta-testing.  PC-Choices has been tested
    on the IBM PS/2 Model 80, IBM PS/2 Model L40SX, IBM PS/55 Note,
    ALR Business VEISA 486-33, AT&T 6386WGS and other 386 PCs, with
    DOS 3.3, 4.0 and 5.0.

_____________________________________________________________________________
PC-Choices Incompatibilities

(1) All extended memory must be usable by PC-Choices.  PC-Choices will
    not work if there are programs or data in extended memory.  Some
    DOSs make use of extended memory and are therefore incompatible
    with PC-Choices.  Change your system configuration before running
    PC-Choices so that nothing is loaded into extended memory.
    Here are some tips for DOS 5.0 users: don't use "DOS=HIGH",
    DEVICEHIGH, HIMEM.SYS or SMARTDRV.SYS in your CONFIG.SYS and
    AUTOEXEC.BAT files.

(2) The machine should not be in virtual-8086 mode when starting
    PC-Choices.  Some memory managers such as EMM386.SYS put the
    machine into virtual-8086 mode while running.  Remove these
    memory managers from your system configuration.

(3) PC-Choices assumes that there is 640K of base memory, and uses
    300K of low memory by default.  The amount of memory to be used
    may be adjusted by changing the configuration file pcc/bin/config.

(4) PC-Choices always uses the first text-mode display page for console
    output.
    
Warning: It is possible that PC-Choices will damage the data on your
         diskette or hard disk (although this has never happened
	 before).  Make sure you have backups of your disks before
	 running PC-Choices.

_____________________________________________________________________________
Setting up PC-Choices

    Copy pcc.zip to the PC, say to the root directory on the C drive (c:\).
    You should have an UNZIP utility that unpacks ZIP archives.  (Contact
    lup@cs.uiuc.edu if you don't.)  Unpack pcc.zip with your UNZIP utility
    like this:

        unzip -d pcc.zip

    (Note: Some old versions of PKUNZIP are buggy and will complain about
    about CRC errors when there are really none.  Use the newest version of
    PKUNZIP or use Info-ZIP's UNZIP instead.)

    The directories pcc, pcc\bin and pcc\cbin and their files will be
    unpacked in the current directory.  Delete pcc.zip.  (If a previous
    version of PC-Choices is already installed on your machine, UNZIP
    will ask you whether it should overwrite the files; just say "yes".)

    We now have to edit pcc\bin\profile to tell the command shell
    (Chocs) where to look for the Choices application binaries.  Edit
    pcc\bin\profile and you will see this:

        PATH=d:/pcc/cbin

    Change it so that it references the correct directory.  For example,
    if you unpacked the PC-Choices package in c:\, you should change
    the line above to:

        PATH=c:/pcc/cbin

    If your PC is an IBM PS/2, PS/55 or something similar, edit
    c:\pcc\bin\config, change "PS2Keyboard = no" to "PS2Keyboard = yes",
    and change "PS2Timer = no" to "PS2Timer = yes".
	    
    PC-Choices is now ready to be used.

_____________________________________________________________________________
Booting PC-Choices

    Go to the pcc\bin directory and type "pcc".  After a while, you
    should see

	Choices Command Shell (Chocs 0.0)
	For help contact lup@cs.uiuc.edu

	Choices>

    If the system does not respond to any keypresses, you cannot continue
    using PC-Choices.  You should reboot the PC, change the system
    configuration and boot PC-Choices again.  Look at pcc\bin\config to
    find out what parameters you can set in order to make PC-Choices
    run on your system.

    If you still have difficulty running PC-Choices, please contact
    me as soon as possible - I'm very eager to fix all compatibility
    problems.

_____________________________________________________________________________
Running Applications

    The "Choices>" prompt indicates that you're in the Choices command
    shell, which allows you to run applications.  For more information
    about the shell, enter "help".  Here is an incomplete list of
    applications that are available (see pcc\cbin\readme for the complete
    list):

    ls      - List the contents of the current directory.
    cd      - Change current directory.  Without arguments, it prints the
    	      name of the current directory.
    hello   - Prints a message.  Can be used with an argument.
    flash   - Flash the screen 5 times.
    count   - Display digits 9 to 0 in large print.
    worms   - Draw a worm on the screen.
    logo    - Displays the PC-Choices logo.
    kindred - "kindred X" shows all living objects in the kernel that belong to
              class X and its subclasses.  (Try "kindred Process",
	      "kindred MemoryObject" and "kindred Domain".)
    dos     - Start a DOS shell as a PC-Choices process.

    To execute an application, just enter its name and arguments at the
    shell prompt; the shell works like the Bourne shell.  To execute an
    application in the background, type the application name and arguments,
    and type '&' at the end of the line before pressing Return.

    If you see the message "Store::alloc() out of memory" while
    multitasking, it means that the PC does not have enough memory to run
    multiple programs at the same time.  You can still use PC-Choices by
    running a single program at a time.

    To shut down PC-Choices, enter "exit" at the shell prompt and the machine
    will return to DOS.
    
_____________________________________________________________________________
Kernel Visualization Monitor

    PC-Choices can visualize its kernel state.  Enter "monitor".
    You should see 10 stripes (called "sliders") at the bottom on the
    screen.  A slider moves when the labelled event happens.  The
    sliders keep track of these events:

        DOS:            Calls to DOS functions (INT 0x21).
	Disk BIOS:      Calls to BIOS disk functions (INT 0x13).
    	Keyboard BIOS:  Calls to BIOS keyboard functions (INT 0x16).
	Interrupt:      Hardware interrupt passed to BIOS.
	Context Switch: Switching the contexts of processes.
	CPU Idle:       CPU is currently idle.
    	Process N:      Application process N is currently running.

    Try running various applications in the foreground and background
    and see how the sliders behave.  To turn off the sliders, enter
    "monitor" again.

_____________________________________________________________________________
Questionnaire

    The PC-Choices project team would like to obtain your comments
    in order to make PC-Choices more useful for you.  Please answer
    the following questions (all answers are optional):

    Please write down your occupation and describe your interests.

    A--->

    Would you like to use PC-Choices in your work?  As a hobby?
    How would you use it?

    B--->

    What new applications would you like us to develop?

    C--->

    If you could use the PC-Choices application compilation
    environment, what applications would you write?

    D--->

    Do you want the source code for the PC-Choices kernel?  Do you
    want the ability to customize the kernel by recompiling the
    kernel yourself?

    E--->

    How do you feel about the performance of PC-Choices?  Is disk
    I/O too slow for ordinary use?

    F--->

    Have you heard of the Choices project before?  How much do you
    know about it?

    G--->

    Other comments:

    H--->

    Please return the questionnaire to lup@cs.uiuc.edu.  Thank you.

_____________________________________________________________________________
Overview of Choices

    Choices, the object-oriented operating system, is well-documented;
    many papers have been written about it.  It is an operating system
    composed of C++ objects.  When Choices is running, numerous
    objects work together in the system in order to provide operating
    system services.  Examples of Choices objects are Processes, Domains,
    MemoryObjects, CPUs, Semaphores and NameServers.  A Domain is a virtual
    memory space in which Processes run, and MemoryObjects represent data
    regions in the Domain that are accessible to Processes.  In Choices,
    C++ classes are also objects, so that programs may ask an object to
    return its class, and given a class, find out all the superclasses
    and subclasses of the class.  Programs may also find out all instances
    of the class.

    Many modern operating systems operating-systems are object-based,
    but only Choices is a real object-oriented operating system, because
    it uses class hierarchies.  For example, SystemProcess is a subclass
    of Process.  ApplicationProcess is also a subclass of Process.  A
    SystemProcess is a special kind of Process that executes in supervisor
    mode and is non-preemptable.  An ApplicationProcess is a special
    kind of Process that executes in user mode, and is preemptable.
    Both SystemProcess and ApplicationProcess inherit methods from Process,
    but because they have different characteristics, the two subclasses
    define certain methods differently.  MemoryObject is subclassed
    to represent various types of data stores such as physical memory
    ranges, files and disks.

    Subclassing is also used to make the operating system as modular
    as possible, and to encapsulate machine-dependent characteristics
    in separate subclasses.  For example, CPU has subclasses i386CPU,
    NS32332CPU, MC68030CPU and SPARCCPU, all of which define their
    methods differently to handle CPU-specific operations like
    context-switching and exception-handling.

    Choices application programs are written in C++ in an object-
    oriented manner too.  System calls in Unix and most other operating
    systems are flat function calls.  System calls in Choices are object-
    oriented - the kernel gives an application program pointers to kernel
    objects and the program may invoke methods on these kernel objects to
    perform system functions.  In the object-oriented interface,
    applications may create kernel objects such as Processes, Semaphores,
    Domains and MemoryObjects.  Kernel objects are not literally handed
    to the application program; Choices contains a secure kernel
    interface whereby "proxies" representing kernel objects are actually
    handed to the application program, and calling any method on that
    proxy will cause a trap into the kernel, and after checking the method
    arguments, the method call will be forwarded to the appropriate kernel
    object.

    Choices has been ported to the multiprocessor Encore Multimax,
    AT&T 6386WGS, IBM PS/2, Apple Macintosh IIx, SPARCstation I & II,
    and we are currently porting it to the Intel Hypercube iPSC/2 and
    Silicon Graphics workstations.  The Multimax port of Choices currently
    has the most number of Choices applications.  Many Unix applications
    have been ported to Multimax Choices: g++, gas, bash, GNU file
    utilities and GNU Smalltalk.  Multimax Choices runs TCP/IP and
    provides Telnet and FTP services.

    PC-Choices is a new port of Choices to 386-based PCs running DOS.
    This is an interesting project because this is the first time
    that a minimal Choices kernel has been isolated.  The PC-Choices
    kernel is only concerned with process management, virtual memory
    and interrupt handling.  All other services are provided by DOS
    and BIOS, which run as user processes.  Application libraries are
    provided to map the DOS and BIOS interface into an object-oriented
    interface so that Choices applications built for other ports
    of Choices will run easily under PC-Choices.  Applications may call
    DOS and BIOS routines through a special object-based interface, and
    through this interface, applications may also spawn off DOS processes.

    PC-Choices was compiled on a SPARCstation with a g++ cross-compiler
    for fast compilation.  The PC-Choices application libraries and
    system interface header files have been ported to DOS, and PC-Choices
    applications may be produced by simply compiling them with DOS g++
    (DJGPP) and linking the object files with the PC-Choices libraries.

    There is currently a small group of Choices researchers.  These people
    are involved in many diverse research projects, such as distributed
    virtual memory, message-passing, transaction processing, networked
    filesystems, networking protocols, Unix compatibility, performance
    visualization and object-oriented graphical interfaces.
    
_____________________________________________________________________________
Conclusion

    If PC-Choices ran on your PC without major problems, you might want
    to try out the PC-Choices application development package,
    which lets you compile PC-Choices applications under DOS.  DOS g++
    (DJGPP) is required for compiling the applications.  Contact
    lup@cs.uiuc.edu for information on obtaining the application
    development package.

    Thank you for using PC-Choices.

Lup
lup@cs.uiuc.edu    Graduate Student    PC-Choices Manager
