                         EUPHORIC ReadMe


0. Installation
1. QuickStart
2. Function Keys
3. Features
4. CLOAD and CSAVE
5. Using disks images
6. Printer output
7. Transfer programs from Oric to PC
8. Hardware requirements and some figures
9. Changing the speed
10. International keyboards
11. Copyrights
12. Problems and answers

________________________________________________________________________________

0. Installation
---------------

Linux only:
	Euphoric needs access rights to physical IO ports : VGA card and
	soundcard.  You should install it as "setuid root".
	Type in the following commands :

		% su
		Password : <root-passwd>
		# chown root euphoric
		# chmod u+s euphoric
		# exit
		%

DOS only:
	Problems have been reported when using the go32 extender after programs
	like DesqView's multitasker. It's safer to start from a simple clean
	config, like no memory manager at all, or using himem.sys and emm386.sys
	from Microsoft. Also note that when using smartdrv, you should't switch
	off your pc before exiting a program (there is no exception with 
	euphoric).

DOS and Linux:
	I suggest you set the ORIC environment variable. This way you will be
	able to run euphoric from any directory, without thinking about dupli-
	cation of the rom file and keyboard map. Then you will easily sort your
	oric programs in different directories. The ORIC variable gives the path
	where the emulator looks for Oric.ROM (Linux users, please take care to
	upper and lowercase). If you don't use the ORIC variable, it will look
	in the current directory. The variable gives also the path to the
	Keyboard.def file, if it is not found there, the emulator will use the
	default US mapping (like on the real oric).
	E.g. under dos :

		C> set oric=c:\euphoric\

	under linux with csh (or tcsh, or...) :

		% setenv ORIC /usr/local/euphoric/

	under linux with bsh, ksh,... :
	
		% ORIC=/usr/local/euphoric/
		% export ORIC

	Of course, you can set the variable once in your autoexec.bat, .profile,
	.login, etc.

	NB: Please always include the final / or \

________________________________________________________________________________

1. QuickStart
-------------

Ok, you want to try the emulator now ? Start "euphoric" then load a program with
the Basic command :

CLOAD "GOBBLER"

...(two hours later), press F10 to exit and go on reading this documentation,
it is not that long, you will use the emulator in a better way, and so I have
written it for someone.

________________________________________________________________________________

2. Function Keys
----------------

Real Oric fans remember these keys, never use the F1 key, and keep the Oric
display identical to the real one...

F1: Display/Hide the help line

F2: Sound on/off switch

Ctrl-F3: Linux users only, this is the BREAK sequence (replaces Ctrl-C)

F7: Reset Button under the oric

F8: Power plug (power on reset)

F9: Dump the state of the oric and exit (restart from this state is allowed)

F10: Exit emulator

PrtSc: Hardcopy to a ScreenXX.bmp file.

________________________________________________________________________________

3. Features
-----------

