atadrvr.ug

~{S2EL~}wdm~{G}6/~}

                             ATADRVR
                   ATA/ATAPI Low Level Driver
                          User's Guide

                         by Hale Landis

                           Version 14C


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

ATADRVR is Hale Landis' C code that shows the low level
programming required to configure and execute commands on ATA and
ATAPI devices.  Over the years this code has been updated to
support all of the ATA and now ATA/ATAPI standards.  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 ATADRVR
-------------

The best way to see how this code can be used is shown in the C
program files EXAMPLE1.C and EXAMPLE2.C.  ATADRVR 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.

ATADRVR also includes detailed low level and command history
tracing funcitons.


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

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

The H files are:

   ATAIO.H
   ATAIOPD.H

The file ATAIO.H defines all of the "public" functions and data
for ATADRVR.  This file should be included into any program using
the ATADRVR functions.

The file ATAIOPD.H defines the "private" functions and data for
ATADRVR.  This file should NOT be included into programs using
the ATADRVR functions.

The C files are:

   ATAIOINT.C
   ATAIOISA.C
   ATAIOPCI.C
   ATAIOPIO.C
   ATAIOREG.C
   ATAIOSUB.C
   ATAIOTMR.C
   ATAIOTRC.C
   EXAMPLE1.C
   EXAMPLE2.C

The file ATAIOINT.C contains the x86 interrupt setup and handling
data and functions.  The public symbols in this file begin with
the characters "int_".

The file ATAIOISA.C contains the x86 ISA bus DMA functions.  The
public symbols in this file begin with characters "dma_isa_".

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

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

The file ATAIOREG.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 ATAIOSUB.C contains severals "private" functions used by
ATADRVR.

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

The file ATAIOTRC.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 ATADRVR to configure
an ATA device and execute a few commands.

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

                              NOTE
                              ----

   If you use ATADRVR in a program you should use only the public
   symbols.  This will allow you too upgrade to newer versions of
   ATADRVR (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 ATADRVR.


USING ATADRVR
-------------

Before using the ATADRVR 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 ATADRVR, as shown in EXAMPLE1.C or
EXAMPLE2.C, are these:

1) #include "ataio.h" in your program.

2) 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.

3) Call reg_config() so that ATADRVR can determine what devices
   are attached to the ATA host adapter.

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

ATADRVR has been developed using Borland C and can be compiled in
any x86 real mode memory mode.

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


Functions And Data In ATAIOINT.C
--------------------------------

These functions setup interrupt handling for the ATA host
adapter.  Interrupts are not required in order to execute ATA or
ATAPI commands but are usually used.  If int_enable_irq() is
called, then int_disable_irq() MUST be called before your program
exits (otherwise your system might hang).  The functions
int_enable_irq() and int_disable_irq() may be called multiple
times in order to switch between polling and interrupt mode on a
command by command basis.

void int_disable_irq( void );

   Disable interrupt use.

int int_enable_irq( int irqNum );      // use irq 8 to 15

   Enable interrupt use.  Only IRQ numbers 8 to 15 are allowed.

int int_irq_number;

   This value is READONLY -- DO NOT ALTER.

   This is the current IRQ number in use.

int int_int_vector;

   This value is READONLY -- DO NOT ALTER.

   This is the current x86 INT number in use.  IRQ 8 uses INT
   70H, IRQ 9 uses INT 71H, etc.

int int_use_intr_flag;

   This value is READONLY -- DO NOT ALTER.

   The value is not zero if an IRQ is currently configured.


Functions And Data In ATAIOISA.C
--------------------------------

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

int dma_isa_ata( int dev,                    // device (0 or 1)
                 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.  See the
   contents of reg_cmd_info.

int dma_isa_ata_lba( int dev,                // device (0 or 1)
                     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.  See the
   contents of reg_cmd_info.

int dma_isa_config( int chan );

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

int dma_isa_packet( int dev,                 // device (0 or 1)
                    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
                    unsigned int dpseg,      // data packet buffer
                    unsigned int dpoff );    // data packet buffer

   Execute an ATAPI Packet (A0H) command in DMA mode.  Note that
   the first byte of the Commmand Packet buffer is the command
   code of the "SCSI CDB" that is to be executed by the device.

   Returns 0 if no error or 1 if there is an error.  See the
   contents of reg_cmd_info.


Functions And Data In ATAIOPCI.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_ata( int dev,                    // device (0 or 1)
                 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.  See the
   contents of reg_cmd_info.

int dma_pci_ata_lba( int dev,                // device (0 or 1)
                     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.  See the
   contents of reg_cmd_info.

int dma_pci_config( unsigned int regAddr );

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

int dma_pci_packet( int dev,                 // device (0 or 1)
                    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
                    unsigned int dpseg,      // data packet buffer
                    unsigned int dpoff );    // data packet buffer

   Execute an ATAPI Packet (A0H) command in DMA mode.  Note that
   the first byte of the Commmand Packet buffer is the command
   code of the "SCSI CDB" that is to be executed by the device.

   Returns 0 if no error or 1 if there is an error.  See the
   contents of reg_cmd_info.

unsigned int dma_pci_prd_addr;        // SFF-8038 PRD address