This README belongs to release 3.4 or newer of the SoundBlaster Pro
(Matsushita, Kotobuki, Panasonic, CreativeLabs, Longshine and soon TEAC, too)
CD-ROM driver for Linux.

The driver is able to drive the whole family of "traditional" IDE-style (that
has nothing to do with the new "Enhanced IDE" drive standard) Matsushita,
Kotobuki, Panasonic drives, sometimes labelled as "CreativeLabs". The
well-known drives are CR-521, CR-522, CR-523, CR-562, CR-563.

The Longshine LCS-7260 is a double-speed drive which uses the "old"
Matsushita command set. It is supported now - with help by Serge Robyns.

There exists an "IBM External ISA CD-ROM Drive" which in fact is a CR-563
with a special controller board. This drive is supported (the interface is
of the "LaserMate" type), and it is possibly the best buy today (cheaper than
an internal drive, and you can use it as an internal, too - f.e. plug it into
a soundcard).

The quad-speed TEAC CD-55A drive uses the same interface types, but has a
totally different command and flow control scheme. Support is under
construction, but splitted: Greg Nowicki (nowicki@tardis.larc.nasa.gov)
cares about the separate driver "teaccd". Please, do not mail him merely for
asking "user questions" at the moment - the project is still a "baby".

CreativeLabs has a new drive "CD-200". Support is under construction.
Detection should already work.

Regarding CD200 support:
    Please, don't mail me about it if you are not a competent BETA tester 
            (if you are: mail!; I do not have such drives).
    Please, don't drop simple questions about the new drives in the
            newsgroups. Full support needs more or less time.
If you like to help, you can mail me the "SBPCD:..." messages, regarding the
new drives. But I mostly will not answer (just use) it.

This driver is NOT for Mitsumi or Sony or Aztech or Philips or XXX drives,
and this driver is in no way usable for any new IDE ATAPI drive.
For Aztech CDA-268 drives (and for some Wearnes, Okano and Orchid drives),
Werner Zimmermann has done a driver which currently resides at ftp.gwdg.de
under /pub/linux/cdrom/drivers/aztech/.

This driver will work with the soundcard interfaces (SB Pro, SB 16, Galaxy,
SoundFX, ...) and/or with the "no-sound" cards (Panasonic CI-101P, LaserMate,
WDH-7001C, Longshine LCS-6853, older Aztech cards, ...).

It should work too now with the "configurable" interface "Sequoia S-1000",
which is found on the Spea Media FX sound card. I still need feedback about
this, or such a card. Anyways, the procedure "boot DOS and wait until 
CONFIG.SYS is done, then use CTL-ALT-DEL to boot Linux" should make it
work.

The interface type has to get configured in /usr/include/linux/sbpcd.h, 
because the behavior of some sound card interfaces is different.

The driver respects all known drive firmware releases - my old drive is a 2.11,
but it should work with "old" drives <2.01 ... >3.00 and with "new" drives
(which count the releases around 0.75 or 1.00).

Up to 4 drives per interface card, and up to 4 interface cards are supported.
All supported drive families can be mixed, but the CR-521 drives are 
hard-wired to drive ID 0. The drives have to use different drive IDs, and each
drive has to get a unique minor number (0...3), corresponding indirectly to 
its drive ID.
The drive IDs may be selected freely from 0 to 3 - they do not have to be in
consecutive order.

As Don Carroll, don@ds9.us.dell.com or FIDO 1:382/14, told me, it is possible
to change old drives to any ID, too. He writes in this sense:
   "In order to be able to use more than one single speed drive
   (they do not have the ID jumpers) you must add a DIP switch
   and two resistors. The pads are already on the board next to
   the power connector. You will see the silkscreen for the
   switch if you remove the top cover.
                    1 2 3 4
             ID 0 = x F F x             O = "on"
             ID 1 = x O F x             F = "off"
             ID 2 = x F O x             x = "don't care"
             ID 3 = x O O x
   Next to the switch are the positions for R76 (7k) and R78
   (12k). I had to play around with the resistor values - ID 3
   did not work with other values. If the values are not good,
   ID 3 behaves like ID 0."

To use more than 4 drives, you simply need a second controller card at a 
different address and a second cable.

The driver supports reading of data from the CD and playing of audio tracks.
The audio part should run with WorkMan, xcdplayer, with the "non-X11" products
CDplayer and WorkBone - tell me if it is not compatible with other software.

