Device Driver Technical Update for Tru64 UNIX Version 4.0F


	Device Driver Technical Update for Tru64 UNIX Version 4.0F
	Tru64 UNIX Version 4.0F or higher, May 1999

© Digital Equipment Corporation, 1999.
All rights reserved. Compaq, the Compaq logo, and the DIGITAL logo are registered in the U.S. Patent and Trademark Office. DIGITAL, DEC, the DIGITAL logo, and Alpha AXP are trademarks of Digital Equipment Corporation. UNIX is a registered trademark and The Open Group is a trademark of The Open Group in the U.S. and other Countries.

This technical update includes all device driver updates and modifications for Tru64 UNIX (formerly DIGITAL UNIX) Version 4.0F.

Updated: 13 May 1999

Contents

64-Bit DMA Address Support (13 May 1999)

PCI Driver Configuration Failover (13 May 1999)

dma_get_sgentry_reset (13 May 1999)

dma_get_num_val_sgentrys (13 May 1999)

64-Bit DMA Address Support
Date: 13 May 1999

Some PCI devices can generate 64-bit addresses when performing direct memory access (DMA) accesses. The use of 64-bit addressing eliminates the need for device drivers to request scatter-gather resources on large memory systems (systems with greater than 1 GB of main memory). Using a 64-bit PCI address to directly access main memory without the use of scatter-gather hardware support can improve the performance of DMA transfers that are typically less than or equal to a virtual page in size. (On AlphaServers, the virtual page size is 8 KB.)

In order for a driver to obtain a 64-bit PCI address for a DMA mapping, it must explicitly request it in the flags field of a dma_map_alloc routine and its associated dma_map_load routine. If a system supports 64-bit PCI addresses, Dual-Address Cycles (DACs), then the DMA mapping subsystem will provide ba members of the dma_handle's sg_entry structures with some number of address bits set above bit 31.

A system that does not have the hardware support for 64-bit PCI addresses will return DMA sg_entry structures with only the lower, nonzero 32 bits; the upper 32 bits will be zero. To request 64-bit addresses from a DMA mapping, you must set the flag bit DMA_64BIT in the dma_map_alloc and dma_map_load routines.

Like the DMA_CONTIG flag, the DMA_64BIT flag is a preferred mapping mode. A dma_map_alloc or dma_map_load routine may not provide 64-bit PCI addresses when DMA_64BIT is set. If a dma_map_load routine does provide a 64-bit PCI address, one or more of the <63:32> address bits will be set in the ba member of the sg_entry structure.

Note: You can use the DMA_CONTIG flag in conjunction with DMA_64BIT. This functionality is beneficial when a transfer is larger than a virtual page and the PCI device's DMA engine takes only one sg_entry structure. Under these conditions, stopping, reloading, and restarting a DMA engine doing 64-bit DMA transfers at every virtual page crossing is relatively time consuming with respect to the time it takes to transfer a virtual page-sized block of data.

DMA_64BIT support is provided in Tru64 UNIX Version 4.0E. The following Alpha-based PCI systems support 64-bit PCI DMA mapping: AlphaServer 4100, AlphaServer 4000, AlphaServer 800, AlphaStation 500, and AlphaStation 600.

PCI Driver Configuration Failover
Date: 13 May 1999

In previous DIGITAL UNIX releases, the PCI bus support allowed only one driver to be configured for a device. The matching of driver to device is controlled through a table called the option data table, shipped as a source (.c) file and as PCI_Option entries in /etc/sysconfigtab. The driver-matching support allowed a number of elements in the device's PCI configuration header to be used to match to a known driver. Multiple entries for a single device could exist in the option data tables, but only the highest-precedence driver match would be tried by the PCI bus configuration code. A failure of the highest-precedence driver yielded a failed configuration of the device. For more information, see Writing PCI Bus Device Drivers.

In Tru64 UNIX Version 4.0F and higher, the device-to-driver matching rules still apply, but the PCI driver configuration support allows more than one driver to be called for configuration. Therefore, if the highest-precedence driver fails, a more generic, lower-precedence, class-level driver can be configured for the device.

For example, if the operating system knows that a device-specific driver exists for a given graphics card, but the kernel does not presently have the driver configured into it, then the operating system will try a generic VGA device driver if the hardware is a VGA-compatible device.

