Bull AIX 4.3 - Kernel Extensions and Device Support Programming Guide

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

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

Readers’ Comments — We’d Like to

Hear from You . . . . . . . . . . . 599

Contents xiii

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.

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

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

Page is loading ...

Bull AIX 4.3 - Kernel Extensions and Device Support Programming Guide

Bull AIX 4.3 - Kernel Extensions and Device Support Programming Guide

Related papers

Other documents