
	     Optical disk driver for FreeBSD 3.3-RELEASE
	     ===========================================


                                                         26 Oct, 1999
                                                     Shunsuke Akiyama
                                               akiyama@jp.FreeBSD.org


Preface
-------
  Od-driver is back again.  New od-driver for FreeBSD 3.3-RELEASE has
  just released.

  od(4) had been disappeared since FreeBSD 3.0-RELEASE, SCSI subsystem
  changed from Julian's SCSI driver to CAM driver.
  I was very disappointed about that, and I was not able to continue
  developing od-driver with some reasons.
  But disappearing od(4) made me many mistakes such as wrong
  disklabel or newfs operations.  Then I decided to re-develop
  od-driver again.

  This driver set contains new od(4) driver, fits in the SCSI optical
  memory device characteristics.  And fixes some bugs in FreeBSD
  3.3-RELEASE kernel.

  Features:

    * SCSI optical memory devices (MO, PD, etc) used as od(4).
    * DVD-RAM drive (Matsushita AKA Panasonic LF-D100, Toshiba
      SD-W1101) also used as od(4) and cd(4).
    * MSDOS-FS works with 512, 1024 and 2048 byte/sector media.
    * UFS works with non 512 byte/sector media newfs'd by
      2.X-RELEASE systems.
    * Several driver specific options can be controlled by sysctl
      command.

  Primary distribution site URL is:

    ftp://daemon.jp.freebsd.org/pub/FreeBSD-jp/OD/

  There are old versions of driver/patch sets and several utilities.


Operating Environment
---------------------
  I verified this driver set work on FreeBSD 3.3-RELEASE.

  This is what I developed this on:

             CPU : AMD K6-III 450MHz
              MB : ASUS P5A-B WOA
          Memory : 128 MB
    SCSI Adapter : Adaptec AHA-2940UW
        MO Drive : Fujitsu M2512A 3.5" internal MO drive
                 : Fujitsu M2513A 3.5" internal MO drive
   DVD-RAM Drive : Matsushita LD-D100 internal DVD-RAM drive.

  The MO drive is used in the "optical memory device mode" (in
  FreeBSD, what is shown as "Removable Optical" in the device probing
  stage during the boot up).


Known Problems
--------------
  Here are some known problems:

    1. Kernel freezes when writes to bad sector on the media.

       It seems bug in the FreeBSD kernel.  I can't solve this problem
       now.

    2. Media eject not work with ports/mei.

       mei does not support CAMfied devices.
       Please use camcontrol command or my small program eject instead.

    3. DVD-RAM drive limitations.

       FreeBSD kernel can't read UDF only media.  It must contain
       ISO-9660 bridge to read DVD-ROM with FreeBSD kernel.  UDF is
       not supported by FreeBSD.

       DVD-RAM drives work as od(4) and cd(4).  But simultaneous
       accesses of these devices is not supported.  You shouldn't
       mount same media by od(4) and cd(4) at a time.


Manifest
--------
  This driver set contains following files.

    README.od		This file.
    README.od-J		Japanese document.
    kernel.diff		Patch for kernel sources.
    msdosfs.diff        1024 byte/sector or 2048 byte/sector media
                        support patch to MSDOS-FS.
    MAKEDEV.diff        Patch for MAKEDEV script.
    release.diff        Patch for sysinstall command.
    disktab.od		Sample disktab entries for optical disk.
    tested.txt          Beta testers environment list.
                        (Several Japanese were there.)
    3.3-STABLE/         Patches for 3.3-STABLE.

  And Nobuhiro Ito <bobson@egg.ics.nitech.ac.jp> sent me lists of
  working MO drives.

    MO-REPORT/MO-List991006.txt
                        Working MO drive list #1. (Japanese only)
    MO-REPORT/result-991006.txt
                        Working MO drive list #2. (Japanese only)