With the CR-562 and CR-563 drives, the reading of audio frames is possible.
This is implemented by an IOCTL function which per default reads only up to
4 frames of 2352 bytes at once (configurable with the "READ_AUDIO" define).
Reading the same frame a second time gives different data; the frame data 
start at a different position, but all read bytes are valid, and we always
read 98 consecutive chunks (of 24 Bytes) as a frame. Reading more than 1 frame
at once misses some chunks at each frame boundary.This lack has to get 
corrected by external, "higher level" software which reads the same frame 
again and tries to find and eliminate overlapping chunks (24-byte-pieces).

The transfer rate with reading audio (1-frame-pieces) is as slow as 32 kB/sec.
This could be better reading bigger chunks, but the "missing" chunks occur at
the beginning of each single frame.
The software interface possibly may change a bit the day the SCSI driver
supports it too.

With the CR-562 and CR-563 drives, MultiSession is supported.
Photo CDs work (the "old" drives like CR-521 can access only the first
session of a photoCD).
At ftp.gwdg.de:/pub/linux/hpcdtoppm/ you will find Hadmut Danisch's package to
convert photo CD image files and Gerd Knorr's viewing utility.

The transfer rate will reach 150 kB/sec with "old" drives and 300 kB/sec with
double-speed drives. XA (PhotoCD) disks with "old" drives give only 50 kB/sec.

This release is part of the standard kernel and consists of
- this README file
- the driver file linux/drivers/block/sbpcd.c
- the header file linux/include/linux/sbpcd.h.


To install:
-----------

1. Setup your hardware parameters. Though the driver does "auto-probing" at a
   lot of (not all possible!) addresses, this step is recommended for
   every-day use.
   a. Go into /usr/src/linux/include/linux/sbpcd.h and configure it for your
      hardware (near the beginning):
      a1. Set it up for the appropriate type of interface board.
          "Original" CreativeLabs sound cards need "SBPRO 1".
          Most "compatible" sound cards (for example "Highscreen", "SoundFX"
          and "Galaxy") need "SBPRO 0".
          The "no-sound" board from OmniCd needs the "SBPRO 1" setup.
          All other "no-sound" boards need the "SBPRO 0" setup.
          The Spea Media FX sound card needs "SBPRO 2".
          sbpcd.c holds some examples in its auto-probe list.
          If you configure "SBPRO" wrong, the playing of audio CDs will work,
          but you will not be able to mount a data CD.
      a2. Tell the address of your CDROM_PORT (not of the sound port).
   b. Additionally for 2.a1 and 2.a2, the setup may be done during
      boot time (via the "kernel command line" or "LILO option"):
          sbpcd=0x230,SoundBlaster
      or
          sbpcd=0x320,LaserMate
      or
          sbpcd=0x330,SPEA
      (these strings are case sensitive!).
      This is especially useful if you install a fresh distribution.
2. "cd /usr/src/linux" and do a "make config" and select "y" for Matsushita
   CD-ROM support and for ISO9660 FileSystem support. If you do not have a
   second, third, or fourth controller installed, do not say "y" to the 
   secondary Matsushita CD-ROM questions.
   SCSI and/or SCSI CD-ROM support is not needed.

3. Then do a "make dep", then make the kernel image ("make zlilo" or else).

4. Make the device file(s). The driver uses definitely and exclusive the
   MAJOR 25, so do
        mknod /dev/sbpcd  b 25 0       (if you have only one drive)
   and/or
        mknod /dev/sbpcd0 b 25 0
        mknod /dev/sbpcd1 b 25 1
        mknod /dev/sbpcd2 b 25 2
        mknod /dev/sbpcd3 b 25 3
   to make the node(s).

   The driver no longer uses the "AT bus style" device numbering; the SCSI
   scheme is used now; that means, the "first found" drive gets MINOR 0
   (regardless to its jumpered ID), the "next found" (at the same cable)
   gets MINOR 1, ...
   
   For a second interface board, you have to make nodes like
        mknod /dev/sbpcd4 b 26 0
        mknod /dev/sbpcd5 b 26 1
   and so on. Use the MAJORs 26, 27, 28.

   If you further make a link like
        ln -s sbpcd /dev/cdrom
   you can use the name /dev/cdrom, too.

5. Reboot with the new kernel.

You should now be able to do
              mkdir /CD
and 
              mount -t iso9660 -o ro /dev/sbpcd /CD
or
              mount -t iso9660 -o ro,block=2048 /dev/sbpcd /CD
