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 ". 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 .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: \ 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: \ (0x0A) \ (0x0D) \ (0x7F) \ (0x80) \ (0x81) \ (0x8B) \ (0x8C) \ (0x8E) \ (0x93) \ (0x97) \ (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 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: is the REPT key is the MODE key is the CLEAR key is the LOAD key invokes the debugger causes the emulator to single step the 8080 program, stepping "over" CALL and RST instructions. 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 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 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