Euphoric emulates Oric 1 and Oric Atmos :

	- complete emulation of MOS technology 6502 microprocessor, including
	unofficial op-codes, and even hangs up the emulator on invalid op_codes
	(you will have to plug the virtual power off and on in this case)

	- emulation of the clock, by counting the clock cycles needed for each
	instruction.

	- speed identical to the original oric, whatever cpu you have (please
	read paragraph 'hardware requirements', though)

	- emulation of the VIA 6522 : I/O ports, programmable timers counted
	down with clock above, interrupt control (only the serial register is
	missing, it is not used in the oric)

	- emulation of peripherals interfaced to the 6522 : printer, keyboard
	matrix, programmable sound generator access (soon joystick and hardware
	tape interface)

	- emulation of the Reset switch under the oric with F7 key.

	- emulation of the programmable sound generator GI AY-3-8912 : three
	sound chanels with original envelopes, and partial noise generator
	emulation (frequency is not programmable). Also, the emulation needs
	to retrieve the original square wave.

	- emulation of the Floppy Disk Controller WD1793, and support for up
	to 4 virtual drives (3", 3"1/2, 5"1/4... size does not matter)

	- emulation of ROMDIS and ROMSELECT signals, as used with the original
	disk interface, enabling switch to and from Basic rom, overlay ram, 
	disk eprom.

	- emulation of the UAL to build the screen image, with all the serial
	attributes, including blinking and mode changes (text/hires), dynamic
	redefinition of char sets, and so on.

	- emulation of the TV with 50 screen refreshes per second (depending
	on the host processor power, only some lines of the screen might be
	refreshed, or more than a full screen)

Plus:

	- reading and writing of files on the host by interception of read/write
	to the tape.

	- sound switch on/off (F2)

	- more keys on the oric's keyboard matrix for national keyboards, and
	interception of ascii translation.

	- power switch (F8) : complete reset of the oric.

	- Dump of the state of the oric in two files ('State' for cpu registers,
	VIA registers, etc. 'Dump' for the whole memory). Resuming this state is
	achieved with the -r option on the command line, so you may use saved
	games, examine memory...

	- 'On the fly' hardcopy of the screen to a .bmp file

	- an oric speed index may be given on the command line, to obtain a
	faster oric (or slower) than the original.

	- F1 key summarizes the functions. 

________________________________________________________________________________

4. CLOAD and CSAVE , internal logic
------------------

Well, you surely notice CLOAD looks for the program on the disk of the host (Dos
or Linux). This allows a very intuitive use of all the programs working with 
tapes, even machine language ones and protected ones.

You may want to read this paragraph to master advanced use, eg. sorting your
programs in several directories, creating multi-parts programs, or using no-name
files.

- CLOAD and CSAVE forward the name given to the host with no modification. This
means you can use full pathnames provided they are valid on the host ! E.g :

	CLOAD "A:\GAMES\GOBBLER"

	CSAVE "/tmp/release1",AUTO

First example above is for Dos, of course. Second example works with Linux and
Dos too (try it just to verify you remember Ctrl-T switch to lowercase).
BTW, it is easier to use uppercase for oric programs.

So you are able to sort your oric files, but BE AWARE oric truncates names at
16 chars : chose between long names, one level of directory, or short directory
names.

- You may save a program without a name :

	CSAVE ""

or CLOAD it in the same way. Since system hosts do not allow no-name files, the
file takes the name "________" on the host (eight underline chars).
It is NOT recommanded to use this feature : you will not remember what the file
is, and it may be suppressed with the next no-name save.

But you will sometimes see this file in a directory, this means that a program
saves something without giving it a name (e.g saved game). Under the host, you
may then rename this file to give it a longer lifetime, and juggle with several
saved games.

- You already have used multi-parts programs if you loaded GOBBLER. Multi-parts
programs may reside in several files or be catenated in a single file.
When you CLOAD a file containing multiple parts, the command loads the first
part and leaves the file opened. Successive CLOAD commands will read the next
parts in the same file.

The logic is : the first CLOAD command gives the name of the file to open for
reading, and the first part found in it is loaded. The file is kept opened,
and is considered like a tape (sequential access). This means that a part may
be skipped if its name does not match the name looked for. Then if a CLOAD
command is issued while the end-of-file has been reached, the system close the
current file, and opens a new one whose name is given by the command.

Not so clear ? Let's take an example : assume The Hobbit is a four parts game
in a single file named HOBBIT on the host. With CLOAD"HOBBIT", you open the
file and read the first part (whatever name it has). This part executes and
loads the next three parts (with machine language instructions in this example),
then assume you want to restore a game you saved the day before : The Hobbit
understands the LOAD command, it wants to load a no-name saved game but the end
of the current file has been reached. So, a new file is opened (here the special
"no-name" file), the first program found inside is loaded (a block of data
in this example) and the file remains opened (The Hobbit will load three other
data blocks, this is how it stores the state of a game). And so on...

In brief, you usually don't have to worry about this behaviour, it is like you
have a robot with direct access to your tapes, it inserts the tape you want in
your recorder, and then you have to go sequential through the whole tape. The
logic explained above will only be useful to you if you build your own "tapes".

What about CSAVE ? Because you don't want to write your programs anywhere, and
surely not in your precious "tapes", a new file is opened for writing every
time a CSAVE command is issued (with the name given of course). Two programs
will not be catenated in a single file, so (if this were the result you
expected, you may use host commands for that, e.g 'cat' under linux and
'COPY /B' under Dos). The exception comes with no-name CSAVEs : first CSAVE
will store the program in the host's ________ file (eventually removing previous
content), but next no-name CSAVEs will append to this file.

