AIX 5L Version 5.1

Kernel Extensions and Device SupportProgramming Concepts

���

AIX 5L Version 5.1

Kernel Extensions and Device SupportProgramming Concepts

���

Fourth Edition (April 2001)

Before using the information in this book, read the general information in “Appendix. Notices” on page 595.

A reader’s comment form is provided at the back of this publication. If the form has been removed, addresscomments to Publications Department, Internal Zip 9561, 11400 Burnet Road, Austin, Texas 78758-3493. To sendcomments electronically, use this commercial Internet address: aix6kpub@austin.ibm.com. Any information that yousupply may be used without incurring any obligation to you.

This edition applies to AIX 5L Version 5.1 and to all subsequent releases of this product until otherwise indicated innew editions.

© Copyright International Business Machines Corporation 1997, 2001. All rights reserved.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiWho Should Use This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiHow to Use This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiHighlighting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiISO 9000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiRelated Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiTrademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii

Chapter 1. Kernel Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Understanding Kernel Extension Symbol Resolution . . . . . . . . . . . . . . . . . . . . 1

Exporting Kernel Services and System Calls . . . . . . . . . . . . . . . . . . . . . . 2Using Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Using System Calls with Kernel Extensions . . . . . . . . . . . . . . . . . . . . . . 2Using Private Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Understanding Dual-Mode Kernel Extensions. . . . . . . . . . . . . . . . . . . . . . 4Using Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Understanding Execution Environments . . . . . . . . . . . . . . . . . . . . . . . . . 6Process Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Interrupt Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Understanding Kernel Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Kernel Threads, Kernel Only Threads, and User Threads . . . . . . . . . . . . . . . . . 7Kernel Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Thread Creation, Execution, and Termination . . . . . . . . . . . . . . . . . . . . . . 8Thread Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Thread Signal Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Using Kernel Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Introduction to Kernel Processes . . . . . . . . . . . . . . . . . . . . . . . . . . 9Accessing Data from a Kernel Process . . . . . . . . . . . . . . . . . . . . . . . 10Cross-Memory Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Kernel Process Creation, Execution, and Termination . . . . . . . . . . . . . . . . . . 10Kernel Process Preemption . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Kernel Process Signal and Exception Handling . . . . . . . . . . . . . . . . . . . . 11Kernel Process Use of System Calls . . . . . . . . . . . . . . . . . . . . . . . . 12

Accessing User-Mode Data While in Kernel Mode . . . . . . . . . . . . . . . . . . . . 12Data Transfer Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Using Cross-Memory Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . 13

Understanding Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Lockl Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Simple Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Complex Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Types of Critical Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Priority Promotion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Locking Strategy in Kernel Mode . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Understanding Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . 14Exception Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Kernel-Mode Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . 15Implementing Kernel Exception Handlers . . . . . . . . . . . . . . . . . . . . . . . 16User-Mode Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Using Kernel Extensions to Support 64–bit Processes . . . . . . . . . . . . . . . . . . . 1964-bit Kernel Extension Programming Environment . . . . . . . . . . . . . . . . . . . . 20

C Language Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Kernel Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Functional Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

© Copyright IBM Corp. 1997, 2001 iii

Compiler Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Conditional Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Kernel Extension Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Kernel Execution Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Kernel Address Space. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

32-bit Kernel Extension Considerations . . . . . . . . . . . . . . . . . . . . . . . . 22

Chapter 2. System Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Differences Between a System Call and a User Function . . . . . . . . . . . . . . . . . . 23Understanding System Call Execution . . . . . . . . . . . . . . . . . . . . . . . . . 23

User Protection Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Kernel Protection Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Actions of the System Call Handler . . . . . . . . . . . . . . . . . . . . . . . . . 24Accessing Kernel Data While in a System Call. . . . . . . . . . . . . . . . . . . . . 25Passing Parameters to System Calls . . . . . . . . . . . . . . . . . . . . . . . . 25Preempting a System Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Handling Signals While in a System Call . . . . . . . . . . . . . . . . . . . . . . . 33Handling Exceptions While in a System Call . . . . . . . . . . . . . . . . . . . . . 34Understanding Nesting and Kernel-Mode Use of System Calls . . . . . . . . . . . . . . . 35Page Faulting within System Calls . . . . . . . . . . . . . . . . . . . . . . . . . 35Returning Error Information from System Calls. . . . . . . . . . . . . . . . . . . . . 35

System Calls Available to Kernel Extensions . . . . . . . . . . . . . . . . . . . . . . 36System Calls Available to All Kernel Extensions . . . . . . . . . . . . . . . . . . . . 36System Calls Available to Kernel Processes Only. . . . . . . . . . . . . . . . . . . . 36

Chapter 3. Virtual File Systems. . . . . . . . . . . . . . . . . . . . . . . . . . . 39Logical File System Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Component Structure of the Logical File System . . . . . . . . . . . . . . . . . . . . 40Virtual File System Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Understanding Virtual Nodes (V-nodes) . . . . . . . . . . . . . . . . . . . . . . . 40Understanding Generic I-nodes (G-nodes) . . . . . . . . . . . . . . . . . . . . . . 41Understanding the Virtual File System Interface . . . . . . . . . . . . . . . . . . . . 41

Understanding Data Structures and Header Files for Virtual File Systems . . . . . . . . . . . . 42Configuring a Virtual File System. . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Chapter 4. Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Categories of Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45I/O Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Block I/O Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Buffer Cache Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Character I/O Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Interrupt Management Services . . . . . . . . . . . . . . . . . . . . . . . . . . 46Memory Buffer (mbuf) Kernel Services. . . . . . . . . . . . . . . . . . . . . . . . 46DMA Management Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . . 47

Block I/O Buffer Cache Kernel Services: Overview . . . . . . . . . . . . . . . . . . . . 48Managing the Buffer Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Using the Buffer Cache write Services . . . . . . . . . . . . . . . . . . . . . . . . 49

Understanding Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Interrupt Priorities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Understanding DMA Transfers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Hiding DMA Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Accessing Data While the DMA Operation Is in Progress . . . . . . . . . . . . . . . . . 51

Kernel Extension and Device Driver Management Services . . . . . . . . . . . . . . . . . 51Kernel Extension Loading and Binding Services . . . . . . . . . . . . . . . . . . . . 51Other Functions of the Kernel Extension and Device Driver Management Services . . . . . . . 51List of Kernel Extension and Device Driver Management Kernel Services . . . . . . . . . . . 52

iv Kernel Extensions and Device Support Programming Concepts

Locking Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Lock Allocation and Other Services . . . . . . . . . . . . . . . . . . . . . . . . . 53Simple Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Complex Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Lockl Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Atomic Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

File Descriptor Management Services . . . . . . . . . . . . . . . . . . . . . . . . . 55Logical File System Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . . 55

Other Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56List of Logical File System Kernel Services . . . . . . . . . . . . . . . . . . . . . . 56

Memory Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Memory Management Kernel Services. . . . . . . . . . . . . . . . . . . . . . . . 57Memory Pinning Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . . . 57User-Memory-Access Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . 57Virtual Memory Management Kernel Services . . . . . . . . . . . . . . . . . . . . . 58Cross-Memory Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Understanding Virtual Memory Manager Interfaces . . . . . . . . . . . . . . . . . . . . 60Virtual Memory Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Addressing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Moving Data to or from a Virtual Memory Object . . . . . . . . . . . . . . . . . . . . 61Data Flushing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Discarding Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Protecting Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Executable Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Installing Pager Backends . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Referenced Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Services that Support 64-bit Processes . . . . . . . . . . . . . . . . . . . . . . . 63Services that Support 64-bit Processes (POWER family only) . . . . . . . . . . . . . . . 63

