
 Ohio Scientific Superboard II Emulator V2.0d Documentation
 http://vintagecomputers.bplaced.net/Emulator.html

 This document describes the basic use of this emulator.  

 W_OSI Program:
  The startup configuration is located in the OSI.INI file
  Upload during Hard Reset [MENUE] or at program Start-Up
	Configuration			Content
	Osi.ini				default on program start up
	24x29_C1P_YEDOS.ini		Orig. YE-OSI DOS 160k disks
	24x29_C1P_YEDOS_35.ini		Orig. YE-OSI DOS 40 Tracks
	32x32_C1P_YEDOS_ORIG.ini	Large YE-OSI DOS 160k disks
	48x31_uk101_CEGMON.ini		YE-OSI DOS for UK101 model
	48x31_C1P_YEDOS_ORIG.ini	UK101 CEGMON for 64x32 mode
	32x32_Dealerdemo.ini		OSI minimal disk OS with demo
	32x32_Superboard.ini		original SB600
	32x32_Superboard_HGR.ini	High Res Graphic ROM
	32x32_uk101_OS65D30.ini		UK101 running version OS65D30
	64x16_uk101_OS65D33.ini		UK101 running version OS65D33
	64x32_SB600_OS65D32E.ini	SB600 running version OS65D32
	Superboard_Hexdos.ini		HEXDOS running on SBII
	32x32_uk101.ini			UK101 CEGMON for 32x32 mode
	64x16_uk101.ini			UK101 ORIGINAL 64x16 mode
	64x32_uk101_SERIAL_TERMINAL.ini	Micro UK101 serial Monitor
	64x32_WEMON.ini			WEMON ROM and BASIC
	64x32_WEMON_4K.ini		WEMON 4k ROM
	64x32_uk101_BASIC_X.ini		PremierBasic ROM 4,5,X
	
  
  Optional Command Line Options:
  W_OSI.EXE Filename.INI to run the choosen configuration file. 
  If parameter ends with .PRG, the PRG will be started by using 
  the default OSI.ini
  Files can be Dragged and Dropped onto the emulator window
  You may drag or open PGRs or disk images (IMG/65D) to start

 Use of Emulator:
	F1:  Open this HELP file
	F2:  Open program or disk image (.prg or .img type)
	F3 or Alt T:  Open Serial Terminal Interface
	F4:  Toggle between Fullscreen and Window mode
	F7:  Pause Emulation
	F8:  Toggle between graphic character or normal display mode
	F9:  Save to Serial Output file, similar to the tape save 
             routine *)
	F10: Load Serial Input file, similar to the tape load 
             routine **)
	F11 or Alt-M: Enter advanced debugger
	F12 or Alt-R: Soft RESET CPU !!!!

 REMARKS:
	The SD-card interface, replacing the ACIA, is now emulated.
	SD-card files are located in the OSI.SD file(Zip type). Depending
	on the RAM available, the corresponding OSI_8k to OSI_40k folder
	is used. Loading from SD-card, do first a BASIC cold start !
	Type M,L after RESET (F12) within five seconds.
	SD drive must have be enabled and SD image file selected.
	(or pre defined in the *.ini file, see *_SD.ini example)
	For UK101 nachines, at least a CEGEMON monitor ROM is required.

	LOADER.SYS is the file loaded on monitor L command. The system
	will boot into the BOOOT.SYS file on the SD card.
	BOOT.SYS is a program that provides extended BASIC commands.
	BOOT.SYS can be any alternative program of your choice.
	BOOT.SYS is in this version identical to the program BASIC and
	will show the usual BASIC OK prompt. BOOT.SYS will occupy 1280
	bytes at the TOP of RAM and adjust the BASIC memory pointers
	accordingly. It runs well on 8k machines. It also will place a
	jump instruction at $00BC to process the extended BASIC commands. 
	It provides extended resident BASIC commands as:

	SDLIST 				List current directory
	SDLOAD "FILENAME", [ADDRESS]
					Loads BASIC or Binary file
	VAL=SDSAVE "FILENAME", [START ADDRESS, END ADDRESS]
					Saves BASIC or binary file
	VAL=SDLEN "FILENAME"		Returns length of file
	SDGOSUB "PATH"			Select Directory
	VAL=SDLOG			Returns last error
	VAL=SDCLEAR "FILENAME"		Removes a file
	STRING=SDCHR$(x)	Get directory entry at position x
				""(empty) returned  if nothing found
	VAL=SDFRE		Returns free space on SD card
	VAL=SDVAL		Validate SD / Close file, return 1 if OK     
	SDDEF 0 or 1		Set/Reset AutoStart for BASIC files
	SDRUN			Runs the "MENU" program
 
