XEUPHORIC(1) XEUPHORIC(1)
NAME
xeuphoric - an Oric emulator for X
SYNOPSIS
xeuphoric --help
xeuphoric --version
xeuphoric [-1|a|t] [-djJpQr] [-A file] [-R file] [-s num] [-S
arts|auto|oss] [-X always|auto|never] [-z num] [file ...]
DESCRIPTION
Xeuphoric is an Oric emulator for X. It emulates the Oric-1, the Oric
Atmos and the Telestrat. It is derived from version 0.99b of Euphoric.
Xeuphoric has a single window and three modes (or "screens") :
emulation, setup and file selector.
+-----------+ +--------+ +----------+
| | [f1] | | [ret] | |
| Emulation | -----> | Setup | -------------> | File |
| screen | <----- | screen | <------------- | selector |
| | [f1] | | [esc], [ret] | |
+-----------+ +--------+ +----------+
The following keys are caught by the emulator and never passed to the
virtual Oric :
[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.
Emulation screen
In emulation mode, the window shows the video output of the virtual
Oric and most keystrokes are passed to the virtual Oric. See the
EMULATION section for further details.
Setup screen
While in the setup screen, emulation is paused and all keystrokes are
caught by the emulator. The top line contains the string "Setup" and
the version number of Xeuphoric. The following options are available :
CWD The current working directory of the Xeuphoric process. This
affects certain aspects of Xeuphoric's operation, notably
cassette and diskette emulation. To change directory, press
[ret].
Colour scheme
See ColourScheme in the CONFIGURATION VARIABLES section.
FD1 Diskette image (.dsk file) in virtual drive A. This item is
enabled if diskette emulation is (-d or -j). The label on the
right reflects the write-protect status of the virtual
diskette : "RW" stands for read/write, "RO" stands for read-
only. A virtual diskette is writable if and only if the
diskette image could be opened for writing ; there is no way to
write-protect a virtual diskette when the underlying file is
writable.
FD2 Same as FD1 but for drive B.
FD3 Same as FD1 but for drive C.
FD4 Same as FD1 but for drive D.
Hardware Tape
FIXME to be written.
Clock Speed
FIXME to be written.
Sound FIXME to be written.
NumPad FIXME to be written.
File Selector
The top line shows the name of the current directory. Below is a list
of the entries it contains. The first field is the size of the entry
in bytes, using a k/M/G/T/P/E/Z/Y suffix if it would exceed 6 digits.
The second field is the mtime of the entry, in YYYY-MM-DD format. The
third field is the name followed by a file type indicator similar to ls
-F. The entries are sorted by name, with all the directories at the
top. Non-printable and non-ASCII characters are percent-encoded (see
RFC 1738/2396/3986). Names too long to fit in the screen are
abbreviated with an ellipsis (...) in the middle.
The bottom two lines give a list of the available keys, which is a
subset of :
[up] Move the previous item in the list.
[down] Move the next item in the list.
[pu] Move one page up in the list.
[pd] Move one page down in the list.
[home] Move to the first item in the list.
[end] Move to the last item in the list.
[left] Change to the parent directory (..) unless already at the root
(/).
[right] Descend into the current item if it is a directory.
[ret] Select the current item. If the file selector was entered to
select a file and the current item is a directory, [ret] is
ignored. If the file selector was entered to select a
directory and the current item is a non-directory, its parent
directory is selected instead.
[esc] Quit the file selector without selecting anything.
Prior to release 0.19.0, the file selector parsed the output of ls(1)
and changed the current working directory of the Xeuphoric process.
OPTIONS
If the first argument is --help, Xeuphoric writes a usage summary to
standard output and exits successfully.
If the first argument is --version, Xeuphoric writes its version number
to 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 and -1t are
mutually exclusive.
-R file Use file as a ROM in place of atmos_name/oric1_name.
-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 for 8-bit
signed 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 is available and fall back on regular
XImages otherwise. This is the default.
never Do not use XShm, even if it is available.
-z num Set the zoom factor to num. Permitted values are 1, 2 and 3.
The default is 2.
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.
EMULATION
Video Output
The video output of the ULA is shown on a 240 × 224 window (times the
zoom factor). The emulation is believed to be accurate for most uses
except for the 60-Hz attribute which is ignored.
Effects which rely on sub-frame timing will not be emulated properly.
The video output of a real Oric is progressive ; Xeuphoric renders the
entire frame at once from a snapshot of the video RAM. The frame rate
is also slightly off (20,000 cycles instead of 19,968).
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.
The video emulation is influenced by the ColourScheme variable.
Sound Output
Xeuphoric emulates the 8912 by generating a mono PCM stream at 25600 Hz
in 8-bit signed 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 host key to exactly one Oric key. 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 is 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. On a French keyboard, [ralt] is [altgr].
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] [left] [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], [del] [x] [x]
[down] [down], [lalt] [y] [y]
[e] [e] [z] [z]
[esc] [tab], [esc]
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 the argument is left
out (CSAVE ""), the host file is ________.tap (eight underscores).
By passing CSAVE a Unix pathname, one can save to a file anywhere in
the file system and not just in the current working directory. For
example, assuming the current working directory is /home/me/oric,
CSAVE "FOO" will save to /home/me/oric/foo.tap,
CSAVE "SUBDIR/FOO" will save to /home/me/oric/subdir/foo.tap,
CSAVE "../ORIC2/FOO" will save to /home/me/oric2/foo.tap and
CSAVE "/TMP/FOO" will save to /tmp/foo.tap.
However, this will only work as long as the desired pathname minus the
.tap extension is no longer than 16 characters. Furthermore, the path
will appear in the .tap header, which might not be desired. For these
reasons, it is generally preferable to switch to the target directory
and pass CSAVE a basename without a path.
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, after the
sequence
CSAVE "FOO"
CSAVE ""
CSAVE "FOO"
CSAVE ""
foo.tap would contain one save and ________.tap two.
If the host file cannot be opened, a diagnostic is written 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 writes an error message to stderr 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 tried :
CLOAD "FOO"
foo.tap
FOO.TAP
foo
FOO
CLOAD ""
________.tap
________.TAP
________
By passing CLOAD a Unix pathname, one can load a file anywhere in the
file system and not just in the current working directory. However,
this will only work as long as the pathname minus the .tap extension is
no longer than 16 characters. Furthermore, the path will be part of
the name to load, which might not be desired. For these reasons, it is
generally preferable to switch to the target directory and pass CLOAD a
basename without a path.
Tape files
A tape file begins with the three-byte sequence 16h 16h 16h, normally
followed by 24h.
Diskette I/O
FIXME - to be written
CONFIGURATION VARIABLES
Machine to emulate
Computer (string)
This variable can take the following values:
Oric1 Emulate an Oric-1.
Atmos Emulate an Oric Atmos.
Telestrat
Emulate a Telestrat.
Stratos
Same as Telestrat.
Invalid values are currently not caught.
Oric1Rom (file name)
Sets oric1_name.
AtmosRom (file name)
Sets atmos_name.
Bank1 (file name)
Sets bank_name[1].
Bank2 (file name)
Sets bank_name[2].
Bank3 (file name)
Sets bank_name[3].
Bank4 (file name)
Sets bank_name[4].
Bank5 (file name)
Sets bank_name[5].
Bank6 (file name)
Sets bank_name[6].
Bank7 (file name)
Sets bank_name[7].
Clock (real)
Sets cycles and initial_cycles to its value rounded down to one
digit after the decimal point times 20,000.
RamPattern (bool)
Sets ram_pattern to false if the value of is empty of if the
ASCII code of its first character is even, true otherwise.
DumpFile (file name)
Sets dump_name.
Peripherals to emulate
DiskController (string)
This variable can take the following values:
Microdisc
Emulate a Microdisc floppy disk controller.
Jasmin Emulate a Jasmin floppy disk controller.
Invalid values are currently not caught.
MicrodiscEprom (file name)
Sets microdisc_name.
JasminEprom (file name)
Sets jasmin_name.
DriveA (bool)
Sets drives[0] to true if the value is empty or its first
character is not "n" or "N", false otherwise.
DriveB (bool)
Sets drives[1] to true if the value is empty or its first
character is not "n" or "N", false otherwise.
DriveC (bool)
Sets drives[2] to true if the value is empty or its first
character is not "n" or "N", false otherwise.
DriveD (bool)
Sets drives[3] to true if the value is empty or its first
character is not "n" or "N", false otherwise.
AsynchronousController (bool)
Sets acia to true if the value is empty or its first character
is not "n" or "N", false otherwise.
SerialPort (file name)
Sets serial_name.
RealTimeClock (bool)
Sets rtclock to true if the value is empty or its first
character is not "n" or "N", false otherwise.
Joystick (bool)
Sets joystick to true if the value is empty or its first
character is not "n" or "N", false otherwise.
JoystickPort (bool)
Sets joystickport to true if the value is empty or its first
character is not "n" or "N", false otherwise.
Printer (bool)
Sets printer to true if the value is empty or its first
character is not "n" or "N", false otherwise.
PrinterOutput (file name)
Sets printer_name.
Video
ColourScheme (string)
This variable can take the following values:
normal Same colours as a real oric. The eight foreground
colours are #000, #f00, #0f0, #ff0, #00f, #f0f, #0ff and
#fff. The eight background colours are identical. This
is the default.
bg50 Same as normal except that each background colour has
50% of the intensity of its foreground counterpart, E.G.
#088 instead of #0ff.
bg75 Same as normal except that each background colour has
75% of the intensity of its foreground counterpart, E.G.
#0cc instead of #0ff.
bgfog25 Same as normal except that each background colour is one
quarter of the way between grey (#888) and its normal
value, E.G. #2ee instead of #0ff.
bgfog50 Same as normal except that each background colour is
halfway between grey (#888) and its normal value, E.G.
#4cc instead of #0ff.
bgfog75 Same as normal except that each background colour is
three quarters of the way between its normal value and
grey (#888), E.G. #6aa instead of #0ff.
At the moment, ColourScheme has no effect on [f12] screenshots
and might misbehave on non-TrueColor visuals.
This variable is for the curious who would like to understand
what an Oric program does with the screen. Still a poor
substitute for an attribute view of the video RAM, I'm afraid.
FILES
Xeuphoric attempts to parse all the following config files in order:
/etc/xeuphoric/0.19.0/xeuphoricrc
~/.xeuphoric/0.19.0/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.19.0
/usr/local/share/xeuphoric/0.19.0
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.
GLOSSARY
6522 VIA
8912 PSG
Cassette Tape
Diskette Floppy disc drive, Floppy disk drive, FDC, FDD
[down] Arrow key, Cursor key
[esc] Escape key
[left] Arrow key, Cursor key
[pd] Page down, Page-down, pg dn, pgdn key
Printer Centronics, LP, LPT, Parallel
[pu] Page up, Page-up, pg up, pgup key
[ret] Return key, Enter key
[right] Arrow key, Cursor key
Setup screen Config screen, Environment screen
Sound 8912, Audio, PSG
[up] Arrow key, Cursor key
Zoom factor Magnification, Scale
AUTHOR
André Majorel http://www.teaser.fr/~amajorel/
Contributions by Jede http://www.oric.org/
Euphoric was written by Fabrice Francès
http://homepage.ensica.fr/~frances/
LEGAL
atmos.rom, microdisc.rom and oric1.rom are copyright Tangerine 1983.
Tangerine is defunct. We don't know who might hold the copyright.
hyperbasic.rom, teleass.rom, telematic.rom and telemon-2.4.rom are
copyright Oric International. Oric International is defunct. We don't
know who might hold the copyright.
jasmin.rom is copyright Technologie Recherche et Applications
Nouvelles. T.R.A.N. is apparently defunct. We don't know who might
hold the copyright.
Euphoric 0.99b is copyright Fabrice Francès 1994-1997 and available
under the terms of the GNU General Public License version 2.
The rest is copyright André Majorel 2000-2010 and available under the
terms of the GNU General Public License version 2.
SEE ALSO
doc/euphoric-0.99b (the original Euphoric documentation)
http://oric.free.fr/emulator.html
ppm(5)
Xeuphoric 0.19.0 2010-08-24 XEUPHORIC(1)