This guide describes how to set up the xmcd device configuration file if your CD drive is not listed in xmcd's configuration script menu or if you encounter a drive configuration related difficulty using xmcd or cda.
Xmcd and cda use a very flexible configuration scheme that allows the software to adapt and function with just about any CD-ROM, CD-R, CD-RW or DVD drive. It may only require changing a parameter or two in the configuration file to make it all work.
All descriptions below refer only to xmcd for brevity. The same configuration files are used by xmcd and cda. If you have to change the configuration file to get your drive to work, contact the author and describe what you had to do. Please include your drive manufacturer, model number and the type of device that it is (i.e., SCSI or IDE/ATAPI, CD-ROM, CD-R or CD-RW).
If you cannot get your drive to work with xmcd using these instructions, you may also contact the author for help.
The device configuration file is:
where XMCDLIB is the xmcd library directory that was specified when installing xmcd, and DEVICE is the base name of the drive's device node. For example, if your XMCDLIB is /usr/lib/X11/xmcd and your drive is /dev/scd0, then the configuration file is /usr/lib/X11/xmcd/config/scd0.
This is a text file contains all the parameters that you can tweak. There are comments above each parameter which describe the function. You may edit this file with an editor and make changes. After a change you can re-start xmcd to check the behavior.
You may also run xmcd with the -debug command line option to see what it's doing (For xmcd version 3.0 and later, use -debug 3). If you write to the author for help, please include this debugging output in its entirety.
It is assumed that you have already installed the xmcd package on your system. The installation procedure is displayed on this web site when you downloaded the software. For the source code version of xmcd, the instructions are also found in the docs_d/INSTALL file.
To configure xmcd, you should run the XMCDLIB/config/config.sh script. This script is also run automatically when you install using "sh ./install.sh" (binary distribution) or "make install" (source code distribution, after compilation).
When you run config.sh, it configures xmcd for CDDB access, web browser, and CD drive. It is the CD drive configuration portion that you will see a menu of manufacturers. If your drive manufacturer is listed, select it. If not, choose "other (SCSI)" or "other (non-SCSI)" depending on the type of drive you have.
If you had selected a manufacturer, you will be presented with a list of drive models to choose from. If your drive is listed, congratulations. Select the appropriate drive and you are done. If not, then select another model from the same manufacturer which is the same type ("SCSI-1", "SCSI-2" or "OS driver ioctl" for non-SCSI drives). To decide which model to choose, look for a model number that is similar to yours. You may have a new-generation model that is not yet listed in xmcd's configuration menu, but is otherwise compatible with a previous model. For example, Toshiba's model number scheme generally use an increasing model number for each new generation of drive (XM-3501, XM-3601, XM-3701, etc).
If you choose "other (SCSI-2)", then you will be asked a number of questions about the capabilities of the drive. You may not know the answers, so just accept the defaults.
If you choose a non-SCSI drive configuration, you will be prompted to select an OS ioctl device interface method. Use the one that matches the operating system platform that you're running on.
If your drive is listed in xmcd's configuration menu, then everything should work. There may be some features that your drive doesn't implement, so those will not function. The features that are disabled in the configuration are displayed when you finish running the config.sh script. Also, the configuration data for most of the drives are contributed by users, and may require further fine-tuning. If you encounter an error with some xmcd features, use the hints outlined in this guide to adjust some of the xmcd's drive configuration parameters. If you discover errors in xmcd's configuration tables, please send corrections to the author so that the table would be fixed for the next release.
On recent versions of Linux and FreeBSD, you have the option of running IDE/ATAPI drives under SCSI-emulation. If your system kernel is configured to use this method, treat your drive as a generic SCSI drive for xmcd configuration purposes.
Likewise, some platforms employ SCSI-emulation for IDE/ATAPI drive support by default. These platforms are: BSDI/WindRiver BSD/OS, Digital UNIX/Compaq Tru64 UNIX 4.x and later, HP-UX 10.x and later, and SCO Open Server 5.x. The config.sh script automatically sets up IDE/ATAPI drives as "Generic SCSI" on these platforms. However, further manual fine-tuning may be needed to make use of all the drive's capabilities.
You should also read the DRIVES file that comes in the xmcd distribution for specific information about xmcd's drive support.
Now start xmcd and give it a spin.
NOTE: You will need to restart xmcd each time you change a parameter in the drive configuration file, in order to have it take effect. Be aware that sending an unsupported command to a drive sometimes causes the drive to misbehave or lock up. It may even cause a SCSI bus problem that could lead to a system crash. Type the sync(1) command prior to experimenting with these parameters, and do not do this on a mission-critical server.
There are several areas where drive capabilities and compatibilities differ from brand to brand (sometimes even model to model). Here are the symptoms of a misconfiguration:
Non-SCSI drives are supported by the CD-ROM driver in your kernel, The driver dictates the feature set supported and its compatibility with specific drives. The only parameters that may have an effect are:
Read the comments in the configuraion file about what these parameters affect.
If the REW and FF scan-search functionality does not work well, try adjusting the searchSkipBlocks and searchPauseInterval parameters to see if this may help the behavior. It may be better to use the "Track Warp" slider in the xmcd keypad sub-window instead, especially in the CDDA playback mode.
|*||These parameters were introduced in xmcd 2.5.|
|**||These parameters were introduced in xmcd 2.6.|
|***||These parameters were introduced in xmcd 3.2.0.|
|****||These parameters were introduced in xmcd 3.3.0.|
|Most CDDA-related parameters were introduced in xmcd 3.1.|
Most other CD player software do not require any configuration, and simply rely on the OS CD-ROM driver's ioctl code to control the drive. Xmcd can operate in this mode on many platforms, and in fact uses this method for non-SCSI drives. This often restricts xmcd from extracting the full capabilities of the drive. Hence, for SCSI drives (and for those platforms where IDE/ATAPI drives are handled via SCSI-emulation), xmcd uses the SCSI pass-through mechanism to deliver commands to the drive, in effect becoming a user-mode device driver. Since drives vary in capabilities and SCSI command support, it is necessary for xmcd to determine these drive-specific nuances in order to make the drives operate correctly and to their full capability.
Some players hard-code these configurations in the software. The vendor and model names (as returned by the SCSI "Inquiry" command) are then used as a key to determine the mode of operation. This method has the obvious disadvantage that code modification and recompilation needed in order to support new and different drives.
Some players attempt to perform "auto-probing" of the drive. Differing commands are sent to the drive to see if they succeed, and an internal capabilities table is then established. While this method has the benefit that code changes are not usually needed to support new drives, it has the risk of causing the drive to misbehave or lock-up, as some drives do not take unsupported commands gracefully.
Xmcd uses an external configuration file to set up a capabilities list. The config.sh script uses a directory full of support tables (one file for each CD drive manufacturer) so that the user needs only to select the manufacturer and model of the drive from interactive configuration menus, and the configuration file will be filled in with the appropriate capabilities. For new drives or drives that do not appear in the config.sh menus, this guide provides help on getting the drive to work by manually editing the configuration file. There is no auto-probing of the drive each time xmcd is run. The configuration file is external, so no code modifications or recompilation is needed to adapt xmcd to new and different drives.
Many users would prefer to have the software work without any configuration. However, given the above facts it becomes apparent that the xmcd way of drive configuration is the best method to make use of the full capabilities of the drive. Fortunately, xmcd drive configuration only needs to be done once after installation (or after drive replacement with a different brand/model), so the inconvenience is minimal.