Message Queue Kernel Services. . . . . . . . . . . . . . . . . . . . . . . . . . . 63Network Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Address Family Domain and Network Interface Device Driver Kernel Services . . . . . . . . . 64Routing and Interface Address Kernel Services . . . . . . . . . . . . . . . . . . . . 65Loopback Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Protocol Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Communications Device Handler Interface Kernel Services . . . . . . . . . . . . . . . . 66

Process and Exception Management Kernel Services . . . . . . . . . . . . . . . . . . . 66Creating Kernel Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Creating Kernel Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Kernel Structures Encapsulation . . . . . . . . . . . . . . . . . . . . . . . . . . 66Registering Exception Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . 67Signal Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Events Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67List of Process, Thread, and Exception Management Kernel Services . . . . . . . . . . . . 68

RAS Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Security Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Timer and Time-of-Day Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . 69

Time-Of-Day Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Fine Granularity Timer Kernel Services . . . . . . . . . . . . . . . . . . . . . . . 70Timer Kernel Services for Compatibility . . . . . . . . . . . . . . . . . . . . . . . 70Watchdog Timer Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Using Fine Granularity Timer Services and Structures . . . . . . . . . . . . . . . . . . . 70Timer Services Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . 71Coding the Timer Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Using Multiprocessor-Safe Timer Services . . . . . . . . . . . . . . . . . . . . . . . 71Virtual File System (VFS) Kernel Services . . . . . . . . . . . . . . . . . . . . . . . 72

Contents v

Chapter 5. Asynchronous I/O Subsystem . . . . . . . . . . . . . . . . . . . . . . . 73Asynchronous I/O Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

How do I know if I need to use AIO? . . . . . . . . . . . . . . . . . . . . . . . . 73How many AIO Servers am I currently using? . . . . . . . . . . . . . . . . . . . . . 74How many AIO servers do I need? . . . . . . . . . . . . . . . . . . . . . . . . . 74

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Functions of Asynchronous I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Large File-Enabled Asynchronous I/O (AIX 4.2.1 or later) . . . . . . . . . . . . . . . . . 75Nonblocking I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Notification of I/O Completion . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Cancellation of I/O Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Asynchronous I/O Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Order and Priority of Asynchronous I/O Calls . . . . . . . . . . . . . . . . . . . . . 77

Subroutines Affected by Asynchronous I/O . . . . . . . . . . . . . . . . . . . . . . . 77Changing Attributes for Asynchronous I/O . . . . . . . . . . . . . . . . . . . . . . . 7864-bit Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Chapter 6. Device Configuration Subsystem . . . . . . . . . . . . . . . . . . . . . 81Scope of Device Configuration Support . . . . . . . . . . . . . . . . . . . . . . . . 81Device Configuration Subsystem Overview . . . . . . . . . . . . . . . . . . . . . . . 81General Structure of the Device Configuration Subsystem . . . . . . . . . . . . . . . . . 82

High-Level Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Device Method Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Low-Level Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Device Configuration Database Overview. . . . . . . . . . . . . . . . . . . . . . . . 83Basic Device Configuration Procedures Overview. . . . . . . . . . . . . . . . . . . . . 83Device Configuration Manager Overview . . . . . . . . . . . . . . . . . . . . . . . . 84

Devices Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Configuration Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Invoking the Configuration Manager. . . . . . . . . . . . . . . . . . . . . . . . . 85

Device Classes, Subclasses, and Types Overview . . . . . . . . . . . . . . . . . . . . 85Writing a Device Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Invoking Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Example Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Understanding Device Methods Interfaces . . . . . . . . . . . . . . . . . . . . . . . 87Configuration Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Run-Time Configuration Commands . . . . . . . . . . . . . . . . . . . . . . . . 88

Understanding Device States . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Adding an Unsupported Device to the System . . . . . . . . . . . . . . . . . . . . . . 89

Modifying the Predefined Database . . . . . . . . . . . . . . . . . . . . . . . . . 89Adding Device Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Adding a Device Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Using installp Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Understanding Device Dependencies and Child Devices . . . . . . . . . . . . . . . . . . 90Accessing Device Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Modifying an Attribute Value . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Device Dependent Structure (DDS) Overview . . . . . . . . . . . . . . . . . . . . . . 92

How the Change Method Updates the DDS . . . . . . . . . . . . . . . . . . . . . . 92Guidelines for DDS Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Example of DDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

List of Device Configuration Commands . . . . . . . . . . . . . . . . . . . . . . . . 93List of Device Configuration Subroutines . . . . . . . . . . . . . . . . . . . . . . . . 94

Chapter 7. Communications I/O Subsystem . . . . . . . . . . . . . . . . . . . . . . 95User-Mode Interface to a Communications PDH . . . . . . . . . . . . . . . . . . . . . 95Kernel-Mode Interface to a Communications PDH . . . . . . . . . . . . . . . . . . . . 95

vi Kernel Extensions and Device Support Programming Concepts

CDLI Device Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Communications Physical Device Handler Model Overview . . . . . . . . . . . . . . . . . 96

Use of mbuf Structures in the Communications PDH . . . . . . . . . . . . . . . . . . 96Common Communications Status and Exception Codes . . . . . . . . . . . . . . . . . 97

Status Blocks for Communications Device Handlers Overview . . . . . . . . . . . . . . . . 97CIO_START_DONE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98CIO_HALT_DONE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98CIO_TX_DONE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98CIO_NULL_BLK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98CIO_LOST_STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98CIO_ASYNC_STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

MPQP Device Handler Interface Overview . . . . . . . . . . . . . . . . . . . . . . . 99Binary Synchronous Communication (BSC) with the MPQP Adapter . . . . . . . . . . . . 100Description of the MPQP Card . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Serial Optical Link Device Handler Overview . . . . . . . . . . . . . . . . . . . . . . 102Special Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Entry Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Configuring the Serial Optical Link Device Driver . . . . . . . . . . . . . . . . . . . . 103Physical and Logical Devices . . . . . . . . . . . . . . . . . . . . . . . . . . 103Changeable Attributes of the Serial Optical Link Subsystem . . . . . . . . . . . . . . . 103

Forum-Compliant ATM LAN Emulation Device Driver . . . . . . . . . . . . . . . . . . . 104Adding ATM LANE Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Configuration Parameters for the ATM LANE Device Driver . . . . . . . . . . . . . . . 105Device Driver Configuration and Unconfiguration . . . . . . . . . . . . . . . . . . . 109Device Driver Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Device Driver Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Data Transmission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Data Reception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Asynchronous Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Device Control Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Tracing and Error Logging in the ATM LANE Device Driver . . . . . . . . . . . . . . . . 114Adding an ATM MPOA Client . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Configuration Parameters for ATM MPOA Client . . . . . . . . . . . . . . . . . . . . 115Tracing and Error Logging in the ATM MPOA Client . . . . . . . . . . . . . . . . . . 116Getting Client Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Fiber Distributed Data Interface (FDDI) Device Driver . . . . . . . . . . . . . . . . . . . 117Configuration Parameters for FDDI Device Driver . . . . . . . . . . . . . . . . . . . 117FDDI Device Driver Configuration and Unconfiguration . . . . . . . . . . . . . . . . . 118Device Driver Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Device Driver Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Data Transmission. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Data Reception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Reliability, Availability, and Serviceability for FDDI Device Driver . . . . . . . . . . . . . . 119