and see the contents of your CD in the /CD directory, and/or hear music with
"workman -c /dev/sbpcd &".


Using sbpcd as a "loadable module":
-----------------------------------

If you do NOT select "Matsushita/Panasonic CDROM driver support" during the
"make config" of your kernel, you can build the "loadable module" sbpcd.o.
Read /usr/src/linux/README.modules on this.

If sbpcd gets used as a module, the "audio copy" feature is disabled, and the
internal read-ahead buffer has a reduced size (the latter may affect throughput
a little bit under "slow" CPUs). Further, support of more than one interface
card (i.e. drives 4...15) is disabled.


Things of interest:
-------------------

The driver is configured to try the LaserMate type of interface at I/O port
0x0340 first. If this is not appropriate, sbpcd.h should get changed
(you will find the right place - just at the beginning).

No DMA and no IRQ is used.

To reduce or increase the amount of kernel messages, edit sbpcd.c and play
with the "DBG_xxx" switches (initialization of the variable "sbpcd_debug").
This is the way to get rid of the initial warning message block, too.

The driver uses the "variable BLOCK_SIZE" feature. To use it, you have to
specify "block=2048" as a mount option. Doing this will disable the direct
execution of a binary from the CD; you have to copy it to a device with the
standard BLOCK_SIZE (1024) before. So, do not use this if your system is
directly "running from the CDROM" (like some of YGGDRASIL's installation
variants). There are CDs on the market (like the german "unifix" Linux
distribution) which MUST get handled with a block_size of 1024. Generally,
one can say all the CDs which hold files of the name YMTRANS.TBL are defective;
do not use block=2048 with those.

At the beginning of sbpcd.c, you will find some "#define"s (f.e. EJECT and
JUKEBOX). With that, you can configure the driver for some special things.
The following program disables the auto-eject feature during runtime:

/*=================== begin program ========================================*/
/*
 * set the "eject" switch (enable/disable auto-ejecting)
 *
 * (c) 1994 Eberhard Moenkeberg <emoenke@gwdg.de>
 *          may be used & enhanced freely
 *
 * Disables or enables the auto-eject feature at run time.
 * Works only if a CD is in the drive (just like the feature itself ;-) 
 * Useful for a "quiet" shutdown or for weird audio player programs.
 */
#define EJECT 0 /* 0: disable, 1: enable auto-ejecting */

#include <stdio.h>
#include <sys/ioctl.h>
#include <linux/cdrom.h>

static char arg=EJECT;
static int drive;
static int err;

main(int argc, char *argv[])
{
/*
 * open /dev/cdrom
 */
  drive=open("/dev/cdrom", 0);
  if (drive<0)
    {
      fprintf(stderr, "can't open drive /dev/cdrom.\n");
      exit (-1);
    }
/*
 * set EJECT_SW
 */
  err=ioctl(drive, CDROMEJECT_SW, arg);
  if (err!=0)
    {
      fprintf(stderr, "can't set EJECT_SW (error %d).\n", err);
      exit (-1);
    }
  else
    fprintf(stdout, "EJECT_SW set to %d\n", arg);
}
/*===================== end program ========================================*/

Jeff Tranter's "eject" utility can do this, too (and more) for you.

There is a new ioctl CDROMMULTISESSION to obtain with a user program if
the CD is an XA disk and - if it is - where the last session starts. The
following example illustrates how to call it:

/*=================== begin program ========================================*/
/*
 * ask for multisession redirection info
 *
 * (c) 1994 Eberhard Moenkeberg <emoenke@gwdg.de>
 *          may be used & enhanced freely
 *
 */
#include <stdio.h>
#include <sys/ioctl.h>
#include <linux/cdrom.h>

static struct cdrom_multisession ms_info;
static int drive;
static int err;

main(int argc, char *argv[])
{
/*
 * open /dev/cdrom
 */
  drive=open("/dev/cdrom", 0);
  if (drive<0)
    {
      fprintf(stderr, "can't open drive /dev/cdrom.\n");
      exit (-1);
    }
/*
 * 
 */
  ms_info.addr_format=CDROM_LBA;
  err=ioctl(drive, CDROMMULTISESSION, &ms_info);
  if (err!=0)
    {
      fprintf(stderr, "CDROMMULTISESSION(lba) returns error %d.\n", err);
      exit (-1);
    }
  else
	if (ms_info.xa_flag)
	    fprintf(stdout, "lba: %d\n", ms_info.addr.lba);
	else
	    fprintf(stdout, "not an XA disk.\n");

  ms_info.addr_format=CDROM_MSF;
  err=ioctl(drive, CDROMMULTISESSION, &ms_info);
  if (err!=0)
    {
      fprintf(stderr, "CDROMMULTISESSION(msf) returns error %d.\n", err);
      exit (-1);
    }
  else
	if (ms_info.xa_flag)
	    fprintf(stdout, "msf: %02d:%02d:%02d\n",
				 ms_info.addr.msf.minute,
				 ms_info.addr.msf.second,
				 ms_info.addr.msf.frame);
	else
	    fprintf(stdout, "not an XA disk.\n");
}
/*===================== end program ========================================*/