________________________________________________________________________________

5. Using disks images
---------------------

Euphoric emulates an Oric with up to 4 drives. Just feed it with 4 disks images
on the command line and you will get a 4 drives system booting on the first.
If you don't give any disk image, you will get a no-disk system, i.e working
with tapes only.
Disks images are files on the host with the exact contents of real oric disks,
sector by sector. It is independent of the Oric Disk Operating System you
want to use (today, oric users prefer to use SEDORIC (SED is the equivalent of
DOS in French : Systeme d'Exploitation Disque)).
Disks images may be created with a DOS (Bios) program reading 3"1/2 or 5"1/4
oric disks (256-bytes sectored). The program is named readdsk and is able to
read near every exotic format, whatever head/track/sector numbers the disk is.
Of course, once you have a disk image, you may duplicate it free with the host
copy command, this is one advantage of virtuality...

Time for an example : assume you have three disks images called
	Sed10.dsk
	Arcade1.dsk
	Nibble.dsk
you may start a 3 drives system by issuing the following command:

	euphoric Sed10.dsk Arcade1.dsk Nibble.dsk

so, you will boot on Sed10 image in drive A, and have the opportunity to access
Arcade1 image in drive B and Nibble in drive C.

Now assume you need a new virtual floppy disk, just go to a free drive (ie with
no disk in it) and format it. A blank disk will automagically materialize in it
and you get a formatted floppy disk with no stick label (the name will be
________.dsk on the host). When you exit from euphoric, don't forget to put a
label on it, I mean rename the file...

Conversely, you may write 3"1/2 or 5"1/4 oric disks from disks images with
the writedsk tool (available for DOS only), although you have to format the
disks on a real oric (I will work on this soon).

________________________________________________________________________________

6. Printer output
-----------------

No problem here, file Printer.Out will cumulate all outputs to the printer
(even the first NUL char during power on...). You will then have the opportunity
to print this file with the host, or do some post-processing.

________________________________________________________________________________

7. Transfer programs from Oric to PC
------------------------------------

If you don't have a 3"1/2 disk drive, I suggest you use the parallel transfer
below. This is the most reliable, and fastest way. Reading tapes with a sound
card has proven only effective with high quality recordings.

Of course, you need to be still able to load your programs with your real oric.
Ensure your tapes or 3" disks are still in good condition, and your oric and
peripherals are still working properly.

This parallel link will be unidirectional only. 
Why not a bidirectional link ? Well, I have made one also : I have modified an
Atmos rom to replace the rarely used instructions STORE and RECALL with my
own SEND and RECEIVE, so my Atari serves as a file server. But there is risks
to misuse it : the printer port on the Oric has only ten lines (the ten other
pins are grounded), i.e 8 data lines plus Strobe and Acknowledge. The data lines
is the port A of the VIA, and is also used to communicate with the sound
generator, which is itself used to write to a keyboard latch (and for playing
music, but you know that). So, every program wants the A port to be an output
port most of the time (you can tell the port or a part of it to be an input
if you know what you do, for example reading a joystick with interrupts disabled)
If you want to connect an output PC line on an Oric data line, the latter should
be programmed as an input for all the time (so you need to start a transfer
utility on the Oric BEFORE plugging in the parallel link (hot plugging ?!),
do the transfer, plug out the link BEFORE terminating the utility program.
Dubious, isn't it ?). It was ok on my atari since its parallel port is also a
bidirectional one, so I made a kind of half-duplex parallel protocol, taking
care to simultaneously change each side from input to output, and vice-versa.
I have also made an Oric<->PC bidirectional parallel link, but it uses an
additional external VIA.

Anyway, this uni-directional link might be just what you need to recover your
programs from the Oric to the PC. Your PC will be turned in a kind of 
half-a-printer ;-)
If you intend to do some cross-development, I will send you schematics of my
custom add-on with an external VIA.

Ready ? Ok, let's proceed :

    A) Build your cable :

     PC	DB25 	Oric 20 pins
     -------	------------
	15	3 (D0)
	13	5 (D1)
	12	7 (D2)
	10	9 (D3)
	11	1 (STROBE)
	6	19 (ACK)
	18-25	2,4,6,8,10,12,14,16,18,20 or just one of it (GROUND)
	all the others pins not connected.

    Be sure to know the position of the Oric pins : when you look the parallel
    port (male) at the back of your Oric, here is what you see :

		1 3 5 7  9 11 13 15 17 19
		2 4 6 8 10 12 14 16 18 20

    Alternatively, if you already have a PC<->PC parallel link, you may chose to
    just add a small Oric-PC converter, which you will connect to your PC
    parallel cable :

	DB25	Oric 20 pins
	----	------------
	2	3 (D0)
	3	5 (D1)
	4	7 (D2)
	5	9 (D3)
	6	1 (STROBE)
	11	19 (ACK)
	18-25	2,4,6,8,10,12,14,16,18,20 or just one of it (GROUND)
	(if you chose to only ground one of the 18-25 pins, be sure to have the
	ground connected from end to end when connecting the whole thing)

    B) The safety point : verify that you can CSAVE and CLOAD on a fresh tape
    with your old oric.

    C) The hassle point : type the Oric utility (about 1155 keystrokes, you can
    do it). Run it. Verify it if you made an error in the datas. You don't need
    any more this Basic program, but if you want to save it, it's not a bad idea
    (perhaps one day you will want to modify it).

        100 DATA141,1,3,173,0,3,73,16
        101 DATA141,0,3,173,13,3,41,2
        102 DATA240,249,96,72,32,0,4,104
        103 DATA74,74,74,74,32,0,4,96
        104 DATA162,4,189,168,2,149,0,202
        105 DATA208,248,96,162,4,181,0,157
        106 DATA168,2,202,208,248,96,56,173
        107 DATA171,2,237,169,2,141,171,2
        108 DATA173,172,2,237,170,2,24,105
        109 DATA6,141,172,2,169,0,141,169
        110 DATA2,169,6,141,170,2,96,16
        111 DATA7,83,101,110,116,58,32,0
        112 DATA16,7,76,111,97,100,101,100
        113 DATA58,32,0,8,32,178,231,32
        114 DATA106,231,32,125,229,32,172,228
        115 DATA32,155,229,32,32,4,32,54
        116 DATA4,32,224,228,32,61,233,40
        117 DATA32,43,4,169,96,160,4,32
        118 DATA171,229,32,81,230,96,120,169
        119 DATA191,141,0,3,169,228,160,4
        120 DATA32,171,229,162,9,189,167,2
        121 DATA32,19,4,202,208,247,189,147
        122 DATA2,240,6,32,19,4,232,208
        123 DATA245,32,19,4,32,32,4,32
        124 DATA54,4,173,169,2,172,170,2
        125 DATA133,51,132,52,160,0,177,51
        126 DATA32,19,4,32,108,229,144,246
        127 DATA32,43,4,169,87,160,4,32
        128 DATA171,229,88,96,16,7,83,101
        129 DATA110,100,105,110,103,32,0
        200 FORI=#400TO#4EE
        210 READA:POKEI,A
        215 S=S+A
        220 NEXT
        230 IFS<>22457THENPRINT"YOU MADE AN ERROR IN THE DATAS"

    D) The important point : save the code with CSAVE"XFER",A#400,E#4FF so that
    you will be able to use it another day without retyping all the previous
    stuff (are you sure you ran the Basic program before?).

    E) The safety point II : verify your recording (CLOAD"XFER",V)

    F) Ok, you are quite ready. Beginning with point F, you will have to do this
    every time you reload this utility : DOKE#2F5,#46B so that you will just
    have to type !"" to load a program from tape (don't do it before point G).

    G) The integrity point : type HIMEM#5FF so that the programs you load won't
    be corrupted by the BASIC commands you use. Note that I have kept this
    utility small enough to allow the biggest programs to be read (you have room
    for a 44800 sized program, and even more if you can blindly type).

    H) Ok, now you are ready. Type !"" to load a program from tape, look at the
    top line for status (if you get ERRORS FOUND, your tape is aging, remember a
    few hints : start your recorder a few seconds before, type !"" while the
    synchro has already started, use a small screwdriver to adjust the screw and
    get the clearest sound, etc)

    I) Start the oriclink utility on the PC, type CALL#496 on the ORIC, and the
    Enter key on the PC, 'et voil' : the PC has got it, type a PC filename to 
    save it, and restart points 8 and 9 for as many programs you like.

