advdrvr.ug

pc机上经由pci连接的ata和atapi设备驱动

                             ADVDRVR
               Advanced ATA/ATAPI Low Level Driver
                          User's Guide

                         by Hale Landis

                      Version 1H and higher


INTRODUCTION
------------

ADVDRVR is Hale Landis' C code that shows the low level
programming required to configure and execute commands on ATA and
ATAPI devices.  This C code is based on Hale's ATADRVR.  The
major change from ATADRVR is that ADVDRVR can be configured to
operate on any number of controllers and devices and is intended
for use in multi-threaded programs like ATAMDT.  This C code has
been placed into the public domain by Hale Landis.  This C code
has no copyright or other restrictions on how it is used.


USING ADVDRVR
-------------

Before using ADVDRVR in your project you should read the
PIO.UG, DMA.UG and SATA.UG documentation files.

ADVDRVR and the EXAMPLE1 and EXAMPLE2 programs are DOS "real
mode" programs.  This software will not execute in a Windows DOS
session (a virtual x86 session).  You must use a compiler and
linker that are able to create DOS real mode programs.  Hale uses
Borland C/C++ 4.5.  Note that the free (or low cost) Borland C++
5.x compiler will not compile this code -- you need the full
Borland C++ 5.x compiler.  And you also need the Borland TASM
assembler.  See the EXAMPLE1.MAK and EXAMPLE2.MAK 'make' files.

The best way to see how this code can be used is shown in the C
program files EXAMPLE1.C and EXAMPLE2.C.  ADVDRVR provides all of
the funcitons and facilities needed to perform the low level I/O
port activities on an x86 computer so that ATA and ATAPI commands
can be executed.

EXAMPLE1.C and EXAMPLE2.C show only how to setup a single device
with ADVDRVR.  If multiple devices are used some may be on the
same physical ATA channel.  In this case the caller is
responsible for serializing the commands issued to the devices on
the shared ATA channel.  This is only an issue if you allow the
DMA command execution code (see ADVIOPCI.C) to 'yield' to some
other task of the calling program.

ADVDRVR also includes detailed low level and command history
tracing funcitons.  When ADVDRVR is used to control more than one
device at a time, some of those devices may be on the same
physical ATA channel.  In this case those devices could share the
same CHT and LLT trace buffers but it is the responsibility of
the ADVDRVR caller to keep the 'current index' for these trace
buffers in sync.


FILE ORGANIZATION
-----------------

ADVDRVR source code is organized into two H files and several C
files.

The H files are:

   ADVIO.H
   ADVIOCFG.H

The file ADVIO.H defines all of the "public" functions and data
for ADVDRVR.  This file should be included into any program using
the ADVDRVR functions. The file ATAIOCFG.H contains #defines that
determine what functions are included in ADVDRVR.

The C files are:

   ADVIOINT.C
   ADVIOPCI.C
   ADVIOPIO.C
   ADVIOREG.C
   ADVIOSUB.C
   ADVIOTMR.C
   ADVIOTRC.C
   EXAMPLE1.C
   EXAMPLE2.C

The file ADVIOINT.C contains the interrupt handling functions.
These functions support only PIC mode interrupts (APIC is not
supported).

The file ADVIOPCI.C contains the x86 PCI Bus Mastering DMA
functions.  The public symbols in this file begin with characters
"dma_pci_".

The file ADVIOPIO.C contains the lowest level I/O port access
functions.  The public symbols in this file begin with characters
"pio_".

The file ADVIOREG.C contains ATA and ATAPI functions to perform
ATA Soft Reset, Non-Data, PIO Data IN, PIO Data Out and ATAPI
Packet command protocols.  The public symbols in this file begin
with characters "reg_".

The file ADVIOSUB.C contains several "private" functions used by
ADVDRVR.

The file ADVIOTMR.C contains the timer reading and command
timeout functions.  The public symbols in this file begin with
characters "tmr_".

The file ADVIOTRC.C contains the low level and command history
trace functions.  The public symbols in this file begin with
characters "trc_".

The file EXAMPLE1.C is an example of using ADVDRVR to configure
an ATA device and execute a few commands.

The file EXAMPLE2.C is an example of using ADVDRVR to configure
an ATAPI CD-ROM device and execute a few commands.

                              NOTE
                              ----

   If you use ADVDRVR in a program you should use only the public
   symbols.  This will allow you too upgrade to newer versions of
   ADVDRVR (assuming there will be new versions in the future)
   with minimum effort.  The private data and functions are
   subject to change in future versions of ADVDRVR.


USING ADVDRVR
-------------

Before using the ADVDRVR code in your program, please review the
EXAMPLE1.C, EXAMPLE1.MAK, EXAMPLE2.C and EXAMPLE2.MAK files.
These files will provide a basic overview of how this driver code
can be used.

The basics of using ADVDRVR, as shown in EXAMPLE1.C or
EXAMPLE2.C, are these:

1) #include "advio.h" in your program. #include "adviocfg.h" with
   the configuation options set appropriately.

2) Define (allocate) a device data area (see struct ADVIO_DEVICE)
   for each device to be used by your program.

