AIX Version 7.2 Writing AIX Device Driver Programs IBM Note Before using this information and the product it supports, read the information in “Notices” on page 3 . This edition applies to AIX Version 7.2 and to all subsequent releases and modifications until otherwise indicated in new editions. © Copyright International Business Machines Corporation 2019. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. About this document This document provides detailed information about AIX device drivers. You can use this document to access configuration settings of sample device drivers and to access the instructions to run sample device drivers. Highlighting The following highlighting conventions are used in this document: Bold Identifies commands, subroutines, keywords, files, structures, directories, and other items whose names are predefined by the system. Bold highlighting also identifies graphical objects, such as buttons, labels, and icons that the you select. Italics Identifies parameters for actual names or values that you supply. Identifies examples of specific data values, examples of text similar to what you Monospace might see displayed, examples of portions of program code similar to what you might write as a programmer, messages from the system, or text that you must type. Case sensitivity in AIX Everything in the AIX® operating system is case sensitive, which means that it distinguishes between uppercase and lowercase letters. For example, you can use the ls command to list files. If you type LS, the system responds that the command is not found. Likewise, FILEA, FiLea, and filea are three distinct file names, even if they reside in the same directory. To avoid causing undesirable actions to be performed, always ensure that you use the correct case. ISO 9000 ISO 9000 registered quality systems were used in the development and manufacturing of this product. Support for the single UNIX specification The AIX operating system is designed to support The Open Group's Single UNIX Specification Version 3 (UNIX 03) for portability of operating systems based on the UNIX operating system. Many new interfaces, and some current ones, have been added or enhanced to meet this specification. To determine the correct way to develop a UNIX 03 portable application, see The Open Group's UNIX 03 specification on The UNIX System website (http://www.unix.org). © Copyright IBM Corp. 2019 v Chapter 1. Device Driver Overview Many computer programs are dedicated to working with attached devices in some way. For example, there are programs to send control characters to a printer, programs to receive characters from a terminal, and programs to read data from a tape. In a broad sense, each of these programs is a device driver because the program is dedicated to handling input from or output to a device. Such programs are usually regarded as being part of, or an extension of, the computer’s operating system. Any operating system that supports multitasking (such as AIX) needs some way to prevent one program from writing to, or changing the state of, some device that is already being accessed by another program. So, a multitasking operating system relies on the computer's processors to distinguish between privileged and non-privileged execution of instructions. Therefore, one must distinguish between programs that execute in privileged mode (kernel mode) and those that execute in user mode. The AIX kernel consists of all software that executes in kernel mode. Even though AIX programs that execute in user mode can drive devices, such as a network adapter or some device attached to a USB port, they can only do so by invoking software that is part of the kernel. Because kernel device drivers are considerably more complex than drivers that execute in user mode, from here on, the term device driver will only refer to software that handles a device while executing in kernel mode. Device drivers are more complex than user software for several reasons: • Device drivers output data to a device or demand data from a device. This means that the driver may have to read or write to registers on a card attached to an I/O bus, or the driver may have to set up the means for the data to be transferred in some other way. A device driver is intimately interconnected with processor memory design, how the processor performs I/O, and with the architecture of the I/O bus attached to the system. So, device drivers are not portable; migrating the driver routines from one system to another often requires the routines to be rewritten. • Device drivers may have to process interrupts generated by a card attached to the system I/O bus. When a terminal sends a character to the computer, or a disk drive has completed writing a block of data, the card serving as an adapter between the device and the I/O bus on the computer generates an interrupt. The software routines, within a device driver, that process interrupts (called interrupt handlers) take some sort of action like buffering incoming data, or signaling a process. Because such interrupts occur asynchronously, meaning that they occur without regard to what instructions the computer’s processors are executing, the interrupt may occur while a processor on the computer is in the middle of handling another interrupt. Therefore, interrupt handlers must be reentrant; in other words, they must be able to access shared resources (such as non-private data) and exclude concurrent access by any software including another instance of itself. Device driver routines that (asynchronously) execute in the context of handling an interrupt are said to be, on the interrupt side, and are occasionally referred to as the device handler, but this is not the same thing as a network device handler. Device driver routines that (synchronously) execute in the context of a calling process are said to be on the call side. For more information on concurren t access o f shared data, see Chapter 5, “Synchronization and Serialization.” Device Driver Overview 1-1 • Device drivers may have to execute in real time. Device drivers may have to respond to an interrupt, or perform some other function within a certain fixed period of time. • A device driver is a collection of routines. There is no main routine. The rou tines are usu ally wri tten in C an d co mpiled to pr oduce on e o r two Ex tende d Obje ct File Forma t (XCOFF o r XCOFF 64) object files. Begin ning with AIX V ersio n 6, a ll device driv ers are 64-b it only (XCOFF64): ther e no lo ng er support for 3 2-bit dev ice driv ers. The obj ect file s are link ed to en a ble the ker n el loader to r es olve ker nel sym bols. As a resu lt of linki ng , the loa der section is filled o ut wit h a list of sy m bo ls to imp ort from th e kernel. The sy mbo ls are in t he fi le /lib /ke rnex.exp. The linking also es tabli shes the dri ver’ s configuratio n routine as t he defa ult entr y point for be ginni ng execution. A simple ex a mple is shown in “Sa m ple De vice Driver” on pag e 1-15 . Aspects of the Kernel that Affect Device Drivers There are a number of attributes of the AIX kernel that affect device drivers: • Kernel routines can only call kernel services. Kernel routines cannot call routines meant to execute in user mode. So, device driver routines are not linked with the C library libc.a, nor can they invoke system calls. The re are some kernel DMA and timer routines in libsys.a, and there are some C library calls written to execute in kernel mode in the library libcsys.a. For more information on the m, please refer to U nders tanding K erne l B inding. • Kernel code and data that is not pinned (explicitly or implicitly) is paged into system RAM from a paging logical volume on disk. So, one must distinguish between device driver routines that are to be collectively pinned, called the bottom half, and those that are to be paged, called the top half. Because device driver routines on the interrupt side must be pinned, the phrases in the bottom half and on the interrupt sideare sometimes used as if they are synonyms, but they really are not synonyms. Due to real-time concerns, sometimes routines on the call side are placed in the bottom half. • Kernel routines are difficult to debug. There is a kernel debugger, kdb, but it is not as easy to use as is dbx. References to improper addresses may cause data corruption (because the kernel is privileged) or a system crash. It is possible to trace the execution of a device driver with printf; but printf only prints to a native serial/console port, when the kernel debugger is enabled . Also it may affect a device driver ’s timing. See Debug Facilities for more details on debugging • Execution of kernel routines, in the context of a process, can be preempted by the scheduler in favor of a process with greater priority. This means that device driver routines cannot depend on disabling interrupts as being sufficient to avert concurrent access to shared resources. It also means that drivers (not just interrupt handlers) must be reentrant. • The AIX kernel is dynamically extendible. Object files acceptable to the kernel loader, are bound into the AIX kernel while the computer is still operating; there is no need to restart the system.