docs: cdrom: convert docs to ReST and rename to *.rst

IDE-CD driver documentation

Originally by scott snyder  <snyder@fnald0.fnal.gov> (19 May 1996)

Carrying on the torch is: Erik Andersen <andersee@debian.org>

New maintainers (19 Oct 1998): Jens Axboe <axboe@image.dk>

===========================

:Originally by: scott snyder  <snyder@fnald0.fnal.gov> (19 May 1996)

:Carrying on the torch is: Erik Andersen <andersee@debian.org>

:New maintainers (19 Oct 1998): Jens Axboe <axboe@image.dk>

1. Introduction

---------------

both ATAPI-compliant drives and drives which use a proprietary

interface.  If your drive uses one of those proprietary interfaces,

this driver will not work with it (but one of the other CDROM drivers

probably will).  This driver will not work with `ATAPI' drives which

probably will).  This driver will not work with `ATAPI` drives which

attach to the parallel port.  In addition, there is at least one drive

(CyCDROM CR520ie) which attaches to the IDE port but is not ATAPI;

this driver will not work with drives like that either (but see the

1. Make sure that the ide and ide-cd drivers are compiled into the

   kernel you're using.  When configuring the kernel, in the section

   entitled "Floppy, IDE, and other block devices", say either `Y' 

   (which will compile the support directly into the kernel) or `M'

   entitled "Floppy, IDE, and other block devices", say either `Y`

   (which will compile the support directly into the kernel) or `M`

   (to compile support as a module which can be loaded and unloaded)

   to the options: 

   to the options::

      ATA/ATAPI/MFM/RLL support

      Include IDE/ATAPI CDROM support

   0x1f0 and 14 for the primary interface and 0x170 and 15 for the

   secondary interface.  Each interface can control up to two devices,

   where each device can be a hard drive, a CDROM drive, a floppy drive,

   or a tape drive.  The two devices on an interface are called `master'

   and `slave'; this is usually selectable via a jumper on the drive.

   or a tape drive.  The two devices on an interface are called `master`

   and `slave`; this is usually selectable via a jumper on the drive.

   Linux names these devices as follows.  The master and slave devices

   on the primary IDE interface are called `hda' and `hdb',

   on the primary IDE interface are called `hda` and `hdb`,

   respectively.  The drives on the secondary interface are called

   `hdc' and `hdd'.  (Interfaces at other locations get other letters

   `hdc` and `hdd`.  (Interfaces at other locations get other letters

   in the third position; see Documentation/ide/ide.txt.)

   If you want your CDROM drive to be found automatically by the

   driver, you should make sure your IDE interface uses either the

   primary or secondary addresses mentioned above.  In addition, if

   the CDROM drive is the only device on the IDE interface, it should

   be jumpered as `master'.  (If for some reason you cannot configure

   be jumpered as `master`.  (If for some reason you cannot configure

   your system in this manner, you can probably still use the driver.

   You may have to pass extra configuration information to the kernel

   when you boot, however.  See Documentation/ide/ide.txt for more

   information.)

4. Boot the system.  If the drive is recognized, you should see a

   message which looks like

   message which looks like::

     hdb: NEC CD-ROM DRIVE:260, ATAPI CDROM drive

   If you do not see this, see section 5 below.

5. You may want to create a symbolic link /dev/cdrom pointing to the

   actual device.  You can do this with the command

   actual device.  You can do this with the command::

     ln -s  /dev/hdX  /dev/cdrom

   drive is installed.

6. You should be able to see any error messages from the driver with

   the `dmesg' command.

   the `dmesg` command.

3. Basic usage

--------------

An ISO 9660 CDROM can be mounted by putting the disc in the drive and

typing (as root)

typing (as root)::

  mount -t iso9660 /dev/cdrom /mnt/cdrom

device (as described in step 5 of the last section) and /mnt/cdrom is

an empty directory.  You should now be able to see the contents of the

CDROM under the /mnt/cdrom directory.  If you want to eject the CDROM,

you must first dismount it with a command like

you must first dismount it with a command like::

  umount /mnt/cdrom

this are Sony and Toshiba drives.  You will get errors if you try to

use this function on a drive which does not support it.

