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)