                         EUPHORIC : Reference Manual

 1. Command line options
 2. Features
 3. Tape images
 4. Using tapes: loose emulation
 5. Using tapes: hardware emulation
 6. Disk images
 7. Using the Microdisc
 8. Using the Jasmin
 9. Telestrat
10. Printer
11. Joystick
12. RS232
13. Programmable PC Keyboard
14. Dumping and restoring state
15. Screen snapshots
A1. Hardware requirements and some figures
A2. Performance problems ?
A3. Transfering programs from Oric to PC
A4. Copyright and credits

________________________________________________________________________________

1. Command line options
-----------------------

Euphoric accepts the following options on the command line :
	-com2 : use the second serial port instead of the first
	-m : use a gray level palette for monochrome VGA monitors
	-r : restart a state (saved with F9)
	-s N : use a speed index of N (default N=100)
	-t : start a Telestrat
	-j : use a Jasmin controller instead of a Microdisc
	-p : add a joystick on the P.A.S.E interface (on the printer port),
		emulated with keys on the numeric keypad (0 for fire button)
	-tj : add a joystick on the normal joystick ports of the Telestrat,
		emulated with keys on the numeric keypad (0 for fire button)
	-q : cube vga mode, special 256x256 resolution in order to get
		rectangular pixels as on the real Oric. DON'T use on a LCD
		monitor.
Every other parameter is considered as a file that should contain a disk image.

________________________________________________________________________________

2. Features
-----------

Euphoric emulates Oric 1, Oric Atmos, Telestrat and their peripherals :

	- complete emulation of N-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 first 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)

	- partial emulation of the second VIA (telestrat only) for now:
	the 3 low bits of port A to select memory banks, and port B to read
	joystick.

	- emulation of the Reset switch under the oric with F7 key. (Telestrat:
	Reset switch)

	- 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 the Microdisc electronics.

	- emulation of the Jasmin electronics.

	- partial emulation of the Real Time Clock extension (the alarm
	is not emulated, since it is quite useless without an IRQ line)

	- 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), and a special resolution on vga
	monitors to retrieve the correct aspect of pixels.

Plus:

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

	- sound switch on/off (F2)

	- Oric keyboard or programmable PC keyboard switch (F3)

	- 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

	- clock speed of the oric adjustable, to obtain a faster or slower oric

	- configuration screen to swap disks, with F1 key

________________________________________________________________________________

3. Tape images
--------------

Two tape image formats are used. The first one is for loose tape emulation: it
is an image of the bytes saved on a tape by the oric rom routines (however, the
number of synchronization bytes has been lowered to 3). This format is the most
used and is also used by Amoric, Jean-Franois Fabre's emulator. Near all the
programs available on archive servers are in this format. There is no peculiar
extension in the name of tape images.
The second format is more recent, it is a representation of the signal sent to
the tape recorder, sampled at 4800 Hz. It allows a very precise emulation of
tapes, mandatory for the (rare) programs that don't use rom routines at all.
It also eases oric/pc transfers.

________________________________________________________________________________

4. Using tapes: loose emulation
-------------------------------

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 most 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 recommended 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 tapes: hardware emulation
----------------------------------

The configuration screen (accessed with F1) includes a virtual tape recorder
with controls allowing fast rewind and forward, record, and a counter to locate
programs on a tape. Select 'Hardware tape' on the screen, then choose a tape
image with the file selector (unless you want to create a new tape).
Reading a tape is straight-forward: note that the tape player doesn't have any
'play' button, this is because the oric has a remote control relay (so, 'play'
button is always pressed). Just use CLOAD"" to load the first program on tape,
or CLOAD"program_name" to load a particular program. Thanks to the remote
control, you don't need to stop the tape player after reading a program, oric
routines do it for you.
Writing to a tape requires more care, as for real tapes. You have to press the
RECord button on the configuration screen (it switches to reverse video) before
issueing your CSAVE command. As for reading a tape, the remote control disables
the tape recorder's motor until the CSAVE command is launched, and stops it
again when the command is complete. Be careful, however, don't forget to release
the RECord button after your recording, or you risk to erase a tape during next
CLOAD command ! Be careful again, if you want to record a program on an already
used tape. Position the tape counter to a blank area, like the end of the tape,
or you will erase something.
I suggest you put only one program on a tape (or the parts of a program), unless
you want to prepare a tape for a real oric.
Finally, don't forget to protect your valuable tapes against writing, by using
the file access rights of your host system (chmod command under Linux, attrib
command under dos)