BASIC commands only available on 16k RAM or more:

	VAL=SDNULL "DIRECTORY"	Remove directory in current path.
	VAL=SDDIM "DIRECTORY"	Create directory name in current path
	VAL=SDASC "FILENAME", "FILENAME"	Rename File


ROMS:

	For EPROM1_V52 & EPROM_HGR, new key function exist:
	Backspace: Delete previous character
	Cursor: This keys generate keystrokes for some cursor programs.
	For EPROM1_V52 only:
	Curor can be moved onto text elements. "shift ENTER" will copy
	text under the cursor into the input section.
	For EPROM_HGR only:
	Ins: Copy character under cursor location
	Cursor: This keys generate keystrokes for some cursor programs.
	Keyboard Layout can be redefined in the System menu.

	Type in BASIC "LOAD" to open a program file.
	Type "SAVE" to select an output file for serial output data.

 *)	Address 515 controls transfer to ACIA chip
 **)	SPACE returns to Keyboard Input !
	After Open Serial Input/Output, use basic command
	like usual to start serial data transfer

	IMPORTANT: Select Close All Serial files after SAVE,
	to end Output and close file or press F12 (Reset)

 The Debugger:
  The debugger allows you to watch the Emulator working, stepping thru 
  code or setting breakpoints. It shows the 6502's A,X, and Y registers,
  stack pointer, stack dump, etc. Registers can be modified in Step Mode.

  You can get into the monitor by pressing F11 while the emulator is 
  running normally. If a breakpoint is set, the Debugger will open 
  automatically.

 Debugger Commands:
	HARD-RESET: like Power OFF/ON
	EDIT-CONFIG: opens actual .INI file for change
	-> activate with HART-RESET (or SYSTEM/LOAD CONFIG FILE)
	RESET: reset CPU
	SetPC: change program counter to new hex value
	SetBP: change debugger break point to hex value
	ClrBP: SET breakpoint to default
	IRQ/NMI: allows or not interrupt handling
	Run: starts free run mode within debugger
	Single Step: execute single instruction
	Close: close debugger window and continue code execution
	CLR: Clears CPU cycle tick counter for cycle measurements

 Monitor Flags:
	Stop on Error code: 
		pop up debugger, when invalid opcode is detected
	Trace into subs: 
		During STEP mode, subroutines are bridged, means
		code is executes, but debugger will not trace into
		the subroutines.
	Display Mem/Stack: 
		displays RAM and PC-Stack. After entering a new memory
		address, you can change Memory or CPU Stack view.
	Three I/O Address brakpoints can be entered and activated.

-----------------------------------------------------

 Notes/Bugs/Future Improvements:



20-Jun-2001:	first available executable Rev.0.93
19-Apr-2002:	some improvements to ACIA read and MC decimal mode
25-May-2002:	key mapping introduced, new OSI loader in Export function
31-May-2002:	key mapping updated for flexible use. 
03-Mar-2003:	Correct Game font (Superboard II) by default.
		Enhanced graphic modes, New machine
10-Jun-2003:	WAVE to File conversion by using a KCS converter module
18-Dez-2005:	Fullscreen Mode and some other bug fixes
30-May-2009:	Rewritten for wxDEV-Cpp including some minor improvements
		Improved speed timing and debugger performance.
12-Aug-2012:	Correction of several bugs in the user Interface
05-Feb-2019:	Graphic ROM EPROM2 updated to HGR with more functions
20-Jun-2021:	Updated Floppy disk routines that will work with
		OS65D and HEXDOS. New KSC conversion tool added for W7+
