5    Kernel Interfaces That TURBOchannel Device Drivers Use

This chapter describes when and why you would use the kernel interfaces developed for use with TURBOchannel device drivers. Included are brief examples on how to use these interfaces in device drivers. For complete descriptions of the definitions and arguments for these kernel interfaces, see Appendix A.

When writing device drivers for the TURBOchannel bus, you need to be familiar with kernel interfaces that:

• Determine the base address of a device

• Determine the name of a specific option module

• Isolate and determine the status of a memory error

• Ensure that a write to input/output space has completed

• Obtain the page frame number

• Manage memory map registers

Additionally, the I/O subsystems for the DEC 3000 series processors allow a TURBOchannel device driver to use a hardware scatter-gather map to transfer data to and from noncontiguous physical memory.

5.1    Determining the Name of an Option Module

The tc_module_name interface returns the name of a specific TURBOchannel option module. You pass a pointer to a controller structure and a character array to be filled in by tc_module_name.

The following code fragment shows a call to the tc_module_name interface:

.
.
.

struct controller *ctlr; [1]
char cp[TC_ROMNAMLEN + 1]; [2]

.
.
.

        if (tc_module_name(ctlr, cp) == -1) { [3]
            printf("Module name conversion failed\n"); [4]
}
else {
           printf("Module name is %s\n", cp); [5]

.
.
.

1. Declares a pointer to the controller structure for this controller. The controller structure represents an instance of a controller entity, one that connects logically to a bus. A controller can control devices that are directly connected or can perform some other controlling operation, such as a network interface or terminal controller operation. [Return to example]

2. Declares a character array to hold the module name. This character array is of size TC_ROMNAMLEN + 1, which is large enough to accommodate the module's name. [Return to example]

3. If the call returns -1, then name lookup failed. [Return to example]

4. Prints an error message if the conversion failed. [Return to example]

5. If the call does not return -1, then name lookup was successful; prints the module name. [Return to example]

5.2    Determining a Device's Base Address

In the tc_module_name interface, you pass a pointer to a controller structure to determine the TURBOchannel option's module name. However, the pointer to the controller structure is not valid in the driver's xxprobe interface. Therefore, if you need to determine the name of a device in the xxprobe interface, use the tc_addr_to_name interface. The tc_addr_to_name interface returns the TURBOchannel option's module name referred to by the base address of the device (the base address of the device is the I/O handle passed to the driver's xxprobe interface).

The following code fragment shows a call to tc_addr_to_name:

.
.
.

struct controller *ctlr; [1]
char cp[10]; [2]

 

        if (tc_addr_to_name(ctlr->addr, cp) == -1) { [3]
               printf("Address to Name lookup failed\n"); [4]
        }
        else {
              printf("Module name is %s\n", cp); [5]

.
.
.

1. Declares a pointer to the controller structure for this controller. The controller structure represents an instance of a controller entity, one that connects logically to a bus. A controller can control devices that are directly connected or can perform some other controlling operation, such as a network interface or terminal controller operation.

   The addr member stores the address of the device registers for the controller. [Return to example]

2. Declares a character array to hold the module name. [Return to example]

3. If the conversion fails, the interface returns -1. [Return to example]

4. Prints an error message if the conversion fails. [Return to example]

5. On success, prints the module name. [Return to example]

5.3    Isolating and Handling Memory Errors

To obtain and log information about errors that occur on a direct memory access (DMA) operation, call the tc_isolate_memerr interface. Support for this interface is CPU specific. The call to tc_isolate_memerr returns -1 if the interface is not supported by the CPU. The tc_isolate_memerr interface takes a pointer to a structure that contains the following information:

• The physical address of the error

• The virtual address of the error

• A flag to indicate whether to log the error

• The size of the DMA block being transferred

• The error type

  Error types are returned to indicate if a parity (transient, hard, or soft) error occurred or if no error occurred.

The following code fragment for the /dev/xx device driver shows a call to the tc_isolate_memerr interface:

.
.
.

#include <io/dec/tc/tc.h>

.
.
.

struct tc_memerr_status *xx_memerr_status; [1]
xx_memerr_status = &xx_memerr; [2]

 

xx_memerr_status->pa = err_addr; [3]
xx_memerr_status->log = TC_LOG_MEMERR; [4]

 

tc_isolate_memerr(xx_memerr_status); [5]

.
.
.

1. Declares a pointer to the tc_memerr_status structure. [Return to example]

2. Initializes the pointer to the tc_memerr_status structure. [Return to example]

3. Stores the error address. [Return to example]

4. Requests that the error be logged. [Return to example]

5. Calls the tc_isolate_memerr interface, passing to it the pointer to the tc_memerr_status structure. [Return to example]

5.4    Ensuring a Write to I/O Space Has Completed

TURBOchannel device drivers that operate on the ULTRIX operating system and MIPS CPUs call the wbflush interface to ensure that a write to I/O space has completed. Device drivers that operate on the Digital UNIX operating system and Alpha CPUs should call the mb interface. See Writing Device Drivers: Tutorial for discussions of how and when to use the mb interface.

5.5    Using Scatter-Gather Maps

Previous versions of this book discuss how TURBOchannel device drivers use the following TURBOchannel-specific interfaces associated with scatter-gather maps: tc_map_alloc, tc_loadmap, and tc_map_free. Digital UNIX now provides generic interfaces to perform DMA data transfer operations. Use of these generic interfaces makes device drivers more portable between DMA hardware-mapping implementations across different hardware platforms because it masks out any future changes in the kernel- and system-level DMA mapping data structures.

The following interfaces replace the TURBOchannel-specific interfaces associated with scatter-gather maps:

• dma_map_alloc

• dma_map_dealloc

• dma_map_load

• dma_map_unload