How to use this driver set
--------------------------
  1. Prepare kernel and other source files.

     You need kernel and other command source files.  Extract these
     files from source distribution sets (at least ssys.??).
     If you want to rebuild /stand/sysinstall command, you need
     sources related sysinstall (srelease.??), library sources
     (slib.??), libdialog sources (sgnu.??), disklabel command sources
     (ssbin.??) and cksum command sources (subin.??).

     You also need to extract this driver set.

  2. Apply MAKEDEV patch.

     Apply MAKEDEV patch (MAKEDEV.diff) to /dev/MAKEDEV to support
     od(4).

     ex.
      # cd /dev
      # patch < /somewhere/od-driver-3.3R/MAKEDEV.diff

  3. Apply kernel patch.

     Apply kernel patch (kernel.diff) at /usr/src directory.  You need
     patch command option "-p1".

     ex.
      # cd /usr/src
      # patch -p1 < /somewhere/od-driver-3.3R/kernel.diff

     Next, apply MSDOS-FS (msdosfs.diff) patch in the same directory.
     You also need patch command option "-p1".

     ex.
      # patch -p1 < /somewhere/od-driver-3.3R/msdosfs.diff

  4. Rebuild sysinstall and install it.

     If you don't want to rebuild/install /stand/sysinstall command,
     skip this step and go forward to step 5.

     (1) Apply release related patch.

       Apply release related patch (release.diff) to source files.
       You need patch command option "-p1".

       ex.
       # cd /usr/src
       # patch -p1 < /somewhere/od-driver-3.3R/release.diff

     (2) Rebuild libdisk library and install it.

       Rebuild libdisk library to support od(4) and install it.

       ex.
       # cd /usr/src/lib/libdisk
       # make obj
       # make depend
       # make
       # make install

     (3) Rebuild sysinstall and install it.

       Rebuild sysinstall command to support od(4) and install it.

       ex.
       # cd /usr/src/release/sysinstall
       # make obj
       # make depend
       # make
       # make install

  5. Rebuild kernel and install it.

     Optical disk device name/entry is "od".  Put following entry in
     your kernel configuration file.  (GENERIC already has "od0"
     entry.)

       device   od0

     If you want to make Matsushita/Panasonic LF-D100 DVD-RAM or
     Toshiba SD-W1101 DVD-RAM drive recognized as a cd, put following
     entry in your kernel configuration file.  (GENERIC already has
     "cd0" entry, too.)

       device   cd0

     Then configure kernel and rebuild it.  Install the new kernel,
     when kernel rebuilding is done successfully.

     ex.
      # cd /sys/i386/conf
      # cp GENERIC ODDRIVER
      # vi ODDRIVER                     [modify and put od entry in it]
      # config ODDRIVER
      # cd ../../compile/ODDRIVER
      # make depend
      # make
      # make install

  6. Make device files.

     Re-make device files for optical disk.  You already have od0 and
     related, those devices were made at FreeBSD installation time.
     But these devices can't be used for od-driver at all.

     You *** MUST *** re-make od(4) related device files.

     If you don't do it properly, the od-driver won't run.
     Make sliced device files, if you want to slice access.

     ex.
      # cd /dev
      # sh MAKEDEV od0
      # sh MAKEDEV od0s1a	[make UFS partition device at slice 1]

  7. Reboot system.

     Reboot your system.
     Then, you can access optical disk as:

        /dev/od*[a-h]   /dev/rod*[a-h]
        /dev/od*        /dev/rod*
        /dev/od*s[1-4]  /dev/od*s[1-4][a-h]
        /dev/rod*s[1-4] /dev/rod*s[1-4][a-h]

     These devices are almost same as da(4) devices except device
     name.


Optical disk driver configurations
----------------------------------
  You can configure od-driver using modifying kernel MIB style
  parameters by /sbin/sysctl command.  Some sort of configurations
  are provided with options for kernel configuration parameters.

  1. using kernel MIB style parameters.

    Kernel MIB style parameters are modified by /sbin/sysctl command.
    This driver set can configure following parameters.  You should
    modify these parameters in rc.local (Oops! this is obsoleted.) or
    something like that.

    (1) kern.cam.od.auto_turnoff

           Type : integer
        Default : 0

        For an automatic spindown, try this.  If this parameter set to
        non zero value, od driver turning off the spindle motor
        rotation when device is closed.

        Note: some drives might not work CAM passthrough device
        (/dev/pass*) with this parameter setting.

    (2) kern.cam.od.wait_ready_count

           Type : integer
        Default : 0

        To wait if unit becoming ready.  In most cases you got an
        error for opening od device when you inserting a media into
        the drive, after a while.  This is because most drives reading
        the DMA information from the media in this period, then
        returns an error to the host adapter.  If you want to avoid
        this, try to set this parameter in interval count.  This
        interval time is 1 second in this version.

  2. options for kernel configuration file.

    Here are some sort of compile time kernel configurations.  You
    need reconfigure, compile and install new kernel, when you using
    following kernel configuration parameters.

    (1) FFS_COMPAT_XXXXBSD

        options FFS_COMPAT_XXXXBSD

        Large sector media device handling of /sbin/newfs command had
        been changed between version 2 and 3.  Therefore there is an
        incompatibility of interoperability for UFS.  This option gets
        compatibility for old version of newfs'ed media.  Try this
        option if you couldn't access UFS media, newfs'ed by old
        version of FreeBSD.


