Auto merge with /home/aegl/GIT/linus

DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \

DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \

	    kernel-hacking.xml kernel-locking.xml deviceiobook.xml \

	    kernel-hacking.xml kernel-locking.xml deviceiobook.xml \

	    procfs-guide.xml writing_usb_driver.xml scsidrivers.xml \

	    procfs-guide.xml writing_usb_driver.xml \

	    sis900.xml kernel-api.xml journal-api.xml lsm.xml usb.xml \

	    sis900.xml kernel-api.xml journal-api.xml lsm.xml usb.xml \

	    gadget.xml libata.xml mtdnand.xml librs.xml

	    gadget.xml libata.xml mtdnand.xml librs.xml

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"

	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>

<book id="scsidrivers">

 <bookinfo>

  <title>SCSI Subsystem Interfaces</title>

  <authorgroup>

   <author>

    <firstname>Douglas</firstname>

    <surname>Gilbert</surname>

    <affiliation>

     <address>

      <email>dgilbert@interlog.com</email>

     </address>

    </affiliation>

   </author>

  </authorgroup>

  <pubdate>2003-08-11</pubdate>

  <copyright>

   <year>2002</year>

   <year>2003</year>

   <holder>Douglas Gilbert</holder>

  </copyright>

  <legalnotice>

   <para>

     This documentation is free software; you can redistribute

     it and/or modify it under the terms of the GNU General Public

     License as published by the Free Software Foundation; either

     version 2 of the License, or (at your option) any later

     version.

   </para>

   <para>

     This program is distributed in the hope that it will be

     useful, but WITHOUT ANY WARRANTY; without even the implied

     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

     See the GNU General Public License for more details.

   </para>

   <para>

     You should have received a copy of the GNU General Public

     License along with this program; if not, write to the Free

     Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,

     MA 02111-1307 USA

   </para>

   <para>

     For more details see the file COPYING in the source

     distribution of Linux.

   </para>

  </legalnotice>

 </bookinfo>

<toc></toc>

  <chapter id="intro">

      <title>Introduction</title>

  <para>

This document outlines the interface between the Linux scsi mid level

and lower level drivers. Lower level drivers are variously called HBA

(host bus adapter) drivers, host drivers (HD) or pseudo adapter drivers.

The latter alludes to the fact that a lower level driver may be a

bridge to another IO subsystem (and the "ide-scsi" driver is an example

of this). There can be many lower level drivers active in a running

system, but only one per hardware type. For example, the aic7xxx driver

controls adaptec controllers based on the 7xxx chip series. Most lower

level drivers can control one or more scsi hosts (a.k.a. scsi initiators).

  </para>

<para>

This document can been found in an ASCII text file in the linux kernel 

source: <filename>Documentation/scsi/scsi_mid_low_api.txt</filename> .

It currently hold a little more information than this document. The

<filename>drivers/scsi/hosts.h</filename> and <filename>

drivers/scsi/scsi.h</filename> headers contain descriptions of members

of important structures for the scsi subsystem.

</para>

  </chapter>

  <chapter id="driver-struct">

      <title>Driver structure</title>

  <para>

Traditionally a lower level driver for the scsi subsystem has been

at least two files in the drivers/scsi directory. For example, a

driver called "xyz" has a header file "xyz.h" and a source file

"xyz.c". [Actually there is no good reason why this couldn't all

be in one file.] Some drivers that have been ported to several operating

systems (e.g. aic7xxx which has separate  files for generic and

OS-specific code) have more than two files. Such drivers tend to have

their own directory under the drivers/scsi directory.

  </para>

  <para>

scsi_module.c is normally included at the end of a lower

level driver. For it to work a declaration like this is needed before

it is included:

<programlisting>

    static Scsi_Host_Template driver_template = DRIVER_TEMPLATE;

    /* DRIVER_TEMPLATE should contain pointers to supported interface

       functions. Scsi_Host_Template is defined hosts.h */

    #include "scsi_module.c"

</programlisting>

  </para>

  <para>

The scsi_module.c assumes the name "driver_template" is appropriately

defined. It contains 2 functions:

<orderedlist>

<listitem><para>

     init_this_scsi_driver() called during builtin and module driver

     initialization: invokes mid level's scsi_register_host()

</para></listitem>

<listitem><para>

     exit_this_scsi_driver() called during closedown: invokes

     mid level's scsi_unregister_host()