25-Oct-2021:	Direct Serial Comm. Port connection added
30-Sep-2021:    Finally works with OS65D, HEXDOS and my YE-OSI DOS
22-Apr-2022:    Minor changes, runs again on old W2k & XP systems
17-May-2022:	Introducing graphic improvements (double buffering)
27-May-2022:	Improvement of UK101 features and YE-DOS usage
30-Jul-2022:    Correction to Serial Port handling
15-Dec-2022:	Improved ROM version to run on 610 board
23-May-2023:	Improved YE-DOS 3.52 to run on 5.25 and 3.5 real drives
8-July-2023:	Lowres graphic mode compatibility for different displays 
10-Oct-2023:	Sound for DAC and RTS line introduced 
16-Nov-2023:	Mayor changes to the user interface.
		Now with SOUND Output (4 or 8 Bits per *.ini)
		Emulator supports Low Res(RTS) and Hires graphic modes
27-Nov-2023:	Adding SN76489AN programmable sound generator
08-Dec-2023:	Adding AY-3-8910 programmable sound generator + DEMO
19-Dec-2023:	Adding Color for C1P/Rev-D boards. Enable with $D800=2
17-Feb-2024:	Now with two double sided drives. Improved compability
28-Feb-2024:	X-version for standard ROM's for 32k machines only
02-Sep-2024:	Introducing Character RAM graphics and improved OS65D
10-Oct-2024:	Character RAM graphics now in color like C1E
26-Oct-2024:	Additional Color mode for Character RAM Color for text
13-Nov-2024:    Overlay of Text/Graphics corrected
03-Jun-2025:    PRG header for BASIC files improved, minor corrections
03-Nov-2025:    SD-card interface support, C1P visualization corrected
09-May-2026:	Region keyboard layout support 

-----------------------------------------------------

 * Keep these files always in the main program directory:
	  KEY*.DAT	Map for PC keystrokes to OSI
	  OSI.TXT	This Help File
	  KSC.EXE	OSIKCS borrowed from marks-lab.com

 * If in the <System> ini files under section Keyboard, the 
   KEYTRANSLATION is set to 1, the keyboard takes PC key characters
   according to your reginal layout. Set to 0, it is mapped close
   to the original key locations and works only with US keyboards
   layouts.

  With the Keyboard Mapping function you can modify the
  mapping file KEY.DAT. with KEYTRANSLATION=1, only the special
  function keys will be available 
  USAGE: Set with left Mouse key or remove with right Mouse
  Special PC function keys can assign two OSI keys strokes to
  emulate Joystick or special ROM key requirements.

-----------------------------------------------------

 SYSTEM REQUIREMENTS

 This has not been tested thoroughly, but the minimum 
 requirements should be:
 a 1Ghz Pentium4 class machine or better,8 Mbytes of RAM,
 10MB hard drive space, Windows 7 and up.
 
-----------------------------------------------------

 ROM, DISK Images, BASIC programs and Cassette files are located
 in subdirectories like ROM, IMG, ...

 Check the diffrent configuration files, to see, which ROM or Image
 file are needed to run the desired machine correctly.

 A BACKUP folder under Disk Images is present, in case you have
 damaged, lost or folded a disk accidently.

-----------------------------------------------------
 My special System ROMs

 EPROM1_V52.ROM ($F800): YE-OSI SYSTEM ROM

 1.) "C" cold start to initial memory
 2.) "W" warm start of BASIC
 3.) "M" OSI Monitor
 4.) "A" Start HEX EDITOR on disk

On first start-up choose DOS to load DOS to $E000 and upwards
The Boot sector program will ask for next steps. The DOSSUP supplement
program DOSSUP is loaded, if present on the boot disk.