High-Performance (8fc8) Token-Ring Device Driver . . . . . . . . . . . . . . . . . . . 121Configuration Parameters for Token-Ring Device Driver . . . . . . . . . . . . . . . . . 121Device Driver Configuration and Unconfiguration . . . . . . . . . . . . . . . . . . . 122Device Driver Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Device Driver Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Data Transmission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Data Reception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Asynchronous Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Device Control Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Trace Points and Error Log Templates for 8fc8 Token-Ring Device Driver . . . . . . . . . . 127

High-Performance (8fa2) Token-Ring Device Driver . . . . . . . . . . . . . . . . . . . 129Configuration Parameters for 8fa2 Token-Ring Device Driver . . . . . . . . . . . . . . . 129Device Driver Configuration and Unconfiguration . . . . . . . . . . . . . . . . . . . 129

Contents vii

Device Driver Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Device Driver Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Data Transmission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Data Reception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Asynchronous Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Device Control Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Trace Points and Error Log Templates for 8fa2 Token-Ring Device Driver . . . . . . . . . . 134

PCI Token-Ring High Performance (14101800) Device Driver . . . . . . . . . . . . . . . . 136Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Device Driver Configuration and Unconfiguration . . . . . . . . . . . . . . . . . . . 137Device Driver Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Device Driver Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Data Transmission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Data Reception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Asynchronous Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Device Control Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Reliability, Availability, and Serviceability (RAS) . . . . . . . . . . . . . . . . . . . . 141

Ethernet Device Drivers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Interface Entry Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Asynchronous Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150Device Control Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . 151Reliability, Availability, and Serviceability (RAS) . . . . . . . . . . . . . . . . . . . . 154

Chapter 8. Graphic Input Devices Subsystem . . . . . . . . . . . . . . . . . . . . 161open and close Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161read and write Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161ioctl Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Keyboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162Tablet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162GIO (Graphics I/O) Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . 162Dials. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162LPFK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

Input Ring. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163Management of Multiple Keyboard Input Rings . . . . . . . . . . . . . . . . . . . . 163Event Report Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163Keyboard Service Vector . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Special Keyboard Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Chapter 9. Low Function Terminal Subsystem . . . . . . . . . . . . . . . . . . . . 167Low Function Terminal Interface Functional Description . . . . . . . . . . . . . . . . . . 167

Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167Terminal Emulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167IOCTLS Needed for AIXwindows Support . . . . . . . . . . . . . . . . . . . . . . 168Low Function Terminal to System Keyboard Interface . . . . . . . . . . . . . . . . . . 168Low Function Terminal to Display Device Driver Interface . . . . . . . . . . . . . . . . 168Low Function Terminal Device Driver Entry Points . . . . . . . . . . . . . . . . . . . 168

Components Affected by the Low Function Terminal Interface . . . . . . . . . . . . . . . . 168Configuration User Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 168Display Device Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Rendering Context Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Diagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

Accented Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170List of Diacritics Supported by the HFT LFT Subsystem . . . . . . . . . . . . . . . . . 170Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

viii Kernel Extensions and Device Support Programming Concepts

Chapter 10. Logical Volume Subsystem . . . . . . . . . . . . . . . . . . . . . . . 173Direct Access Storage Devices (DASDs) . . . . . . . . . . . . . . . . . . . . . . . 173Physical Volumes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Physical Volume Implementation Limitations . . . . . . . . . . . . . . . . . . . . . 174Physical Volume Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174Reserved Sectors on a Physical Volume . . . . . . . . . . . . . . . . . . . . . . 174Sectors Reserved for the Logical Volume Manager (LVM) . . . . . . . . . . . . . . . . 175

Understanding the Logical Volume Device Driver . . . . . . . . . . . . . . . . . . . . 176Data Structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Top Half of LVDD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Bottom Half of the LVDD . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Interface to Physical Disk Device Drivers . . . . . . . . . . . . . . . . . . . . . . 179

Understanding Logical Volumes and Bad Blocks . . . . . . . . . . . . . . . . . . . . 179Relocating Bad Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Detecting and Correcting Bad Blocks . . . . . . . . . . . . . . . . . . . . . . . . 180

Changing the mwcc_entries Variable . . . . . . . . . . . . . . . . . . . . . . . . . 181Prerequisite Tasks or Conditions . . . . . . . . . . . . . . . . . . . . . . . . . 181Procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Chapter 11. Printer Addition Management Subsystem . . . . . . . . . . . . . . . . . 183Printer Types Currently Supported . . . . . . . . . . . . . . . . . . . . . . . . . . 183Printer Types Currently Unsupported . . . . . . . . . . . . . . . . . . . . . . . . . 183Adding a New Printer Type to Your System . . . . . . . . . . . . . . . . . . . . . . 183

Additional Steps for Adding a New Printer Type . . . . . . . . . . . . . . . . . . . . 183Modifying Printer Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

Adding a Printer Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Adding a Printer Formatter to the Printer Backend . . . . . . . . . . . . . . . . . . . . 185Understanding Embedded References in Printer Attribute Strings . . . . . . . . . . . . . . 185

Chapter 12. Small Computer System Interface Subsystem . . . . . . . . . . . . . . . 187SCSI Subsystem Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Responsibilities of the SCSI Adapter Device Driver. . . . . . . . . . . . . . . . . . . 187Responsibilities of the SCSI Device Driver . . . . . . . . . . . . . . . . . . . . . . 187Communication between SCSI Devices . . . . . . . . . . . . . . . . . . . . . . . 188

Understanding SCSI Asynchronous Event Handling . . . . . . . . . . . . . . . . . . . 188Defined Events and Recovery Actions . . . . . . . . . . . . . . . . . . . . . . . 189Asynchronous Event-Handling Routine . . . . . . . . . . . . . . . . . . . . . . . 190

SCSI Error Recovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190SCSI Initiator-Mode Recovery When Not Command Tag Queuing . . . . . . . . . . . . . 190SCSI Initiator-Mode Recovery During Command Tag Queuing . . . . . . . . . . . . . . 191Analyzing Returned Status . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Target-Mode Error Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

A Typical Initiator-Mode SCSI Driver Transaction Sequence . . . . . . . . . . . . . . . . 193Understanding SCSI Device Driver Internal Commands . . . . . . . . . . . . . . . . . . 194Understanding the Execution of Initiator I/O Requests . . . . . . . . . . . . . . . . . . 194

Spanned (Consolidated) Commands . . . . . . . . . . . . . . . . . . . . . . . . 194Fragmented Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195Gathered Write Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

SCSI Command Tag Queuing . . . . . . . . . . . . . . . . . . . . . . . . . . . 196Understanding the sc_buf Structure . . . . . . . . . . . . . . . . . . . . . . . . . 197

Fields in the sc_buf Structure . . . . . . . . . . . . . . . . . . . . . . . . . . 197Other SCSI Design Considerations . . . . . . . . . . . . . . . . . . . . . . . . . 201

Responsibilities of the SCSI Device Driver . . . . . . . . . . . . . . . . . . . . . . 201SCSI Options to the openx Subroutine . . . . . . . . . . . . . . . . . . . . . . . 201Using the SC_FORCED_OPEN Option . . . . . . . . . . . . . . . . . . . . . . . 202

Contents ix