Another case in which this failover support provides configuration flexibility is when a driver must probe further data beyond the PCI configuration header to determine if it is the proper driver for a given device. For example, if a driver is written for a common SCSI PCI device with on-module firmware data, the device driver can fail when the on-module firmware does not match. Upon failure, a more generic SCSI PCI driver for the specific hardware can be configured. This feature is useful for an Independent Hardware Vendor (IHV), which provides a customized driver for a common PCI device that is not distinguishable in the PCI configuration header of the device. In this case, the IHV's driver can be tested first and if it fails, the more common driver for the PCI device can be configured into the kernel.

dma_get_sgentry_reset (supported in Version 4.0D and higher)
Date: 13 May 1999

NAME
dma_get_sgentry_reset - General: Resets the internal DMA mapping control variable to the beginning of the sg_entry structures

SYNOPSIS
#include <io/common/devdriver.h>
int dma_get_sgentry_reset(dma_handle_t dma_handle)

ARGUMENTS
dma_handle
Specifies a handle to DMA resources associated with the mapping of an in-memory I/O buffer onto a controller's I/O bus. The handle provides the information to initialize the index. When dma_get_next_sgentry or dma_get_current_sgentry is called, the index controls which sg_entry structure is returned. Device driver writers can view the DMA handle as the tag to the allocated system resources needed to perform a DMA operation.

DESCRIPTION
The dma_get_sgentry_reset routine resets internal DMA control structure variables so that a driver can traverse a DMA scatter-gather list any number of times for a single I/O. Drivers need a mechanism to traverse a DMA scatter-gather list more than once per I/O for two known reasons:

Failover - This reset allows a clean retry of a failed DMA transaction by the driver without returning a failed I/O transfer to the upper layers.
Reset after a full or a partial traversal - A driver may need to count or check the number of sg_entry structures that a dma_map_load generates in order to make the device-specific I/O data structure transfer. These types of drivers may have to traverse the list several times.

NOTES
Using the dma_get_sgentry_reset routine makes the device driver more portable between different versions of the operating system.

RETURN VALUES
The dma_get_sgentry_reset routine returns ESUCCESS when the reset is successful and it returns EINVAL when the calling parameter is invalid.

SEE ALSO
Data Structures: dma_handle_t
Kernel Routines: dma_get_next_sgentry, dma_get_curr_sgentry, dma_get_num_val_sgentrys

dma_get_num_val_sgentrys (supported in Version 4.0D and higher)
Date: 13 May 1999

NAME
dma_get_num_val_sgentrys - General: Returns the number of valid sg_entry structures used to map an in-memory DMA buffer

SYNOPSIS
#include <io/common/devdriver.h>
int dma_get_num_val_sgentrys(dma_handle_t dma_handle)

ARGUMENTS
dma_handle
Specifies a handle to the DMA resources associated with the mapping of an in-memory I/O buffer onto a controller's I/O bus. This handle is used to return the number of sg_entry structures associated with a dma_handle for a valid DMA mapping. Device driver writers can view the DMA handle as the tag to the allocated system resources needed to perform a DMA operation.

DESCRIPTION
The dma_get_num_val_sgentrys routine returns the number of valid scatter-gather elements (sg_entry structures) associated with a DMA handle. A DMA handle can have more sg_entry structures allocated than what is used for a particular DMA transfer. This routine provides the count of valid sg_entry structures and not the maximum number of allocated sg_entry structures.

The functionality of dma_get_num_val_sgentrys can be provided by a for loop that executes dma_get_next_sgentry until it returns NULL, followed by a call to dma_get_sgentry_reset. This loop can be relatively slow, and typically this counting operation is in the critical performance path of a driver. The dma_get_num_val_sgentrys routine provides a much faster and simpler algorithm that gives the number of sg_entry structures attached to a DMA handle.

NOTES
Using the dma_get_sgentry_reset routine makes the device driver more portable between different versions of the operating system.

RETURN VALUES
The dma_get_num_val_sgentrys routine returns the number of valid sg_entry structures attached to the DMA handle.

SEE ALSO
Data Structures: dma_handle_t
Kernel Routines: dma_get_next_sgentry, dma_get_current_sgentry, dma_get_sgentry_reset