Auto-probing at boot time:
--------------------------

The driver does auto-probing at many well-known interface card addresses,
but not all:
Some probings can cause a hang if an NE2000 ethernet card gets touched, because
SBPCD's auto-probing happens before the initialization of the net drivers.
Those "hazardous" addresses are excluded from auto-probing; the "kernel 
command line" feature has to be used during installation if you have your 
drive at those addresses.

The auto-probing looks first at the configured address resp. the address
submitted by the kernel command line. With this, it is possible to use this
driver within installation boot floppies, and for any non-standard address,
too.

Auto-probing will make an assumption about the interface type ("SBPRO" or not),
based upon the address. That assumption may be wrong (initialization will be
o.k., but you will get I/O errors during mount). In that case, use the "kernel
command line" feature and specify address & type at boot time to find out the
right setup.

For every-day use, address and type should get configured within sbpcd.h. That
will stop the auto-probing due to success with the first try.

The kernel command "sbpcd=0" suppresses each auto-probing and causes
the driver not to find any drive; it is meant for people who love sbpcd
so much that they do not want to miss it, even if they miss the drives. ;-)  

If you configure "#define CDROM_PORT 0" in sbpcd.h, the auto-probing is
initially disabled and needs an explicit kernel command to get activated.
Once activated, it does not stop before success or end-of-list. This may be
useful within "universal" CDROM installation boot floppies (but using the 
loadable module would be better because it allows an "extended" auto-probing
without fearing NE2000 cards).

To shorten the auto-probing list to a single entry, set DISTRIBUTION 0 within
sbpcd.c.


Setting up address and interface type:
--------------------------------------

If your I/O port address is not 0x340, you have to look for the #defines near
the beginning of sbpcd.h and configure them: set SBPRO to 0 or 1 or 2, and
change CDROM_PORT to the address of your CDROM I/O port.

Most of the "SoundBlaster compatible" cards behave like the no-sound
interfaces! 

With "original" SB Pro cards, an initial setting of CD_volume through the
sound cards MIXER register gets done.
If you are using a "compatible" sound card of types "LaserMate" or "SPEA",
you can set SOUND_BASE (in sbpcd.h) to get it done with your card, too...


Using audio CDs:
----------------

Workman, WorkBone, xcdplayer, cdplayer and the nice little tool "cdplay" (see
README.aztcd from the Aztech driver package) should work.

The program CDplayer likes to talk to "/dev/mcd" only, xcdplayer wants
"/dev/rsr0", workman loves "/dev/sr0" or "/dev/cdrom" - so, do the appropriate
links for using them without the need of supplying parameters.


Copying audio tracks:
---------------------

The following program will copy track 1 (or a piece of it) from an audio CD
into the file "track01":

/*=================== begin program ========================================*/
/*
 * read an audio track from a CD
 *
 * (c) 1994 Eberhard Moenkeberg <emoenke@gwdg.de>
 *          may be used & enhanced freely
 *
 * Due to non-existent sync bytes at the beginning of each audio frame (or due
 * to a firmware bug within all known drives?), it is currently a kind of
 * fortune if two consecutive frames fit together.
 * Usually, they overlap, or a little piece is missing. This happens in units
 * of 24-byte chunks. It has to get fixed by higher-level software (reading
 * until an overlap occurs, and then eliminate the overlapping chunks). 
 * ftp.gwdg.de:/pub/linux/misc/cdda2wav-sbpcd.*.tar.gz holds an example of
 * such an algorithm.
 * This example program further is missing to obtain the SubChannel data
 * which belong to each frame.
 *
 * This is only an example of the low-level access routine. The read data are
 * pure 16-bit CDDA values; they have to get converted to make sound out of
 * them.
 * It is no fun to listen to it without prior overlap/underlap correction!
 */