</para></listitem>

</orderedlist>

  </para>

<para>

When a new, lower level driver is being added to Linux, the following 

files (all found in the drivers/scsi directory) will need some attention: 

Makefile, Config.help and Config.in . It is probably best to look at what 

an existing lower level driver does in this regard.

</para>

  </chapter>

  <chapter id="intfunctions">

     <title>Interface Functions</title>

!EDocumentation/scsi/scsi_mid_low_api.txt

  </chapter>

  <chapter id="locks">

     <title>Locks</title>

<para>

Each Scsi_Host instance has a spin_lock called Scsi_Host::default_lock

which is initialized in scsi_register() [found in hosts.c]. Within the

same function the Scsi_Host::host_lock pointer is initialized to point

at default_lock with the scsi_assign_lock() function. Thereafter

lock and unlock operations performed by the mid level use the

Scsi_Host::host_lock pointer.

</para>

<para>

Lower level drivers can override the use of Scsi_Host::default_lock by

using scsi_assign_lock(). The earliest opportunity to do this would

be in the detect() function after it has invoked scsi_register(). It

could be replaced by a coarser grain lock (e.g. per driver) or a

lock of equal granularity (i.e. per host). Using finer grain locks

(e.g. per scsi device) may be possible by juggling locks in

queuecommand().

</para>

  </chapter>

  <chapter id="changes">

     <title>Changes since lk 2.4 series</title>

<para>

io_request_lock has been replaced by several finer grained locks. The lock

relevant to lower level drivers is Scsi_Host::host_lock and there is one

per scsi host.

</para>

<para>

The older error handling mechanism has been removed. This means the

lower level interface functions abort() and reset() have been removed.

</para>

<para>

In the 2.4 series the scsi subsystem configuration descriptions were

aggregated with the configuration descriptions from all other Linux

subsystems in the Documentation/Configure.help file. In the 2.5 series,

the scsi subsystem now has its own (much smaller) drivers/scsi/Config.help

file.

</para>

  </chapter>

  <chapter id="credits">

     <title>Credits</title>

<para>

The following people have contributed to this document:

<orderedlist>

<listitem><para>

Mike Anderson <email>andmike@us.ibm.com</email>

</para></listitem>

<listitem><para>

James Bottomley <email>James.Bottomley@steeleye.com</email>

</para></listitem>

<listitem><para>

Patrick Mansfield <email>patmans@us.ibm.com</email>

</para></listitem>

</orderedlist>

</para>

  </chapter>

</book>

Generic HDLC layer

Generic HDLC layer

Krzysztof Halasa <khc@pm.waw.pl>

Krzysztof Halasa <khc@pm.waw.pl>

January, 2003

Generic HDLC layer currently supports:

Generic HDLC layer currently supports:

- Frame Relay (ANSI, CCITT and no LMI), with ARP support (no InARP).

1. Frame Relay (ANSI, CCITT, Cisco and no LMI).

  Normal (routed) and Ethernet-bridged (Ethernet device emulation)

   - Normal (routed) and Ethernet-bridged (Ethernet device emulation)

     interfaces can share a single PVC.

     interfaces can share a single PVC.

