May-01-2002

This document comes in two parts.  The first part is for the impatient.
It simply gives a quick overview of how to get going.  The second part
is a methodical exposition on the various menu commands available in
Solace.

-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

*) Getting started

So you've downloaded Solace and have gotten this far.  Now what?

When you fire up Solace, you will be greeted with a black screen
with the SOLOS prompt in the upper left, like this:

      >

You can type in any SOLOS command, but be forwarned that some
of the I/O commands, such as SET I or SET O to redirect to/from
the serial or parallel ports, isn't yet emulated.

What you probably want to do is load a game or BASIC and run
that.  Go to the "File" menu item, select "Load Program...",
then pick, say, "targ.ent".  After loading the program, for
about four seconds you will see "program load address is $0000"
appear on the statusbar.

Then type "EX 0" (that is, execute the program starting at
address hex 0000).  When tired of that program, select from
the Processor menu the "Warm reset", then load another program.

Feel free to play with the menu options to change the display
color, or try running TARG with a 15 MHz 8080!

For a more authentic experience, select the menu "File/Tape 1"
item.  From the File menu item on the tape control panel, load
a .SVT (Sol Virtual Tape).  Press PLAY on the control panel,
then type "CAT" from SOLOS.  Note the programs that are listed
on the tape.  Press the REWind button on the tape control panel
to rewind the tape.  Noting a program that you want to load,
type "XE <filename>".  Note that BASIC programs can't be loaded
from SOLOS.  First you must execute the proper version of BASIC,
and then "GET" the file from within BASIC.

If you want a more luxurious experience, from the main menu, pick
"Options/Northstar Disk" and select
    "Northstar Disk Controller is Present"
Make sure the base address is set to 0xE800.  Click on the leftmost
disk icon on the titlebar of the main window.  Using the file
browser, find "cpm_util.svn" and open it.  From the SOLOS command
line, type the command "EX E800".  You should then get a CP/M prompt.
Type "DIR" to see what is on the disk.


*) Quick SOLOS Command Overview

    For a better understanding of SOLOS, read the online manual:

        http://www.thebattles.net/sol20/manuals/solos.pdf

    but here is a *very* terse summary, taken directly from the
    SOLOS source listing:

;COMMANDS:
;       TE                      TERMINAL MODE
;       DU SSSS EEEE            DUMP (START ADDR   END ADDR)
;       EN SSSS                 ENTER HEX TO MEMORY
;       EX SSSS                 EXECUTE
;       GE FILENAME/U           GET (U=TAPE UNIT 0 OR 1, DFLT=1)
;       SA FNAME/U SSSS EEEE    SAVE ON TAPE (UNIT 0 OR 1)
;       XE FILENAME/U           AUTO LOAD/EXECUTE
;       CA                      CATALOG OF TAPE FILES
;       CU LL SSSS              CUSTOM COMMAND (LL=LABLE)
;       SET TA N                SET TAPE SPEED (N:0=FAST,1=SLOW)
;       SET S=NN                SET DISPLAY SPEED (O-->FF)
;       SET I=N                 SET IN PSEUDO PORT (N=0 - 3)
;       SET O=N                 SET OUT PSEUDO PORT (N=0 - 3)
;       SET N=NN                SET NULLS (N=0 - FF)
;       SET CI SSSS             SET CUSTOM INPUT DRIVER ADDR
;       SET CO SSSS             SET CUSTOM OUTPUT DRIVER ADDR
;       SET XE SSSS             SET AUTO-EXECUTE ADDRESS FOR TAPE SAVE
;       SET TY NN               SET FILE TYPE FOR TAPE HEADER
;       SET CR NN               OVERRIDE CRC ERRORS (FF=IGNORE ERRORS)
;
;
;       PSEUDO PORTS:   0 = KEYBOARD/VIDEO
;                       1 = SERIAL PORT
;                       2 = PARALLEL PORT
;                       3 = USER DEFINED (SET CI, SET CO)