For supported changers, you can use the `cdchange' program (appended to

For supported changers, you can use the `cdchange` program (appended to

the end of this file) to switch between changer slots.  Note that the

drive should be unmounted before attempting this.  The program takes

two arguments:  the CDROM device, and the slot number to which you wish

IDE support code.  Some of these items apply only to earlier versions

of the driver, but are mentioned here for completeness.

In most cases, you should probably check with `dmesg' for any errors

In most cases, you should probably check with `dmesg` for any errors

from the driver.

a. Drive is not detected during booting.

   - If the autoprobing is not finding your drive, you can tell the

     driver to assume that one exists by using a lilo option of the

     form `hdX=cdrom', where X is the drive letter corresponding to

     form `hdX=cdrom`, where X is the drive letter corresponding to

     where your drive is installed.  Note that if you do this and you

     see a boot message like

     see a boot message like::

       hdX: ATAPI cdrom (?)

    probably not making it to the host.

  - IRQ problems may also be indicated by the message

    `IRQ probe failed (<n>)' while booting.  If <n> is zero, that

    `IRQ probe failed (<n>)` while booting.  If <n> is zero, that

    means that the system did not see an interrupt from the drive when

    it was expecting one (on any feasible IRQ).  If <n> is negative,

    that means the system saw interrupts on multiple IRQ lines, when

    Unfortunately, these drives seem to become very confused when we perform

    the standard Linux ATA disk drive probe. If you own one of these drives,

    you can bypass the ATA probing which confuses these CDROM drives, by

    adding `append="hdX=noprobe hdX=cdrom"' to your lilo.conf file and running 

    adding `append="hdX=noprobe hdX=cdrom"` to your lilo.conf file and running

    lilo (again where X is the drive letter corresponding to where your drive

    is installed.)

    likely cause is that you have a buggy IDE adapter which doesn't

    properly handle simultaneous transactions on multiple interfaces.

    The most notorious of these is the CMD640B chip.  This problem can

    be worked around by specifying the `serialize' option when

    be worked around by specifying the `serialize` option when

    booting.  Recent kernels should be able to detect the need for

    this automatically in most cases, but the detection is not

    foolproof.  See Documentation/ide/ide.txt for more information

    about the `serialize' option and the CMD640B.

    about the `serialize` option and the CMD640B.

  - Note that many MS-DOS CDROM drivers will work with such buggy

    hardware, apparently because they never attempt to overlap CDROM

d. Can't mount a CDROM.

  - If you get errors from mount, it may help to check `dmesg' to see

  - If you get errors from mount, it may help to check `dmesg` to see

    if there are any more specific errors from the driver or from the

    filesystem.

  - Make sure there's a CDROM loaded in the drive, and that's it's an

    ISO 9660 disc.  You can't mount an audio CD.

  - With the CDROM in the drive and unmounted, try something like

  - With the CDROM in the drive and unmounted, try something like::

      cat /dev/cdrom | od | more

    OK, and the problem is at the filesystem level (i.e., the CDROM is

    not ISO 9660 or has errors in the filesystem structure).

  - If you see `not a block device' errors, check that the definitions

  - If you see `not a block device` errors, check that the definitions

    of the device special files are correct.  They should be as

    follows:

    follows::

      brw-rw----   1 root     disk       3,   0 Nov 11 18:48 /dev/hda

      brw-rw----   1 root     disk       3,  64 Nov 11 18:48 /dev/hdb

    If you have a /dev/cdrom symbolic link, check that it is pointing

    to the correct device file.

    If you hear people talking of the devices `hd1a' and `hd1b', these

    If you hear people talking of the devices `hd1a` and `hd1b`, these

    were old names for what are now called hdc and hdd.  Those names

    should be considered obsolete.

    always give meaningful error messages.

e. Directory listings are unpredictably truncated, and `dmesg' shows

   `buffer botch' error messages from the driver.

e. Directory listings are unpredictably truncated, and `dmesg` shows

   `buffer botch` error messages from the driver.

  - There was a bug in the version of the driver in 1.2.x kernels

    which could cause this.  It was fixed in 1.3.0.  If you can't

5. cdchange.c

-------------