Note to Linux users : as every program that needs to access physical IO
ports, oriclink must be run with root privileges. Run it as root or set the
setuid bit (ie. chown root oriclink ; chmod u+s oriclink ).

________________________________________________________________________________

8. Hardware requirements and some figures
-----------------------------------------

VGA :	Euphoric runs with every VGA compatible card, in 320x200 mode X

386 :	Euphoric runs on every 386 compatible cpu (even 386SX).
	BUT, if your cpu is not powerful enough, you will not see anything on
	screen ! (the emulator wants to be synchronized with the real oric,
	so it has no time to refresh the screen) This is the case with genuine
	386 from Intel, even running at 40 MHz. If you are in this case, you
	must use a slower oric, please read following chapter.
	You may know that loading a register from memory can be 4 times slower
	on a 386 than on a 486.
	BTW, an optimised 386 chip like those from IBM or Cyrix may be enough,
	Euphoric runs on a Cyrix 486 SLC 33 (an optimised 386 SX with 1KB cache)
	With an Intel 486 SX 16, you will be able to run Euphoric with a 100%
	Oric index speed, but if you want a satisfactory screen refresh, you
	must have a 486 SX 33.
	Euphoric is written in machine code optimised for the 486 and is
	developed on a Cyrix 486 DLC 40 (about the same power as a 486 SX 33
	from Intel). As optimization for a 486 is different than for a 386, I
	am currently working on a "light" version for 386, without write-
	protected rom, without overlay ram (so no disk), that should allow 386
	owners to run their favorite games at full speed.

	In the other hand, the more powerful your cpu, the bigger screen refresh
	rate you have : no cpu cycle is lost, as soon as the emulator has dealed
	with an virtual oric time quantum, it refreshes the screen until the
	end of the real time quantum.

