@(#)RELNOTES	6.22 02/05/17

XMCD/CDA RELEASE NOTES
----------------------

General Notes
-------------

Xmcd works best on an X display with a three-button mouse.  Most features
are operated with the left mouse button, and feature-specific help can
be invoked with the right mouse button.  In addition, xmcd supports
copy-and-paste between its text fields as well as with other compliant
X and Motif applications (such as xterm).  The left button is used for
highlighting and copying, and the middle button is used for pasting.

This distribution comes with several 32x32 pixmap files suitable
for use as an xmcd desktop icon.  These are installed in
XMCDLIB/pixmaps:

    xmcd.icon - for Novell/SCO UnixWare 2.x, 2 colors
    xmcd_a.px - for SCO Open Desktop (XPM2 format), 2 colors
    xmcd_b.px - for SCO Open Desktop (XPM2 C format), 2 colors
    xmcd.xpm  - for other systems that use XPM format, 2 colors

You can use the appropriate icon setup utilities under each of
these environments to create an xmcd icon (with which you can use to
launch xmcd).

Your xmcd/cda executable binary should only be run on the same OS
platform group that it was compiled on.  For example, UNIX SVR4.0
binaries must not be run on a UNIX SVR4.2 system.  Likewise, a binary
compiled on a SunOS 4.x platform cannot be used on a Sun Solaris 2.x
and later system.

The XMCDLIB/app-defaults/XMcd file contains several long lines broken
into separate lines using the "\" continuation marker (in particular,
the "XMcd*someWidgetName.fontList" lines).  This has been known to cause
error messages on some Motif implementations.  If you encounter such a
problem, the remedy is to remove the "\" continuation markers and join
the multiple lines back into a single line.

The default xmcd *.fontList resources in the XMCDLIB/app-defaults/XMcd
file are appropriate for 75dpi fonts.  If you are using 100dpi the
*.fontList resource may need adjustments.  Use the xlsfonts(1) command
to see the list of available fonts for your display.

Do not use xmcd/cda if the CD-ROM drive contains a mounted filesystem
data disc (ISO-9660, High Sierra or other formats).  Always use the
"df" or "mount" command to check if such a filesystem is mounted
before invoking the application.

Certain OS platforms will print console error messages or record error
messages in a log file if the CD device is accessed without a CD loaded
in the drive.  If you encounter this situation, the workaround is to
load a CD in the drive before starting xmcd or cda, and refrain from
leaving xmcd in the "no disc" state for an extended period of time.

Unless otherwise instructed by your OS or system hardware vendor,
it is generally a bad idea to turn off the power of the CD-ROM drive
while the operating system is running.  Cycling the power may
cause the CD-ROM drive to assert a SCSI bus reset or otherwise glitch
the SCSI bus, which is not always gracefully handled by the SCSI
adapter or your system's SCSI device driver (i.e., possible system
hang or crash).  Thus, it is best to turn on the CD-ROM drive
before booting the OS, and do not turn it off until after OS shutdown.


Security Notes
--------------

Xmcd and cda must be installed as a suid-root program on many platforms.
This is because these utilities use the SCSI pass-through mechanism to
control the CD-ROM drive, which requires root privilege on many systems.
Security issues have been addressed, however, since they will refuse
to send any more command to a device if the initial inquiry shows that
the device is not a CD-ROM or WORM device.  Also, xmcd changes the uid
and gid to that of the real user before reading/writing any files,
accessing CDDB services or executing external programs.

On systems that do not require super-user privilege for SCSI
pass-through, it is actually more secure to turn off the user and group
permissions of the SCSI device nodes, and make xmcd and cda suid-root.
This prevents malicious users from writing other programs that send
arbitrary commands to the devices.

Xmcd and cda have also been developed, debugged, scrutinized and
rigorously tested with security as a very high priority.  If, despite
this, you feel uncomfortable about the suid aspect of xmcd/cda then
please do not use these applications.

Exceptions to the suid-root requirement:  If you configure xmcd
and cda to operate the drive via the "SunOS/Solaris/Linux ioctl
method" the "FreeBSD/NetBSD/OpenBSD ioctl method" or the "AIX IDE ioctl
method" (see the NON-SCSI DRIVES section in the DRIVES file), suid-root
privilege is not required.  Likewise, suid-root permissions is not
required on Solaris systems.  Also, the suid requirement does not
apply on the Digital OpenVMS platform.  Lastly, suid-root privilege
is required on QNX.

If your platform does not require suid-root priviledge and you are
installing xmcd and cda as a non-root user, then you must have read
and write permissions to the specified BINDIR, XMCDLIB and MANDIR
directories.

If you run xmcd/cda without suid-root privilege, then you must make
sure that the CD-ROM drive devide node has the appropriate permissions
for "other" users.  On most platforms it is sufficient to have read-only
permission, others may also require write permission.


CDDA (CD digital audio) Notes
-----------------------------

Please refer to the xmcd and cda man pages for a general description
of the "standard" and "CDDA" playback modes.