Using the SC_RETAIN_RESERVATION Option . . . . . . . . . . . . . . . . . . . . 202Using the SC_DIAGNOSTIC Option . . . . . . . . . . . . . . . . . . . . . . . . 202Using the SC_NO_RESERVE Option. . . . . . . . . . . . . . . . . . . . . . . . 202Using the SC_SINGLE Option . . . . . . . . . . . . . . . . . . . . . . . . . . 203Closing the SCSI Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204SCSI Error Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Device Driver and Adapter Device Driver Interfaces . . . . . . . . . . . . . . . . . . 205Performing SCSI Dumps . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

SCSI Target-Mode Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206Configuring and Using SCSI Target Mode . . . . . . . . . . . . . . . . . . . . . . 206Managing Receive-Data Buffers. . . . . . . . . . . . . . . . . . . . . . . . . . 207Understanding Target-Mode Data Pacing . . . . . . . . . . . . . . . . . . . . . . 207Understanding the SCSI Target Mode Device Driver Receive Buffer Routine . . . . . . . . . 208Understanding the tm_buf Structure . . . . . . . . . . . . . . . . . . . . . . . . 209Understanding the Running of SCSI Target-Mode Requests . . . . . . . . . . . . . . . 210

Required SCSI Adapter Device Driver ioctl Commands . . . . . . . . . . . . . . . . . . 211Initiator-Mode ioctl Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 211Target-Mode ioctl Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 213Target- and Initiator-Mode ioctl Commands . . . . . . . . . . . . . . . . . . . . . 215Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Chapter 13. Fibre Channel Protocol for SCSI Subsystem . . . . . . . . . . . . . . . . 217FCP Subsystem Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Responsibilities of the FCP Adapter Device Driver . . . . . . . . . . . . . . . . . . . 217Responsibilities of the FCP Device Driver . . . . . . . . . . . . . . . . . . . . . . 217Communication between FCP Devices . . . . . . . . . . . . . . . . . . . . . . . 218Initiator-Mode Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Understanding FCP Asynchronous Event Handling. . . . . . . . . . . . . . . . . . . . 218Defined Events and Recovery Actions . . . . . . . . . . . . . . . . . . . . . . . 219Asynchronous Event-Handling Routine . . . . . . . . . . . . . . . . . . . . . . . 220

FCP Error Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220autosense data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220NACA=1 error recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

FCP Initiator-Mode Recovery When Not Command Tag Queuing . . . . . . . . . . . . . . 221FCP Initiator-Mode Recovery During Command Tag Queuing . . . . . . . . . . . . . . . . 221

Analyzing Returned Status . . . . . . . . . . . . . . . . . . . . . . . . . . . 222Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

A Typical Initiator-Mode FCP Driver Transaction Sequence . . . . . . . . . . . . . . . . . 223Understanding FCP Device Driver Internal Commands . . . . . . . . . . . . . . . . . . 224Understanding the Execution of Initiator I/O Requests . . . . . . . . . . . . . . . . . . 224

Spanned (Consolidated) Commands . . . . . . . . . . . . . . . . . . . . . . . . 224Fragmented Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

FCP Command Tag Queuing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225Understanding the scsi_buf Structure. . . . . . . . . . . . . . . . . . . . . . . . . 226

Fields in the scsi_buf Structure . . . . . . . . . . . . . . . . . . . . . . . . . . 226Other FCP Design Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Responsibilities of the FCP Device Driver . . . . . . . . . . . . . . . . . . . . . . 231FCP Options to the openx Subroutine . . . . . . . . . . . . . . . . . . . . . . . 232Using the SC_FORCED_OPEN Option . . . . . . . . . . . . . . . . . . . . . . . 232Using the SC_RETAIN_RESERVATION Option . . . . . . . . . . . . . . . . . . . . 232Using the SC_DIAGNOSTIC Option . . . . . . . . . . . . . . . . . . . . . . . . 233Using the SC_NO_RESERVE Option. . . . . . . . . . . . . . . . . . . . . . . . 233Using the SC_SINGLE Option . . . . . . . . . . . . . . . . . . . . . . . . . . 233Closing the FCP Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235FCP Error Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235Length of Data Transfer for FCP Commands . . . . . . . . . . . . . . . . . . . . . 235

x Kernel Extensions and Device Support Programming Concepts

Device Driver and Adapter Device Driver Interfaces . . . . . . . . . . . . . . . . . . 235Performing FCP Dumps . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Required FCP Adapter Device Driver ioctl Commands . . . . . . . . . . . . . . . . . . 236Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236Initiator-Mode ioctl Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 237Initiator-Mode ioctl Command used by FCP Device Drivers. . . . . . . . . . . . . . . . 240

Chapter 14. FCP Device Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . 243Programming FCP Device Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . 243FCP Device Driver Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243FCP Adapter Device Driver Overview. . . . . . . . . . . . . . . . . . . . . . . . . 243FCP Adapter/Device Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

scsi_buf Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244Adapter/Device Driver Intercommunication . . . . . . . . . . . . . . . . . . . . . . 249

FCP Adapter Device Driver Routines . . . . . . . . . . . . . . . . . . . . . . . . . 249config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250open. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250openx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250ioctl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251interrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

FCP Adapter ioctl Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . 251IOCINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251SCIOLSTART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252SCIOLSTOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252SCIOLEVENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252SCIOLINQU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253SCIOLSTUNIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254SCIOLTUR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254SCIOLREAD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255SCIOLRESET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256SCIOLHALT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256SCIOLCMD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257SCIOLNMSRV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258SCIOLQWWN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258SCIOLPAYLD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Chapter 15. Integrated Device Electronics (IDE) Subsystem . . . . . . . . . . . . . . . 261Responsibilities of the IDE Adapter Device Driver . . . . . . . . . . . . . . . . . . . . 261Responsibilities of the IDE Device Driver . . . . . . . . . . . . . . . . . . . . . . . 261Communication Between IDE Device Drivers and IDE Adapter Device Drivers . . . . . . . . . 261IDE Error Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

Analyzing Returned Status . . . . . . . . . . . . . . . . . . . . . . . . . . . 262A Typical IDE Driver Transaction Sequence . . . . . . . . . . . . . . . . . . . . . . 263IDE Device Driver Internal Commands . . . . . . . . . . . . . . . . . . . . . . . . 263Execution of I/O Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Spanned (Consolidated) Commands . . . . . . . . . . . . . . . . . . . . . . . . 264Fragmented Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265Gathered Write Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

ataide_buf Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266Fields in the ataide_buf Structure . . . . . . . . . . . . . . . . . . . . . . . . . 266

Other IDE Design Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 268IDE Device Driver Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268Closing the IDE Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Contents xi

IDE Error Processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269Device Driver and Adapter Device Driver Interfaces . . . . . . . . . . . . . . . . . . 269Performing IDE Dumps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

Required IDE Adapter Device Driver ioctl Commands . . . . . . . . . . . . . . . . . . . 270ioctl Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

Chapter 16. Serial Direct Access Storage Device Subsystem . . . . . . . . . . . . . . 273DASD Device Block Level Description . . . . . . . . . . . . . . . . . . . . . . . . 273

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

Chapter 17. Debugging Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . 275System Dump Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

Configure a Dump Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275Start a System Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276Check the Status of a System Dump . . . . . . . . . . . . . . . . . . . . . . . . 278Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278Copy a System Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278Increase the Size of a Dump Device . . . . . . . . . . . . . . . . . . . . . . . . 281

Low Level Kernel Debugger (LLDB) . . . . . . . . . . . . . . . . . . . . . . . . . 282LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . . . . . . . . . 282Loading and Starting the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . 283Using a Terminal with the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . 283Entering the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . . . . . 283Debugging Multiprocessor Systems . . . . . . . . . . . . . . . . . . . . . . . . 284LLDB Kernel Debug Program Concepts . . . . . . . . . . . . . . . . . . . . . . . 284LLDB Kernel Debug Program Commands . . . . . . . . . . . . . . . . . . . . . . 287LLDB Kernel Debug Program Commands grouped in Alphabetical Order . . . . . . . . . . 287LLDB Kernel Debug Program Commands grouped by Task Category . . . . . . . . . . . . 289Descriptions of the LLDB Kernel Debug Program Commands . . . . . . . . . . . . . . . 291alter Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . 291back Command for the LLDB Kernel Debug Program. . . . . . . . . . . . . . . . . . 291break Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . 292breaks Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . 292buckets Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . 292clear Command for the LLDB Kernel Debug Program. . . . . . . . . . . . . . . . . . 293cpu Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . 293display Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . 294dmodsw Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . 294drivers Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . 295find Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . 295float Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . 296fmodsw Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . 296fs Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . . 297go Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . 297help Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . 298loop Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . 298map Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . 298mblk Command for the LLDB Kernel Debug Program. . . . . . . . . . . . . . . . . . 299mst64 Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . 299netdata Command for the LLDB Kernel Debug Program. . . . . . . . . . . . . . . . . 300next Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . 300origin Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . 300ppd Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . 300proc Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . 301queue Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . 301quit Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . 302

xii Kernel Extensions and Device Support Programming Concepts

reason Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . 302reboot Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . 302reset Command for the LLDB Kernel Debug Program. . . . . . . . . . . . . . . . . . 302screen Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . 303segst64 Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . 304set Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . 304sregs Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . 305sr64 Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . 305st Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . . 306stack Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . 306stc Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . 306step Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . 307sth Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . 307stream Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . 307swap Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . 309sysinfo Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . 309thread Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . 309trace Command for the LLDB Kernel Debug Program. . . . . . . . . . . . . . . . . . 310trb Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . 311tty Command for the LLDB Kernel Debug Program. . . . . . . . . . . . . . . . . . . 311un Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . 312user Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . 312user64 Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . 312uthread Command for the LLDB Kernel Debug Program. . . . . . . . . . . . . . . . . 313vars Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . . 314vmm Command for the LLDB Kernel Debug Program. . . . . . . . . . . . . . . . . . 314watch Command for the LLDB Kernel Debug Program . . . . . . . . . . . . . . . . . 315xlate Command for the LLDB Kernel Debug Program. . . . . . . . . . . . . . . . . . 315Maps and Listings as Tools for the LLDB Kernel Debug Program . . . . . . . . . . . . . 315Compiler Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315Map File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317Using the LLDB Kernel Debug Program. . . . . . . . . . . . . . . . . . . . . . . 319Setting Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320Viewing and Modifying Global Data . . . . . . . . . . . . . . . . . . . . . . . . 323Displaying Registers on a Micro Channel Adapter . . . . . . . . . . . . . . . . . . . 324Stack Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325Error Messages for the LLDB Kernel Debug Program. . . . . . . . . . . . . . . . . . 326

KDB Kernel Debugger and Command for the POWER-based Platform . . . . . . . . . . . . 328KDB Kernel Debugger and kdb Command . . . . . . . . . . . . . . . . . . . . . . 328The kdb Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328KDB Kernel Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329Loading and Starting the KDB Kernel Debugger in AIX 4.3.3 . . . . . . . . . . . . . . . 329Loading and Starting the KDB Kernel Debugger in AIX 5.1 and Subsequent Releases. . . . . . 330Using a Terminal with the KDB Kernel Debugger . . . . . . . . . . . . . . . . . . . 330Entering the KDB Kernel Debugger . . . . . . . . . . . . . . . . . . . . . . . . 331Debugging Multiprocessor Systems . . . . . . . . . . . . . . . . . . . . . . . . 331Kernel Debug Program Concepts . . . . . . . . . . . . . . . . . . . . . . . . . 331

Subcommands for the KDB Kernel Debugger and kdb Command . . . . . . . . . . . . . . 332Introduction to Subcommands . . . . . . . . . . . . . . . . . . . . . . . . . . 332KDB Kernel Debug Program Subcommands grouped in Alphabetical Order. . . . . . . . . . 334KDB Kernel Debug Subcommands grouped by Task Category . . . . . . . . . . . . . . 338

Basic Subcommands for the KDB Kernel Debugger and kdb Command . . . . . . . . . . . . 345h Subcommand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345his Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346e Subcommand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347set Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

Contents xiii

f Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349ctx Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352cdt Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

Trace Subcommands for the KDB Kernel Debugger and kdb Command . . . . . . . . . . . . 355bt Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355ct and cat Subcommands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

Breakpoints/Steps Subcommands for the KDB Kernel Debugger and kdb Command . . . . . . . 357b Subcommand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357lb Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358r and gt Subcommands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360c, lc, and ca Subcommands . . . . . . . . . . . . . . . . . . . . . . . . . . . 361n s, S, and B Subcommands . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

Dumps/Display/Decode Subcommands for the KDB Kernel Debugger and kdb Command . . . . . 363d, dw, dd, dp, dpw, dpd Subcommands . . . . . . . . . . . . . . . . . . . . . . . 363ddvb, ddvh, ddvw, ddvd, ddpd, ddph, and ddpw Subcommands . . . . . . . . . . . . . . 364dc and dpc Subcommands . . . . . . . . . . . . . . . . . . . . . . . . . . . 365dr Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366find and findp Subcommands . . . . . . . . . . . . . . . . . . . . . . . . . . 368ext and extp Subcommands . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

Modify Memory Subcommands for the KDB Kernel Debugger and kdb Command . . . . . . . . 371m, mw, md, mp, mpw, and mpd Subcommands . . . . . . . . . . . . . . . . . . . . 371mdvb, mdvh, mdvw, mdvd, mdpb, mdph, mdpw, mdpd Subcommands . . . . . . . . . . . 372mr Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373

Namelist/Symbol Subcommands for the KDB Kernel Debugger and kdb Command . . . . . . . . 374nm and ts Subcommands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374ns Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

Watch Break Points Subcommands for the KDB Kernel Debugger and kdb Command. . . . . . . 376wr, ww, wrw, cw, lwr, lww, lwrw, and lcw Subcommands . . . . . . . . . . . . . . . . . 376

Miscellaneous Subcommands for the KDB Kernel Debugger and kdb Command. . . . . . . . . 377time and debug Subcommands . . . . . . . . . . . . . . . . . . . . . . . . . . 377

Conditional Subcommands for the KDB Kernel Debugger and kdb Command . . . . . . . . . . 378test Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

Calculator Converter Subcommands for the KDB Kernel Debugger and kdb Command . . . . . . 378hcal and dcal Subcommands. . . . . . . . . . . . . . . . . . . . . . . . . . . 378

Machine Status Subcommands for the KDB Kernel Debugger and kdb Command . . . . . . . . 379stat Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379sw Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

Kernel Extension Loader Subcommands for the KDB Kernel Debugger and kdb Command . . . . . 383lke, stbl, and rmst Subcommands . . . . . . . . . . . . . . . . . . . . . . . . . 383ex Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

Address Translation Subcommands for the KDB Kernel Debugger and kdb Command . . . . . . 386tr and tv Subcommands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

Process Subcommands for the KDB Kernel Debugger and kdb Command . . . . . . . . . . . 388ppda Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388intr Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389mst Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390proc Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392thread Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395ttid and tpid Subcommands . . . . . . . . . . . . . . . . . . . . . . . . . . . 398user Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399

LVM Subcommands for the KDB Kernel Debugger and kdb Command . . . . . . . . . . . . 401pbuf Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401volgrp Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402pvol Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404lvol Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404

SCSI Subcommands for the KDB Kernel Debugger and kdb Command . . . . . . . . . . . . 405

xiv Kernel Extensions and Device Support Programming Concepts

asc Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405vsc Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408scd Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412

Memory Allocator Subcommands for the KDB Kernel Debugger and kdb Command . . . . . . . 415heap Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415xm Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417kmbucket Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420kmstats Subcommands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421

File System Subcommands for the KDB Kernel Debugger and kdb Command . . . . . . . . . 423buffer Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423hbuffer Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424fbuffer Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424gnode Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425gfs Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425file Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426inode Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427hinode Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429icache Subcommand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429rnode Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431vnode Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431vfs Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432specnode Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433devnode Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434fifonode Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435hnode Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436

System Table Subcommands for the KDB Kernel Debugger and kdb Command . . . . . . . . . 437var Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437devsw Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438trb Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439slk and clk Subcommands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441ipl Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441trace Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443

Net Subcommands for the KDB Kernel Debugger and kdb Command. . . . . . . . . . . . . 445ifnet Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445tcb Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445udb Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446sock Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447sockinfo Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447tcpcb Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450mbuf Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451

VMM Subcommands for the KDB Kernel Debugger and kdb Command . . . . . . . . . . . . 451vmker Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452rmap Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453pfhdata Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454vmstat Subcommand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455vmaddr Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456pdt Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457scb Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457pft Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459pte Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462pta Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463ste Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464sr64 Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465segst64 Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466apt Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467vmwait Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467

Contents xv

ames Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469zproc Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470vmlog Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471vrld Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471ipc Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472lockanch Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472lockhash Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473lockword Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475vmdmap Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478vmlocks Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479

SMP Subcommands for the KDB Kernel Debugger and kdb Command . . . . . . . . . . . . 481start and stop Subcommands . . . . . . . . . . . . . . . . . . . . . . . . . . 481cpu Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482

Block Address Translation (bat) Subcommands for the KDB Kernel Debugger and kdb Command 482dbat Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482ibat Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483mdbat Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484mibat Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485

btac/BRAT Subcommands for the KDB Kernel Debugger and kdb Command . . . . . . . . . . 486btac, cbtac, lbtac, lcbtac Subcommands. . . . . . . . . . . . . . . . . . . . . . . 486

machdep Subcommands for the KDB Kernel Debugger and kdb Command . . . . . . . . . . 487reboot Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487Using the KDB Kernel Debug Program . . . . . . . . . . . . . . . . . . . . . . . 487Example Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488Generating Maps and Listings . . . . . . . . . . . . . . . . . . . . . . . . . . 488Compiler Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489Map File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490Setting Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491Viewing and Modifying Global Data . . . . . . . . . . . . . . . . . . . . . . . . 495Stack Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498demo.c Example File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503demokext.c Example File . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505demo.h Example File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507demokext.exp Example File . . . . . . . . . . . . . . . . . . . . . . . . . . . 507comp_link Example File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508

IADB Kernel Debugger for the Itanium-based platform . . . . . . . . . . . . . . . . . . 508IADB Kernel Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508Example of using the Kernel Debugger . . . . . . . . . . . . . . . . . . . . . . . 509

Break Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509Memory Display/Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . 509Register Display/Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . 510Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510Structures Display/Modification . . . . . . . . . . . . . . . . . . . . . . . . . . 510Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511

Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511Display/Set Software Break Points (br) . . . . . . . . . . . . . . . . . . . . . . . 511Clear Software Breakpoints (c) . . . . . . . . . . . . . . . . . . . . . . . . . . 512Clear Data Address Break Points (cdbr) . . . . . . . . . . . . . . . . . . . . . . . 512Clear Hardware Instruction Break Points (cibr) . . . . . . . . . . . . . . . . . . . . 513Display/Set Data Address Breakpoints (dbr) . . . . . . . . . . . . . . . . . . . . . 513Display/Set Hardware Breakpoints (ibr) . . . . . . . . . . . . . . . . . . . . . . . 514

Memory Display/Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514Display Virtual Memory (d) . . . . . . . . . . . . . . . . . . . . . . . . . . . 514Display I/O Port Space (dioport) . . . . . . . . . . . . . . . . . . . . . . . . . 515

xvi Kernel Extensions and Device Support Programming Concepts

Disassemble (dis) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515Display Physical Memory (dp) . . . . . . . . . . . . . . . . . . . . . . . . . . 515Display PCI Config Space (dpci) . . . . . . . . . . . . . . . . . . . . . . . . . 516Modify Virtual Memory (m). . . . . . . . . . . . . . . . . . . . . . . . . . . . 516Modify I/O Port Space (mioport). . . . . . . . . . . . . . . . . . . . . . . . . . 516Modify Physical Memory (mp) . . . . . . . . . . . . . . . . . . . . . . . . . . 517Modify PCI Config Space (mpci) . . . . . . . . . . . . . . . . . . . . . . . . . 517

Register Display/Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517Display/Set Branch Registers (b) . . . . . . . . . . . . . . . . . . . . . . . . . 517Display Current Stacked Register (cfm) . . . . . . . . . . . . . . . . . . . . . . . 518Display FPR(s) (f0 - f127) (fpr) . . . . . . . . . . . . . . . . . . . . . . . . . . 518Display Uthread Structure Information (ut) . . . . . . . . . . . . . . . . . . . . . . 518Display User Structure Information (us) . . . . . . . . . . . . . . . . . . . . . . . 518Display or Modify Instruction Pointer (iip) . . . . . . . . . . . . . . . . . . . . . . 519Display Instruction Previous Address (iipa) . . . . . . . . . . . . . . . . . . . . . . 519Display Fault Address (ifa). . . . . . . . . . . . . . . . . . . . . . . . . . . . 519Display Interrupt Registers (intr). . . . . . . . . . . . . . . . . . . . . . . . . . 519Display/Decode IPSR (ipsr) . . . . . . . . . . . . . . . . . . . . . . . . . . . 520Display/Decode ISR (isr) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520Display Time Registers ITC ITM & ITV (itc) . . . . . . . . . . . . . . . . . . . . . 520Display/Set Kernel Register (kr) . . . . . . . . . . . . . . . . . . . . . . . . . . 520Display/Set Predicate Register (p) . . . . . . . . . . . . . . . . . . . . . . . . . 521Display Performance Register (perfr) . . . . . . . . . . . . . . . . . . . . . . . . 521Display/Set General Register (r) . . . . . . . . . . . . . . . . . . . . . . . . . 521Display/Set Region Register (rr). . . . . . . . . . . . . . . . . . . . . . . . . . 522Display Register Stack Registers (rse) . . . . . . . . . . . . . . . . . . . . . . . 522

Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522Single Step Into Current Instruction (s) . . . . . . . . . . . . . . . . . . . . . . . 522Step Bundle (whole bundle) (sb) . . . . . . . . . . . . . . . . . . . . . . . . . 522Single Step Over Current Instruction (so) . . . . . . . . . . . . . . . . . . . . . . 523Step Return From Current Procedure (sr) . . . . . . . . . . . . . . . . . . . . . . 523Step to Next Taken Branch (stb) . . . . . . . . . . . . . . . . . . . . . . . . . 523

Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523Display CPU status or Change debugging CPU (cpu). . . . . . . . . . . . . . . . . . 523Display Reason Debugger was Entered (reason) . . . . . . . . . . . . . . . . . . . 524Display System Status Information (stat) . . . . . . . . . . . . . . . . . . . . . . 524Switch to a thread (sw) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524Display System Information (sys) . . . . . . . . . . . . . . . . . . . . . . . . . 524Stack Traceback (t) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524