Adlib:	The programmable sound generator of the oric is emulated with 2 operator
	FM synthesis on an Adlib compatible card (so SoundBlasters and
	compatible cards work too). People have run it with a GUS card and an
	Adlib software emulator under Dos.

Euphoric is freeware, freely distributable. If you enjoy it, you can make me 
know, I accept donations sent to the following address :

	Fabrice Frances
	16, allee du Vaucluse
	31770 COLOMIERS
	FRANCE

________________________________________________________________________________

9. Changing the speed
---------------------

This option is intended for 386 owners who can't use euphoric at the oric
nominal speed (but owners of powerful cpu may use it to try a fast oric...)

Euphoric reads a speed index on the command line, 100 is the index of the real
oric and is the default value. Smaller values will give a slower oric, bigger
values will lead to a faster oric.

For example, in order to have a two times slower oric, you just have to type

	euphoric -s 50

________________________________________________________________________________

10. International keyboards
--------------------------

Euphoric looks for the Keyboard.def file and uses the mappings it contains.
If the file is not found, euphoric will use the original US mapping found on the
genuine oric.

If you have a UK keyboard, just copy file Keybuk.def onto Keyboard.def
Same thing if you have a german keyboard with file Keybde.def
It is easy to make other keyboard mappings.

Using a national keyboard is not a problem with arcade games since they use
the position of keys and only the position->ascii code translation in rom is
affected by this mapping. To achieve this result, three keys were added in the
keyboard matrix of the oric : the AltGr key, the key next to left shift, and
a CAPS key which was not mandatory but of more practical use than the Ctrl-T
combination.