The CDDA modes imposes much higher system CPU loads than the standard
mode, and requires a high performance computer system not laden with
other CPU-intensive tasks in order to play smoothly without audible
glitches and drop-outs.  This is particularly true if jitter correction
is enabled (which is required of many CD drives).  CDDA performance is
heavily dependent on the speed of the CD drive, the read chunk size,
and the system's overall performance.  Note that many drives transfer
CDDA much more slowly than CD-ROM data (e.g., Some drives advertised
as "15x" can only transfer CDDA at 1x, and are not well suited for
real-time CDDA playback).  In general, a minimum configuration for
CDDA playback is as follows:

    250MHz CPU or better
    CD drive capable of 2x CDDA transfer or better

The default xmcd start-up mode can be altered via the playMode parameter
in the device-specific configuration files.

Platform support for the CDDA modes for this release of xmcd/cda is
as follows:

    IBM AIX 4.x (*)
    BSDI/WindRiver BSD/OS 2.x and later (*)
    Digital UNIX 4.x, Compaq Tru64 UNIX 5.x (*)
    FreeBSD 3.x and later
    HP-UX 9.x and later
    Linux 2.x and later
    SCO UNIX 3.2v4.x, Open Desktop 2.x, Open Desktop 3.x, Open Server 5.x
    SCO UnixWare 2.1.x, 7.x, Caldera Open UNIX 8.x
    SunOS 4.1.x
    Sun Solaris 2.x and later

CDDA support for platforms denoted with (*) is implemented, but not well
tested.

The OSS (Open Sound System http://www.opensound.com) CDDA write method
is supported on the above listed platforms, if OSS is available for it.
The native Linux sound driver and Solaris audio driver are also supported
on Linux and Solaris, respectively.

The native Digital UNIX/Compaq Tru64 UNIX, IBM AIX, HP-UX and SunOS 4.x
audio drivers are *not* supported at this time.  Hence, real-time CDDA
audio playback is only possible with the OSS sound driver (if available
and installed) on these platforms.

Not all CD drives nor all hardware configurations support real-time
CDDA playback.  On some of these systems only the CDDA "save-to-file"
and "pipe-to-program" modes can be used with xmcd and cda.

Only SCSI CD drives are supported for CDDA operation on SCO UnixWare and
Caldera Open UNIX.

On Linux, it is advisable to run ATAPI/IDE drives under SCSI emulation
(using the ide-scsi driver) and configure xmcd to run the drive as
a generic SCSI drive.  This yields better results.

Some platform/HBA card combinations impose a maximum CDDA read
chunk size of 16KB or lower.  It may be possible to use a CDDA mode only
with jitter correction disabled on these systems, because jitter
correction adds additional CDDA blocks to each transfer than that
specified by the cddaReadChunkBlocks parameter.

The xmcd/cda drive configuration table has been expanded to add support
for CDDA capabilities.  The author does not have samples of all the
drives to personally test the settings, therefore it is likely that the
xmcd configuration process may yield incorrect results for some drives.
If you have a CDDA-capable drive running on one of the above supported
platforms, and the CDDA feature does not work, try following the
procedures outlined in the "Xmcd Configuration Guide" at
http://www.amb.org/xmcd/ (Click on "Configuration Guide").  Kindly
send any updated configuration information to xmcd@amb.org so that
the configuration table may be corrected for future releases.


Problem Reporting
-----------------

Although xmcd and cda should run reliably on the supported platforms
and CD hardware as noted, if you encounter a problem, please send a
report to "xmcd@amb.org" with detailed descriptions of the configuration
and problem symptoms.  It would also be helpful to reproduce the
problem while running either application with the -debug option (see the
xmcd(1) and cda(1) man pages for the appropriate debug levels to use),
and capture the diagnostic output.  Send the output to the author for
examination.  Please also include detailed information about your
software and hardware configuration.

Better yet, send bug fixes!


Porting Xmcd
------------

The modular design of xmcd and cda is such that support for other UNIX
environments and CD-ROM drives can be readily added.  See the PORTING
file for details if you are interested in contributing to the development
effort.  Before you start a porting effort or add significant code,
contact the author to ensure that this effort isn't being duplicated
by others.


Uninstalling Xmcd
-----------------

If you wish to remove the installed xmcd and cda executables and support
files from your system, this is how to do it:

    1. Log in as root
    2. cd BINDIR
       rm xmcd cda .xmcd_start
    3. rm -r XMCDLIB

BINDIR is the executable directory that you specified when installing
xmcd.  XMCDLIB is the top level directory of the xmcd library directory
hierarchy.

In addition, each xmcd user will have a $HOME/.xmcdcfg directory that may
be removed.

You may also remove the CDDB library symbolic link, if it exists.
These are usually named libcddb.so.1 and libcddb2.so, installed in the
/usr/lib or /usr/local/lib directory on your system (on HP-UX, the file
is libcddb2.sl).