________________________________________________________________________________

6. Disk images
--------------

Disk images are files on the host, reproducing the bits of a MFM disk (double
density). Disk images of an old format might still be found on some archive
server, and some Oric->PC transfer tools still produce the obsolete format
(not supported by euphoric anymore): you need to convert old images with the
oric2mfm tool.
Disk images usually have a ".dsk" suffix, but this is not mandatory: Euphoric
controls the signature of the disk in the 256 bytes header.
There are several ways to get a disk image: grabing it on a server, building it
during an oric->pc transfer, or formatting a new disk with euphoric (you need
a system disk of course)

If you need a new disk in euphoric, just launch a format command in an empty 
drive. This way you create a disk image without name (the name is ________.dsk
on the host). When you exit euphoric, I suggest you rename the disk...
Finally, you can write-protect your virtual disks: under Dos, use the ATTRIB +R
command to set the read-only attribute; under Linux, access rights may be used,
owner and groups too.

________________________________________________________________________________

7. Using the Microdisc
----------------------

The Microdisc controller forces the oric to reset on an 8 KB eprom. You need a
OricDisk.ROM file (it is an image of the eprom), whose code tries to load an
operating system from the first drive. Sedoric is the most advanced of these
operating systems, and the most used nowadays.
In order to use the Microdisc controller, you just need to enter one or more
disk images on the command line. Disks are inserted in the successive drives
(4 max), and the oric will boot on the first.
During emulation, you can eject and insert new disks, with the configuration
screen (be careful not to swap disks during a disk write: you would damage a
disk in the same way as real disks !)

________________________________________________________________________________

8. Using the Jasmin
-------------------

Start euphoric with option -j on the command line to use a Jasmin controller.
The Jasmin controller also has a 2 KB eprom (you should have a Jasmin.ROM file),
but it doesn't force the oric to boot when powering it. The oric starts as it
does when no disk controller is connected, and you have to wait the 'Ready'
prompt, then press the Jasmin boot button (F6 on the emulator). Of course, a
disk containing the Tran DOS should be present in the first drive.

_________________________________________________________________________________

9. Telestrat
-------------

For those who still don't know, the Telestrat is the latest Oric issued by the
french Eureka company, when Oric UK didn't exist anymore. However, the project
was started in UK (codename IQ64), and the computer should be named Stratos.
This superb machine is upward compatible with the Atmos+Microdisc, and has
additional capabilities: cartridges (all the system software is on cartridges),
integrated floppy disk controller, RS232 and Minitel interface, joystick/mouse
ports. A real time clock add-on also exists, and it is emulated by euphoric.

The Telestrat needs at least one cartridge in order to boot.
Euphoric doesn't know about cartridges, but uses a more flexible way to deal
with memory banks. It looks for any Bank1, Bank2... Bank7 files in the directory
pointed to by the ORIC environment variable, and handles them as rom banks.
Every missing rom bank file gives a free bonus 16 K ram ! So if you start with
a Telemon image in Bank7 and an HyperBasic image in Bank6, you will have 6 free
ram banks ie a total of 48 + 6 * 16 = 144 K ram (however, Bank0 is the overlay
ram and usually contains StratSed), surely the cheapest ram you have ever seen !