3) Call pio_set_iobase_addr() or pio_set_memory_addr() to set the
   base I/O or memory address used by the ATA host adapter.

4) Call reg_config() so that ADVDRVR can determine what devices
   are attached to the ATA controller.

5) Call reg_reset() or any of the other "reg" functions to issue
   ATA or ATAPI commands in PIO data transfer mode.

6) To use PCI DMA, call dma_pci_config(), call int_enable() and
   then call the other dma_pci_*() functions to execute
   read/write commands.


48-BIT LBA PIO DATA TRANSFERS
-----------------------------

One of the dumber things T13 did was to allow the 48-bit LBA
commands to transfer huge amounts of data, up to 65536 sectors
(33Mbytes) in a single command.  ADVDRVR is able to support these
huge transfers even if the data buffer is not that big.  The I/O
buffer must be at least the size of the largest DRQ block that
will be transferred by a PIO data transfer command.  For
READ/WRITE SECTORS that is a single sector buffer.  For
READ/WRITE MULTIPLE that is a buffer that holds the current
multiple block count number of sectors.

This mode of PIO data transfer is enabled when the
reg_drq_block_call_back function pointer is not NULL.  Note that
this facility of ADVDRVR can be used with any PIO Data In/Out
command.

ADVDRVR supports these transfers by calling back to a user
supplied function at these times:

* For PIO Data In commands, after each DRQ block has been read
   from the device.  The call back function should use this call
   to access the data buffer.

* For PIO Data Out commands, before each DRQ block is written to
   the device.  The call back function should use this call to
   fill the data buffer.

The call back function receives a pointer to the device data area
structure.  It must use the data in this structure to determine
what is happening.  The call back function has no return value.

The reg_drq_block_call_back function pointer is set to NULL
before the PIO Data In/Out functions return.


ADVDRVR REFERENCE
-----------------

Each of the public functions and symbols of ADVDRVR are described
below in alphabetical order.


Functions And Data In ADVIOINT.C
--------------------------------

These functions set up interrupts (PIC mode only). Interrupts
are required by read/write DMA commands - see ADVIOPCI.C.

int int_config( int shared, int irqNum, int chanNum, int devNum );

   Set up an interrupt handler for the current device.

   shared is not-zero if the IRQ is to be shared. irqNum is the
   IRQ number (1-15, but not including 2). chanNum is zero if
   configuring an IRQ for a device on a Primary side of an ATA
   controller, and non-zero for a device on the Secondary side of
   an ATA controler. devNum is the device number (0 or 1).

   Returns a non-zero value if there is an error.

   If int_config() is called then int_disable must be called
   before exiting back to DOS.

int int_enable( void );

   Installed the interrupt handlers that have been configured by
   calls to int_config().

   If int_enable() is called then int_disable must be called
   before exiting back to DOS.

void int_disable( void );

   Disable all interrupts.  Must be called if there have been any
   calls to int_enable();

Functions And Data In ADVIOPCI.C
--------------------------------

These functions setup PCI bus DMA (ATA Multiword or Ultra DMA)
and perform ATA and ATAPI commands using DMA.  The function
dma_pci_config() MUST be called with no error before any of the
other functions will attempt to execute a command.

int dma_pci_chs( int cmd,                    // command register
                 int fr,                     // feature register
                 int sc,                     // sector count
                 unsigned int cyl,           // CHS cylinder high/low
                 int head,                   // CHS head
                 int sect,                   // CHS sector
                 unsigned seg,               // buffer address
                 unsigned off );             // buffer address

   Execute an ATA Read DMA (C8H) or ATA Write DMA (CAH) command
   using CHS sector addressing.

   Returns 0 if no error or 1 if there is an error.

int dma_pci_lba28( int cmd,                // command register
                   int fr,                 // feature register
                   int sc,                 // sector count
                   long lba,               // LBA
                   unsigned seg,           // buffer address
                   unsigned off );         // buffer address

   Execute an ATA Read DMA (C8H) or ATA Write DMA (CAH) command
   using LBA sector addressing.

   Returns 0 if no error or 1 if there is an error.

int dma_pci_lba48( int cmd,                // command register
                   int fr,                 // feature register
                   int sc,                 // sector count
                   long lbahi,             // LBA upper 16-bits
                   long lbalo,             // LBA lower 32 bits
                   unsigned seg,           // buffer address
                   unsigned off );         // buffer address

   Execute an ATA Read DMA (C8H) or ATA Write DMA (CAH) command
   using LBA sector addressing.

   Returns 0 if no error or 1 if there is an error.

int dma_pci_config( unsigned int regAddr );

   Configure ADVDRVR to use ISA bus DMA (ATA Multiword DMA) on
   ISA DMA Channel 5, 6 or 7.

int dma_pci_packet( unsigned int cpbc,       // command packet size
                    unsigned int cpseg,      // command packet buffer
                    unsigned int cpoff,      // command packet buffer
                    int dir,                 // 0 for no data or read, 1 for write
                    unsigned int dpbc,       // max data packet size