Or, how about this summary from the SOLOS manual:

    COMMAND                FUNCTION

                          Console

    EXEC addr               Begin program execution at 'addr'
    ENTR addr               Enter data into memory starting at 'addr'
    DUMP addr1 (addr2)      Dump memory data, 'addr1' to 'addr2'
    TERM (portin (portout)) Enter Terminal Mode
    CUST name (addr)        Insert or remove a custom command

                            Tape

    GET (name(/unit) (addr))              Get a tape file into memory
    SAVE name (/unit) addrl addr2 (addr3) Save a file from memory to tape
    XEQ (name(/unit) (addr))              Get then execute a tape file
    CAT (/unit)                           Catalog tape files

                            Set

    SET S=data          Screen character rate
    SET I=port          Input port to SOLOS
    SET O=port          Output port to SOLOS
    SET N=data          Number of NULLS following CRLF
    SET XEQ addr        Auto-execute addr
    SET TAPE 0 or 1     0=1200 baud, 1=300 baud
    SET TYPE data       Type 'byte' header
    SET COUT addr       Custom output addr
    SET CIN addr        Custom input addr
    SET CRC data        Allows ignoring of tape CRC Read Errors

Note that only the first two characters of any command are significant.

-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

*) Menus

   Currently, there are six active top-level menus in Solace, most with
   their own submenus.

       FILE
           Load Program...
           Load ROM...
           Disk Factory...
           Run Script...
           Snapshot
           Exit

       PROCESSOR
           Reset
           Power cycle

       Windows
           Tape 1
           Tape 2
           Debugger
           Options

       Options
           Dipswitch 1
           Dipswitch 2
           Dipswitch 3
           Dipswitch 4
           8080 Speed
           Display
           Tape Players
           Northstar Disk
           Character Set
           Audio
           Save Options

       HELP
           About...
           Key Mapping...
           Options...
           Debugger...
           Virtual tapes...
           N* Disk system...
           CP/M...


   The various menu items are described in more detail below.

       FILE, Load Program...

           A real Sol computer has to load its programs from somewhere --
           cassette tape or disk drive typically.  Because those aren't
           emulated, and the cassette interface is slow and somewhat
           unreliable, this function allows you to read a file in a
           special format off the PC and update the memory image on the
           simulated Sol, as if you had a 1Mb/s cassette tape, but better.

           Selecting this menu item will present you with a standard
           "Open File" dialog box.  By default the screen displays only
           files that end in ".ent" or ".hex".  By convention, ".ent"
           files are in a format unique to the Sol and this emulator.
           This format is described later.  ".hex" files are standard
           Intel hex format files.

           Finally, when a memory image is loaded this way, Solace looks
           for a file of the same base name in the same directory
           but with a suffix of ".prn", which is the suffix that
           the CP/M utilties ASM and MAC use for listing the output
           of a file assembly.  Solace uses this as a source code
           overlay so that should the user need to use the debugger,
           the disassembled output will have labels and comments.

       FILE, Load ROM...

           This menu item lets something other than the default SOLOS
           personality module ROM to be used by the emulator.
           The format of the ROM is a .ent (enter) or .hex (intel hex)
           file, but with a suffix of .rom to distinguish this type of
           file from general programs.

           The Sol computer has a little daughtercard, called the
           Personality Module.  It is up to 2 KB of ROM or EPROM,
           and contains the boot program.  It resides in the address
           space of $C000 to $C7FF on the CPU.

           The typical stock Sol has the SOLOS monitor; that is what
           this emulator uses too.  Processor Technology made a few
           others, but Solos is probably the one you want.  Solace
           "ships" with a few images in the ROMs directory.  Use
           "solos.rom" if you aren't running CP/M, and "solos_cpm.rom"
           if you are.  The latter fixes an annoyance due to the
           original SOLOS implementation.

           To find out about other pesonality modules, go to:
               http://www.thebattles.net/sol20/sol_pm.html

           Like loading a .ENT or .HEX file, Solace looks for a
           file named <basename>.PRN so that source code listings
           can be supplied in the debugger disassembly window.

       FILE, Disk Factory...

           Starting with Solace 3.0, the emulator supports the
           emulation of a Northstar disk controller.  This menu
           item brings up a dialog to allow you to create new
           virtual floppy disks, inspect properties of a virtual
           disk, edit the label on virtual disks, or modify the
           write protect tab on virtual disks.

           You can find more information about this by selecting
           "Help/Northstar Disk" from the main menu of Solace.

       FILE, Run Script...

           This menu item lets the user specify a file that contains
           a series of commands.  After that, whenver a program attempts
           to read the keyboard for a character, it instead is supplied
           by the next character in the supplied file.  At some point,
           when all the characters of the file have been read, the
           script will end and normal keyboard emulation resumes.

           If, during a script, the user wants to abort the script,
           just hit the ESC key.

           A script can include the contents of another script, and so
           on, up to three scripts deep.  From within a script, a new
           file is invoked by having a line in the following format,
           with no leading spaces:

                \<include anotherfile.name>

           In order to allow entering non-ASCII characters from a
           script, such as the MODE key, Solace recognizes a few
           escape sequences, as given in the following table showing
           the escape sequence and the value seen by the emulated CPU:

                \<LF>     (0x0A)
                \<CR>     (0x0D)
                \<DEL>    (0x7F)
                \<MODE>   (0x80)
                \<LEFT>   (0x81)
                \<CLEAR>  (0x8B)
                \<LOAD>   (0x8C)
                \<HOME>   (0x8E)
                \<RIGHT>  (0x93)
                \<UP>     (0x97)
                \<DOWN>   (0x9A)

           Finally, a specific keycode can be specifed in hex.  Eg:
                \3D       (=)
                \5C       (\)
                \7F       (DEL)

       FILE, Snapshot

           Selecting this menu item causes the emulator to dump
           a .BMP image to the current directory.  Each time the
           snapshot function is used, a sequential file name is
           generated, starting with "snap0000.bmp".  These can be
           converted to other file formats with external programs.

       FILE, Exit

           What don't you get?


       PROCESSOR, Reset

           Reset is identical to the ALLCAPS-REPT key combination
           of the Sol.  It resets the CPU to start running back
           at $C000 (the personality module entry address) but it
           doesn't affect the memory image.  Many Sol programs
           could be reset and run again this way without needing
           to reload the program.

       PROCESSOR, Power cycle

           Selecting power cycle restarts the emulator, including
           loading the personality module ROM and initializing the
           simulated memory image to $76 (the 8080 HLT instruction).
           This doesn't correspond to any reset on the Sol, but is
           in the emulator for completeness.


       WINDOWS, Tape 1...
       WINDOWS, Tape 2...

           These two allow opening or closing the two windows that
           represent two virtual cassette tape players.  These windows
           can also be opened and closed by clicking on the tape icons on
           the toolbar.  For more detailed information on the Sol virtual
           tape feature, read the help file in html/solace_tape.html.

       WINDOWS, Debugger...

           This menu item opens and closes the 8080 debugger built
           into Solace.  The debugger can also be opened and closed
           by hitting the <F5> function key, or by clicking on the
           debugger icon on the toolbar.  For more detailed information
           on the debugger, read the help file in html/solace_dbg.html.

       WINDOWS, Options...

           This menu item opens and closes the window used to control
           Solace options settings.  The options window can also be
           opened and closed by clicking on the properties icon on the
           toolbar.


       OPTIONS, Dipswitch 1
       OPTIONS, Dipswitch 2
       OPTIONS, Dipswitch 3
       OPTIONS, Dipswitch 4
       OPTIONS, 8080 Speed
       OPTIONS, Display
       OPTIONS, Tape Players
       OPTIONS, Northstar Disk
       OPTIONS, Character Set
       OPTIONS, Audio

           Selecting one of these menu items pulls up the Options
           window, with the specified property sheet preselected.
           Note that all changes selected via the options dialog are
           applied immediately to the emulator.  For more detailed
           information on the Options that can be manipulated, read
           the help file in html/solace_options.html.

       OPTIONS, Save Options

           All changes made to Solace via the Options dialog take
           immediate effect, but all such changes aren't saved between
           sessions.  Selecting this option causes Solace to create
           the file "solace.ini" in the current directory.  This file
           is subsequently read the next time Solace starts up so that
           preferences from the previous session can automatically be
           restored.  There is no registry diddling.


       HELP, About...
       HELP, Key Mapping...

           About gives a few credits and the version information,
           while the Key Mapping dialog box gives some reminders about
           what some of the function keys have been mapped to do.

       HELP, Options...
       HELP, Debugger...
       HELP, Virtual tapes...
       HELP, N* Disk system...
       HELP, CP/M...

           These bring up local HTML docs to better explain how to
           use these features of Solace.


*) Keyboard Mapping

    Most of the keys on the Sol have a directly corresponding key
    on the PC keyboard.  Such keys have their keycodes translated
    from the PC value to the Sol value.

    The Sol has a few keys that the PC keyboard doesn't.  These have
    been mapped to function keys on the PC keyboard, as follows:

        <F1> is the REPT key
        <F2> is the MODE key
        <F3> is the CLEAR key
        <F4> is the LOAD key

        <F5> invokes the debugger
        <F6> causes the emulator to single step the 8080 program,
             stepping "over" CALL and RST instructions.
        <F7> causes the emulator to single step the 8080 program,
             stepping "into" call and RST instructions.

    Note the typematic behavior of the Sol keyboard has been emulated.
    That is, holding down a key for a length of time does not produce
    a series of keystrokes, just one.  To automatically repeat a key,
    hold down the REPT key (the <F1> on the PC) and then hold down the
    key you want repeated.  Stupid, huh?  Just like the Sol does it.

    To reset the Sol computer, you could hold down the ALL CAPS key
    and the REPT key at the same time.  On the PC, hold CAPS LOCK
    and <F1> at the same time to reboot the virtual Sol.

    Remember to have the NUMLOCK key set on the numeric keypad to
    get behavior largely like that of the Sol.


*) Display

    The Sol's is capable of displaying only text displays, not bit-
    mapped graphics.  Solace supplies a choice between two similar
    character generators, whose fonts are taken bit-for-bit from
    the Sol.

    Unfortunately, the display isn't exactly the same.  The Sol
    produced video timing suitable for a standard television,
    with even and odd interlace fields displaying the exact same
    pixels.  The modern PC has square pixels, so displaying the
    font dot-for-dot the same would make the characters seem
    squashed.  Doubling them in height makes them a little too
    tall, but it is better than the squashed look.

    It would be possible to write a DOS-mode video driver to
    generate video timing that better matched that of the original
    Sol, and something similar could be done with one of the DirectX
    interfaces as well.  As it stands, the display looks OK, so
    getting the exact aspect ratio right is not high on the list of
    priorities.

    Also, the font size does not change as the window is made larger
    or smaller.  The display is simply clipped or centered in the
    available window.