- raw HDLC - either IP (IPv4) interface or Ethernet device emulation.

   - ARP support (no InARP support in the kernel - there is an

- Cisco HDLC,

     experimental InARP user-space daemon available on:

- PPP (uses syncppp.c),

     http://www.kernel.org/pub/linux/utils/net/hdlc/).

- X.25 (uses X.25 routines).

2. raw HDLC - either IP (IPv4) interface or Ethernet device emulation.

3. Cisco HDLC.

4. PPP (uses syncppp.c).

5. X.25 (uses X.25 routines).

There are hardware drivers for the following cards:

Generic HDLC is a protocol driver only - it needs a low-level driver

- C101 by Moxa Technologies Co., Ltd.

for your particular hardware.

- RISCom/N2 by SDL Communications Inc.

- and others, some not in the official kernel.

Ethernet device emulation (using HDLC or Frame-Relay PVC) is compatible

Ethernet device emulation (using HDLC or Frame-Relay PVC) is compatible

with IEEE 802.1Q (VLANs) and 802.1D (Ethernet bridging).

with IEEE 802.1Q (VLANs) and 802.1D (Ethernet bridging).

Make sure the hdlc.o and the hardware driver are loaded. It should

Make sure the hdlc.o and the hardware driver are loaded. It should

create a number of "hdlc" (hdlc0 etc) network devices, one for each

create a number of "hdlc" (hdlc0 etc) network devices, one for each

WAN port. You'll need the "sethdlc" utility, get it from:

WAN port. You'll need the "sethdlc" utility, get it from:

	http://hq.pm.waw.pl/hdlc/

	http://www.kernel.org/pub/linux/utils/net/hdlc/

Compile sethdlc.c utility:

Compile sethdlc.c utility:

	gcc -O2 -Wall -o sethdlc sethdlc.c

	gcc -O2 -Wall -o sethdlc sethdlc.c

* v35 | rs232 | x21 | t1 | e1 - sets physical interface for a given port

* v35 | rs232 | x21 | t1 | e1 - sets physical interface for a given port

                                if the card has software-selectable interfaces

                                if the card has software-selectable interfaces

  loopback - activate hardware loopback (for testing only)

  loopback - activate hardware loopback (for testing only)

* clock ext - external clock (uses DTE RX and TX clock)

* clock ext - both RX clock and TX clock external

* clock int - internal clock (provides clock signal on DCE clock output)

* clock int - both RX clock and TX clock internal

* clock txint - TX internal, RX external (provides TX clock on DCE output)

* clock txint - RX clock external, TX clock internal

* clock txfromrx - TX clock derived from RX clock (TX clock on DCE output)

* clock txfromrx - RX clock external, TX clock derived from RX clock

* rate - sets clock rate in bps (not required for external clock or

* rate - sets clock rate in bps (for "int" or "txint" clock only)

                                 for txfromrx)

Setting protocol:

Setting protocol:

* x25 - sets X.25 mode

* x25 - sets X.25 mode

* fr - Frame Relay mode

* fr - Frame Relay mode

  lmi ansi / ccitt / none - LMI (link management) type

  lmi ansi / ccitt / cisco / none - LMI (link management) type

  dce - Frame Relay DCE (network) side LMI instead of default DTE (user).

  dce - Frame Relay DCE (network) side LMI instead of default DTE (user).

  It has nothing to do with clocks!

  It has nothing to do with clocks!

  t391 - link integrity verification polling timer (in seconds) - user

  t391 - link integrity verification polling timer (in seconds) - user

If you have a problem with N2 or C101 card, you can issue the "private"

If you have a problem with N2, C101 or PLX200SYN card, you can issue the

command to see port's packet descriptor rings (in kernel logs):

"private" command to see port's packet descriptor rings (in kernel logs):

	sethdlc hdlc0 private

	sethdlc hdlc0 private

The hardware driver has to be build with CONFIG_HDLC_DEBUG_RINGS.

The hardware driver has to be build with #define DEBUG_RINGS.

Attaching this info to bug reports would be helpful. Anyway, let me know

Attaching this info to bug reports would be helpful. Anyway, let me know

if you have problems using this.

if you have problems using this.

For patches and other info look at http://hq.pm.waw.pl/hdlc/

For patches and other info look at:

<http://www.kernel.org/pub/linux/utils/net/hdlc/>.

ni65		YES		YES		YES		Software(#)

ni65		YES		YES		YES		Software(#)

seeq		NO		NO		NO		N/A

seeq		NO		NO		NO		N/A

sgiseek		<------------------ Buggy ------------------>

sgiseek		<------------------ Buggy ------------------>

sk_g16		NO		NO		YES		N/A

smc-ultra	YES		YES		YES		Hardware

smc-ultra	YES		YES		YES		Hardware

sunlance	YES		YES		YES		Hardware

sunlance	YES		YES		YES		Hardware

tulip		YES		YES		YES		Hardware

tulip		YES		YES		YES		Hardware

seeq8005.c: *Not modularized*

seeq8005.c: *Not modularized*

	(Probes ports: 0x300, 0x320, 0x340, 0x360)

	(Probes ports: 0x300, 0x320, 0x340, 0x360)

sk_g16.c: *Not modularized*

	(Probes ports: 0x100, 0x180, 0x208, 0x220m 0x288, 0x320, 0x328, 0x390)

skeleton.c: *Skeleton*

skeleton.c: *Skeleton*

slhc.c:

slhc.c: