Page is loading ...
Bull
Kernel Extensions and Device Support
Programming Concepts
AIX
86 A2 36JX 02
ORDER REFERENCE
Bull
Kernel Extensions and Device Support
Programming Concepts
AIX
Software
November 1999
BULL ELECTRONICS ANGERS
CEDOC
34 Rue du Nid de Pie – BP 428
49004 ANGERS CEDEX 01
FRANCE
86 A2 36JX 02
ORDER REFERENCE
The following copyright notice protects this book under the Copyright laws of the United States of America
and other countries which prohibit such actions as, but not limited to, copying, distributing, modifying, and
making derivative works.
Copyright
Bull S.A. 1992, 1999
Printed in France
Suggestions and criticisms concerning the form, content, and presentation of
this book are invited. A form is provided at the end of this book for this purpose.
To order additional copies of this book or other Bull Technical Publications, you
are invited to use the Ordering Form also provided at the end of this book.
Trademarks and Acknowledgements
We acknowledge the right of proprietors of trademarks mentioned in this book.
AIX
R
is a registered trademark of International Business Machines Corporation, and is being used under
licence.
UNIX is a registered trademark in the United States of America and other countries licensed exclusively through
the Open Group.
Year 2000
The product documented in this manual is Year 2000 Ready.
The information in this document is subject to change without notice. Groupe Bull will not be liable for errors
contained herein, or for incidental or consequential damages in connection with the use of this material.
Contents
Trademarks and Acknowledgements . . iii
About This Book . . . . . . . . . . xv
Who Should Use This Book . . . . . . . . . xv
How to Use This Book . . . . . . . . . . xv
Overview of Contents . . . . . . . . . . xv
Highlighting . . . . . . . . . . . . . xvi
ISO 9000 . . . . . . . . . . . . . . . xvi
AIX 32-Bit Support for the X/Open UNIX95
Specification . . . . . . . . . . . . . . xvi
AIX 32-Bit and 64-Bit Support for the UNIX98
Specification . . . . . . . . . . . . . xvii
Related Publications . . . . . . . . . . . xvii
Ordering Publications . . . . . . . . . . xvii
Chapter 1. Kernel Environment . . . . . 1
Understanding Kernel Extension Binding . . . . . 2
Base Kernel Services - the /unix Name Space . . 2
Using System Calls with Kernel Extensions . . . 3
Using Private Routines . . . . . . . . . . 4
Using Libraries . . . . . . . . . . . . 5
Understanding Execution Environments . . . . . 7
Process Environment . . . . . . . . . . 8
Interrupt Environment . . . . . . . . . . 8
Understanding Kernel Threads . . . . . . . . 9
Kernel Threads, Kernel Only Threads, and User
Threads . . . . . . . . . . . . . . . 9
Kernel Data Structures. . . . . . . . . . 10
Thread Creation, Execution, and Termination . . 10
Thread Scheduling . . . . . . . . . . . 10
Thread Signal Handling . . . . . . . . . 10
Using Kernel Processes . . . . . . . . . . 11
Introduction to Kernel Processes . . . . . . 11
Accessing Data from a Kernel Process . . . . 12
Cross-Memory Services . . . . . . . . . 13
Kernel Process Creation, Execution, and
Termination . . . . . . . . . . . . . 13
Kernel Process Preemption . . . . . . . . 14
Kernel Process Signal and Exception Handling . 14
Kernel Process Use of System Calls . . . . . 15
Accessing User-Mode Data While in Kernel Mode 15
Data Transfer Services . . . . . . . . . . 15
Using Cross-Memory Kernel Services. . . . . 16
Understanding Locking . . . . . . . . . . 16
Lockl Locks . . . . . . . . . . . . . 16
Simple Locks . . . . . . . . . . . . . 17
Complex Locks . . . . . . . . . . . . 17
Types of Critical Sections . . . . . . . . . 17
Priority Promotion . . . . . . . . . . . 17
Locking Strategy in Kernel Mode . . . . . . 17
Understanding Exception Handling . . . . . . 18
Exception Processing . . . . . . . . . . 18
Kernel-Mode Exception Handling . . . . . . 18
Implementing Kernel Exception Handlers . . . 20
User-Mode Exception Handling . . . . . . 23
64-bit Kernel Extension Development. . . . . . 23
Chapter 2. System Calls . . . . . . . 25
Differences Between a System Call and a User
Function . . . . . . . . . . . . . . . 25
Understanding System Call Execution . . . . . 25
User Protection Domain . . . . . . . . . 26
Kernel Protection Domain . . . . . . . . 26
Actions of the System Call Handler . . . . . 26
Accessing Kernel Data While in a System Call. . 27
Preempting a System Call . . . . . . . . 28
Handling Signals While in a System Call . . . 28
Handling Exceptions While in a System Call . . 29
Understanding Nesting and Kernel-Mode Use of
System Calls . . . . . . . . . . . . . 30
Page Faulting within System Calls. . . . . . 30
Returning Error Information from System Calls 31
System Calls Available to Kernel Extensions . . . 31
System Calls Available to All Kernel Extensions 31
System Calls Available to Kernel Processes Only 32
Chapter 3. Virtual File Systems . . . . 33
Logical File System Overview . . . . . . . . 33
Component Structure of the Logical File System 34
Virtual File System Overview . . . . . . . . 35
Understanding Virtual Nodes (V-nodes) . . . . 35
Understanding Generic I-nodes (G-nodes) . . . 35
Understanding the Virtual File System Interface 36
Understanding Data Structures and Header Files for
Virtual File Systems . . . . . . . . . . . 37
Configuring a Virtual File System . . . . . . . 38
Chapter 4. Kernel Services . . . . . . 39
Categories of Kernel Services . . . . . . . . 39
I/O Kernel Services . . . . . . . . . . . 39
Block I/O Kernel Services . . . . . . . . 39
Buffer Cache Kernel Services . . . . . . . 40
Character I/O Kernel Services . . . . . . . 40
Interrupt Management Services. . . . . . . 40
Memory Buffer (mbuf) Kernel Services . . . . 41
DMA Management Kernel Services . . . . . 42
Block I/O Buffer Cache Kernel Services: Overview 42
Managing the Buffer Cache . . . . . . . . 43
Using the Buffer Cache write Services . . . . 43
Understanding Interrupts. . . . . . . . . . 44
Interrupt Priorities . . . . . . . . . . . 44
Understanding DMA Transfers . . . . . . . . 44
Hiding DMA Data . . . . . . . . . . . 45
Accessing Data While the DMA Operation Is in
Progress . . . . . . . . . . . . . . 45
Kernel Extension and Device Driver Management
Kernel Services . . . . . . . . . . . . . 46
Kernel Extension Loading and Binding Services 46
Other Functions for the Kernel Extension and
Device Driver Management Services . . . . . 46
© Copyright IBM Corp. 1997, 1999 v
List of Kernel Extension and Device Driver
Management Kernel Services . . . . . . . 47
Locking Kernel Services . . . . . . . . . . 48
Lock Allocation and Other Services . . . . . 48
Simple Locks . . . . . . . . . . . . . 48
Complex Locks . . . . . . . . . . . . 49
Lockl Locks . . . . . . . . . . . . . 50
Atomic Lock Operations . . . . . . . . . 50
Atomic Operations . . . . . . . . . . . 51
File Descriptor Management Services . . . . . . 51
Logical File System Kernel Services . . . . . . 51
Other Considerations . . . . . . . . . . 52
List of Logical File System Kernel Services . . . 52
Memory Kernel Services . . . . . . . . . . 53
Memory Management Kernel Services . . . . 53
Memory Pinning Kernel Services . . . . . . 53
User Memory Access Kernel Services . . . . . 54
Virtual Memory Management Kernel Services . . 54
Cross-Memory Kernel Services . . . . . . . 55
Understanding Virtual Memory Manager Interfaces 56
Virtual Memory Objects . . . . . . . . . 56
Addressing Data. . . . . . . . . . . . 57
Moving Data to or from a Virtual Memory Object 57
Data Flushing . . . . . . . . . . . . 57
Discarding Data . . . . . . . . . . . . 57
Protecting Data . . . . . . . . . . . . 58
Executable Data . . . . . . . . . . . . 58
Installing Pager Backends. . . . . . . . . 58
Referenced Routines . . . . . . . . . . 58
Services that Support 64-bit Processes . . . . 59
Message Queue Kernel Services . . . . . . . 60
Network Kernel Services . . . . . . . . . . 61
Address Family Domain and Network Interface
Device Driver Kernel Services . . . . . . . 61
Routing and Interface Address Kernel Services 62
Loopback Kernel Services. . . . . . . . . 62
Protocol Kernel Services . . . . . . . . . 62
Communications Device Handler Interface Kernel
Services . . . . . . . . . . . . . . 63
Process and Exception Management Kernel Services 63
Creating Kernel Processes . . . . . . . . 63
Creating Kernel Threads . . . . . . . . . 63
Kernel Structures Encapsulation . . . . . . 64
Registering Exception Handlers. . . . . . . 64
Signal Management. . . . . . . . . . . 64
Events Management . . . . . . . . . . 64
List of Process, Thread, and Exception
Management Kernel Services . . . . . . . 65
RAS Kernel Services . . . . . . . . . . . 66
List of RAS Kernel Services . . . . . . . . 66
Security Kernel Services . . . . . . . . . . 67
Timer and Time-of-Day Kernel Services . . . . . 67
Time-Of-Day Kernel Services . . . . . . . 67
Fine Granularity Timer Kernel Services . . . . 67
Timer Kernel Services for Compatibility . . . . 68
Watchdog Timer Kernel Services . . . . . . 68
Using Fine Granularity Timer Services and
Structures . . . . . . . . . . . . . . . 68
Timer Services Data Structures . . . . . . . 68
Coding the Timer Function . . . . . . . . 69
Using Multiprocessor-Safe Timer Services . . . . 69
Virtual File System (VFS) Kernel Services . . . . 69
Chapter 5. Asynchronous I/O
Subsystem . . . . . . . . . . . . . 71
Asynchronous I/O Overview . . . . . . . . 71
How do I know if I need to use AIO? . . . . 72
How many AIO Servers am I currently using?. . 72
How many AIO servers do I need? . . . . . 73
Prerequisites . . . . . . . . . . . . . . 73
Functions of Asynchronous I/O . . . . . . . 73
Large File-Enabled Asynchronous I/O (AIX
Version 4.2.1 or later) . . . . . . . . . . 73
Nonblocking I/O . . . . . . . . . . . 74
Notification of I/O Completion. . . . . . . 74
Cancellation of I/O Requests . . . . . . . 75
Asynchronous I/O Subroutines. . . . . . . . 75
Order and Priority of Asynchronous I/O Calls . 76
Subroutines Affected by Asynchronous I/O . . . 76
Changing Attributes for Asynchronous I/O. . . . 76
64-bit Enhancements . . . . . . . . . . . 77
Chapter 6. Device Configuration
Subsystem . . . . . . . . . . . . . 79
Scope of Device Configuration Support . . . . . 79
Device Configuration Subsystem Overview . . . . 79
General Structure of the Device Configuration
Subsystem . . . . . . . . . . . . . . . 80
High-Level Perspective . . . . . . . . . 83
Device Method Level . . . . . . . . . . 84
Low-Level Perspective. . . . . . . . . . 84
Device Configuration Database Overview . . . . 84
Basic Device Configuration Procedures Overview. . 85
Device Configuration Manager Overview . . . . 85
Devices Graph . . . . . . . . . . . . 86
Configuration Rules . . . . . . . . . . 86
Invoking the Configuration Manager . . . . . 87
Device Classes, Subclasses, and Types Overview . . 87
Writing a Device Method . . . . . . . . . . 88
Invoking Methods . . . . . . . . . . . 88
Example Methods . . . . . . . . . . . 88
Understanding Device Methods Interfaces . . . . 89
Configuration Manager . . . . . . . . . 89
Run-Time Configuration Commands . . . . . 90
Understanding Device States . . . . . . . . 90
Adding an Unsupported Device to the System . . 92
Modifying the Predefined Database . . . . . 92
Adding Device Methods . . . . . . . . . 92
Adding a Device Driver . . . . . . . . . 93
Using installp Procedures. . . . . . . . . 93
Understanding Device Dependencies and Child
Devices . . . . . . . . . . . . . . . . 93
Accessing Device Attributes . . . . . . . . . 94
Modifying an Attribute Value . . . . . . . 95
Device Dependent Structure (DDS) Overview . . . 95
How the Change Method Updates the DDS . . 96
Guidelines for DDS Structure . . . . . . . 96
Example of DDS. . . . . . . . . . . . 97
List of Device Configuration Commands . . . . 97
List of Device Configuration Subroutines . . . . 98
vi Kernel Extensions and Device Support Programming Concepts
Chapter 7. Communications I/O
Subsystem . . . . . . . . . . . . . 99
User-Mode Interface to a Communications PDH . . 99
Kernel-Mode Interface to a Communications PDH 99
CDLI Device Drivers . . . . . . . . . . . 100
Communications Physical Device Handler Model
Overview. . . . . . . . . . . . . . . 100
Use of mbuf Structures in the Communications
PDH . . . . . . . . . . . . . . . 101
Common Communications Status and Exception
Codes . . . . . . . . . . . . . . . 101
Status Blocks for Communications Device Handlers
Overview. . . . . . . . . . . . . . . 102
CIO_START_DONE . . . . . . . . . . 102
CIO_HALT_DONE . . . . . . . . . . 102
CIO_TX_DONE . . . . . . . . . . . 103
CIO_NULL_BLK . . . . . . . . . . . 103
CIO_LOST_STATUS . . . . . . . . . . 103
CIO_ASYNC_STATUS . . . . . . . . . 103
MPQP Device Handler Interface Overview . . . 104
Binary Synchronous Communication (BSC) with
the MPQP Adapter . . . . . . . . . . 104
Description of the MPQP Card . . . . . . 105
Serial Optical Link Device Handler Overview . . 108
Special Files . . . . . . . . . . . . . 108
Entry Points . . . . . . . . . . . . . 108
Configuring the Serial Optical Link Device Driver 109
Physical and Logical Devices . . . . . . . 109
Changeable Attributes of the Serial Optical Link
Subsystem . . . . . . . . . . . . . 110
Forum-Compliant ATM LAN Emulation Device
Driver . . . . . . . . . . . . . . . . 110
Adding ATM LANE Clients . . . . . . . 113
Configuration Parameters for the ATM LANE
Device Driver . . . . . . . . . . . . 113
Device Driver Configuration and
Unconfiguration . . . . . . . . . . . 118
Device Driver Open . . . . . . . . . . 118
Device Driver Close . . . . . . . . . . 118
Data Transmission . . . . . . . . . . . 118
Data Reception . . . . . . . . . . . . 119
Asynchronous Status . . . . . . . . . . 119
Device Control Operations . . . . . . . . 120
Tracing and Error Logging in the ATM LANE
Device Driver . . . . . . . . . . . . 124
Adding an ATM MPOA Client . . . . . . 124
Configuration Parameters for ATM MPOA
Client . . . . . . . . . . . . . . . 126
Tracing and Error Logging in the ATM MPOA
Client . . . . . . . . . . . . . . . 126
Fiber Distributed Data Interface (FDDI) Device
Driver . . . . . . . . . . . . . . . . 127
Configuration Parameters for FDDI Device
Driver . . . . . . . . . . . . . . . 127
FDDI Device Driver Configuration and
Unconfiguration . . . . . . . . . . . 128
Device Driver Open . . . . . . . . . . 128
Device Driver Close . . . . . . . . . . 128
Data Transmission. . . . . . . . . . . 128
Data Reception . . . . . . . . . . . . 129
Reliability, Availability, and Serviceability for
FDDI Device Driver . . . . . . . . . . 129
High-Performance (8fc8) Token-Ring Device Driver 131
Configuration Parameters for Token-Ring Device
Driver . . . . . . . . . . . . . . . 132
Device Driver Configuration and
Unconfiguration . . . . . . . . . . . 132
Device Driver Open . . . . . . . . . . 132
Device Driver Close . . . . . . . . . . 132
Data Transmission. . . . . . . . . . . 133
Data Reception . . . . . . . . . . . . 133
Asynchronous Status . . . . . . . . . . 133
Device Control Operations . . . . . . . . 136
Trace Points and Error Log Templates for 8fc8
Token-Ring Device Driver . . . . . . . . 138
High-Performance (8fa2) Token-Ring Device Driver 140
Configuration Parameters for 8fa2 Token-Ring
Device Driver . . . . . . . . . . . . 141
Device Driver Configuration and
Unconfiguration . . . . . . . . . . . 141
Device Driver Open . . . . . . . . . . 141
Device Driver Close . . . . . . . . . . 142
Data Transmission. . . . . . . . . . . 142
Data Reception . . . . . . . . . . . . 142
Asynchronous Status . . . . . . . . . . 143
Device Control Operations . . . . . . . . 145
Trace Points and Error Log Templates for 8fa2
Token-Ring Device Driver . . . . . . . . 147
PCI Token-Ring High Performance (14101800)
Device Driver . . . . . . . . . . . . . 149
Configuration Parameters . . . . . . . . 150
Device Driver Configuration and
Unconfiguration . . . . . . . . . . . 151
Device Driver Open . . . . . . . . . . 151
Device Driver Close . . . . . . . . . . 151
Data Transmission. . . . . . . . . . . 151
Data Reception . . . . . . . . . . . . 151
Asynchronous Status . . . . . . . . . . 152
Device Control Operations . . . . . . . . 153
Reliability, Availability, and Serviceability (RAS) 155
Ethernet Device Drivers . . . . . . . . . . 157
Configuration Parameters . . . . . . . . 159
Interface Entry Points . . . . . . . . . 164
Asynchronous Status . . . . . . . . . . 166
Device Control Operations . . . . . . . . 168
Reliability, Availability, and Serviceability (RAS) 171
Chapter 8. Graphic Input Devices
Subsystem . . . . . . . . . . . . 179
open and close Subroutines. . . . . . . . . 179
read and write Subroutines . . . . . . . . . 179
ioctl Subroutines . . . . . . . . . . . . 179
Keyboard. . . . . . . . . . . . . . 179
Mouse. . . . . . . . . . . . . . . 180
Tablet . . . . . . . . . . . . . . . 180
GIO (Graphics I/O) Adapter . . . . . . . 180
Dials . . . . . . . . . . . . . . . 180
LPFK . . . . . . . . . . . . . . . 180
Input Ring . . . . . . . . . . . . . . 181
Management of Multiple Keyboard Input Rings 181
Event Report Formats . . . . . . . . . 181
Contents vii
Keyboard Service Vector. . . . . . . . . 182
Special Keyboard Sequences . . . . . . . 183
Chapter 9. Low Function Terminal
Subsystem . . . . . . . . . . . . 185
Low Function Terminal Interface Functional
Description . . . . . . . . . . . . . . 185
Configuration . . . . . . . . . . . . 185
Terminal Emulation . . . . . . . . . . 185
IOCTLS Needed for AIXwindow Support . . . 186
Low Function Terminal to System Keyboard
Interface . . . . . . . . . . . . . . 186
Low Function Terminal to Display Device
Driver Interface . . . . . . . . . . . 186
Low Function Terminal Device Driver Entry
Points . . . . . . . . . . . . . . . 186
Components Affected by the Low Function
Terminal Interface . . . . . . . . . . . . 186
Configuration User Commands . . . . . . 186
Display Device Driver . . . . . . . . . 187
Rendering Context Manager . . . . . . . 187
Diagnostics . . . . . . . . . . . . . 188
Accented Characters . . . . . . . . . . . 188
List of Diacritics Supported by the HFT LFT
Subsystem . . . . . . . . . . . . . 188
Chapter 10. Logical Volume
Subsystem . . . . . . . . . . . . 191
Direct Access Storage Devices (DASDs). . . . . 191
Physical Volumes . . . . . . . . . . . . 191
Physical Volume Implementation Limitations 192
Physical Volume Layout . . . . . . . . . 192
Reserved Sectors on a Physical Volume . . . . 192
Sectors Reserved for the Logical Volume
Manager (LVM) . . . . . . . . . . . 193
Understanding the Logical Volume Device Driver 195
Data Structures . . . . . . . . . . . . 195
Top Half of LVDD. . . . . . . . . . . 196
Bottom Half of the LVDD . . . . . . . . 196
Interface to Physical Disk Device Drivers . . . 198
Understanding Logical Volumes and Bad Blocks 199
Relocating Bad Blocks . . . . . . . . . 199
Detecting and Correcting Bad Blocks . . . . 199
Changing the mwcc_entries Variable . . . . . 200
Prerequisite Tasks or Conditions . . . . . . 200
Procedure . . . . . . . . . . . . . 200
Chapter 11. Printer Addition
Management Subsystem . . . . . . 203
Printer Types Currently Supported . . . . . . 203
Printer Types Currently Unsupported . . . . . 203
Adding a New Printer Type to Your System . . . 203
Additional Steps for Adding a New Printer
Type . . . . . . . . . . . . . . . 203
Modifying Printer Attributes . . . . . . . 204
Adding a Printer Definition . . . . . . . . 204
Adding a Printer Formatter to the Printer Backend 205
Understanding Embedded References in Printer
Attribute Strings . . . . . . . . . . . . 205
Chapter 12. Small Computer System
Interface Subsystem . . . . . . . . 207
SCSI Subsystem Overview . . . . . . . . . 207
Responsibilities of the SCSI Adapter Device
Driver . . . . . . . . . . . . . . . 207
Responsibilities of the SCSI Device Driver . . . 207
Communication between SCSI Devices . . . . 208
Understanding SCSI Asynchronous Event
Handling . . . . . . . . . . . . . . . 209
Defined Events and Recovery Actions . . . . 210
Asynchronous Event-Handling Routine. . . . 210
SCSI Error Recovery . . . . . . . . . . . 211
SCSI Initiator-Mode Recovery When Not
Command Tag Queuing . . . . . . . . . 211
SCSI Initiator-Mode Recovery During Command
Tag Queuing . . . . . . . . . . . . 212
Analyzing Returned Status . . . . . . . . 213
Target-Mode Error Recovery . . . . . . . 214
A Typical Initiator-Mode SCSI Driver Transaction
Sequence . . . . . . . . . . . . . . . 214
Understanding SCSI Device Driver Internal
Commands . . . . . . . . . . . . . . 215
Understanding the Execution of Initiator I/O
Requests . . . . . . . . . . . . . . . 215
Spanned (Consolidated) Commands . . . . . 216
Fragmented Commands . . . . . . . . . 216
Gathered Write Commands. . . . . . . . 217
SCSI Command Tag Queuing . . . . . . . . 218
Understanding the sc_buf Structure . . . . . . 218
Fields in the sc_buf Structure . . . . . . . 218
Other SCSI Design Considerations . . . . . . 223
Responsibilities of the SCSI Device Driver . . . 223
SCSI Options to the openx Subroutine . . . . 223
Using the SC_FORCED_OPEN Option . . . . 224
Using the SC_RETAIN_RESERVATION Option 224
Using the SC_DIAGNOSTIC Option. . . . . 224
Using the SC_NO_RESERVE Option. . . . . 225
Using the SC_SINGLE Option . . . . . . . 225
Closing the SCSI Device . . . . . . . . . 227
SCSI Error Processing . . . . . . . . . 227
Device Driver and Adapter Device Driver
Interfaces. . . . . . . . . . . . . . 227
Performing SCSI Dumps . . . . . . . . 228
SCSI Target-Mode Overview . . . . . . . . 229
Configuring and Using SCSI Target Mode . . . 229
Managing Receive-Data Buffers . . . . . . 230
Understanding Target-Mode Data Pacing . . . 230
Understanding the SCSI Target Mode Device
Driver Receive Buffer Routine . . . . . . . 231
Understanding the tm_buf Structure. . . . . 232
Understanding the Execution of SCSI
Target-Mode Requests . . . . . . . . . 233
Required SCSI Adapter Device Driver ioctl
Commands . . . . . . . . . . . . . . 235
Initiator-Mode ioctl Commands . . . . . . 235
Target-Mode ioctl Commands . . . . . . . 237
Target- and Initiator-Mode ioctl Commands . . 239
Chapter 13. Fibre Channel Protocol
for SCSI Subsystem . . . . . . . . 241
viii Kernel Extensions and Device Support Programming Concepts
FCP Subsystem Overview . . . . . . . . . 241
Responsibilities of the FCP Adapter Device
Driver . . . . . . . . . . . . . . . 241
Responsibilities of the FCP Device Driver . . . 241
Communication between FCP Devices . . . . 242
Initiator-Mode Support . . . . . . . . . 242
Understanding FCP Asynchronous Event Handling 242
Defined Events and Recovery Actions . . . . 243
Asynchronous Event-Handling Routine. . . . 244
FCP Error Recovery . . . . . . . . . . . 244
autosense data . . . . . . . . . . . . 245
NACA=1 error recovery . . . . . . . . . 245
FCP Initiator-Mode Recovery When Not Command
Tag Queuing . . . . . . . . . . . . . 245
FCP Initiator-Mode Recovery During Command
Tag Queuing . . . . . . . . . . . . . 246
Analyzing Returned Status . . . . . . . . 247
A Typical Initiator-Mode FCP Driver Transaction
Sequence . . . . . . . . . . . . . . . 248
Understanding FCP Device Driver Internal
Commands . . . . . . . . . . . . . . 249
Understanding the Execution of Initiator I/O
Requests . . . . . . . . . . . . . . . 249
Spanned (Consolidated) Commands . . . . . 250
Fragmented Commands . . . . . . . . . 250
FCP Command Tag Queuing . . . . . . . . 251
Understanding the scsi_buf Structure . . . . . 251
Fields in the scsi_buf Structure . . . . . . 251
Other FCP Design Considerations . . . . . . 257
Responsibilities of the FCP Device Driver . . . 257
FCP Options to the openx Subroutine . . . . 257
Using the SC_FORCED_OPEN Option . . . . 258
Using the SC_RETAIN_RESERVATION Option 258
Using the SC_DIAGNOSTIC Option. . . . . 258
Using the SC_NO_RESERVE Option. . . . . 259
Using the SC_SINGLE Option . . . . . . . 259
Closing the FCP Device . . . . . . . . . 261
FCP Error Processing . . . . . . . . . . 261
Length of Data Transfer for FCP Commands . . 261
Device Driver and Adapter Device Driver
Interfaces. . . . . . . . . . . . . . 262
Performing FCP Dumps . . . . . . . . . 262
Required FCP Adapter Device Driver ioctl
Commands . . . . . . . . . . . . . . 263
Description . . . . . . . . . . . . . 263
Initiator-Mode ioctl Commands . . . . . . 263
Initiator-Mode ioctl Command used by FCP
Device Drivers . . . . . . . . . . . . 266
Chapter 14. FCP Device Drivers . . . 269
Programming FCP Device Drivers . . . . . . 269
FCP Device Driver Overview . . . . . . . . 269
FCP Adapter Device Driver Overview . . . . . 269
FCP Adapter/Device Interface. . . . . . . . 270
scsi_buf Structure . . . . . . . . . . . 270
Adapter/Device Driver Intercommunication . . 275
FCP Adapter Device Driver Routines . . . . . 276
config . . . . . . . . . . . . . . . 276
open . . . . . . . . . . . . . . . 276
close . . . . . . . . . . . . . . . 276
openx . . . . . . . . . . . . . . . 276
strategy . . . . . . . . . . . . . . 277
ioctl . . . . . . . . . . . . . . . 277
start . . . . . . . . . . . . . . . 277
interrupt . . . . . . . . . . . . . . 277
FCP Adapter ioctl Operations . . . . . . . . 277
IOCINFO. . . . . . . . . . . . . . 277
SCIOLSTART . . . . . . . . . . . . 278
SCIOLSTOP . . . . . . . . . . . . . 278
SCIOLEVENT . . . . . . . . . . . . 279
SCIOLINQU. . . . . . . . . . . . . 279
SCIOLSTUNIT . . . . . . . . . . . . 280
SCIOLTUR . . . . . . . . . . . . . 281
SCIOLREAD . . . . . . . . . . . . 281
SCIOLRESET . . . . . . . . . . . . 282
SCIOLHALT. . . . . . . . . . . . . 282
SCIOLCMD . . . . . . . . . . . . . 283
Chapter 15. Integrated Device
Electronics (IDE) Subsystem . . . . . 285
Responsibilities of the IDE Adapter Device Driver 285
Responsibilities of the IDE Device Driver . . . . 285
Communication Between IDE Device Drivers and
IDE Adapter Device Drivers . . . . . . . . 286
IDE Error Recovery . . . . . . . . . . . 286
Analyzing Returned Status . . . . . . . . 286
A Typical IDE Driver Transaction Sequence . . . 287
IDE Device Driver Internal Commands . . . . . 288
Execution of I/O Requests . . . . . . . . . 288
Spanned (Consolidated) Commands . . . . . 289
Fragmented Commands . . . . . . . . . 290
Gathered Write Commands. . . . . . . . 290
ataide_buf Structure . . . . . . . . . . . 291
Fields in the ataide_buf Structure. . . . . . 291
Other IDE Design Considerations . . . . . . 293
IDE Device Driver Tasks. . . . . . . . . 293
Closing the IDE Device . . . . . . . . . 294
IDE Error Processing . . . . . . . . . . 294
Device Driver and Adapter Device Driver
Interfaces. . . . . . . . . . . . . . 294
Performing IDE Dumps . . . . . . . . . 294
Required IDE Adapter Device Driver ioctl
Commands . . . . . . . . . . . . . . 295
ioctl Commands . . . . . . . . . . . 295
Chapter 16. Serial Direct Access
Storage Device Subsystem . . . . . 299
DASD Device Block Level Description . . . . . 299
Chapter 17. Debugging Tools . . . . 301
System Dump . . . . . . . . . . . . . 301
Initiating a System Dump . . . . . . . . 301
Including Device Driver Information in a
System Dump . . . . . . . . . . . . 302
Formatting a System Dump . . . . . . . 304
The crash Command . . . . . . . . . . . 305
Addresses in crash . . . . . . . . . . 306
Command-line Editing . . . . . . . . . 306
Output Redirection . . . . . . . . . . 306
crash Subcommands . . . . . . . . . . 307
Low Level Kernel Debugger (LLDB). . . . . . 332
Contents ix
LLDB Kernel Debug Program . . . . . . . 332
Loading and Starting the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 333
Using a Terminal with the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 333
Entering the LLDB Kernel Debug Program . . 334
Debugging Multiprocessor Systems . . . . . 334
LLDB Kernel Debug Program Concepts . . . 335
LLDB Kernel Debug Program Commands . . . 338
LLDB Kernel Debug Program Commands
grouped in Alphabetical Order . . . . . . 338
LLDB Kernel Debug Program Commands
grouped by Task Category . . . . . . . . 340
Descriptions of the LLDB Kernel Debug
Program Commands . . . . . . . . . . 341
alter Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 341
back Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 342
break Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 342
breaks Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 343
buckets Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 344
clear Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 344
cpu Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 345
display Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 345
dmodsw Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 346
drivers Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 347
find Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 348
float Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 349
fmodsw Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 349
fs Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 350
go Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 350
help Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 351
loop Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 351
map Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 352
mblk Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 353
mst64 Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 353
netdata Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 354
next Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 354
origin Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 354
ppd Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 355
proc Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 355
queue Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 356
quit Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 357
reason Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 357
reboot Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 358
reset Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 358
screen Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 359
segst64 Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 360
set Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 361
sregs Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 362
sr64 Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 362
st Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 363
stack Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 364
stc Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 364
step Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 365
sth Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 365
stream Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 366
swap Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 367
sysinfo Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 368
thread Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 368
trace Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 370
trb Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 371
tty Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 371
un Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 372
user Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 372
user64 Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 373
uthread Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 373
vars Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 375
vmm Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 375
x Kernel Extensions and Device Support Programming Concepts
watch Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 376
xlate Command for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 376
Maps and Listings as Tools for the LLDB Kernel
Debug Program . . . . . . . . . . . 377
Compiler Listing . . . . . . . . . . . 377
Map File . . . . . . . . . . . . . . 378
Using the LLDB Kernel Debug Program . . . 381
Setting Breakpoints . . . . . . . . . . 381
Viewing and Modifying Global Data . . . . 384
Displaying Registers on a Micro Channel
Adapter . . . . . . . . . . . . . . 386
Stack Trace . . . . . . . . . . . . . 387
Error Messages for the LLDB Kernel Debug
Program . . . . . . . . . . . . . . 388
KDB Kernel Debugger and Command . . . . . 390
KDB Kernel Debugger and kdb Command . . 390
The kdb Command . . . . . . . . . . 390
KDB Kernel Debugger . . . . . . . . . 391
Loading and Starting the KDB Kernel Debugger 391
Using a Terminal with the KDB Kernel
Debugger. . . . . . . . . . . . . . 392
Entering the KDB Kernel Debugger . . . . . 392
Debugging Multiprocessor Systems . . . . . 393
Kernel Debug Program Concepts . . . . . . 393
Subcommands for the KDB Kernel Debugger and
kdb Command . . . . . . . . . . . . . 394
Introduction to Subcommands. . . . . . . 394
KDB Kernel Debug Program Subcommands
grouped in Alphabetical Order . . . . . . 396
KDB Kernel Debug Subcommands grouped by
Task Category . . . . . . . . . . . . 402
Basic Subcommands for the KDB Kernel Debugger
and kdb Command . . . . . . . . . . . 410
h Subcommand. . . . . . . . . . . . 410
his Subcommand . . . . . . . . . . . 411
e Subcommand . . . . . . . . . . . . 412
set Subcommand . . . . . . . . . . . 412
f Subcommand . . . . . . . . . . . . 414
ctx Subcommand . . . . . . . . . . . 417
cdt Subcommand . . . . . . . . . . . 419
Trace Subcommands for the KDB Kernel Debugger
and kdb Command . . . . . . . . . . . 420
bt Subcommand . . . . . . . . . . . 420
ct and cat Subcommands . . . . . . . . 420
bt script Subcommand . . . . . . . . . 421
bt [ cond ] Subcommand . . . . . . . . 421
Breakpoints/Steps Subcommands for the KDB
Kernel Debugger and kdb Command . . . . . 421
b Subcommand. . . . . . . . . . . . 421
lb Subcommand . . . . . . . . . . . 422
c, lc, and ca Subcommands . . . . . . . . 423
r and gt Subcommands . . . . . . . . . 424
n s, S, and B Subcommands . . . . . . . 425
Dumps/Display/Decode Subcommands for the
KDB Kernel Debugger and kdb Command . . . 426
d, dw, dd, dp, dpw, dpd Subcommands . . . 426
dc and dpc Subcommands . . . . . . . . 427
dr Subcommand . . . . . . . . . . . 428
ddvb, ddvh, ddvw, ddvd, ddpd, ddph, and
ddpw Subcommands . . . . . . . . . . 430
find and findp Subcommands . . . . . . . 430
ext and extp Subcommands . . . . . . . 431
Modify Memory Subcommands for the KDB
Kernel Debugger and kdb Command . . . . . 432
m, mw, md, mp, mpw, and mpd Subcommands 432
mr Subcommand . . . . . . . . . . . 434
mdvb, mdvh, mdvw, mdvd, mdpb, mdph,
mdpw, mdpd Subcommands . . . . . . . 434
Namelist/Symbol Subcommands for the KDB
Kernel Debugger and kdb Command . . . . . 436
nm and ts Subcommands . . . . . . . . 436
ns Subcommand . . . . . . . . . . . 436
Watch Break Points Subcommands for the KDB
Kernel Debugger and kdb Command . . . . . 437
wr, ww, wrw, cw, lwr, lww, lwrw, and lcw
Subcommands . . . . . . . . . . . . 437
Miscellaneous Subcommands for the KDB Kernel
Debugger and kdb Command . . . . . . . . 438
time and debug Subcommands . . . . . . 438
Conditional Subcommands for the KDB Kernel
Debugger and kdb Command . . . . . . . . 439
test Subcommand . . . . . . . . . . . 439
Calculator Converter Subcommands for the KDB
Kernel Debugger and kdb Command . . . . . 439
hcal and dcal Subcommands . . . . . . . 439
Machine Status Subcommands for the KDB Kernel
Debugger and kdb Command . . . . . . . . 439
status Subcommand . . . . . . . . . . 439
switch Subcommand . . . . . . . . . . 441
Kernel Extension Loader Subcommands for the
KDB Kernel Debugger and kdb Command . . . 442
lke, stbl, and rmst Subcommands. . . . . . 442
export table Subcommand . . . . . . . . 445
Address Translation Subcommands for the KDB
Kernel Debugger and kdb Command . . . . . 446
tr and tv Subcommands . . . . . . . . . 446
Process Subcommands for the KDB Kernel
Debugger and kdb Command . . . . . . . . 447
ppda Subcommand . . . . . . . . . . 447
intr Subcommand . . . . . . . . . . . 448
mst Subcommand . . . . . . . . . . . 449
proc Subcommand . . . . . . . . . . 450
thread Subcommand . . . . . . . . . . 453
ttid and tpid Subcommands . . . . . . . 456
runq, lockq, and sleepq Subcommands . . . . 457
user Subcommand. . . . . . . . . . . 457
LVM Subcommands for the KDB Kernel Debugger
and kdb Command . . . . . . . . . . . 459
pbuf Subcommand . . . . . . . . . . 459
volgrp Subcommand . . . . . . . . . . 459
pvol Subcommand . . . . . . . . . . 461
lvol Subcommand . . . . . . . . . . . 461
SCSI Subcommands for the KDB Kernel Debugger
and kdb Command . . . . . . . . . . . 462
ascsi Subcommand . . . . . . . . . . 462
vscsi Subcommand . . . . . . . . . . 464
scdisk Subcommand . . . . . . . . . . 468
Memory Allocator Subcommands for the KDB
Kernel Debugger and kdb Command . . . . . 471
Contents xi
heap Subcommand . . . . . . . . . . 471
xm Subcommand . . . . . . . . . . . 473
bucket Subcommand . . . . . . . . . . 475
kmstats Subcommands . . . . . . . . . 476
File System Subcommands for the KDB Kernel
Debugger and kdb Command . . . . . . . . 477
buffer Subcommand . . . . . . . . . . 477
hbuffer Subcommand. . . . . . . . . . 478
fbuffer Subcommand . . . . . . . . . . 478
gnode Subcommand . . . . . . . . . . 478
gfs Subcommand . . . . . . . . . . . 479
file Subcommand . . . . . . . . . . . 479
inode Subcommand . . . . . . . . . . 480
hinode Subcommand . . . . . . . . . . 481
icache Subcommand . . . . . . . . . . 482
rnode Subcommand . . . . . . . . . . 483
cku Subcommand . . . . . . . . . . . 483
vnode Subcommand . . . . . . . . . . 484
mount Subcommand . . . . . . . . . . 484
specnode Subcommand . . . . . . . . . 485
devnode Subcommand . . . . . . . . . 486
fifonode Subcommand . . . . . . . . . 487
hnode Subcommand . . . . . . . . . . 488
System Table Subcommands for the KDB Kernel
Debugger and kdb Command . . . . . . . . 488
var Subcommand . . . . . . . . . . . 488
devsw Subcommand . . . . . . . . . . 489
timer Subcommand . . . . . . . . . . 490
slk and clk Subcommands . . . . . . . . 491
iplcb Subcommand . . . . . . . . . . 491
trace Subcommand . . . . . . . . . . 492
Net Subcommands for the KDB Kernel Debugger
and kdb Command . . . . . . . . . . . 494
ifnet Subcommand . . . . . . . . . . 494
tcb Subcommand . . . . . . . . . . . 495
udb Subcommand . . . . . . . . . . . 495
sock Subcommand . . . . . . . . . . 496
tcpcb Subcommand . . . . . . . . . . 496
mbuf Subcommand . . . . . . . . . . 497
VMM Subcommands for the KDB Kernel Debugger
and kdb Command . . . . . . . . . . . 497
vmker Subcommand . . . . . . . . . . 497
rmap Subcommand . . . . . . . . . . 498
pfhdata Subcommand . . . . . . . . . 499
vmstat Subcommand . . . . . . . . . . 500
vmaddr Subcommand . . . . . . . . . 501
pdt Subcommand . . . . . . . . . . . 501
scb Subcommand . . . . . . . . . . . 502
pft Subcommand . . . . . . . . . . . 503
pte Subcommand . . . . . . . . . . . 506
pta Subcommand . . . . . . . . . . . 506
ste Subcommand . . . . . . . . . . . 507
sr64 Subcommand . . . . . . . . . . . 508
segst64 Subcommand. . . . . . . . . . 508
apt Subcommand . . . . . . . . . . . 509
vmwait Subcommand . . . . . . . . . 509
ames Subcommand . . . . . . . . . . 510
zproc Subcommand . . . . . . . . . . 511
vmlog Subcommand . . . . . . . . . . 512
vrld Subcommand. . . . . . . . . . . 512
ipc Subcommand . . . . . . . . . . . 512
lockanch Subcommand . . . . . . . . . 513
lockhash Subcommand . . . . . . . . . 514
lockword Subcommand . . . . . . . . . 515
vmdmap Subcommand . . . . . . . . . 518
vmlocks Subcommand . . . . . . . . . 519
SMP Subcommands for the KDB Kernel Debugger
and kdb Command . . . . . . . . . . . 520
start and stop Subcommands . . . . . . . 520
cpu Subcommand . . . . . . . . . . . 521
bat/Block Address Translation Subcommands for
the KDB Kernel Debugger and kdb Command . . 522
dbat Subcommand . . . . . . . . . . 522
ibat Subcommand . . . . . . . . . . . 522
mdbat Subcommand . . . . . . . . . . 523
mibat Subcommand . . . . . . . . . . 524
btac/BRAT Subcommands for the KDB Kernel
Debugger and kdb Command . . . . . . . . 524
btac, cbtac, lbtac, lcbtac Subcommands . . . . 524
machdep Subcommands for the KDB Kernel
Debugger and kdb Command . . . . . . . . 526
reboot Subcommand . . . . . . . . . . 526
Using the KDB Kernel Debug Program . . . . 526
Example Files . . . . . . . . . . . . 526
Generating Maps and Listings . . . . . . . 527
Compiler Listing . . . . . . . . . . . 527
Map File . . . . . . . . . . . . . . 528
Setting Breakpoints . . . . . . . . . . 530
Viewing and Modifying Global Data . . . . 534
Stack Trace . . . . . . . . . . . . . 538
demo.c Example File . . . . . . . . . . 542
demokext.c Example File . . . . . . . . 544
demo.h Example File . . . . . . . . . . 546
demokext.exp Example File. . . . . . . . 546
comp_link Example File . . . . . . . . . 546
Error Logging . . . . . . . . . . . . . 546
Precoding Steps to Consider . . . . . . . 547
Coding Steps . . . . . . . . . . . . 548
Writing to the /dev/error Special File . . . . 553
Debug and Performance Tracing . . . . . . . 554
Introduction . . . . . . . . . . . . . 554
Using the trace Facility . . . . . . . . . 556
Controlling trace . . . . . . . . . . . 559
Producing a trace Report . . . . . . . . 561
Defining trace Events. . . . . . . . . . 564
Usage Hints . . . . . . . . . . . . . 577
SMIT Trace Hook Groups . . . . . . . . 579
Memory Overlay Detection System (MODS) . . . 579
AIX Kernel Memory Overlay Detection System
(MODS) . . . . . . . . . . . . . . 579
Appendix A. Alphabetical List of
Kernel Services . . . . . . . . . . 583
Kernel Services Available in Process and Interrupt
Environments . . . . . . . . . . . . . 583
Kernel Services Available in the Process
Environment Only. . . . . . . . . . . 588
Index . . . . . . . . . . . . . . . 593
xii Kernel Extensions and Device Support Programming Concepts
xiv Kernel Extensions and Device Support Programming Concepts
About This Book
This book provides information on the kernel programming environment, and
about writing system call, kernel service, and virtual file system kernel extensions.
Conceptual information on existing kernel subsystems is also provided.
More detailed information on existing kernel services and interface requirements
for kernel extensions can be found in AIX Version 4.3 Technical Reference: Kernel and
Subsystems Volume 1, Order Number SC23-4163, and AIX Version 4.3 Technical
Reference: Kernel and Subsystems Volume 2, Order Number SC23-4164.
Note: The information in this book can also be found on the AIX Version 4.3
Extended Documentation CD. This online documentation is designed for use
with an HTML version 3.2 compatible web browser.
Who Should Use This Book
This book is intended for system programmers who are knowledgeable in
operating system concepts and kernel programming and want to extend the kernel.
How to Use This Book
This book provides two types of information: (1) an overview of the kernel
programming environment and information a programmer needs to write kernel
extensions, and (2) information about existing kernel subsystems.
Overview of Contents
This book contains the following chapters and appendixes:
v Chapter 1, ″Kernel Environment″, provides an overview of programming in the
kernel environment, including kernel extension binding, kernel processes, signal
handling, and exception handling.
v Chapter 2, ″System Calls″, contrasts a user function and a system call, and
discusses aspects of system call execution.
v Chapter 3, ″Virtual File Systems″, discusses the components of a virtual file
system, and the steps needed to configure it.
v Chapter 4, ″Kernel Services″, discusses the various types of kernel services.
v Chapter 5, ″Asynchronous I/O Subsystem″, describes asynchronous I/O.
v Chapter 6, ″Device Configuration Subsystem″, provides an overview of the
configuration process, the routines and databases involved, and the requirements
for configuring new devices.
v Chapter 7, ″Communications I/O Subsystem″, contains some information
common to all communications device drivers and some information about
specific communications device drivers.
v Chapter 8, ″Graphic Input Devices Subsystem″, describes the programming
interface of the graphic input device driver.
v Chapter 9, ″Low Function Terminal (LFT) Subsystem″, discusses the component
structure of the high function terminal and the concept of the virtual terminal
low function terminal.
v Chapter 10, ″Logical Volume Subsystem″, includes information on physical
volumes, the logical volume device driver, and logical volumes and bad blocks.
© Copyright IBM Corp. 1997, 1999 xv
v Chapter 11, ″Printer Addition Management Subsystem″, describes the steps
involved in adding a printer to the system.
v Chapter 12, ″Small Computer System Interface (SCSI) Subsystem″, discusses
SCSI subsystem architecture and aspects of writing SCSI device drivers.
v Chapter 13, ″Fibre Channel Protocol for SCSI Subsystem″, describes the interface
between a Fibre Channel Protocol (FCP) for SCSI device driver and a FCP
adapter device driver.
v Chapter 14, ″FCP Device Drivers″, includes information on programming FCP
device drivers.
v Chapter 15,″Integrated Device Electronics (IDE) Subsystem″, discusses IDE
subsystem architecture and aspects of writing IDE device drivers.
v Chapter 16, ″Serial Direct Access Storage Device Subsystem″, includes
information on using serial direct access storage devices.
v Chapter 17, ″Debugging Tools″, includes information on debugging device
drivers.
v Appendix A, ″Alphabetical List of Kernel Services″, lists and summarizes the
function of the kernel services. The list is divided based on the execution
environment from which each service can be called.
Highlighting
The following highlighting conventions are used in this book:
Bold Identifies commands, subroutines, keywords,
files, structures, directories, and other items
whose names are predefined by the system.
Also identifies graphical objects such as
buttons, labels, and icons that the user
selects.
Italics Identifies parameters whose actual names or
values are to be supplied by the user.
Monospace Identifies examples of specific data values,
examples of text similar to what you might
see displayed, examples of portions of
program code similar to what you might
write as a programmer, messages from the
system, or information you should actually
type.
ISO 9000
ISO 9000 registered quality systems were used in the development and
manufacturing of this product.
AIX 32-Bit Support for the X/Open UNIX95 Specification
Beginning with AIX Version 4.2, the operating system is designed to support the
X/Open UNIX95 Specification for portability of UNIX-based operating systems.
Many new interfaces, and some current ones, have been added or enhanced to
meet this specification. Beginning with Version 4.2, AIX is even more open and
portable for applications.
At the same time, compatibility with previous AIX releases is preserved. This is
accomplished by the creation of a new environment variable, which can be used to
set the system environment on a per-system, per-user, or per-process basis.
xvi Kernel Extensions and Device Support Programming Concepts
To determine the proper way to develop a UNIX95-portable application, you may
need to refer to the X/Open UNIX95 Specification, which can be obtained on a
CD-ROM by ordering the printed copy of AIX Version 4.3 Commands Reference,
order number SBOF-1877, or by ordering Go Solo: How to Implement and Go Solo
with the Single Unix Specification, order number SR28-5705, a book which includes
the X/Open UNIX95 Specification on a CD-ROM.
AIX 32-Bit and 64-Bit Support for the UNIX98 Specification
Beginning with AIX Version 4.3, the operating system is designed to support the
X/Open UNIX98 Specification for portability of UNIX-based operating systems.
Many new interfaces, and some current ones, have been added or enhanced to
meet this specification. Making AIX Version 4.3 even more open and portable for
applications.
At the same time, compatibility with previous AIX releases is preserved. This is
accomplished by the creation of a new environment variable, which can be used to
set the system environment on a per-system, per-user, or per-process basis.
To determine the proper way to develop a UNIX98-portable application, you may
need to refer to the X/Open UNIX98 Specification, which can be obtained on a
CD-ROM by ordering the printed copy of AIX Version 4.3 Commands Reference,
order number SBOF-1877, or by ordering Go Solo: How to Implement and Go Solo
with the Single Unix Specification, order number SR28-5705, a book which includes
the X/Open UNIX98 Specification on a CD-ROM.
Related Publications
The following books contain additional information on kernel extension
programming and the existing kernel subsystems:
v AIX Ethernet Local Broadcast/6000, Order Number GC23-2439
v Ethernet HUB Installation, Order Number GA27-4024
v Ethernet LAN Adapter Family, Order Number G221-3457
v AIX Version 4.3 Guide to Printers and Printing, Order Number SC23-4130.
v AIX Version 4 Keyboard Technical Reference, Order Number SC23-2631.
v AIX Version 4.3 Problem Solving Guide and Reference, Order Number SC23-4123.
v AIX Version 4.3 System Management Guide: Operating System and Devices, Order
Number SC23-4126.
v AIX Version 4.3 Technical Reference: Kernel and Subsystems Volume 1, Order
Number SC23-4163.
v AIX Version 4.3 Technical Reference: Kernel and Subsystems Volume 2, Order
Number SC23-4164
v Token-Ring Network Architecture Reference, Order Number SC30-3374
Ordering Publications
You can order publications from your sales representative or from your point of
sale.
To order additional copies of this book, use order number SC23-4125.
Use AIX and Related Products Documentation Overview for information on related
publications and how to obtain them.
About This Book xvii
xviii Kernel Extensions and Device Support Programming Concepts
Chapter 1. Kernel Environment
The kernel is dynamically extendable and can be expanded by adding routines that
belong to any of the following functional classes:
v System calls
v Virtual file systems
v Kernel Extension and Device Driver Management Kernel Services
v Device Drivers
These kernel extensions can be added at system boot or while the system is in
operation.
The Types of Kernel Extensions diagram illustrates the addition of extensions to
the kernel environment.
The following kernel-environment programming information is provided to assist
you in programming kernel extensions:
v Understanding Kernel Extension Binding
v Understanding Execution Environments
COMMANDS
File System Interface System Calls
SYSTEM CALL INTERFACE
VIRTUAL
FILE
SYSTEM
DEVICE
DRIVERS
EXTENDED
SYSTEM
CALLS
EXTENDED
KERNEL
SERVICES
EXTENDED KERNEL MODE EXPORTS
NUCLEUS SERVICES
KERNEL INTERFACE
PRIVATE
ROUTINES
Types of Kernel Extensions
© Copyright IBM Corp. 1997, 1999 1
v Understanding Kernel Threads
v Using Kernel Processes
v Accessing User-Mode Data While in Kernel Mode
v Understanding Locking
v Understanding Exception Handling
v 64-bit Kernel Extension Development
A process executing in user mode can customize the kernel by using the sysconfig
subroutine, if the process has appropriate privilege. In this way, a user-mode
process can load, unload, initialize, or terminate kernel routines. Kernel
configuration can also be altered by changing tuneable system parameters.
Kernel extensions can also customize the kernel by using kernel services to load,
unload, initialize, and terminate dynamically loaded kernel routines; to create and
initialize kernel processes; and to define interrupt handlers. Binding of kernel
extensions can be performed at link-edit, load, or run time.
Note: Private kernel routines (or kernel services) execute in a privileged
protection domain and can affect the operation and integrity of the whole
system. See “Kernel Protection Domain” on page 26 for more information.
Understanding Kernel Extension Binding
The following information is provided to assist you in understanding kernel
extension binding.
v “Base Kernel Services - the /unix Name Space”
v “Using System Calls with Kernel Extensions” on page 3
v “Using Private Routines” on page 4
v “Using Libraries” on page 5
Base Kernel Services - the /unix Name Space
The kernel provides a set of base kernel services to be used by kernel extensions.
(See “Chapter 4. Kernel Services” on page 39.) These services, which are described
in the services documentation, are made available to a kernel extension by
specifying the kernex.exp kernel export file as an import file during the link-edit of
the extension. The link-edit operation is performed by using the ld command.
The kernel provides a set of base kernel services to be used by kernel extensions.
These services, which are described in the services documentation, are made
available to a kernel extension by specifying the kernex.exp kernel export file as an
import file during the link-edit of the extension. The link-edit operation is
performed by using the ld command.
A kernel extension provides additional kernel services and system calls by
supplying an export file when it is link-edited. This export file specifies the
symbols to be added to the /unix name space, which is the global kernel name
space. Symbols that name system calls to be exported must specify one of the
SYSCALL, SYSCALL32, SYSCALL64, or SYSCALL3264 keywords next to the
symbol in the export file.
The kernel extension export file must also have #!/unix as its first entry. The export
file can then be used by other extensions as an import file. The #!/unix as the first
2 Kernel Extensions and Device Support Programming Concepts
/
