This README belongs to release 2.0 of the SoundBlaster Pro (Matsushita,
Kotobuki, Panasonic, CreativeLabs) CD-ROM driver for Linux.

The driver is able to drive the whole family of IDE-style
Matsushita/Kotobuki/Panasonic drives (the "double speed" versions like CR-562
and CR-563, too), and it 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, Aztech, ...).
It should work too now with the "configurable" interface "Sequoia S-1000",
which is found on the Spea Media FX sound card.
The interface type has to get configured in /usr/include/linux/sbpcd.h, 
because the behavior is different.

The driver respects different 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 are supported. CR-52x ("old") and CR-56x ("new") drives can be
mixed, but the CR-521 ones 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 to it's drive ID. The drive IDs may be selected freely
from 0 to 3 - they must not 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 (now that the single-speed CR-521's are as cheap as
50$), you have to "duplicate" the driver. Just copy sbpcd.c into sbpcd2.c and
change SBPCD_ISSUE accordingly.

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 "new" drive family CR-562 and CR-563, the reading of audio frames is
possible. This is currently implemented by an IOCTL function which reads only
one frame of 2352 bytes at a time. The transfer rate is as slow as 32 kB/sec.
This will get better, and the software interface may change. We have to 
standardize it the day the SCSI driver supports it too.

MultiSession is supported (even my "old" CR-521 can handle it), "ManySession"
(not recommended, see below) alternatively.
Photo CDs work, too. At ftp.gwdg.de:/pub/linux/hpcdtoppm/ is Hadmut Danisch's
package to convert photo CD image files.

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.
          The Spea Media FX sound card needs "SBPRO 2".
          sbpcd.c holds some examples in it's 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. Do a "make config" and select "yes" for Matsushita CD-ROM support and for
   ISO9660 FileSystem support.
   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 drive #0)
   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).
   Take care that you create a node with the same MINOR as your drive ID is.
   So, if the DOS driver tells you have drive id #3, you have to
        mknod /dev/<any_name> b 25 3
   
   For a second interface board, you have to make nodes like
        mknod /dev/sbpcd4 b 26 0
   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 "mount -t iso9660 -o block=2048 /dev/sbpcd /mnt"
and see the contents of your CD in the /mnt directory, and/or hear music with
"workman -c /dev/sbpcd &".


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

The driver is configured to try the SoundBlaster Pro type of interface at
I/O port 0x0230 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, so the IRQ line stays free for the SB Pro sound
drivers.

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

With "#define MANY_SESSION 1" (sbpcd.c), the driver can use "many-session" CDs.
This will work only with "new" drives like CR-562 or CR-563. That is NOT
multisession - it is a CD with multiple independent sessions, each containing
block addresses as if it were the only session. With this feature enabled, the
driver will read the LAST session. Without it, the FIRST session gets read.
If you would like the support of reading "in-between" sessions, drop me a mail
and some food for the soul. :-)
Those "many-session" CDs can get made by CDROM writers like Philips CDD 521.
If you enable this feature, it is impossible to read true multisession CDs.

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.


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

The driver does auto-probing at many well-known interface card addresses. The
idea to do that came from Adam J. Richter (YGGDRASIL). Some well-known
addresses are excluded from auto-probing because they can cause a hang if an
ethernet card gets touched.

This 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.

SBPCD's auto-probing happens before the initialization of the net drivers. That
makes a hang possible if an ethernet card gets touched.

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.


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

If your I/O port address is not 0x0230 or if you use a "no-sound" interface
other than OmniCD, 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. That happens at the end of "sbpcd_init".
If you are using a "compatible" sound card of type "LaserMate", you can change
that code to get it done with your card, too...


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

Workman, WorkBone, xcdplayer and cdplayer should work good now, even with the
double-speed drives.

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


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

The following little program will copy track 2 of an audio CD into the file
"track02":

/*=================== 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,
 * it is currently a kind of fortune if two consecutive frames fit together.
 * Usually, they overlap, or a little piece is missing. This has to get
 * fixed by higher-level software (reading until an overlap occurs, and then
 * eliminate the overlapping bytes). Possibly the first read bytes of each
 * frame must get discarded because they are read before we got synchronized.
 * 
 * This example program further is missing to obtain the SubChannel data
 * which belong to each frame.
 */
#include <stdio.h>
#include <sys/ioctl.h>
#include <linux/cdrom.h>

static struct cdrom_tochdr hdr;
static struct cdrom_tocentry entry[100];
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;i++)
    {
      entry[i].cdte_track = i;
      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=2;
#if 0 /* just read a little piece */
entry[track].cdte_addr.lba=170;
entry[track+1].cdte_addr.lba=190;
#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 is still buggy, I know that */
  arg.nframes=1;
  arg.buf=&buffer[0];
  limit=entry[track+1].cdte_addr.lba;
  for (i=arg.addr.lba;i<limit;i++)
    {
      err=ioctl(drive, CDROMREADAUDIO, &arg);
      if (err!=0)
	{
	  fprintf(stderr, "can't read frame #%d (error %d).\n", 
		 i-entry[track].cdte_addr.lba+1, err);
	  exit (-1);
	}
      j=write(datafile, &buffer[0], CD_FRAMESIZE_RAW);
      if (j!=CD_FRAMESIZE_RAW)
	{
	  fprintf(stderr,"I/O error (datafile) at frame %d\n",
		 i-entry[track].cdte_addr.lba+1);
	}
      arg.addr.lba++;
    }
}
/*===================== end program ========================================*/


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

Currently, the detection of disk change or removal does not work as good as it
should.

The "door (un)lock" commands get done at every "(u)mount" (only the "new"
drives support it), but after an unlock, locking again does not work properly.

All attempts to read the UPC/EAN code result in a stream of zeroes. All my
drives are telling there is no UPC/EAN code on disk or there is, but it is an
all-zero number.

Bug reports, comments, wishes, donations (technical information is a donation,
too :-) etc. to
                         emoenke@gwdg.de
 or to                   eberhard_moenkeberg@rollo.central.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
---