The Telestrat boots on bank 7, ie the Telemon firmware. This one checks the
contents of the other banks, displaying their copyrights, and tries to load the
Stratsed operating system from the first drive to bank 0. If the disk in this
drive also has a BONJOUR.COM file, it is executed, otherwise the bank with the
highest number is started (but not #7), usually it is bank 6 with the HyperBasic
software. Latest versions of this bank display a menu offering the ability to
choose the Telematic software (if it is present) or a language bank, in the
latter case, an other menu allows you to choose HyperBasic or the TeleAssembler
bank (if present). TeleAss is usually in bank 5 and TeleMatic in bank 3.

If you use Linux, I suggest you use symbolic links to juggle easily with banks:
for example, name your roms Telemon2.3, Telematic, Hyperbasic, Forth, Teleass,
Stratoric, Basic1.1, etc. and make two symbolic links with 
	ln -s Basic1.1 Bank6
	ln -s Stratoric Bank7
to get a telestrat with a Stratoric cartridge. With such a scheme, you won't 
risk to accidentally destroy any rom when switching from one configuration to
another (just delete the links Bank6, Bank7...)

Starting a Telestrat instead of an Oric1/Atmos just need an additional -t
on the command line. The Telestrat is designed to work with floppy disks, so
you should also give at least one stratsed image disk name.
Your virtual telestrat has 4 drives, so some tools that install a ramdisk in
drive D don't work yet.

________________________________________________________________________________

10. Printer
-----------

Nothing special 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. The PASE interface
doesn't disturb the printer.

________________________________________________________________________________

11. Joysticks
-------------

Euphoric emulates a joystick with the numeric keypad (2,4,6,8 to move and 0 to
fire). I prefer this because Oric joysticks are binary joysticks while PC ones
are analog.
You emulate a joystick on a P.A.S.E interface (on the printer port) with the -p
option.
The Telestrat has two joystick ports, use the -tj option to emulate one of them.

________________________________________________________________________________

12. RS232
---------

The Telestrat has an integrated serial controller, which communication port can
be directed to either a V24 port (standard EIA levels) or a Minitel port (TTL
levels).
With Euphoric, the signals of the serial controller of the oric are redirected
to a serial port of the PC: default is first serial port, but you can select the
second serial port with the -com2 option on the command line or change the port
in the configuration screen.
A PC doesn't have a Minitel port, but you just have to plug a PC/Minitel cable
to use the Telematic software for example (however, ring detection is not
available on the emulator yet, this prevents you to use the emulator has a BBS
server).
When you start the emulator in Atmos+disc controller mode, the serial controller
is usable too, like if you Atmos were equiped with an serial add-on (6551 ACIA
located at address $031C).

________________________________________________________________________________

13. Programmable PC keyboard
----------------------------

Two keyboard emulations are managed by euphoric: the simplest one uses about the
same mapping as the real oric keyboard (US keyboard), I suggest you use it for
most games. Differences from the real Oric keyboard are: arrows location, Funct
key of the Oric is replaced by one of the Alt keys of the PC, and the idiot Ctrl
key of the extended PC keyboard is under the shift instead of above it.

The second keyboard emulation is programmable and allows you to have WYTIWYG on
your PC ("What you type is what you get" !), so national keyboards are usable.
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. A Keybfr.def file is bundled in the package, it should help you
when designing a keyboard mapping for your national keyboard.
Also, the programmable keyboard allows for a faster typing on your oric. You
surely know the keyboard routines of the Atmos prevent you to type a second key
when a first one has not been depressed yet. Euphoric's programmable keyboard
simulates a release of the first key when a second one is pressed.
A consequence of this is that this emulation doesn't allow to play games that
check for several keys pressed simultaneously, you have to use the first
keyboard in this case. So I suggest you use a Keyboard.def file, that eases
your typings, and use F3 to switch to a direct mapping when you start a game.

________________________________________________________________________________

14. Dumping and restoring state
-------------------------------

Pressing F9 during the emulation will make you save an euphoric state and
quit the emulator. Actually, both the contents of the memory and the hardware
state of the components are saved to two files: State and Dump.
You may start euphoric later, with -r option, to restart at the exact point
where you quit. Of course, you need to restart with the same configuration,
don't try to restart an Atmos state on a Telestrat. If you used a disk
configuration, restart euphoric with the same disks in the drives.
For example, if you start euphoric like this:
	euphoric -t hypercat.dsk
and you quit by hitting the F9 key, you have to type
	euphoric -t hypercat.dsk -r
in order to restart with the dumped state.

________________________________________________________________________________

15. Screen snapshots
--------------------

Simply use the PrtSc key...
A BMP file is generated, each PrtSc creates a new file: 
Screen01.bmp, Screen02.bmp, etc.

________________________________________________________________________________

A1. Hardware requirements and some figures
-----------------------------------------

VGA :	Euphoric runs with every VGA compatible card, in 320x240 mode X, or in
	256x256 mode Q (no need to use this mode on an LCD, you won't be able
	to get rectangular pixels)

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 386SX16,
	you will have to use a slower oric, please read following chapter.

	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.

	Euphoric is written in machine code optimised for the 386 (a minimum of
	memory accesses and branchs). I will perhaps write a 286 version for
	DOS, emulating a bare Oric with tapes, but don't ask for miracles, it
	will not run at speed index 100 on a 286 running at 16 MHz (and the
	perspective of developing for a 286 under DOS is not appealing...)

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.

________________________________________________________________________________

A2. Performance problems ?
--------------------------

If your screen keeps black, and if you can still exit with F10 key, your
processor is not fast enough. In such a case, Euphoric doesn't have enough
time to refresh the screen, particularly when in tight loops accessing IOs.
You have to use the -s option and a smaller than 100 speed index...
If you use Sedoric on an Atmos, or if you use a Telestrat, you may have noticed
the frame rate is lower than on an Atmos with tapes, this is due to the fact
bank switching (or rom/overlay ram switching) is used a lot on these systems,
making euphoric adjust its page pointers.
With Sedoric, you can use the QUIT command, this frees the keyboard waiting
loop and the interpreter loop of these costly switches (however, you won't be
able to use the function keys of Sedoric, and you will be oblige to prefix 
every Sedoric command with '!' ).

________________________________________________________________________________


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

If you own a 3"1/2 or 5"1/4 drive on your Oric, no doubt you already know the
readdsk tool allows you to read your disks on a PC, making images of them.
If you don't have a 3"1/2 or 5"1/4 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.
The program below allows you to transfer a whole tape (or a part of it) to a PC.
If you have 3" disks, there is a similar program written by Philippe Menard,
using the same cable.

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 :

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

    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) On your Atmos or Oric1, type the following small program:

	100 DATA #20,#6A,#E7	' replace by #20,#CA,#E6 on Oric1
	101 DATA #A9,#FF
	102 DATA #8D,#00,#03
	103 DATA #20,#1C,#E7	' replace by #20,#7D,#E6 on Oric1
	104 DATA #2A
	105 DATA #8D,#01,#03
	106 DATA #AD,#00,#03
	107 DATA #48
	108 DATA #29,#EF
	109 DATA #8D,#00,#03
	110 DATA #A9,#02
	111 DATA #2C,#0D,#03
	112 DATA #F0,#FB
	113 DATA #68
	114 DATA #8D,#00,#03
	115 DATA #4C,#08,#B8
	120 FOR I=#B800 TO #B825
	125 READ A : POKE I,A
	130 NEXT
	135 CALL #B800
	
    C) Start the oriclink utility on the PC, type RUN on the ORIC and press
    the PLAY button of your tape recorder. When you want to stop the transfer,
    press the RESET button of your oric (under the box) et a key on the PC.
    You get a tape image (image.tap) directly usable with euphoric in hardware
    tape emulation mode.

    D) You may try to convert the tape image to a more compact file with the
    tap2oric tool. However, this is not always possible, some protected programs
    don't use the standard format.

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 ).

________________________________________________________________________________

A3. Copyrights and credits
--------------------------

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 in 32 bits mode.

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
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, Laurent Chiacchierini and all the members of the
CEO who make the Oric live
(Club Europe Oric/Jean Boileau/33 av Henri Barbusse/93140 BONDY/FRANCE)
(Club Europe Oric UK/M.Jonathan Haworth/3 Madingley Road/Cambridge/CB3 0EE/
England)
and thanks to Dave Dick and all the members of OUM
(Oric User Monthly/Dave Dick/65 Barnard Crescent/Aylesbury/HP21 9PW/England)

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

Thanks to generous supporters : Roger Barbier, Simon Guyart, Jeremie Petit,
Eric Fevrier, Pierre Guyon, Andre Franz.

Euphoric is giftware, freely distributable. However, it's copyrighted and nobody
is allowed to make profit with it. If you paid for it, you should have only
paid for the medium, there are better ways to spend your money, eg. sending it
to me... I accept donations sent to the following address :

	Fabrice Frances
	63 bis, chemin de Pahin
	31170 TOURNEFEUILLE
	FRANCE
