XEUPHORIC(1) XEUPHORIC(1)
NAME
xeuphoric - an Oric emulator
SYNOPSIS
xeuphoric --help
xeuphoric --version
xeuphoric [-1|a|t] [-djJpQr] [-A file] [-s num] [-S arts|auto|oss] [-X
always|auto|never] [-z num] [file ...]
DESCRIPTION
xeuphoric is a port to X of Euphoric, Fabrice Francès' Oric emulator.
It emulates the Oric-1, the Oric Atmos and the Telestrat. This version
is based on Euphoric 0.99b, which was the most recent source available
at the time.
The original documentation of Euphoric 0.99b is in doc/euphoric-0.99b.
Differences with Euphoric 0.99b
· There is no oriclite target.
· The keyboard handling code is different. The new code only
implements raw mode. The so-called ASCII mode has been removed.
· The video emulation code is different. In this version, the 60 Hz
attribute is ignored.
· There is a man page.
· The distribution archive is source code, not binaries.
· The distribution archive is in tar format, not zip format. The name
of the archive includes the version number. When extracted, it
creates a directory including the version number.
· [prtsc] is disabled. It's replaced by [f12], which writes a
screenshot in PPM format.
· Joystick handling is disabled.
· The command line is now parsed with getopt(3). Syntax errors in
command line do not cause the usage to be printed anymore.
· The -tj option has been renamed -J.
· Error messages are printed to standard error instead of standard
output. They now include strerror(errno) if relevant. Numerous
fixes in host.c error messages.
· New options --help and --version.
· New option -A, to disable audio output or write it to file.
· The config files and ROM files are now dealt with so that you can
run Xeuphoric from any directory without having to set the ORIC
environment variable (which has been removed).
· Tape emulation has been changed to favour lower-case file names on
the host and a .tap extension. CLOAD still supports file names in
all caps and/or without an extension for compatibility.
OPTIONS
If the first argument is --help, Xeuphoric prints a usage message on
standard output and exits successfully.
If the first argument is --version, Xeuphoric prints its version number
on standard output and exits successfully.
Otherwise, the command line is parsed with getopt(3).
Machine to emulate
-1 Emulate an Oric-1. -1 and -at are mutually exclusive.
-a Emulate an Oric Atmos. This is the default. -a, -1t are
mutually exclusive.
-t Emulate a Telestrat. Telestrat emulation implies 6551 emulation
which requires (1) the ioperm(2) system call and (2) super-user
privileges (i.e. you must be logged in as root or make the
xeuphoric executable setuid root). Failing either of the above,
Xeuphoric will run with 6551 emulation disabled. -t and -1adj
are mutually exclusive.
Peripherals to emulate
-d Emulate a Microdisc. -d and -t are mutually exclusive.
-j Emulate a Jasmin. -j and -t are mutually exclusive.
-J Emulate a Telestrat joystick. This used to be -tj in Euphoric.
-J and -1a are mutually exclusive.
-p Emulate a P.A.S.E. joystick interface.
Audio
-A file
With the OSS output method, write audio to file. file is
assumed to be an OSS dsp device. It is configured to 8-bit
unsigned mono PCM at 25600 Hz.
If the configuration ioctl()s fail, which probably means that
file is not an OSS dsp device, a warning is printed but audio
output is written to it anyway. You can take advantage of this
to save the audio output to file. Note that for this to work,
file must already exist. E.G.: touch audio.raw && xeuphoric
-Aaudio.raw. Likewise, you can disable audio output, by using
-A/dev/null.
By default, /dev/dsp is used.
-S arts|auto|oss
Sound output method.
arts Only try libarts (or abort if compiled without libarts
support).
auto Try libarts first and fall back on OSS. It's the
default.
oss Only try OSS (or abort if compiled without OSS support).
Video
-X always|auto|never
XShm usage.
always Always use XShm; if compiled without XShm support or XShm
is not available at run-time, abort.
auto Use XShm if it's available and fall back on regular
XImages otherwise. It's the default.
never Don't use XShm, even if it's available.
-z num Set the zoom factor to num. Allowed values are 1, 2 and 3. The
default is 1.
Miscellaneous
-Q Quit on illegal instructions (the default is to hang).
-r Restart from a dump.
-s num Set the speed index to num percent of an actual Oric. The
default is 100.
VIDEO OUTPUT
The video part of the ULA is emulated into a 240×224 window (times the
zoom factor). The emulation is believed to be accurate for most uses
except for the 60-Hz attributes which is ignored.
Uses that rely on microscopic (sub-frame) timing characteristics won't
be emulated properly. In particular, while the video output of the
real Oric is interlaced, Xeuphoric displays both odd and even lines on
every frame. The frame rate is also slightly off (20000 cycles instead
of 19968). Another potential cause of incompatibilities is that while
the real ULA renders the display little by little, Xeuphoric renders it
all at once from a snapshot of the video RAM.
On greyscale displays, Xeuphoric does not attempt to weight the
components, as the most common X server implementation (XFree86)
appears to do that already. If you have problems distinguishing Oric
colours on your display, let me know about it.
SOUND OUTPUT
Xeuphoric emulates the 8912 by generating a mono PCM stream at 25600 Hz
in 8-bit unsigned format. See the -A option for further details.
The sound quality is lousy, probably because of the single-threaded
nature of Xeuphoric.
PRINTER OUTPUT
FIXME - to be written
KEYBOARD INPUT
Xeuphoric maps one physical key of the host to exactly one physical key
of the Oric. Any keymap that may exist on the host is cheerfully
ignored. In particular, if you have an AZERTY keyboard and you press
the key labelled [a] on your physical keyboard, the virtual Oric thinks
you have pressed the [q] key on its virtual keyboard. Note that more
than one host key may be mapped to the same Oric key.
Here's a list of Oric keys along with the names of the PC keys that are
mapped to them. The host key names in the listing assume US layout.
Oric key Host key Oric key Host key
['] ['] [f] [f]
[,] [,] [g] [g]
[-] [-] [h] [h]
[.] [.] [i] [i]
[/] [/] [j] [j]
[0] [0] [k] [k]
[1] [1] [l] [l]
[2] [2] [le] [lctrl], [left]
[3] [3] [lshift] [<], [lshift]
[4] [4] [m] [m]
[5] [5] [n] [n]
[6] [6] [o] [o]
[7] [7] [p] [p]
[8] [8] [q] [q]
[9] [9] [r] [r]
[;] [;] [return] [enter]
[=] [=] [right] [right], [rctrl]
[[] [[] [rshift] [rshift]
[\] [\] [s] [s]
[]] []] [space] [space]
[a] [a] [t] [t]
[b] [b] [u] [u]
[c] [c] [up] [up], [ralt]
[ctrl] [capslk] [v] [v]
[d] [d] [w] [w]
[del] [backsp] [x] [x]
[down] [down], [lalt] [y] [y]
[e] [e] [z] [z]
[esc] [tab]
JOYSTICK INPUT
FIXME - to be written
CASSETTE I/O
All cassette I/O is emulated via files on the host. There are two
emulation modes, physical and logical. See the Euphoric documentation
for a description of the physical mode and how to activate it.
In logical mode, the Oric ROM is patched to use host files. read-sync
(E696h/E735h) is patched to locate the host file and open it in read-
only mode. read-byte (E630h/E6C9h) is patched to read a character from
the file opened by read-sync. write-sync (E6BAh/E75Ah) is patched to
compute the name of the host file, open it for writing, and write the
.tap header. write-byte (E5C6h/E65Eh) is patched to write a character
to the file opened by write-sync.
CSAVE
The CSAVE command is patched to take its argument, lower-case it,
append .tap and use that as a host file name. If you leave out the
argument (CSAVE ""), the host file is ________.tap (eight underscores).
There is no way to save to a file whose name contains upper case or
non-ASCII characters or doesn't have the .tap extension.
The host file is opened in truncate mode. However, the second and
subsequent times you CSAVE"", the host file is opened in append mode,
even if you CSAVE"" to other files in between. For example,
CSAVE"/TMP/FOO" overwrite /tmp/foo.tap
CSAVE"" overwrite ________.tap
CSAVE"/TMP/FOO" overwrite /tmp/foo.tap
CSAVE"" append to ________.tap
If the host file can't be opened, a diagnostic is printed to standard
error. If running in Atmos mode, 02B1h is also incremented. Warning:
write errors are not detected. Consider this a bug.
CLOAD
There exist a significant number of .tap files that don't follow the
same naming conventions as Xeuphoric (all-caps names, no extension,
extensions other than .tap). CLOAD attempts to be compatible with both
CSAVE and the more creatively named files out there by trying several
host file names in sequence :
#1 The name formed by lower-casing the argument and appending .tap.
#2 The name formed by appending .TAP to the argument.
#3 The name formed by lower-casing the argument.
#4 The argument.
For each name, Xeuphoric attempts to open the named file. If that
succeeds, we've got a winner. If that fails with error ENOENT ("No
such file or directory"), it goes on to the next name. If that fails
for any other reason, it prints an error message and returns to the
first name.
If all file names are exhausted, Xeuphoric returns to the first name.
Thus the algorithm loops until a name is successfully opened or CLOAD
is interrupted by NMI.
Leaving the argument out (CLOAD "") is equivalent to providing an
argument of ________ (eight underscores).
For example, here are two CLOAD commands along with the file names that
would be used:
CLOAD "/TMP/FOO"
/tmp/foo.tap
/TMP/FOO.TAP
/tmp/foo
/TMP/FOO
CLOAD ""
________.tap
________.TAP
________
Tape files
A tape file begins with the three-byte sequence 16h 16h 16h, normally
followed by 24h.
HOT KEYS
The following keys are special to Xeuphoric:
[f1] Switch between the emulation and the setup screen.
[f2] Toggle the sound (disabled).
[f4] Double the emulation clock frequency (or reset it to the nominal
value if it was below it). You can go as high as your hardware
will allow, up to 65,536 MHz.
[f5] Halve the emulation clock frequency (or reset it to the nominal
value if it was above it). You can go as low as you want as
long as the number of cycles per frame is an integer. With the
current value of 20,000 cycles per frame, the minimum clock
frequency is 31.25 kHz.
[f6] Jasmin boot.
[f7] Warm reset (NMI).
[f8] Cold reset (RES)
[f9] Dump and quit.
[f10] Quit.
[f12] Writes a screenshot in packed PPM format as xeuphoric_%03u.ppm.
FILES
Xeuphoric attempts to parse all the following config files in order:
/etc/xeuphoric/0.18.2/xeuphoricrc
~/.xeuphoric/0.18.2/xeuphoricrc
./.xeuphoricrc
Xeuphoric does not stop at the first match ; if all three files exist,
they're all parsed. Thus you can set defaults for all the parameters
in the system-wide config file. Users inherit those settings but can
override some or all of them from their personal config files.
Likewise, it's possible to override parameters on a per-directory basis
by creating a .xeuphoricrc file in that directory. For example, if
~/o1 contains an Oric-1 project you are working on, you can make
Xeuphoric start in Oric-1 mode by default in that directory by typing
echo Computer=Oric1 >~/o1/.xeuphoricrc.
The ROM files are searched for in the following directories:
.
~/.xeuphoric/0.18.2
/usr/local/share/xeuphoric/0.18.2
For a given file, the first match found is used. For example, it's
possible to use an alternative ROM file for a project by putting a copy
of that file in the directory where the project resides.
ENVIRONMENT
DISPLAY
The name of the X server to connect to.
HOME Used to locate config files and ROM files.
EXIT STATUS
0 OK
>0 An error occurred
BUGS
See TODO.
AUTHOR
André Majorel <URL:http://www.teaser.fr/~amajorel/>
Contributions by Jede <URL:http://www.oric.org/>
Euphoric was written by Fabrice Francès
<URL:http://homepage.ensica.fr/~frances/>
LEGAL
atmos.rom, microdisc.rom and oric1.rom are copyright 1983 Tangerine.
Tangerine is defunct. We don't know who the current assignee of the
copyright is (if any).
hyperbasic.rom, teleass.rom, telematic.rom and telemon-2.4.rom are
copyright Oric International. Oric International is defunct. We don't
know who the current assignee of the copyright is (if any).
jasmin.rom is copyright Technologie Recherche et Applications
Nouvelles. As far as I know, T.R.A.N. doesn't exist anymore. We don't
know who the current assignee of the copyright is (if any).
Euphoric 0.99b is copyright Fabrice Francès 1994-1997 and available
under the terms of version 2 of the GNU General Public License.
The rest is copyright André Majorel 2000-2004 and available under the
terms of version 2 of the GNU General Public License.
SEE ALSO
<URL:http://oric.free.fr/emulator.html>
ppm(5)
Xeuphoric 0.18.2 2004-08-21 XEUPHORIC(1)