Help: ICE_DRIVERS_GENERAL

Overview of driver functions

The following discussions refer to any of the ICE cards on the PCI bus.
The ICE-PIC, ICE-MBT, and ICE-SLimpIC all look the same to the driver.
Note that in this document, only the ICE-PIC is referenced.

This section describes the functions and responsibilities of the ICE-PIC 
device driver:  

1. Provide a logical handle to each device on the system.  This is a device
   file in UNIX and a device name in VMS or Windows.

2. Read and Write registers on the PCI interface chip.

3. Lock a user buffer in memory and map its pages to physical memory for PCI 
   bus DMA mastering by the ICE-PIC.

To achieve high sustained DMA rates, the driver does not implement the standard
read and write interfaces.  Instead, the driver is responsible for locking a 
user buffer in memory and mapping these pages to physical memory.  The Ice-PIC
then takes control of the PCI bus to arbitrate input/output DMAs between the host
memory and the Ice-PIC's onboard memory.

Data is written into (or read from) the ICE-PIC using a circular buffer.  
The application polls the ICE-PIC for the current buffer pointer to find out
if new data has been written or read from the host buffer.  There are no host
interrupts or other host CPU activity involved with the data transfer. The 
Ice-PIC processor handles all of the DMA sequencing, and the PCI core handles 
the bus arbitration at the hardware level with the PCI bus controller.

In PCI compliant systems, a card is allowed to specify a minimum time that 
it will have the bus for a burst transfer, and a maximum time that it can be 
denied control of the bus.  By tuning these parameters, it is possible to get 
extremely high transfer rates with relatively small buffers on the card to 
cover the PCI bus sharing latencies.

While the circular DMAs are in progress, the application code can query the
card for the current DMA pointer allowing continuous access to real-time data
with resolution to a 4-byte word.  The cards can simultaneously process 80 DMA
channels to different host buffers, and possibly for different processes.
Since a process must be able to hold a lock on a card for multiple driver 
calls, system level locks are called by the library functions.  The DMAs
are not affected by process locks, only actions performed on the host.

The main security function of the driver is to make sure that the Ice-PIC 
does not perform a DMA to a non-mapped memory address.  This is possible if
the application code unmaps the user buffer while a DMA is still in progress
or unmaps the buffer during a crash.  The first case is handled by checks in 
the run-time libraries.  The driver must implement a procedure to check that 
all buffers for a process are unmapped cleanly before the process exits.  If 
this is not the case, the driver assumes a process has crashed and shuts down 
the Ice-PIC.

The following ioctl() method calls must be implemented by the driver:

  IOCTL_READ - read a register from the PCI-IF core
  IOCTL_WRITE - write a register to the PCI-IF core
  IOCTL_ACMD - execute command packet on the Ice-PIC 
  IOCTL_MAP - map a user buffer into PCI space
  IOCTL_UNMAP - unmaps a user buffer from PCI space

The driver must also implement an open(), close(), and cancel() method.