#include <stdio.h>
#include <sys/ioctl.h>
#include <linux/cdrom.h>

static struct cdrom_tochdr hdr;
static struct cdrom_tocentry entry[101];
static struct cdrom_read_audio arg;
static u_char buffer[CD_FRAMESIZE_RAW];
static int datafile, drive;
static int i, j, limit, track, err;
static char filename[32];

main(int argc, char *argv[])
{
/*
 * open /dev/cdrom
 */
  drive=open("/dev/cdrom", 0);
  if (drive<0)
    {
      fprintf(stderr, "can't open drive.\n");
      exit (-1);
    }
/*
 * get TocHeader
 */
  fprintf(stdout, "getting TocHeader...\n");
  err=ioctl(drive, CDROMREADTOCHDR, &hdr);
  if (err!=0)
    {
      fprintf(stderr, "can't get TocHeader (error %d).\n", err);
      exit (-1);
    }
  else
    fprintf(stdout, "TocHeader: %d %d\n", hdr.cdth_trk0, hdr.cdth_trk1);
/*
 * get and display all TocEntries
 */
  fprintf(stdout, "getting TocEntries...\n");
  for (i=1;i<=hdr.cdth_trk1+1;i++)
    {
      if (i!=hdr.cdth_trk1+1) entry[i].cdte_track = i;
      else entry[i].cdte_track = CDROM_LEADOUT;
      entry[i].cdte_format = CDROM_LBA;
      err=ioctl(drive, CDROMREADTOCENTRY, &entry[i]);
      if (err!=0)
	{
	  fprintf(stderr, "can't get TocEntry #%d (error %d).\n", i, err);
	  exit (-1);
	}
      else
	{
	  fprintf(stdout, "TocEntry #%d: %1X %1X %06X %02X\n",
		 entry[i].cdte_track,
		 entry[i].cdte_adr,
		 entry[i].cdte_ctrl,
		 entry[i].cdte_addr.lba,
		 entry[i].cdte_datamode);
	}
    }
  fprintf(stdout, "got all TocEntries.\n");
/*
 * ask for track number (not implemented here)
 */
track=1;
#if 0 /* just read a little piece (4 seconds) */
entry[track+1].cdte_addr.lba=entry[track].cdte_addr.lba+300;
#endif
/*
 * read track into file
 */
  sprintf(filename, "track%02d\0", track);
  datafile=creat(filename, 0755);
  if (datafile<0)
    {
      fprintf(stderr, "can't open datafile %s.\n", filename);
      exit (-1);
    }
  arg.addr.lba=entry[track].cdte_addr.lba;
  arg.addr_format=CDROM_LBA; /* CDROM_MSF would be possible here, too. */
  arg.nframes=1;
  arg.buf=&buffer[0];
  limit=entry[track+1].cdte_addr.lba;
  for (;arg.addr.lba<limit;arg.addr.lba++)
    {
      err=ioctl(drive, CDROMREADAUDIO, &arg);
      if (err!=0)
	{
	  fprintf(stderr, "can't read abs. frame #%d (error %d).\n", 
		 arg.addr.lba, err);
	}
      j=write(datafile, &buffer[0], CD_FRAMESIZE_RAW);
      if (j!=CD_FRAMESIZE_RAW)
	{
	  fprintf(stderr,"I/O error (datafile) at rel. frame %d\n",
			 arg.addr.lba-entry[track].cdte_addr.lba);
	}
      arg.addr.lba++;
    }
}
/*===================== end program ========================================*/

At ftp.gwdg.de:/pub/linux/misc/cdda2wav-sbpcd.*.tar.gz is an adapted version of
Heiko Eissfeldt's digital-audio to .WAV converter (the original is there, too).
This is preliminary, as Heiko himself will care about it.


Known problems:
---------------

Currently, the detection of disk change or removal is actively disabled.

Most attempts to read the UPC/EAN code result in a stream of zeroes. All my
drives are mostly telling there is no UPC/EAN code on disk or there is, but it
is an all-zero number. I guess now almost no CD holds such a number.

Bug reports, comments, wishes, donations (technical information is a donation,
too :-) etc. to
                         emoenke@gwdg.de
 or to my FIDO address:  Eberhard Moenkeberg, 2:2437/210.27

SnailMail address, preferable for CD editors if they want to submit a free
"cooperation" copy:
                         Eberhard Moenkeberg
                         Reinholdstr. 14
                         D-37083 Goettingen
                         Germany
---