Disk naming: First drive is "0" and second is "2". "1" is second side
of fist drive and "3" of the second. The Emulator only supports 
single sided disk of 160kb or 80k each (Side 0 or 2)

 DOS Commands: 

 PAGE					Clear Screen
 SET Number				Set data READ pointer
 [Val=] CALL, Address, Parameter	Call machine code routine
 SUB					Call USR Vector
 OUT					Setup Serial port to 1200 baud
 OUT 0, Address,Pages			Start IRQ Serial output mode
 OUT 1, Data, ...			Send Serial data to output buffer

 DLOD "Filename"			Load program from disk
 [Val=] ERR				Get last DOS error code
 DOS					Start "DOSSUB" from disk
 ASS					Start "EITOR form disk"
 DISK					BOOT Diskette and other commands
 
 Checkout YE-OSI DOS 3.53.pdf for all the details.

 DOS SUPPLEMENT:
 This ia an extensions in Basic, that provides additional commands
 Code is located at $E900. See also YE-OSI DOSSUP.pdf manual.

 DIR ["String"]				Diskette directory list
 SEL 0..3				Drive select
 DSAV "FILNAME", DRIVE, TYPE, PROT	Save data to disk
 SEQS Address				Set data READ pointer to memory
 NextAddress = SEQW Address, ..		Write data elements to memory
 [Value=] EOF				Check for End of Data on READ
 VER					Shows Disk DOS Version
 DFMT NUMBER, SECTION, DISKTYPE		Formats disktte
 DCHK "FILENAME"			Veryfiy or checks file content
 DREN "FILENAME", "NEW FILENAME",..	Rename or delete file on disk
 VAL=PTR(VARIABLE)			Get variable pointer address
 CLG NUMBER				Change graphic modes
 GDIS  X (0...127), Y(0...63), MODE	Plot low-resolution graphic

 Simple cursor editor function integrated. Copy char under cursor 
 by pressing the "Shift ENTER". 
 Cursor movement ctrl < , ctrl > and Line Feed and shift Line Feed

 -----------------------------------------------------
 
 EPROM_HGR.ROM: Extended SYSTEM ROM with BASIC graphic modes

This ROM includes a full screen Text editor controlled by cursor and
supports the high resulution mode 256x256 monchrome pixel.

Commands:
 CLG 		// Clear screen in HiresMode
 [Var=] SCR X,Y // Set screen text position X,Y(0...31) or get Value
 Var = INKEY	// True Key Poll routine
 CLS 	        // Clear Text screen
 DEY(T) 	// Delay for T*100 msec
 SET LineNumber // Set DATA read pointer to this Basic line
 RAD(D) 	// converts RAD degree in DEG degree (V*57.2958)
 DEG(R) 	// converts DEG degree in RAD degree (R*0.0174533)
 FRAC(R) 	// Cuts integer value from real R (fractional)
 [Var=] CALL Adr,Val // Calls Subroutine by Val (changes $0011)

 PLOT X,Y (,M)	// Draw/Clear pixel/line in HiresMode X,Y(0...255)
		// Set:M=1,Clear:M=0, SetLine:M=2, ClearLine:M=3
 
NMI & IRQ Routines removed from 01xx Stack area to $0223 and $0226

 Cursor functions (defined in key_HGR.dat file):
	BACKSPACE = Backspace clear character
	Ctrl A or HOME= Left Home of line
	Ctrl > or Left Arrow = Cursor Right
	Ctrl < or Right Arrow = Cursor Left
	LF or Down Arrow = Cursor Down
	Shift LF or Up Arrow = Cursor UP
	Ctrl D or DELETE = Delete
	Ctrl I INSERT = Insert

-----------------------------------------------------
 Thanks to all programmers who made their code available.
        
	Based on The Compukit UK101 Emulator
	(Issued by Ian McLaughlin and in 1998)
	see http://www.compukit.org

	Also have a look to http://osi.marks-lab.com/index.php
	Thanks for the KCS conversion program for W7 and up.

	Some nice sources from APPLE //E EMULATOR
	(Issued by Michael O'Brien in 1996)

 The Compiler:
 Compiled with DEV C++ Bloodshed software Version 6.3. 
 Many thanks to make the Dev Cpp++ Compiler available.
 See under https://github.com/Embarcadero/Dev-Cpp


                 GNU GENERAL PUBLIC LICENSE

                     Version 2, June 1991

 Copyright (C) 1989, 1991 Free Software Foundation, Inc.
 675 Mass Ave, Cambridge, MA 02139, USA
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

                            Preamble

 The licenses for most software are designed to take away your 
 freedom to share and change it. By contrast, the GNU General 
 Public License is intended to guarantee your freedom to share and 
 change free software--to make sure the software is free for all its 
 users. This General Public License applies to most of the Free 
 Software Foundation's software and to any other program whose 
 authors commit to using it. (Some other Free Software Foundation 
 software is covered by the GNU Library General Public License 
 instead.) You can apply it to your programs, too.