If you have an unsupported mapping, inspire yourself from the mappings bundled.
They just give the chars found on the keys, sorted by scan codes : each line
corresponds with a key, the first is the escape key. The first char on the line,
if present, is the unshifted key, second is shifted key and third is the char
obtained with AltGr. You shouldn't need to change the position of special keys
(Enter, Escape, BackSpace,...) denoted by special sequences like ~3, since they
always have the same scan codes.

________________________________________________________________________________

11. Copyrights
-------------

Euphoric is copyrighted Fabrice Frances.

Euphoric is developed under Linux, free Unix with the whole GNU development 
environment, particularly the gas assembler and gcc C/C++ compiler, which
produces better code than Borland and Microsoft products.

The same source (apart few details) is assembled with djgpp, DJ Delorie's port
of the GNU environment to Dos, and runs with DJ Delorie's go32 extender.
I am waiting for go32 and djgpp release 2.0, which will allow the emulator to
run on every DPMI box (OS/2 2.x, Warp, Windows NT, Windows 3.1, Windows 95)

Standard IO routines (fopen, fread, fwrite...) from the standard C library are
copyright "The Regents of the University of California" (UCB), that's why I say
"This product includes software developed by the University of California,
Berkeley and its contributors".

No code from the FSF is included in this program, it doesn't fall under the GNU
General Public License, nor the GNU Library Public License.

The svgalib library (Harm Hanemaayer) is used under Linux to switch to mode X
and get keyboard scan codes. Under DOS, no library other than libc.a is used.

The logic of the Adlib code is borrowed from Gerton Lunter's Spectrum emulator,
who had the kindness to send me his source code.

Thanks to Jonathan Haworth, who communicated me all needed informations about
the architecture of the floppy disk controler, and who is certainly the best
Oric supporter on earth (I strongly recommand you read his book, 'Oric, the
story so far...')

Thanks to people who have never given up Oric, like Laurent Chiacchierini and
all members of Club Europe Oric or Oric User Monthly.

Thanks to testers for their suggestions, particularly Philipp Mulrane, Bruno
Thiebot, and Vaggelis Blathras who wins the contest of perfectionism...

________________________________________________________________________________


12. Questions and answers
-----------------------

    A) How to contact me ?

	E-mail is the prefered way : frances@ensica.fr

    B) Is there a newer release ?

	The up-to-date version will always be on a web server, URL :
		http://www.ensica.fr/LOCAL/ORIC/euphoric.html
	There you will also find the latest information, tools and programs for
	the Oric.

    C) Which platforms are supported ?

	Euphoric runs on PCs only, but you can chose between DOS and Linux.
	The DOS version is expected to be soon fully DPMI compatible and runable
	under the DOS boxes of Windows 3.1, OS/2, Windows NT 3.5...
	JF. Fabre and O.Balet have developed an emulator for Unix/X11 
	workstations. Contact them at fabre@cert.fr and balet@ensica.fr.
	JF. Fabre is also working on an emulator for Commodore.

    D) Hitting Ctrl-C quits euphoric under linux !

	Yes, I know, and I can't do much for now. I'm waiting H.Hanemaayer fixes
	svgalib. Please use Ctrl-F3 instead...