::

  /*

   * cdchange.c  [-v]  <device>  [<slot>]

   *

	/* open device */

	fd = open(device, O_RDONLY | O_NONBLOCK);

	if (fd < 0) {

		fprintf (stderr, "%s: open failed for `%s': %s\n",

		fprintf (stderr, "%s: open failed for `%s`: %s\n",

			 program, device, strerror (errno));

		exit (1);

	}

	/* Check CD player status */

	total_slots_available = ioctl (fd, CDROM_CHANGER_NSLOTS);

	if (total_slots_available <= 1 ) {

		fprintf (stderr, "%s: Device `%s' is not an ATAPI "

		fprintf (stderr, "%s: Device `%s` is not an ATAPI "

			"compliant CD changer.\n", program, device);

		exit (1);

	}

	/* close device */

	status = close (fd);

	if (status != 0) {

		fprintf (stderr, "%s: close failed for `%s': %s\n",

		fprintf (stderr, "%s: close failed for `%s`: %s\n",

			 program, device, strerror (errno));

		exit (1);

	}

:orphan:

=====

cdrom

=====

.. toctree::

    :maxdepth: 1

    cdrom-standard

    ide-cd

    packet-writing

.. only::  subproject and html

   Indices

   =======

   * :ref:`genindex`

==============

Packet writing

==============

Getting started quick

---------------------

  Download from http://sourceforge.net/projects/linux-udf/

- Grab a new CD-RW disc and format it (assuming CD-RW is hdc, substitute

  as appropriate):

  as appropriate)::

	# cdrwtool -d /dev/hdc -q

- Setup your writer

- Setup your writer::

	# pktsetup dev_name /dev/hdc

- Now you can mount /dev/pktcdvd/dev_name and copy files to it. Enjoy!

- Now you can mount /dev/pktcdvd/dev_name and copy files to it. Enjoy::

	# mount /dev/pktcdvd/dev_name /cdrom -t udf -o rw,noatime

DVD-RW discs can be written to much like CD-RW discs if they are in

the so called "restricted overwrite" mode. To put a disc in restricted

overwrite mode, run:

overwrite mode, run::

	# dvd+rw-format /dev/hdc

You can then use the disc the same way you would use a CD-RW disc:

You can then use the disc the same way you would use a CD-RW disc::

	# pktsetup dev_name /dev/hdc

	# mount /dev/pktcdvd/dev_name /cdrom -t udf -o rw,noatime

According to the DVD+RW specification, a drive supporting DVD+RW discs

shall implement "true random writes with 2KB granularity", which means

that it should be possible to put any filesystem with a block size >=

2KB on such a disc. For example, it should be possible to do:

2KB on such a disc. For example, it should be possible to do::

	# dvd+rw-format /dev/hdc   (only needed if the disc has never

	                            been formatted)

writes are not 32KB aligned.

Both problems can be solved by using the pktcdvd driver, which always

generates aligned writes.

generates aligned writes::

	# dvd+rw-format /dev/hdc

	# pktsetup dev_name /dev/hdc

- Since the pktcdvd driver makes the disc appear as a regular block

  device with a 2KB block size, you can put any filesystem you like on

  the disc. For example, run:

  the disc. For example, run::

	# /sbin/mke2fs /dev/pktcdvd/dev_name

and can be controlled by it. For example the "pktcdvd" tool uses

this interface. (see http://tom.ist-im-web.de/download/pktcdvd )

"pktcdvd" works similar to "pktsetup", e.g.:

"pktcdvd" works similar to "pktsetup", e.g.::

	# pktcdvd -a dev_name /dev/hdc

	# mkudffs /dev/pktcdvd/dev_name

Using the pktcdvd debugfs interface

-----------------------------------

To read pktcdvd device infos in human readable form, do:

To read pktcdvd device infos in human readable form, do::

	# cat /sys/kernel/debug/pktcdvd/pktcdvd[0-7]/info

M:	Borislav Petkov <bp@alien8.de>

L:	linux-ide@vger.kernel.org

S:	Maintained

F:	Documentation/cdrom/ide-cd

F:	Documentation/cdrom/ide-cd.rst

F:	drivers/ide/ide-cd*

IDEAPAD LAPTOP EXTRAS DRIVER