Structures Display/Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . 525Show/Clear Alignment Fault Table (align) . . . . . . . . . . . . . . . . . . . . . . 525Display Buffer cache and pool (buffer) . . . . . . . . . . . . . . . . . . . . . . . 525Display WLM bio devices (bdev) . . . . . . . . . . . . . . . . . . . . . . . . . 526Display WLM bio queues (bqueue) . . . . . . . . . . . . . . . . . . . . . . . . 526Display WLM Class Information (cla) . . . . . . . . . . . . . . . . . . . . . . . . 526Display Device Switch Table (dev) . . . . . . . . . . . . . . . . . . . . . . . . . 526Display Device Node Structure and Table (devnode) . . . . . . . . . . . . . . . . . . 527Disply dnlc cache (dnlc) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527Display fifonode Table and Structure (fifonode) . . . . . . . . . . . . . . . . . . . . 527Display File Structure and Table (file) . . . . . . . . . . . . . . . . . . . . . . . . 528Display Generic Filesystem Structure (gfs) . . . . . . . . . . . . . . . . . . . . . . 528Display Generic Node Structure (gnode) . . . . . . . . . . . . . . . . . . . . . . 528Display heap Information (heap) . . . . . . . . . . . . . . . . . . . . . . . . . 528Display Inode Structure and Table (inode) . . . . . . . . . . . . . . . . . . . . . . 529Display Interrupt Handler Information and Table (intrh) . . . . . . . . . . . . . . . . . 529Display IPL Control Block (iplcb) . . . . . . . . . . . . . . . . . . . . . . . . . 529

Contents xvii

Display Loaded Kernel Extensions (kext) . . . . . . . . . . . . . . . . . . . . . . 530Display Kernel Memory Buckets (kmbucket) . . . . . . . . . . . . . . . . . . . . . 530Display Kernel Memory Statistics (kmstats) . . . . . . . . . . . . . . . . . . . . . 530Display Complex, Simple, and Lockl Locks List and Structure (lock) . . . . . . . . . . . . 531Display Lock Queue Information (lq) . . . . . . . . . . . . . . . . . . . . . . . . 531Dump Internal Per-CPU Trace Buffer (mltrace) . . . . . . . . . . . . . . . . . . . . 531Display Machine State Stack (mst). . . . . . . . . . . . . . . . . . . . . . . . . 532Display Per Node Descriptor Area (pnda) / Table . . . . . . . . . . . . . . . . . . . 532Display Per Processor Descriptor Area (ppda) / Table. . . . . . . . . . . . . . . . . . 532Process Display (pr) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533Display Run Queue Information (rq) . . . . . . . . . . . . . . . . . . . . . . . . 533Display Pvprocess Information (pvpr) . . . . . . . . . . . . . . . . . . . . . . . . 534Display Pvthread Information (pvth) . . . . . . . . . . . . . . . . . . . . . . . . 534Display WLM Rules (rules) . . . . . . . . . . . . . . . . . . . . . . . . . . . 534Display Specnode Structure (specnode). . . . . . . . . . . . . . . . . . . . . . . 535Display Sleep Queue Information (sq) . . . . . . . . . . . . . . . . . . . . . . . 535Thread Display (th) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535Display var Structure Information (var) . . . . . . . . . . . . . . . . . . . . . . . 536Display Virtual Node Structure (vnode) . . . . . . . . . . . . . . . . . . . . . . . 536Display vfs Table/Structure (vfs). . . . . . . . . . . . . . . . . . . . . . . . . . 536Display Xmalloc Information if xmdbg is Enabled (xm) . . . . . . . . . . . . . . . . . 536

Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537Map Address to Symbol or Symbol to Address (map) . . . . . . . . . . . . . . . . . . 537Translate Virtual to Physical (x) . . . . . . . . . . . . . . . . . . . . . . . . . . 538

Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538Find a Pattern or a String of Characters in Memory (find) . . . . . . . . . . . . . . . . 538Exit the debugger (resume execution) (go). . . . . . . . . . . . . . . . . . . . . . 539Command Listing/Command Help (help [command]) . . . . . . . . . . . . . . . . . . 539Set/Reset Symbols Needed By kdbx . . . . . . . . . . . . . . . . . . . . . . . . 540Reboot the System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540Display/Set Debugger Parameters (set) . . . . . . . . . . . . . . . . . . . . . . . 540

Error Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541Precoding Steps to Consider . . . . . . . . . . . . . . . . . . . . . . . . . . . 541Coding Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542Writing to the /dev/error Special File . . . . . . . . . . . . . . . . . . . . . . . . 546

Debug and Performance Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . 547Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547Using the trace Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548Controlling trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548Producing a trace Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551Defining trace Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551Usage Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566Trace Event Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567

Memory Overlay Detection System (MODS) . . . . . . . . . . . . . . . . . . . . . . 568Kernel Memory Overlay Detection System (MODS) . . . . . . . . . . . . . . . . . . 568

Chapter 18. Loadable Authentication Module Programming Interface . . . . . . . . . . . 571Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571Load Module Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571Authentication Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572

The method_authenticate Interface . . . . . . . . . . . . . . . . . . . . . . . . 572The method_chpass Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 573The method_getpasswd Interface . . . . . . . . . . . . . . . . . . . . . . . . . 573The method_normalize Interface . . . . . . . . . . . . . . . . . . . . . . . . . 574The method_passwdexpired Interface . . . . . . . . . . . . . . . . . . . . . . . 574The method_passwdrestrictions Interface . . . . . . . . . . . . . . . . . . . . . . 574

xviii Kernel Extensions and Device Support Programming Concepts

Identification Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574The method_getentry Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 575The method_getgracct Interface. . . . . . . . . . . . . . . . . . . . . . . . . . 575The method_getgrgid Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 575The method_getgrnam Interface . . . . . . . . . . . . . . . . . . . . . . . . . 576The method_getgrset Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 576The method_getgrusers Interface . . . . . . . . . . . . . . . . . . . . . . . . . 576The method_getpwnam Interface . . . . . . . . . . . . . . . . . . . . . . . . . 576The method_getpwuid Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 577The method_putentry Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 577The method_putgrent Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 577The method_putgrusers Interface . . . . . . . . . . . . . . . . . . . . . . . . . 578The method_putpwent Interface. . . . . . . . . . . . . . . . . . . . . . . . . . 578

Support Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578The method_attrlist Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 578The method_close Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 579The method_commit Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 579The method_delgroup Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 579The method_deluser Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 580The method_lock Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 580The method_newgroup Interface . . . . . . . . . . . . . . . . . . . . . . . . . 580The method_newuser Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 580The method_open Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 581The method_unlock Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . 581

Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581The options Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581

Compound Load Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583