*) Memory

    The Sol came standard with 1 KB of display SRAM and 1 KB of
    program store on the main board.  The S-100 interface was
    used to expand the memory for running larger programs.

    This emulation has a full 64 KB of memory, except for the
    bits that are reserved for the personality module (2 KB).


*) Virutal Disks

    Solace comes with four virtual Northstar disks:

        cpm_util.svn    --  standard cp/m 2.2 utilities
        cpmug.svn       --  programs culled from CPMUG
        nsbios_src.svn  --  source code for CP/M BIOS and boot programs
        ndsos52.svn     --  Northstar DOS v 5.2 (but nothing else)


-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

*) ENT (enter) file format

    The SOLOS monitor has an ENTER command, which is used to
    write values to memory from the input device.  A typical
    use is as follows:

        >ENTER 100
        :10 20 30 40
        :200: 50 60 70/
        >

    In this sequence, the "ENTER 100" command indicates we want
    to start filling memory at location $0100.  Solos then gives
    the ":" prompt.  Hex bytes are entered, separated by spaces
    or carriage returns.  Input can span multiple lines as desired.
    Note that the first number on the second line of input has a
    trailing colon;  rather than being a data item, it is an
    address specifier indicating a new address in which to begin
    filling values.  The ENTER mode is terminated with a slash.

    The .ENT file format follows this sequence.  On a real Sol it
    is OK to enter programs by hand this way only if they are very
    small.  For large programs where some form of mass storage isn't
    available, it is more convenient to download the programs over
    the Sol serial port.  Because SOLOS allows redirecting I/O, it
    is convenient to redirect the serial input port to the command
    input, then transfer the file over the serial line.

    Although this emulator doesn't presently model the serial port,
    the "magic" download ability provided from the "File" menu
    uses the ENT format simply because I already had a large number
    of programs archived in that format.

    Anywhere that an .ENT file can be used, an Intel format .HEX file
    can also be used.  Solace autodetects the format of the file by
    looking at the first line of the file.

-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

*) Directory structure

    Starting with Release 2.2, the directory structure of the releases
    is more hierarchical.  The hierarchy is as follows:

         ReleaseM.N/
             Solace Win32 binary and a few important notes
             binaries/
                 Sol programs and virtual tape images
                 .svt = Solace virtual tape
                 .svn = Solace virtual Northstar floppy disk
             build/
                 makefile, workspace and project files
                 src/
                     source files for building Solace
             html/
                 help files
             resource/
                 audio sample files
             ROMs/
                 personality module ROMs