How to use optical disk
-----------------------
  Optical disk is used (at least) as following file systems:

    a. DOS file system (Super floppy format)
    b. DOS file system (HD compatible format)
    c. UNIX file system (UFS)

  You can handle a and b, use mount command with "-t msdos" option or
  mount_msdos command.
  You can make MSDOS filesystem on FreeBSD system, use
  /sbin/newfs_msdos.

  To use optical disk as UFS, you must write disklabel and make
  filesystem on it.
  You can use /stand/sysinstall to do this.  This is the easiest way
  to build UFS on optical disk.

  Here are brief descriptions how to build UFS by hand.

  In current FreeBSD, UFS can make with:

    (1) Use entire disk space,
    (2) Use slice (AKA physical partition) area.

  In case of (1), to use optical disk as UFS:

    1. Prepare disktab entry

      See sample disktab.od file.  Sample entries are all 1 partition
      per media.  If you need more partition entries, put your own
      entry into /etc/disktab.

    2. Write disklabel

      Write disklabel to optical disk, using existing disktab entry.

        # disklabel -r -w od0 mo128

    3. Make filesystem

      Make UNIX filesystem on optical disk by newfs.

        # newfs /dev/rod0a

        or
        # newfs -t 64 -u 32 /dev/rod0a
        or
        # newfs -t 0 -u 0 /dev/rod0a

  In case of (2), to build UFS on the slice:

    1. Make FreeBSD slice

      Make FreeBSD slice on the optical disk, using fdisk.

        # fdisk -i /dev/rod0
        or
        # fdisk -u /dev/rod0

    2. Prepare disktab entry -+
    3. Write disklabel       -+- Same as case (1), see previous.
    4. Make filesystem       -+

      NOTE: Use sliced device for newfs argument. (/dev/rod*s*[a-h])

Device files
------------
  Optical disk device files are:

    /dev/od*[a-h]       /dev/rod*[a-h]
    /dev/od*            /dev/rod*
    /dev/od*s[1-4]      /dev/od*s[1-4][a-h]
    /dev/rod*s[1-4]     /dev/rod*s[1-4][a-h]

  Those devices are used as:

    +-------------------------+----------------------------------------+
    | Device                  | Description                            |
    +-------------------------+----------------------------------------+
    | /dev/od*                | Access for entire disk.                |
    |                         | To mount DOS super floppy format disk, |
    |                         | use this.                              |
    |                         | Write to MBR, use this also.           |
    +-------------------------+----------------------------------------+
    | /dev/od*[a-h]           | Correspond to UFS each partition.      |
    |                         | Mapped first appeared FreeBSD slice,   |
    |                         | if disk has multiple FreeBSD slices.   |
    +-------------------------+----------------------------------------+
    | /dev/od*s[1-4]          | Correspond to disk slices.             |
    |                         | To mount DOS HD compatible format      |
    |                         | disk, use this.                        |
    +-------------------------+----------------------------------------+
    | /dev/od*s[1-4]*[a-h]    | Correspond to UFS each partition at    |
    |                         | disk slice.                            |
    |                         | To mount UFS at disk slice, use this.  |
    +-------------------------+----------------------------------------+

    NOTE: Character devices not contained here.


Special Thanks
--------------
  Thanks for making us a Beta tester's ML and maintaining it:

    Yuji Takano         <takachan@running-dog.net>

  Thanks for od-driver-3.3R beta testers:

    Akio Morita         <amorita@meadow.scphys.kyoto-u.ac.jp>
    Yuji Takano         <takachan@running-dog.net>
    YABU (Shigeru Kasahara)/Kasahara
                        <bush@jrtokyohosp.gr.jp>
    Toshihiko Shimokawa <toshi@csce.kyushu-u.ac.jp>
    SETA -sheta- Takuji <sheta@kk.iij4u.or.jp>
    Keisuke Inoue       <keisuke@csl.sony.co.jp>
    Sung-ik Ho          <hokun@honet.org>
    Sugiura Takakazu    <sugiurat@mwnet.or.jp>
    Toru YAMAZAKI       <sph40089@se.ritsumei.ac.jp>
    Hiromichi Kawaguchi <guzi@guzi.imasy.or.jp>
    Takeshi OHASHI      <ohashi@mickey.ai.kyutech.ac.jp>
    Yasuhiro Taniguchi  <taniguti@krl.toshiba.co.jp>
    Kazu TAKAMUNE       <takamune@avrl.mei.co.jp>

  Thanks for test FreeBSD(98):

    Nobuyuki Koganemaru <kogane@koganemaru.co.jp>

  Thanks to MSDOS-FS patches:

    Chiharu Shibata     <chi@bd.mbn.or.jp>

  Contributed MO-REPORT:

    Nobuhiro Ito        <bobson@phaser.elcom.nitech.ac.jp>

  Your patches are still alive:

    Koji Imada

  Thank you again.


Others
------
  Bug fixes and enhancements are welcome, please feedback to me.
  Please contribute disktab entries for various optical disks.


$Id: README.od,v 3.4 1999/10/26 13:50:06 akiyama Exp $