Chapter 19. Alphabetical List of Kernel Services . . . . . . . . . . . . . . . . . . . 585Kernel Services Available in Process and Interrupt Environments . . . . . . . . . . . . . . 585

Kernel Services Available in the Process Environment Only . . . . . . . . . . . . . . . 589

Appendix. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597

Contents xix

xx 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 kernelsubsystems is also provided.

Who Should Use This BookThis book is intended for system programmers who are knowledgeable in operating system concepts andkernel programming and want to extend the kernel.

How to Use This BookThis book provides two types of information: (1) an overview of the kernel programming environment andinformation a programmer needs to write kernel extensions, and (2) information about existing kernelsubsystems.

HighlightingThe following highlighting conventions are used in this book:

Bold Identifies commands, subroutines, keywords, files,structures, directories, and other items whose names arepredefined by the system. Also identifies graphical objectssuch as buttons, labels, and icons that the user selects.

Italics Identifies parameters whose actual names or values are tobe supplied by the user.

Monospace Identifies examples of specific data values, examples oftext similar to what you might see displayed, examples ofportions of program code similar to what you might writeas a programmer, messages from the system, orinformation you should actually type.

ISO 9000ISO 9000 registered quality systems were used in the development and manufacturing of this product.

Related PublicationsThe following books contain additional information on kernel extension programming and the existingkernel subsystems:

v AIX 5L Version 5.1 Guide to Printers and Printingv AIX 5L for POWER-based Systems Keyboard Technical Referencev AIX 5L Version 5.1 System Management Guide: Operating System and Devicesv AIX 5L Version 5.1 Technical Reference: Kernel and Subsystems Volume 1v AIX 5L Version 5.1 Technical Reference: Kernel and Subsystems Volume 2

© Copyright IBM Corp. 1997, 2001 xxi

TrademarksThe following terms are trademarks of International Business Machines Corporation in the United States,other countries, or both:

v AIXv IBMv Micro Channelv PowerPCv RS/6000

UNIX is a registered trademark of The Open Group in the United States and other countries.

Other company, product, or service names may be the trademarks or service marks of others.

xxii 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 thefollowing functional classes:

v System callsv Virtual file systemsv Kernel Extension and Device Driver Management Kernel Servicesv Device Drivers

The general term ″kernel extension″ applies to all routines added to the kernel, independent of theirpurpose. Kernel extensions can be added at any time by a user with the appropriate privilege.

Kernel extensions run in the same mode as the kernel. That is, when the 64–bit kernel is used, kernelextensions run in 64–bit mode. These kernel extensions must be compiled in 64–bit mode.

The following kernel-environment programming information is provided to assist you in programming kernelextensions:

v “Understanding Kernel Extension Symbol Resolution”v “Understanding Execution Environments” on page 6v “Understanding Kernel Threads” on page 7v “Using Kernel Processes” on page 9v “Accessing User-Mode Data While in Kernel Mode” on page 12v “Understanding Locking” on page 13v “Understanding Exception Handling” on page 14v “Using Kernel Extensions to Support 64–bit Processes” on page 19

A process executing in user mode can customize the kernel by using the sysconfig subroutine, if theprocess has appropriate privilege. In this way, a user-mode process can load, unload, initialize, orterminate kernel routines. Kernel configuration can also be altered by changing tuneable systemparameters.

Kernel extensions can also customize the kernel by using kernel services to load, unload, initialize, andterminate dynamically loaded kernel routines; to create and initialize kernel processes; and to defineinterrupt handlers.

Note: Private kernel routines (or kernel services) execute in a privileged protection domain and canaffect the operation and integrity of the whole system. See “Kernel Protection Domain” on page 24 formore information.

Understanding Kernel Extension Symbol ResolutionThe following information is provided to assist you in understanding kernel extension symbol resolution:

v “Exporting Kernel Services and System Calls” on page 2v “Using Kernel Services” on page 2v “Using System Calls with Kernel Extensions” on page 2v “Using Private Routines” on page 3v “Understanding Dual-Mode Kernel Extensions” on page 4v “Using Libraries” on page 4

© Copyright IBM Corp. 1997, 2001 1

../../libs/basetrf2/sysconfig.htm

Exporting Kernel Services and System CallsA kernel extension provides additional kernel services and system calls by specifying an export file when itis link-edited. An export file contains a list of symbols to be added to the kernel name space. In addition,symbols can be identified as system calls for 32-bit processes, 64-bit processes, or both.

In an export file, symbols are listed one per line. On the Itanium-based platform, a system call is identifiedby using the ″syscall″ keyword after the symbol name. These system calls are available to both 32- and64-bit processes. On the POWER-based platform, system calls are identified by using one of thesyscall32, syscall64 or syscall3264 keywords after the symbol name. Use syscall32 to make a systemcall available to 32-bit processes, syscall64 to make a system call available to 64-bit processes, andsyscall3264 to make a system call available to both 32- and 64-bit processes. For more information aboutexport files, see ld Command in AIX 5L Version 5.1 Commands Reference, Volume 3.

When a new kernel extension is loaded by the sysconfig or kmod_load subroutine, any symbolsexported by the kernel extension are added to the kernel name space, and are available to allsubsequently loaded kernel extensions. Similarly, system calls exported by a kernel extension areavailable to all user programs or shared objects subsequently loaded.

Using Kernel Services

The kernel provides a set of base kernel services to be used by kernel extensions. Kernel extensions canexport new kernel services, which can then be used by subsequently loaded kernel extensions. Basekernel services, which are described in the services documentation, are made available to a kernelextension by specifying the /usr/lib/kernex.imp import file during the link-edit of the extension.

Note: Link-editing of a kernel extension should always be performed by using the ld command. Do notuse the compiler to create a kernel extension.

If a kernel extension depends on kernel services provided by other kernel extensions, an additional importfile must be specified when link-editing. An import file lists additional kernel services, with each servicelisted on its own line. An import file must contain the line #!/unix for the POWER-based platform or%soname /unix for the Itanium-based platform, before any services are listed. On the POWER-basedplatform, the same file can be used both as an import file and an export file. When linking kernelextensions on the Itanium-based platform, an export file can be used as an import file if the -Bkext flag isused. The #!/unix or %soname /unix line is ignored when a file is used as an export file. For moreinformation on import files, see ld command in AIX 5L Version 5.1 Commands Reference, Volume 3.

Using System Calls with Kernel Extensions

A restricted set of 32-bit system calls can be used by kernel extensions. A kernel process can use a largerset of system calls than a user process in kernel mode. “System Calls Available to Kernel Extensions” onpage 36 specifies which system calls can be used by either type of process. User-mode processes inkernel mode can only use system calls that have all parameters passed by value. Kernel routines runningunder user-mode processes cannot directly use a system call having parameters passed by reference.

The second restriction is imposed because, when they access a caller’s data, system calls withparameters passed by reference access storage across a protection domain. The cross-domain memoryservices performing these cross-memory operations support kernel processes as if they, too, accessedstorage across a protection domain. However, these services have no way to determine that the caller is inthe same protection domain when the caller is a user-mode process in kernel mode.

Note: System calls must not be used by kernel extensions executing in the interrupt handlerenvironment.

2 Kernel Extensions and Device Support Programming Concepts

../../cmds/aixcmds3/ld.htm#HDRA09493AC../../cmds/aixcmds3/ld.htm#HDRA09493AC../../cmds/aixcmds3/ld.htm#HDRA