| blob | 914928fd45affa635be300eec3ad1605915d625a |
1 <html>
2 <head>
3 <title>Linux Device Drivers 3</title>
4 <meta Name="keywords" Content="Linux,device,drivers,kernel,kernel development,kernel modules,Jonathan Corbet,Alessandro Rubini,Greg Kroah-Hartman,char drivers,USB drivers,block drivers,network drivers,TTY drivers,PCI drivers">
5 <style>
6 pre { font-family:Prestige, "Everson Mono", "MS Courier New", Courier; font-size:smaller; margin-left:.4in }
7 font.fixd { font-family:Prestige, "Everson Mono", "MS Courier New", Courier }
8 div.warn { text-align:justify; margin-left:.4in; margin-right:.4in; border:1px solid red; padding:6px 12px; }
9 div.tip { text-align:justify; margin-left:.4in; margin-right:.4in; border:1px solid blue; padding:6px 12px; }
10 div.bq { text-align:justify; margin-left:.4in }
11 div.bql { margin-left:.4in }
12 a.toc { font-variant:small-caps;font-weight:bold;font-size:larger;color:#7519FF }
13 a.tocr { font-variant:small-caps;font-weight:bold;font-size:larger;color:red }
14 </style>
15 </head>
16 <body style="text-align:justify;margin-left:5%;margin-right:5%"><br>
17 <br>
18 <center><font size="7">Linux Device Drivers</font><br>
19 <font size="4">Jonathan Corbet, Alessandro Rubini,<br>and Greg Kroah-Hartman.</font><br>
20 </center><br>
21 <font size="4">Web page format by </font><a href="http://linux.coconia.net" target="_blank"><font size="4">http://linux.coconia.net</font></a><br>
22 <br>
23 <div class="warn">If you redistribute this page you must not remove the attribution to the original authors, Corbet, Rubini and Kroah-Hartman, or, to linux.coconia.net.</div>
24 <br>
25 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
26 <a href="#Index" class="tocr">Index</a><br>
27 <br>
28 <a href="#Numbers">Numbers</a><br>
29 <a href="#A">A</a> <a href="#B">B</a> <a href="#C">C</a> <a href="#D">D</a> <a href="#E">E</a> <a href="#F">F</a> <a href="#G">G</a> <a href="#I">I</a> <a href="#H">H</a> <a href="#J">J</a> <a href="#K">K</a> <a href="#L">L</a> <a href="#M">M</a><br>
30 <a href="#N">N</a> <a href="#O">O</a> <a href="#P">P</a> <a href="#Q">Q</a> <a href="#R">R</a> <a href="#S">S</a> <a href="#T">T</a> <a href="#U">U</a> <a href="#V">V</a> <a href="#W">W</a> <a href="#X">X</a> <a href="#Z">Z</a><br>
31 <br>
32 <a href="#Chapters" class="tocr">Chapters</a><br>
33 <br>
34 <a href="#CHAPTER1">1</a> <a href="#CHAPTER2">2</a> <a href="#CHAPTER3">3</a> <a href="#CHAPTER4">4</a> <a href="#CHAPTER5">5</a> <a href="#CHAPTER6">6</a> <a href="#CHAPTER7">7</a> <a href="#CHAPTER8">8</a> <a href="#CHAPTER9">9</a> <a href="#CHAPTER10">10</a> <a href="#CHAPTER11">11</a><br><a href="#CHAPTER12">12</a> <a href="#CHAPTER13">13</a> <a href="#CHAPTER14">14</a> <a href="#CHAPTER15">15</a> <a href="#CHAPTER16">16</a> <a href="#CHAPTER17">17</a> <a href="#CHAPTER18">18</a><br>
35 <br>
36 <a href="#Preface" class="tocr">Preface</a><br>
37 <br>
38 <a href="#JonsIntroduction">Jon's Introduction</a><br>
39 <a href="#AlessandrosIntroduction">Alessandro's Introduction</a><br>
40 <a href="#GregsIntroduction">Greg's Introduction</a><br>
41 <a href="#AudienceForThisBook">Audience for This Book</a><br>
42 <a href="#OrganizationOfTheMaterial">Organization of the Material</a><br>
43 <a href="#BackgroundInformation">Background Information</a><br>
44 <a href="#OnlineVersionAndLicense">Online Version and License</a><br>
45 <a href="#ConventionsUsedInThisBook">Conventions Used in This Book</a><br>
46 <a href="#UsingCodeExamplesbr">Using Code Examples</a><br>
47 <a href="#WedLikeToHearFromYou">We'd Like to Hear from You</a><br>
48 <a href="#SafariEnabled">Safari Enabled</a><br>
49 <a href="#Acknowledgments">Acknowledgments</a><br>
50 <a href="#Jon">Jon</a><br>
51 <a href="#Alessandro">Alessandro</a><br>
52 <a href="#Greg">Greg</a><br>
53 <br>
54 <a href="#CHAPTER1" class="toc">Chapter 1</a><br>
55 <a href="#AnIntroductionToDeviceDrivers" class="tocr">An Introduction to Device Drivers</a><br>
56 <br>
57 <a href="#TheRoleOfTheDeviceDriver">The Role of the Device Driver</a><br>
58 <a href="#SplittingTheKernel">Splitting the Kernel</a><br>
59 <a href="#LoadableModules">Loadable Modules</a><br>
60 <a href="#ClassesOfDevicesAndModules">Classes of Devices and Modules</a><br>
61 <a href="#SecurityIssues">Security Issues</a><br>
62 <a href="#VersionNumbering">Version Numbering</a><br>
63 <a href="#LicenseTerms">License Terms</a><br>
64 <a href="#JoiningTheKernelDevelopmentCommunity">Joining the Kernel Development Community</a><br>
65 <a href="#OverviewOfTheBook">Overview of the Book</a><br>
66 <br>
67 <a href="#CHAPTER2" class="toc">Chapter 2</a><br>
68 <a href="#BuildingAndRunningModules" class="tocr">Building and Running Modules</a><br>
69 <br>
70 <a href="#SettingUpYourTestSystem">Setting Up Your Test System</a><br>
71 <a href="#TheHelloWorldModule">The Hello World Module</a><br>
72 <a href="#KernelModulesVersusApplications">Kernel Modules Versus Applications</a><br>
73 <a href="#UserSpaceAndKernelSpace">User Space and Kernel Space</a><br>
74 <a href="#ConcurrencyInTheKernel">Concurrency in the Kernel</a><br>
75 <a href="#TheCurrentProcess">The Current Process</a><br>
76 <a href="#AFewOtherDetails">A Few Other Details</a><br>
77 <a href="#CompilingAndLoading">Compiling and Loading</a><br>
78 <a href="#CompilingModules">Compiling Modules</a><br>
79 <a href="#LoadingAndUnloadingModules">Loading and Unloading Modules</a><br>
80 <a href="#VersionDependency">Version Dependency</a><br>
81 <a href="#PlatformDependency">Platform Dependency</a><br>
82 <a href="#TheKernelSymbolTable">The Kernel Symbol Table</a><br>
83 <a href="#Preliminaries">Preliminaries</a><br>
84 <a href="#InitializationAndShutdown">Initialization and Shutdown</a><br>
85 <a href="#TheCleanupFunction">The Cleanup Function</a><br>
86 <a href="#ErrorHandlingDuringInitialization">Error Handling During Initialization</a><br>
87 <a href="#ModuleLoadingRaces">Module-Loading Races</a><br>
88 <a href="#ModuleParameters">Module Parameters</a><br>
89 <a href="#DoingItInUserSpace">Doing It in User Space</a><br>
90 <a href="#QuickReference2">Quick Reference</a><br>
91 <br>
92 <a href="#CHAPTER3" class="toc">Chapter 3</a><br>
93 <a href="#CharDrivers" class="tocr">Char Drivers</a><br>
94 <br>
95 <a href="#TheDesignOfScull">The Design of scull</a><br>
96 <a href="#MajorAndMinorNumbers">Major and Minor Numbers</a><br>
97 <a href="#TheInternalRepresentationOfDeviceNumbers">The Internal Representation of Device Numbers</a><br>
98 <a href="#AllocatingAndFreeingDeviceNumbers">Allocating and Freeing Device Numbers</a><br>
99 <a href="#DynamicAllocationOfMajorNumbers">Dynamic Allocation of Major Numbers</a><br>
100 <a href="#SomeImportantDataStructures">Some Important Data Structures</a><br>
101 <a href="#FileOperations">File Operations</a><br>
102 <a href="#TheFileStructure">The file Structure</a><br>
103 <a href="#TheInodeStructure">The inode Structure</a><br>
104 <a href="#CharDeviceRegistration">Char Device Registration</a><br>
105 <a href="#DeviceRegistrationInScull">Device Registration in scull</a><br>
106 <a href="#TheOlderWay">The Older Way</a><br>
107 <a href="#OpenAndRelease">open and release</a><br>
108 <a href="#TheOpenMethod">The open Method</a><br>
109 <a href="#TheReleaseMethod">The release Method</a><br>
110 <a href="#ScullsMemoryUsage">scull's Memory Usage</a><br>
111 <a href="#ReadAndWrite">read and write</a><br>
112 <a href="#TheReadMethod">The read Method</a><br>
113 <a href="#TheWriteMethod">The write Method</a><br>
114 <a href="#ReadvAndWritev">readv and writev</a><br>
115 <a href="#PlayingWithTheNewDevices">Playing with the New Devices</a><br>
116 <a href="#QuickReference3">Quick Reference</a><br>
117 <br>
118 <a href="#CHAPTER4" class="toc">Chapter 4</a><br>
119 <a href="#DebuggingTechniques" class="tocr">Debugging Techniques</a><br>
120 <br>
121 <a href="#DebuggingSupportInTheKernel">Debugging Support in the Kernel</a><br>
122 <a href="#DebuggingByPrinting">Debugging by Printing</a><br>
123 <a href="#Printk">printk</a><br>
124 <a href="#RedirectingConsoleMessages">Redirecting Console Messages</a><br>
125 <a href="#HowMessagesGetLogged">How Messages Get Logged</a><br>
126 <a href="#TurningTheMessagesOnAndOff">Turning the Messages On and Off</a><br>
127 <a href="#RateLimiting">Rate Limiting</a><br>
128 <a href="#PrintingDeviceNumbers">Printing Device Numbers</a><br>
129 <a href="#DebuggingByQuerying">Debugging by Querying</a><br>
130 <a href="#UsingTheProcFilesystem">Using the /proc Filesystem</a><br>
131 <a href="#ImplementingFilesInProc">Implementing files in /proc</a><br>
132 <a href="#AnOlderInterface">An older interface</a><br>
133 <a href="#CreatingYourProcFile">Creating your /proc file</a><br>
134 <a href="#TheSeqfileInterface">The seq_file interface</a><br>
135 <a href="#TheIoctlMethod">The ioctl Method</a><br>
136 <a href="#DebuggingByWatching">Debugging by Watching</a><br>
137 <a href="#DebuggingSystemFaults">Debugging System Faults</a><br>
138 <a href="#OopsMessages">Oops Messages</a><br>
139 <a href="#SystemHangs">System Hangs</a><br>
140 <a href="#DebuggersAndRelatedTools">Debuggers and Related Tools</a><br>
141 <a href="#UsingGdb">Using gdb</a><br>
142 <a href="#TheKdbKernelDebugger">The kdb Kernel Debugger</a><br>
143 <a href="#TheKgdbPatches">The kgdb Patches</a><br>
144 <a href="#TheUserModeLinuxPort">The User-Mode Linux Port</a><br>
145 <a href="#TheLinuxTraceToolkit">The Linux Trace Toolkit</a><br>
146 <a href="#DynamicProbes">Dynamic Probes</a><br>
147 <br>
148 <a href="#CHAPTER5" class="toc">Chapter 5</a><br>
149 <a href="#ConcurrencyAndRacebrConditions" class="tocr">Concurrency and Race Conditions</a><br>
150 <br>
151 <a href="#PitfallsInScull">Pitfalls in scull</a><br>
152 <a href="#ConcurrencyAndItsManagement">Concurrency and Its Management</a><br>
153 <a href="#SemaphoresAndMutexes">Semaphores and Mutexes</a><br>
154 <a href="#TheLinuxSemaphoreImplementation">The Linux Semaphore Implementation</a><br>
155 <a href="#UsingSemaphoresInScull">Using Semaphores in scull</a><br>
156 <a href="#ReaderWriterSemaphores">Reader/Writer Semaphores</a><br>
157 <a href="#Completions">Completions</a><br>
158 <a href="#Spinlocks">Spinlocks</a><br>
159 <a href="#IntroductionToTheSpinlockAPI">Introduction to the Spinlock API</a><br>
160 <a href="#SpinlocksAndAtomicContext">Spinlocks and Atomic Context</a><br>
161 <a href="#TheSpinlockFunctions">The Spinlock Functions</a><br>
162 <a href="#ReaderWriterSpinlocks">Reader/Writer Spinlocks</a><br>
163 <a href="#LockingTraps">Locking Traps</a><br>
164 <a href="#AmbiguousRules">Ambiguous Rules</a><br>
165 <a href="#LockOrderingRules">Lock Ordering Rules</a><br>
166 <a href="#FineVersusCoarseGrainedLocking">Fine- Versus Coarse-Grained Locking</a><br>
167 <a href="#AlternativesToLocking">Alternatives to Locking</a><br>
168 <a href="#LockFreeAlgorithms">Lock-Free Algorithms</a><br>
169 <a href="#AtomicVariables">Atomic Variables</a><br>
170 <a href="#BitOperations">Bit Operations</a><br>
171 <a href="#Seqlocks">seqlocks</a><br>
172 <a href="#ReadCopyUpdate">Read-Copy-Update</a><br>
173 <a href="#QuickReference5">Quick Reference</a><br>
174 <br>
175 <a href="#CHAPTER6" class="toc">Chapter 6</a><br>
176 <a href="#AdvancedCharDriverOperations" class="tocr">Advanced Char Driver Operations</a><br>
177 <br>
178 <a href="#Ioctl">ioctl</a><br>
179 <a href="#ChoosingTheIoctlCommands">Choosing the ioctl Commands</a><br>
180 <a href="#TheReturnValue">The Return Value</a><br>
181 <a href="#ThePredefinedCommands">The Predefined Commands</a><br>
182 <a href="#UsingTheIoctlArgument">Using the ioctl Argument</a><br>
183 <a href="#CapabilitiesAndRestrictedOperations">Capabilities and Restricted Operations</a><br>
184 <a href="#TheImplementationOfTheIoctlCommands">The Implementation of the ioctl Commands</a><br>
185 <a href="#DeviceControlWithoutIoctl">Device Control Without ioctl</a><br>
186 <a href="#BlockingIO">Blocking I/O</a><br>
187 <a href="#IntroductionToSleeping">Introduction to Sleeping</a><br>
188 <a href="#SimpleSleeping">Simple Sleeping</a><br>
189 <a href="#BlockingAndNonblockingOperations">Blocking and Nonblocking Operations</a><br>
190 <a href="#ABlockingIOExample">A Blocking I/O Example</a><br>
191 <a href="#AdvancedSleeping">Advanced Sleeping</a><br>
192 <a href="#HowAProcessSleeps">How a process sleeps</a><br>
193 <a href="#ManualSleeps">Manual sleeps</a><br>
194 <a href="#ExclusiveWaits">Exclusive waits</a><br>
195 <a href="#TheDetailsOfWakingUp">The details of waking up</a><br>
196 <a href="#AncientHistorySleepon">Ancient history: sleep_on</a><br>
197 <a href="#TestingTheScullpipeDriver">Testing the Scullpipe Driver</a><br>
198 <a href="#PollAndSelect">poll and select</a><br>
199 <a href="#InteractionWithReadAndWrite">Interaction with read and write</a><br>
200 <a href="#ReadingDataFromTheDevice">Reading data from the device</a><br>
201 <a href="#WritingToTheDevice">Writing to the device</a><br>
202 <a href="#FlushingPendingOutput">Flushing pending output</a><br>
203 <a href="#TheUnderlyingDataStructure">The Underlying Data Structure</a><br>
204 <a href="#AsynchronousNotification">Asynchronous Notification</a><br>
205 <a href="#TheDriversPointOfView">The Driver's Point of View</a><br>
206 <a href="#SeekingADevice">Seeking a Device</a><br>
207 <a href="#TheLlseekImplementation">The llseek Implementation</a><br>
208 <a href="#AccessControlOnADeviceFile">Access Control on a Device File</a><br>
209 <a href="#SingleOpenDevices">Single-Open Devices</a><br>
210 <a href="#RestrictingAccessToASingleUserAtATime">Restricting Access to a Single User at a Time</a><br>
211 <a href="#BlockingOpenAsAnAlternativeToEBUSY">Blocking open as an Alternative to EBUSY</a><br>
212 <a href="#CloningTheDeviceOnOpen">Cloning the Device on open</a><br>
213 <a href="#QuickReference6">Quick Reference</a><br>
214 <br>
215 <a href="#CHAPTER7" class="toc">Chapter 7</a><br>
216 <a href="#TimeDelaysAndDeferredWork" class="tocr">Time, Delays, and Deferred Work</a><br>
217 <br>
218 <a href="#MeasuringTimeLapses">Measuring Time Lapses</a><br>
219 <a href="#UsingTheJiffiesCounter">Using the jiffies Counter</a><br>
220 <a href="#ProcessorSpecificRegisters">Processor-Specific Registers</a><br>
221 <a href="#KnowingTheCurrentTime">Knowing the Current Time</a><br>
222 <a href="#DelayingExecution">Delaying Execution</a><br>
223 <a href="#LongDelays">Long Delays</a><br>
224 <a href="#BusyWaiting">Busy waiting</a><br>
225 <a href="#YieldingTheProcessor">Yielding the processor</a><br>
226 <a href="#Timeouts">Timeouts</a><br>
227 <a href="#ShortDelays">Short Delays</a><br>
228 <a href="#KernelTimers">Kernel Timers</a><br>
229 <a href="#TheTimerAPI">The Timer API</a><br>
230 <a href="#TheImplementationOfKernelTimers">The Implementation of Kernel Timers</a><br>
231 <a href="#Tasklets">Tasklets</a><br>
232 <a href="#Workqueues">Workqueues</a><br>
233 <a href="#TheSharedQueue">The Shared Queue</a><br>
234 <a href="#QuickReference7">Quick Reference</a><br>
235 <a href="#Timekeeping">Timekeeping</a><br>
236 <a href="#Delays">Delays</a><br>
237 <a href="#KernelTimers2">Kernel Timers</a><br>
238 <a href="#Tasklets2">Tasklets</a><br>
239 <a href="#Workqueues2">Workqueues</a><br>
240 <br>
241 <a href="#CHAPTER8" class="toc">Chapter 8</a><br>
242 <a href="#AllocatingMemory" class="tocr">Allocating Memory</a><br>
243 <br>
244 <a href="#TheRealStoryOfKmalloc">The Real Story of kmalloc</a><br>
245 <a href="#TheFlagsArgument">The Flags Argument</a><br>
246 <a href="#MemoryZones">Memory zones</a><br>
247 <a href="#TheSizeArgument">The Size Argument</a><br>
248 <a href="#LookasideCaches">Lookaside Caches</a><br>
249 <a href="#AScullBasedOnTheSlabCachesScullc">A scull Based on the Slab Caches: scullc</a><br>
250 <a href="#MemoryPools">Memory Pools</a><br>
251 <a href="#GetfreepageAndFriends">get_free_page and Friends</a><br>
252 <a href="#AScullUsingWholePagesScullp">A scull Using Whole Pages: scullp</a><br>
253 <a href="#TheAllocpagesInterface">The alloc_pages Interface</a><br>
254 <a href="#VmallocAndFriends">vmalloc and Friends</a><br>
255 <a href="#AScullUsingVirtualAddressesScullv">A scull Using Virtual Addresses: scullv</a><br>
256 <a href="#PerCPUVariables">Per-CPU Variables</a><br>
257 <a href="#ObtainingLargeBuffers">Obtaining Large Buffers</a><br>
258 <a href="#AcquiringADedicatedBufferAtBootTime">Acquiring a Dedicated Buffer at Boot Time</a><br>
259 <a href="#QuickReference8">Quick Reference</a><br>
260 <br>
261 <a href="#CHAPTER9" class="toc">Chapter 9</a><br>
262 <a href="#CommunicatingWithHardware" class="tocr">Communicating with Hardware</a><br>
263 <br>
264 <a href="#IOPortsAndIOMemory">I/O Ports and I/O Memory</a><br>
265 <a href="#IORegistersAndConventionalMemory">I/O Registers and Conventional Memory</a><br>
266 <a href="#UsingIOPorts">Using I/O Ports</a><br>
267 <a href="#IOPortAllocation">I/O Port Allocation</a><br>
268 <a href="#ManipulatingIOPorts">Manipulating I/O ports</a><br>
269 <a href="#IOPortAccessFromUserSpace">I/O Port Access from User Space</a><br>
270 <a href="#StringOperations">String Operations</a><br>
271 <a href="#PausingIO">Pausing I/O</a><br>
272 <a href="#PlatformDependencies">Platform Dependencies</a><br>
273 <a href="#AnIOPortExample">An I/O Port Example</a><br>
274 <a href="#AnOverviewOfTheParallelPort">An Overview of the Parallel Port</a><br>
275 <a href="#ASampleDriver">A Sample Driver</a><br>
276 <a href="#UsingIOMemory">Using I/O Memory</a><br>
277 <a href="#IOMemoryAllocationAndMapping">I/O Memory Allocation and Mapping</a><br>
278 <a href="#AccessingIOMemory">Accessing I/O Memory</a><br>
279 <a href="#PortsAsIOMemory">Ports as I/O Memory</a><br>
280 <a href="#ReusingShortForIOMemory">Reusing short for I/O Memory</a><br>
281 <a href="#ISAMemoryBelow1MB">ISA Memory Below 1 MB</a><br>
282 <a href="#IsareadbAndFriends">isa_readb and Friends</a><br>
283 <a href="#QuickReference9">Quick Reference</a><br>
284 <br>
285 <a href="#CHAPTER10" class="toc">Chapter 10</a><br>
286 <a href="#InterruptHandling" class="tocr">Interrupt Handling</a><br>
287 <br>
288 <a href="#PreparingTheParallelPort">Preparing the Parallel Port</a><br>
289 <a href="#InstallingAnInterruptHandler">Installing an Interrupt Handler</a><br>
290 <a href="#TheProcInterface">The /proc Interface</a><br>
291 <a href="#AutodetectingTheIRQNumber">Auto-Detecting the IRQ Number</a><br>
292 <a href="#KernelassistedProbing">Kernel-assisted probing</a><br>
293 <a href="#DoityourselfProbing">Do-it-yourself probing</a><br>
294 <a href="#FastAndSlowHandlers">Fast and Slow Handlers</a><br>
295 <a href="#TheInternalsOfInterruptHandlingOnTheX86">The internals of interrupt handling on the x86</a><br>
296 <a href="#ImplementingAHandler">Implementing a Handler</a><br>
297 <a href="#HandlerArgumentsAndReturnValue">Handler Arguments and Return Value</a><br>
298 <a href="#EnablingAndDisablingInterrupts">Enabling and Disabling Interrupts</a><br>
299 <a href="#DisablingASingleInterrupt">Disabling a single interrupt</a><br>
300 <a href="#DisablingAllInterrupts">Disabling all interrupts</a><br>
301 <a href="#TopAndBottomHalves">Top and Bottom Halves</a><br>
302 <a href="#Tasklets3">Tasklets</a><br>
303 <a href="#Workqueues3">Workqueues</a><br>
304 <a href="#InterruptSharing">Interrupt Sharing</a><br>
305 <a href="#InstallingASharedHandler">Installing a Shared Handler</a><br>
306 <a href="#RunningTheHandler">Running the Handler</a><br>
307 <a href="#TheProcInterfaceAndSharedInterrupts">The /proc Interface and Shared Interrupts</a><br>
308 <a href="#InterruptDrivenIO">Interrupt-Driven I/O</a><br>
309 <a href="#AWriteBufferingExample">A Write-Buffering Example</a><br>
310 <a href="#QuickReference10">Quick Reference</a><br>
311 </td><td align="right" valign="top" width="50%">
312 <a href="#CHAPTER11" class="toc">Chapter 11</a><br>
313 <a href="#DataTypesInThebrKernel" class="tocr">Data Types in the Kernel</a><br>
314 <br>
315 <a href="#UseOfStandardCTypes">Use of Standard C Types</a><br>
316 <a href="#AssigningAnExplicitSizeToDataItems">Assigning an Explicit Size to Data Items</a><br>
317 <a href="#InterfaceSpecificTypes">Interface-Specific Types</a><br>
318 <a href="#OtherPortabilityIssues">Other Portability Issues</a><br>
319 <a href="#TimeIntervals">Time Intervals</a><br>
320 <a href="#PageSize">Page Size</a><br>
321 <a href="#ByteOrder">Byte Order</a><br>
322 <a href="#DataAlignment">Data Alignment</a><br>
323 <a href="#PointersAndErrorValues">Pointers and Error Values</a><br>
324 <a href="#LinkedLists">Linked Lists</a><br>
325 <a href="#QuickReference11">Quick Reference</a><br>
326 <br>
327 <a href="#CHAPTER12" class="toc">Chapter 12</a><br>
328 <a href="#PCIDrivers" class="tocr">PCI Drivers</a><br>
329 <br>
330 <a href="#ThePCIInterface">The PCI Interface</a><br>
331 <a href="#PCIAddressing">PCI Addressing</a><br>
332 <a href="#BootTime">Boot Time</a><br>
333 <a href="#ConfigurationRegistersAndInitialization">Configuration Registers and Initialization</a><br>
334 <a href="#MODULEDEVICETABLE">MODULE_DEVICE_TABLE</a><br>
335 <a href="#RegisteringAPCIDriver">Registering a PCI Driver</a><br>
336 <a href="#OldStylePCIProbing">Old-Style PCI Probing</a><br>
337 <a href="#EnablingThePCIDevice">Enabling the PCI Device</a><br>
338 <a href="#AccessingTheConfigurationSpace">Accessing the Configuration Space</a><br>
339 <a href="#AccessingTheIOAndMemorySpaces">Accessing the I/O and Memory Spaces</a><br>
340 <a href="#PCIInterrupts">PCI Interrupts</a><br>
341 <a href="#HardwareAbstractions">Hardware Abstractions</a><br>
342 <a href="#ALookBackISA">A Look Back: ISA</a><br>
343 <a href="#HardwareResources">Hardware Resources</a><br>
344 <a href="#ISAProgramming">ISA Programming</a><br>
345 <a href="#ThePlugandPlaySpecification">The Plug-and-Play Specification</a><br>
346 <a href="#PC104AndPC104">PC/104 and PC/104+</a><br>
347 <a href="#OtherPCBuses">Other PC Buses</a><br>
348 <a href="#MCA">MCA</a><br>
349 <a href="#EISA">EISA</a><br>
350 <a href="#VLB">VLB</a><br>
351 <a href="#SBus">SBus</a><br>
352 <a href="#NuBus">NuBus</a><br>
353 <a href="#ExternalBuses">External Buses</a><br>
354 <a href="#QuickReference12">Quick Reference</a><br>
355 <br>
356 <a href="#CHAPTER13" class="toc">Chapter 13</a><br>
357 <a href="#USBDrivers" class="tocr">USB Drivers</a><br>
358 <br>
359 <a href="#USBDeviceBasics">USB Device Basics</a><br>
360 <a href="#Endpoints">Endpoints</a><br>
361 <a href="#Interfaces">Interfaces</a><br>
362 <a href="#Configurations">Configurations</a><br>
363 <a href="#USBAndSysfs">USB and Sysfs</a><br>
364 <a href="#USBUrbs">USB Urbs</a><br>
365 <a href="#StructUrb">struct urb</a><br>
366 <a href="#CreatingAndDestroyingUrbs">Creating and Destroying Urbs</a><br>
367 <a href="#InterruptUrbs">Interrupt urbs</a><br>
368 <a href="#BulkUrbs">Bulk urbs</a><br>
369 <a href="#ControlUrbs">Control urbs</a><br>
370 <a href="#IsochronousUrbs">Isochronous urbs</a><br>
371 <a href="#SubmittingUrbs">Submitting Urbs</a><br>
372 <a href="#CompletingUrbsTheCompletionCallbackHandler">Completing Urbs: The Completion Callback Handler</a><br>
373 <a href="#CancelingUrbs">Canceling Urbs</a><br>
374 <a href="#WritingAUSBDriver">Writing a USB Driver</a><br>
375 <a href="#WhatDevicesDoesTheDriverSupport">What Devices Does the Driver Support?</a><br>
376 <a href="#RegisteringAUSBDriver">Registering a USB Driver</a><br>
377 <a href="#ProbeAndDisconnectInDetail">probe and disconnect in Detail</a><br>
378 <a href="#SubmittingAndControllingAUrb">Submitting and Controlling a Urb</a><br>
379 <a href="#USBTransfersWithoutUrbs">USB Transfers Without Urbs</a><br>
380 <a href="#Usbbulkmsg">usb_bulk_msg</a><br>
381 <a href="#Usbcontrolmsg">usb_control_msg</a><br>
382 <a href="#OtherUSBDataFunctions">Other USB Data Functions</a><br>
383 <a href="#QuickReference13">Quick Reference</a><br>
384 <br>
385 <a href="#CHAPTER14" class="toc">Chapter 14</a><br>
386 <a href="#TheLinuxDeviceModel" class="tocr">The Linux Device Model</a><br>
387 <br>
388 <a href="#KobjectsKsetsAndSubsystems">Kobjects, Ksets, and Subsystems</a><br>
389 <a href="#KobjectBasics">Kobject Basics</a><br>
390 <a href="#EmbeddingKobjects">Embedding kobjects</a><br>
391 <a href="#KobjectInitialization">Kobject initialization</a><br>
392 <a href="#ReferenceCountManipulation">Reference count manipulation</a><br>
393 <a href="#ReleaseFunctionsAndKobjectTypes">Release functions and kobject types</a><br>
394 <a href="#KobjectHierarchiesKsetsAndSubsystems">Kobject Hierarchies, Ksets, and Subsystems</a><br>
395 <a href="#Ksets">Ksets</a><br>
396 <a href="#OperationsOnKsets">Operations on ksets</a><br>
397 <a href="#Subsystems">Subsystems</a><br>
398 <a href="#LowLevelSysfsOperations">Low-Level Sysfs Operations</a><br>
399 <a href="#DefaultAttributes">Default Attributes</a><br>
400 <a href="#NondefaultAttributes">Nondefault Attributes</a><br>
401 <a href="#BinaryAttributes">Binary Attributes</a><br>
402 <a href="#SymbolicLinks">Symbolic Links</a><br>
403 <a href="#HotplugEventGeneration">Hotplug Event Generation</a><br>
404 <a href="#HotplugOperations">Hotplug Operations</a><br>
405 <a href="#BusesDevicesAndDrivers">Buses, Devices, and Drivers</a><br>
406 <a href="#Buses">Buses</a><br>
407 <a href="#BusRegistration">Bus registration</a><br>
408 <a href="#BusMethods">Bus methods</a><br>
409 <a href="#IteratingOverDevicesAndDrivers">Iterating over devices and drivers</a><br>
410 <a href="#BusAttributes">Bus attributes</a><br>
411 <a href="#Devices">Devices</a><br>
412 <a href="#DeviceRegistration">Device registration</a><br>
413 <a href="#DeviceAttributes">Device attributes</a><br>
414 <a href="#DeviceStructureEmbedding">Device structure embedding</a><br>
415 <a href="#DeviceDrivers">Device Drivers</a><br>
416 <a href="#DriverStructureEmbedding">Driver structure embedding</a><br>
417 <a href="#Classes">Classes</a><br>
418 <a href="#TheClasssimpleInterface">The class_simple Interface</a><br>
419 <a href="#TheFullClassInterface">The Full Class Interface</a><br>
420 <a href="#ManagingClasses">Managing classes</a><br>
421 <a href="#ClassDevices">Class devices</a><br>
422 <a href="#ClassInterfaces">Class interfaces</a><br>
423 <a href="#PuttingItAllTogether">Putting It All Together</a><br>
424 <a href="#AddADevice">Add a Device</a><br>
425 <a href="#RemoveADevice">Remove a Device</a><br>
426 <a href="#AddADriver">Add a Driver</a><br>
427 <a href="#RemoveADriver">Remove a Driver</a><br>
428 <a href="#Hotplug">Hotplug</a><br>
429 <a href="#DynamicDevices">Dynamic Devices</a><br>
430 <a href="#TheSbinhotplugUtility">The /sbin/hotplug Utility</a><br>
431 <a href="#IEEE1394FireWire">IEEE1394 (FireWire)</a><br>
432 <a href="#Networking">Networking</a><br>
433 <a href="#PCI">PCI</a><br>
434 <a href="#Input">Input</a><br>
435 <a href="#USB">USB</a><br>
436 <a href="#SCSI">SCSI</a><br>
437 <a href="#LaptopDockingStations">Laptop docking stations</a><br>
438 <a href="#S390AndZSeries">S/390 and zSeries</a><br>
439 <a href="#UsingSbinhotplug">Using /sbin/hotplug</a><br>
440 <a href="#LinuxHotplugScripts">Linux hotplug scripts</a><br>
441 <a href="#Udev">udev</a><br>
442 <a href="#DealingWithFirmware">Dealing with Firmware</a><br>
443 <a href="#TheKernelFirmwareInterface">The Kernel Firmware Interface</a><br>
444 <a href="#HowItWorks">How It Works</a><br>
445 <a href="#QuickReference14">Quick Reference</a><br>
446 <a href="#Kobjects">Kobjects</a><br>
447 <a href="#SysfsOperations">Sysfs Operations</a><br>
448 <a href="#BusesDevicesAndDrivers2">Buses, Devices, and Drivers</a><br>
449 <a href="#Classes2">Classes</a><br>
450 <a href="#Firmware">Firmware</a><br>
451 <br>
452 <a href="#CHAPTER15" class="toc">Chapter 15</a><br>
453 <a href="#MemoryMappingbrandDMA" class="tocr">Memory Mapping and DMA</a><br>
454 <br>
455 <a href="#MemoryManagementInLinux">Memory Management in Linux</a><br>
456 <a href="#AddressTypes">Address Types</a><br>
457 <a href="#PhysicalAddressesAndPages">Physical Addresses and Pages</a><br>
458 <a href="#HighAndLowMemory">High and Low Memory</a><br>
459 <a href="#TheMemoryMapAndStructPage">The Memory Map and Struct Page</a><br>
460 <a href="#PageTables">Page Tables</a><br>
461 <a href="#VirtualMemoryAreas">Virtual Memory Areas</a><br>
462 <a href="#TheVmareastructStructure">The vm_area_struct structure</a><br>
463 <a href="#TheProcessMemoryMap">The Process Memory Map</a><br>
464 <a href="#TheMmapDeviceOperation">The mmap Device Operation</a><br>
465 <a href="#UsingRemappfnrange">Using remap_pfn_range</a><br>
466 <a href="#ASimpleImplementation">A Simple Implementation</a><br>
467 <a href="#AddingVMAOperations">Adding VMA Operations</a><br>
468 <a href="#MappingMemoryWithNopage">Mapping Memory with nopage</a><br>
469 <a href="#RemappingSpecificIORegions">Remapping Specific I/O Regions</a><br>
470 <a href="#RemappingRAM">Remapping RAM</a><br>
471 <a href="#RemappingRAMWithTheNopageMethod">Remapping RAM with the nopage method</a><br>
472 <a href="#RemappingKernelVirtualAddresses">Remapping Kernel Virtual Addresses</a><br>
473 <a href="#PerformingDirectIO">Performing Direct I/O</a><br>
474 <a href="#AsynchronousIO">Asynchronous I/O</a><br>
475 <a href="#AnAsynchronousIOExample">An asynchronous I/O example</a><br>
476 <a href="#DirectMemoryAccess">Direct Memory Access</a><br>
477 <a href="#OverviewOfADMADataTransfer">Overview of a DMA Data Transfer</a><br>
478 <a href="#AllocatingTheDMABuffer">Allocating the DMA Buffer</a><br>
479 <a href="#DoityourselfAllocation">Do-it-yourself allocation</a><br>
480 <a href="#BusAddresses">Bus Addresses</a><br>
481 <a href="#TheGenericDMALayer">The Generic DMA Layer</a><br>
482 <a href="#DealingWithDifficultHardware">Dealing with difficult hardware</a><br>
483 <a href="#DMAMappings">DMA mappings</a><br>
484 <a href="#SettingUpCoherentDMAMappings">Setting up coherent DMA mappings</a><br>
485 <a href="#DMAPools">DMA pools</a><br>
486 <a href="#SettingUpStreamingDMAMappings">Setting up streaming DMA mappings</a><br>
487 <a href="#SinglepageStreamingMappings">Single-page streaming mappings</a><br>
488 <a href="#ScattergatherMappings">Scatter/gather mappings</a><br>
489 <a href="#PCIDoubleaddressCycleMappings">PCI double-address cycle mappings</a><br>
490 <a href="#ASimplePCIDMAExample">A simple PCI DMA example</a><br>
491 <a href="#DMAForISADevices">DMA for ISA Devices</a><br>
492 <a href="#RegisteringDMAUsage">Registering DMA usage</a><br>
493 <a href="#TalkingToTheDMAController">Talking to the DMA controller</a><br>
494 <a href="#QuickReference15">Quick Reference</a><br>
495 <a href="#IntroductoryMaterial">Introductory Material</a><br>
496 <a href="#ImplementingMmap">Implementing mmap</a><br>
497 <a href="#ImplementingDirectIO">Implementing Direct I/O</a><br>
498 <a href="#DirectMemoryAccess2">Direct Memory Access</a><br>
499 <br>
500 <a href="#CHAPTER16" class="toc">Chapter 16</a><br>
501 <a href="#BlockDrivers" class="tocr">Block Drivers</a><br>
502 <br>
503 <a href="#Registration">Registration</a><br>
504 <a href="#BlockDriverRegistration">Block Driver Registration</a><br>
505 <a href="#DiskRegistration">Disk Registration</a><br>
506 <a href="#BlockDeviceOperations">Block device operations</a><br>
507 <a href="#TheGendiskStructure">The gendisk structure</a><br>
508 <a href="#InitializationInSbull">Initialization in sbull</a><br>
509 <a href="#ANoteOnSectorSizes">A Note on Sector Sizes</a><br>
510 <a href="#TheBlockDeviceOperations">The Block Device Operations</a><br>
511 <a href="#TheOpenAndReleaseMethods">The open and release Methods</a><br>
512 <a href="#SupportingRemovableMedia">Supporting Removable Media</a><br>
513 <a href="#TheIoctlMethod2">The ioctl Method</a><br>
514 <a href="#RequestProcessing">Request Processing</a><br>
515 <a href="#IntroductionToTheRequestMethod">Introduction to the request Method</a><br>
516 <a href="#ASimpleRequestMethod">A Simple request Method</a><br>
517 <a href="#RequestQueues">Request Queues</a><br>
518 <a href="#QueueCreationAndDeletion">Queue creation and deletion</a><br>
519 <a href="#QueueingFunctions">Queueing functions</a><br>
520 <a href="#QueueControlFunctions">Queue control functions</a><br>
521 <a href="#TheAnatomyOfARequest">The Anatomy of a Request</a><br>
522 <a href="#TheBioStructure">The bio structure</a><br>
523 <a href="#RequestStructureFields">request structure fields</a><br>
524 <a href="#BarrierRequests">Barrier requests</a><br>
525 <a href="#NonretryableRequests">Nonretryable requests</a><br>
526 <a href="#RequestCompletionFunctions">Request Completion Functions</a><br>
527 <a href="#WorkingWithBios">Working with bios</a><br>
528 <a href="#BlockRequestsAndDMA">Block requests and DMA</a><br>
529 <a href="#DoingWithoutARequestQueue">Doing without a request queue</a><br>
530 <a href="#SomeOtherDetails">Some Other Details</a><br>
531 <a href="#CommandPrePreparation">Command Pre-Preparation</a><br>
532 <a href="#TaggedCommandQueueing">Tagged Command Queueing</a><br>
533 <a href="#QuickReference16">Quick Reference</a><br>
534 <br>
535 <a href="#CHAPTER17" class="toc">Chapter 17</a><br>
536 <a href="#NetworkDrivers" class="tocr">Network Drivers</a><br>
537 <br>
538 <a href="#HowSnullIsDesigned">How snull Is Designed</a><br>
539 <a href="#AssigningIPNumbers">Assigning IP Numbers</a><br>
540 <a href="#ThePhysicalTransportOfPackets">The Physical Transport of Packets</a><br>
541 <a href="#ConnectingToTheKernel">Connecting to the Kernel</a><br>
542 <a href="#DeviceRegistration17">Device Registration</a><br>
543 <a href="#InitializingEachDevice">Initializing Each Device</a><br>
544 <a href="#ModuleUnloading">Module Unloading</a><br>
545 <a href="#TheNetdeviceStructureInDetail">The net_device Structure in Detail</a><br>
546 <a href="#GlobalInformation">Global Information</a><br>
547 <a href="#HardwareInformation">Hardware Information</a><br>
548 <a href="#InterfaceInformation">Interface Information</a><br>
549 <a href="#TheDeviceMethods">The Device Methods</a><br>
550 <a href="#UtilityFields">Utility Fields</a><br>
551 <a href="#OpeningAndClosing">Opening and Closing</a><br>
552 <a href="#PacketTransmission">Packet Transmission</a><br>
553 <a href="#ControllingTransmissionConcurrency">Controlling Transmission Concurrency</a><br>
554 <a href="#TransmissionTimeouts">Transmission Timeouts</a><br>
555 <a href="#ScatterGatherIO">Scatter/Gather I/O</a><br>
556 <a href="#PacketReception">Packet Reception</a><br>
557 <a href="#TheInterruptHandler">The Interrupt Handler</a><br>
558 <a href="#ReceiveInterruptMitigation">Receive Interrupt Mitigation</a><br>
559 <a href="#ChangesInLinkState">Changes in Link State</a><br>
560 <a href="#TheSocketBuffers">The Socket Buffers</a><br>
561 <a href="#TheImportantFields">The Important Fields</a><br>
562 <a href="#FunctionsActingOnSocketBuffers">Functions Acting on Socket Buffers</a><br>
563 <a href="#MACAddressResolution">MAC Address Resolution</a><br>
564 <a href="#UsingARPWithEthernet">Using ARP with Ethernet</a><br>
565 <a href="#OverridingARP">Overriding ARP</a><br>
566 <a href="#NonEthernetHeaders">Non-Ethernet Headers</a><br>
567 <a href="#CustomIoctlCommands">Custom ioctl Commands</a><br>
568 <a href="#StatisticalInformation">Statistical Information</a><br>
569 <a href="#Multicast">Multicast</a><br>
570 <a href="#KernelSupportForMulticasting">Kernel Support for Multicasting</a><br>
571 <a href="#ATypicalImplementation">A Typical Implementation</a><br>
572 <a href="#AFewOtherDetails17">A Few Other Details</a><br>
573 <a href="#MediaIndependentInterfaceSupport">Media Independent Interface Support</a><br>
574 <a href="#EthtoolSupport">Ethtool Support</a><br>
575 <a href="#Netpoll">Netpoll</a><br>
576 <a href="#QuickReference17">Quick Reference</a><br>
577 <br>
578 <a href="#CHAPTER18" class="toc">Chapter 18</a><br>
579 <a href="#TTYDrivers" class="tocr">TTY Drivers</a><br>
580 <br>
581 <a href="#ASmallTTYDriver">A Small TTY Driver</a><br>
582 <a href="#StructTermios">struct termios</a><br>
583 <a href="#TtydriverFunctionPointers">tty_driver Function Pointers</a><br>
584 <a href="#OpenAndClose">open and close</a><br>
585 <a href="#FlowOfData">Flow of Data</a><br>
586 <a href="#OtherBufferingFunctions">Other Buffering Functions</a><br>
587 <a href="#NoReadFunction">No read Function?</a><br>
588 <a href="#TTYLineSettings">TTY Line Settings</a><br>
589 <a href="#Settermios">set_termios</a><br>
590 <a href="#TiocmgetAndTiocmset">tiocmget and tiocmset</a><br>
591 <a href="#Ioctls">ioctls</a><br>
592 <a href="#ProcAndSysfsHandlingOfTTYDevices">proc and sysfs Handling of TTY Devices</a><br>
593 <a href="#TheTtydriverStructureInDetail">The tty_driver Structure in Detail</a><br>
594 <a href="#TheTtyoperationsStructureInDetail">The tty_operations Structure in Detail</a><br>
595 <a href="#TheTtystructStructureInDetail">The tty_struct Structure in Detail</a><br>
596 <a href="#QuickReference18">Quick Reference</a><br>
597 </td></tr></table>
598 <br>
599 <div style="text-align:center;margin-left:.4in; margin-right:.4in; border:1px solid blue; padding:6px 12px;">To go directly to, say, page 467, add #467 to the URL, and press enter.</div>
600 <br>
601 <A name="xi"></a><font color="blue">PAGE xi</font><br>
602 <br>
603 <a name="Preface"></a><font color="red"><b>Preface</b></font><br>
604 <br>
605 This is, on the surface, a book about writing device drivers for the Linux system.
606 That is a worthy goal, of course; the flow of new hardware products is not likely to
607 slow down anytime soon, and somebody is going to have to make all those new gadgets
608 work with Linux. But this book is also about how the Linux kernel works and
609 how to adapt its workings to your needs or interests. Linux is an open system; with
610 this book, we hope, it is more open and accessible to a larger community of developers.<br>
611 <br>
612 This is the third edition of <i>Linux Device Drivers</i>. The kernel has changed greatly
613 since this book was first published, and we have tried to evolve the text to match.
614 This edition covers the 2.6.10 kernel as completely as we are able. We have, this time
615 around, elected to omit the discussion of backward compatibility with previous kernel
616 versions. The changes from 2.4 are simply too large, and the 2.4 interface
617 remains well documented in the (freely available) second edition.<br>
618 <br>
619 This edition contains quite a bit of new material relevant to the 2.6 kernel. The discussion
620 of locking and concurrency has been expanded and moved into its own
621 chapter. The Linux device model, which is new in 2.6, is covered in detail. There are
622 new chapters on the USB bus and the serial driver subsystem; the chapter on PCI has
623 also been enhanced. While the organization of the rest of the book resembles that of
624 the earlier editions, every chapter has been thoroughly updated.<br>
625 <br>
626 We hope you enjoy reading this book as much as we have enjoyed writing it.<br>
627 <br>
628 <a name="JonsIntroduction"></a><font color="red"><b>Jon's Introduction</b></font><br>
629 <br>
630 The publication of this edition coincides with my twelth year of working with Linux
631 and, shockingly, my twenty-fifth year in the computing field. Computing seemed like
632 a fast-moving field back in 1980, but things have sped up a lot since then. Keeping
633 <i>Linux Device Drivers </i>up to date is increasingly a challenge; the Linux kernel hackers
634 continue to improve their code, and they have little patience for documentation that
635 fails to keep up.<br>
636 <br>
637 <A name="xii"></a><font color="blue">PAGE xii</font><br>
638 <br>
639 Linux continues to succeed in the market and, more importantly, in the hearts and
640 minds of developers worldwide. The success of Linux is clearly a testament to its
641 technical quality and to the numerous benefits of free software in general. But the
642 true key to its success, in my opinion, lies in the fact that it has brought the fun back
643 to computing. With Linux, anybody can get their hands into the system and play in a
644 sandbox where contributions from any direction are welcome, but where technical
645 excellence is valued above all else. Linux not only provides us with a top-quality
646 operating system; it gives us the opportunity to be part of its future development and
647 to have fun while we're at it.<br>
648 <br>
649 In my 25 years in the field, I have had many interesting opportunities, from programming
650 the first Cray computers (in Fortran, on punch cards) to seeing the minicomputer
651 and Unix workstation waves, through to the current, microprocessor-dominated
652 era. Never, though, have I seen the field more full of life, opportunity,
653 and fun. Never have we had such control over our own tools and their evolution.
654 Linux, and free software in general, is clearly the driving force behind those changes.<br>
655 <br>
656 My hope is that this edition helps to bring that fun and opportunity to a new set of
657 Linux developers. Whether your interests are in the kernel or in user space, I hope
658 you find this book to be a useful and interesting guide to just how the kernel works
659 with the hardware. I hope it helps and inspires you to fire up your editor and to
660 make our shared, free operating system even better. Linux has come a long way, but
661 it is also just beginning; it will be more than interesting to watch--and participate
662 in--what happens from here.<br>
663 <br>
664 <a name="AlessandrosIntroduction"></a><font color="red"><b>Alessandro's Introduction</b></font><br>
665 <br>
666 I've always enjoyed computers because they can talk to external hardware. So, after
667 soldering my devices for the Apple II and the ZX Spectrum, backed with the Unix
668 and free software expertise the university gave me, I could escape the DOS trap by
669 installing GNU/Linux on a fresh new 386 and by turning on the soldering iron once
670 again.<br>
671 <br>
672 Back then, the community was a small one, and there wasn't much documentation
673 about writing drivers around, so I started writing for Linux Journal. That's how
674 things started: when I later discovered I didn't like writing papers, I left the univeristy
675 and found myself with an O'Reilly contract in my hands.<br>
676 <br>
677 That was in 1996. Ages ago.<br>
678 <br>
679 The computing world is different now: free software looks like a viable solution,
680 both technically and politically, but there's a lot of work to do in both realms. I hope
681 this book furthers two aims: spreading technical knowledge and raising awareness
682 about the need to spread knowledge. That's why, after the first edition proved interesting
683 to the public, the two authors of the second edition switched to a free license,<br>
684 <br>
685 <A name="xiii"></a><font color="blue">PAGE xiii</font><br>
686 <br>
687 supported by our editor and our publisher. I'm betting this is the right approach to
688 information, and it's great to team up with other people sharing this vision.<br>
689 <br>
690 I'm excited by what I witness in the embedded arena, and I hope this text helps by
691 doing more; but ideas are moving fast these days, and it's already time to plan for the
692 fourth edition, and look for a fourth author to help.<br>
693 <br>
694 <a name="GregsIntroduction"></a><font color="red"><b>Greg's Introduction</b></font><br>
695 <br>
696 It seems like a long time ago that I picked up the first edition of this <i>Linux Device
697 Drivers </i>book in order to figure out how to write a real Linux driver. That first edition
698 was a great guide to helping me understand the internals of this operating system
699 that I had already been using for a number of years but whose kernel had never
700 taken the time to look into. With the knowledge gained from that book, and by reading
701 other programmers' code already present in the kernel, my first horribly buggy,
702 broken, and very SMP-unsafe driver was accepted by the kernel community into the
703 main kernel tree. Despite receiving my first bug report five minutes later, I was
704 hooked on wanting to do as much as I could to make this operating system the best
705 it could possibly be.<br>
706 <br>
707 I am honored that I've had the ability to contribute to this book. I hope that it
708 enables others to learn the details about the kernel, discover that driver development
709 is not a scary or forbidding place, and possibly encourage others to join in and help
710 in the collective effort of making this operating system work on every computing
711 platform with every type of device available. The development procedure is fun, the
712 community is rewarding, and everyone benefits from the effort involved.<br>
713 <br>
714 Now it's back to making this edition obsolete by fixing current bugs, changing APIs
715 to work better and be simpler to understand for everyone, and adding new features.
716 Come along; we can always use the help.<br>
717 <br>
718 <a name="AudienceForThisBook"></a><font color="red"><b>Audience for This Book</b></font><br>
719 <br>
720 This book should be an interesting source of information both for people who want
721 to experiment with their computer and for technical programmers who face the need
722 to deal with the inner levels of a Linux box. Note that "a Linux box" is a wider concept
723 than "a PC running Linux," as many platforms are supported by our operating
724 system, and kernel programming is by no means bound to a specific platform. We
725 hope this book is useful as a starting point for people who want to become kernel
726 hackers but don't know where to start.<br>
727 <br>
728 On the technical side, this text should offer a hands-on approach to understanding
729 the kernel internals and some of the design choices made by the Linux developers.
730 Although the main, official target of the book is teaching how to write device drivers,
731 the material should give an interesting overview of the kernel implementation as well.<br>
732 <br>
733 <A name="xiv"></a><font color="blue">PAGE xiv</font><br>
734 <br>
735 Although real hackers can find all the necessary information in the official kernel
736 sources, usually a written text can be helpful in developing programming skills. The
737 text you are approaching is the result of hours of patient grepping through the kernel
738 sources, and we hope the final result is worth the effort it took.<br>
739 <br>
740 The Linux enthusiast should find in this book enough food for her mind to start
741 playing with the code base and should be able to join the group of developers that is
742 continuously working on new capabilities and performance enhancements. This
743 book does not cover the Linux kernel in its entirety, of course, but Linux device
744 driver authors need to know how to work with many of the kernel's subsystems.
745 Therefore, it makes a good introduction to kernel programming in general. Linux is
746 still a work in progress, and there's always a place for new programmers to jump into
747 the game.<br>
748 <br>
749 If, on the other hand, you are just trying to write a device driver for your own device,
750 and you don't want to muck with the kernel internals, the text should be modularized
751 enough to fit your needs as well. If you don't want to go deep into the details,
752 you can just skip the most technical sections, and stick to the standard API used by
753 device drivers to seamlessly integrate with the rest of the kernel.<br>
754 <br>
755 <a name="OrganizationOfTheMaterial"></a><font color="red"><b>Organization of the Material</b></font><br>
756 <br>
757 The book introduces its topics in ascending order of complexity and is divided into
758 two parts. The first part (Chapters 1-11) begins with the proper setup of kernel modules
759 and goes on to describe the various aspects of programming that you'll need in
760 order to write a full-featured driver for a char-oriented device. Every chapter covers a
761 distinct problem and includes a quick summary at the end, which can be used as a
762 reference during actual development.<br>
763 <br>
764 Throughout the first part of the book, the organization of the material moves roughly
765 from the software-oriented concepts to the hardware-related ones. This organization
766 is meant to allow you to test the software on your own computer as far as possible
767 without the need to plug external hardware into the machine. Every chapter includes
768 source code and points to sample drivers that you can run on any Linux computer.
769 In Chapters 9 and 10, however, we ask you to connect an inch of wire to the parallel
770 port in order to test out hardware handling, but this requirement should be manageable
771 by everyone.<br>
772 <br>
773 The second half of the book (Chapters 12-18) describes block drivers and network
774 interfaces and goes deeper into more advanced topics, such as working with the virtual
775 memory subsystem and with the PCI and USB buses. Many driver authors do
776 not need all of this material, but we encourage you to go on reading anyway. Much
777 of the material found there is interesting as a view into how the Linux kernel works,
778 even if you do not need it for a specific project.<br>
779 <br>
780 <A name="xv"></a><font color="blue">PAGE xv</font><br>
781 <br>
782 <a name="BackgroundInformation"></a><font color="red"><b>Background Information</b></font><br>
783 <br>
784 In order to be able to use this book, you need to be confident with C programming.
785 Some Unix expertise is needed as well, as we often refer to Unix semantics about system
786 calls, commands, and pipelines.<br>
787 <br>
788 At the hardware level, no previous expertise is required to understand the material in
789 this book, as long as the general concepts are clear in advance. The text isn't based
790 on specific PC hardware, and we provide all the needed information when we do
791 refer to specific hardware.<br>
792 <br>
793 Several free software tools are needed to build the kernel, and you often need specific
794 versions of these tools. Those that are too old can lack needed features, while
795 those that are too new can occasionally generate broken kernels. Usually, the tools
796 provided with any current distribution work just fine. Tool version requirements
797 vary from one kernel to the next; consult <i>Documentation/Changes </i>in the source tree
798 of the kernel you are using for exact requirements.<br>
799 <br>
800 <a name="OnlineVersionAndLicense"></a><font color="red"><b>Online Version and License</b></font><br>
801 <br>
802 <a href="http://www.oreilly.com/catalog/linuxdrive3" target="_blank"><i>http://www.oreilly.com/catalog/linuxdrive3</i></a><br>
803 <br>
804 The authors have chosen to make this book freely available under the Creative Commons
805 "Attribution-ShareAlike" license, Version 2.0:<br>
806 <br>
807 <div class="warn">
808 <b>Attribution-ShareAlike 2.0 <br>
809 <br>
810 You are free:</b><br>
811 <ul>
812 <li>to copy, distribute, display, and perform the work
813 <li>to make derivative works
814 <li>to make commercial use of the work
815 </ul>
816 <b>Under the following conditions:<br>
817 <br>
818 Attribution.</b> You must attribute the work in the manner specified by the author or licensor.<br>
819 <br>
820 <b>Share Alike.</b> If you alter, transform, or build upon this work, you may distribute the resulting work only under a license identical to this one.<br>
821 <ul>
822 <li>For any reuse or distribution, you must make clear to others the license terms of this work.
823 <li>Any of these conditions can be waived if you get permission from the copyright holder.
824 </ul>
825 Your fair use and other rights are in no way affected by the above.<br>
826 <br>
827 This is a human-readable summary of the Legal Code (<a href="http://creativecommons.org/licenses/by-sa/2.0/legalcode" target="_blank">the full license</a>).<br>
828 </div>
829 <br>
830 <a name="ConventionsUsedInThisBook"></a><font color="red"><b>Conventions Used in This Book</b></font><br>
831 <br>
832 The following is a list of the typographical conventions used in this book:<br>
833 <br>
834 <i>Italic</i><br>
835 <br>
836 Used for file and directory names, program and command names, command-line
837 options, URLs, and new terms<br>
838 <br>
839 <font class="fixd">Constant Width</font><br>
840 <br>
841 Used in examples to show the contents of files or the output from commands,
842 and in the text to indicate words that appear in C code or other literal strings<br>
843 <br>
844 <font class="fixd"><i>Constant Width Italic</i></font><br>
845 <br>
846 Used to indicate text within commands that the user replaces with an actual
847 value<br>
848 <br>
849 <font class="fixd"><b>Constant Width Bold</b></font><br>
850 <br>
851 Used in examples to show commands or other text that should be typed literally by the user<br>
852 <br>
853 <A name="xvi"></a><font color="blue">PAGE xvi</font><br>
854 <br>
855 Pay special attention to notes set apart from the text as following:<br>
856 <br>
857 <div class="tip">This is a tip. It contains useful supplementary information about the topic at hand.</div>
858 <br>
859 <div class="warn">This is a warning. It helps you solve and avoid annoying problems.</div>
860 <br>
861 <a name="UsingCodeExamplesbr"></a><font color="red"><b>Using Code Examples</b></font><br>
862 <br>
863 This book is here to help you get your job done. In general, you may use the code in
864 this book in your programs and documentation. The code samples are covered by a dual BSD/GPL license.<br>
865 <br>
866 We appreciate, but do not require, attribution. An attribution usually includes the
867 title, author, publisher, and ISBN. For example: "<i>Linux Device Drivers</i>, Third Edition,
868 by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman. Copyright
869 2005 O'Reilly Media, Inc., 0-596-00590-3."<br>
870 <br>
871 <a name="WedLikeToHearFromYou"></a><font color="red"><b>We'd Like to Hear from You</b></font><br>
872 <br>
873 Please address comments and questions concerning this book to the publisher:<br>
874 <br>
875 <div class="bq">O'Reilly Media, Inc.<br>
876 1005 Gravenstein Highway<br>
877 North Sebastopol, CA 95472<br>
878 (800) 998-9938 (in the United States or Canada)<br>
879 (707) 829-0515 (international or local)<br>
880 (707) 829-0104 (fax)</div>
881 <br>
882 We have a web page for this book, where we list errata, examples, and any additional
883 information. You can access this page at:<br>
884 <br>
885 <a href="http://www.oreilly.com/catalog/linuxdrive3" target="_blank"><i>http://www.oreilly.com/catalog/linuxdrive3</i></a><br>
886 <br>
887 To comment or ask technical questions about this book, send email to:<br>
888 <br>
889 <a href="mailto:bookquestions@oreilly.com" target="_blank"><i>bookquestions@oreilly.com</i></a><br>
890 <br>
891 For more information about our books, conferences, Resource Centers, and the
892 O'Reilly Network, see our web site at:<br>
893 <br>
894 <a href="http://www.oreilly.com" target="_blank"><i>http://www.oreilly.com</i></a><br>
895 <br>
896 <a name="SafariEnabled"></a><font color="red"><b>Safari Enabled</b></font><br>
897 <br>
898 When you see a Safari® Enabled icon on the cover of your favorite technology
899 book, that means the book is available online through the
900 O'Reilly Network Safari Bookshelf.<br>
901 <br>
902 Safari offers a solution that's better than e-books. It's a virtual library that lets you
903 easily search thousands of top tech books, cut and paste code samples, download
904 chapters, and find quick answers when you need the most accurate, current information.
905 Try it for free at <a href="http://safari.oreilly.com" target="_blank"><i>http://safari.oreilly.com</i></a>.<br>
906 <br>
907 <a name="Acknowledgments"></a><font color="red"><b>Acknowledgments</b></font><br>
908 <br>
909 This book, of course, was not written in a vacuum; we would like to thank the many
910 people who have helped to make it possible.<br>
911 <br>
912 Thanks to our editor, Andy Oram; this book is a vastly better product as a result of
913 his efforts. And obviously we owe a lot to the smart people who have laid the philosophical
914 and practical foundations of the current free software renaissance.<br>
915 <br>
916 The first edition was technically reviewed by Alan Cox, Greg Hankins, Hans Lermen,
917 Heiko Eissfeldt, and Miguel de Icaza (in alphabetic order by first name). The
918 technical reviewers for the second edition were Allan B. Cruse, Christian Morgner,
919 Jake Edge, Jeff Garzik, Jens Axboe, Jerry Cooperstein, Jerome Peter Lynch, Michael
920 Kerrisk, Paul Kinzelman, and Raph Levien. Reviewers for the third edition were
921 Allan B. Cruse, Christian Morgner, James Bottomley, Jerry Cooperstein, Patrick
922 Mochel, Paul Kinzelman, and Robert Love. Together, these people have put a vast
923 amount of effort into finding problems and pointing out possible improvements to
924 our writing.<br>
925 <br>
926 Last but certainly not least, we thank the Linux developers for their relentless work.
927 This includes both the kernel programmers and the user-space people, who often get
928 forgotten. In this book, we chose never to call them by name in order to avoid being
929 unfair to someone we might forget. We sometimes made an exception to this rule
930 and called Linus by name; we hope he doesn't mind.<br>
931 <br>
932 <a name="Jon"></a><font color="red"><b>Jon</b></font><br>
933 <br>
934 I must begin by thanking my wife Laura and my children Michele and Giulia for filling
935 my life with joy and patiently putting up with my distraction while working on
936 this edition. The subscribers of LWN.net have, through their generosity, enabled
937 much of this work to happen. The Linux kernel developers have done me a great service
938 by letting me be a part of their community, answering my questions, and setting
939 me straight when I got confused. Thanks are due to readers of the second edition of
940 this book whose comments, offered at Linux gatherings over much of the world,<br>
941 <br>
942 <A name="xviii"></a><font color="blue">PAGE xviii</font><br>
943 <br>
944 have been gratifying and inspiring. And I would especially like to thank Alessandro
945 Rubini for starting this whole exercise with the first edition (and staying with it
946 through the current edition); and Greg Kroah-Hartman, who has brought his considerable
947 skills to bear on several chapters, with great results.<br>
948 <br>
949 <a name="Alessandro"></a><font color="red"><b>Alessandro</b></font><br>
950 <br>
951 I would like to thank the people that made this work possible. First of all, the incredible
952 patience of Federica, who went as far as letting me review the first edition during
953 our honeymoon, with a laptop in the tent. I want to thank Giorgio and Giulia,
954 who have been involved in later editions of the book and happily accepted to be sons
955 of "a gnu" who often works late in the night. I owe a lot to all the free-software
956 authors who actually taught me how to program by making their work available for
957 anyone to study. But for this edition, I'm mostly grateful to Jon and Greg, who have
958 been great mates in this work; it couldn't have existed without each and both of
959 them, as the code base is bigger and tougher, while my time is a scarcer resource,
960 always contended for by clients, free software issues, and expired deadlines. Jon has
961 been a great leader for this edition; both have been very productive and technically
962 invaluable in supplementing my small-scale and embedded view toward programming
963 with their expertise about SMP and number crunchers.<br>
964 <br>
965 <a name="Greg"></a><font color="red"><b>Greg</b></font><br>
966 <br>
967 I would like to thank my wife Shannon and my children Madeline and Griffin for
968 their understanding and patience while I took the time to work on this book. If it
969 were not for their support of my original Linux development efforts, I would not be
970 able to do this book at all. Thanks also to Alessandro and Jon for offering to let me
971 work on this book; I am honored that they let me participate in it. Much gratitude is
972 given to all of the Linux kernel programmers, who were unselfish enough to write
973 code in the public view, so that I and others could learn so much from just reading it.
974 Also, for everyone who has ever sent me bug reports, critiqued my code, and flamed
975 me for doing stupid things, you have all taught me so much about how to be a better
976 programmer and, throughout it all, made me feel very welcome to be part of this
977 community. Thank you.<br>
978 <br>
979 <A name="1"></a><font color="blue">PAGE 1</font><br>
980 <br>
981 <a name="CHAPTER1"></a><font color="red"><b>CHAPTER 1</b></font><br>
982 <br>
983 <a name="AnIntroductionToDeviceDrivers"></a><font color="#7519FF" size="+1"><b>An Introduction to Device Drivers</b></font><br>
984 <br>
985 One of the many advantages of free operating systems, as typified by Linux, is that
986 their internals are open for all to view. The operating system, once a dark and mysterious
987 area whose code was restricted to a small number of programmers, can now be
988 readily examined, understood, and modified by anybody with the requisite skills.
989 Linux has helped to democratize operating systems. The Linux kernel remains a
990 large and complex body of code, however, and would-be kernel hackers need an
991 entry point where they can approach the code without being overwhelmed by complexity.
992 Often, device drivers provide that gateway.<br>
993 <br>
994 Device drivers take on a special role in the Linux kernel. They are distinct "black
995 boxes" that make a particular piece of hardware respond to a well-defined internal
996 programming interface; they hide completely the details of how the device works.
997 User activities are performed by means of a set of standardized calls that are independent
998 of the specific driver; mapping those calls to device-specific operations that act
999 on real hardware is then the role of the device driver. This programming interface is
1000 such that drivers can be built separately from the rest of the kernel and "plugged in"
1001 at runtime when needed. This modularity makes Linux drivers easy to write, to the
1002 point that there are now hundreds of them available.<br>
1003 <br>
1004 There are a number of reasons to be interested in the writing of Linux device drivers.
1005 The rate at which new hardware becomes available (and obsolete!) alone guarantees
1006 that driver writers will be busy for the foreseeable future. Individuals may need to
1007 know about drivers in order to gain access to a particular device that is of interest to
1008 them. Hardware vendors, by making a Linux driver available for their products, can
1009 add the large and growing Linux user base to their potential markets. And the open
1010 source nature of the Linux system means that if the driver writer wishes, the source
1011 to a driver can be quickly disseminated to millions of users.<br>
1012 <br>
1013 This book teaches you how to write your own drivers and how to hack around in
1014 related parts of the kernel. We have taken a device-independent approach; the programming
1015 techniques and interfaces are presented, whenever possible, without being
1016 tied to any specific device. Each driver is different; as a driver writer, you need to<br>
1017 <br>
1018 <A name="2"></a><font color="blue">PAGE 2</font><br>
1019 <br>
1020 understand your specific device well. But most of the principles and basic techniques
1021 are the same for all drivers. This book cannot teach you about your device,
1022 but it gives you a handle on the background you need to make your device work.<br>
1023 <br>
1024 As you learn to write drivers, you find out a lot about the Linux kernel in general;
1025 this may help you understand how your machine works and why things aren't
1026 always as fast as you expect or don't do quite what you want. We introduce new
1027 ideas gradually, starting off with very simple drivers and building on them; every new
1028 concept is accompanied by sample code that doesn't need special hardware to be
1029 tested.<br>
1030 <br>
1031 This chapter doesn't actually get into writing code. However, we introduce some
1032 background concepts about the Linux kernel that you'll be glad you know later,
1033 when we do launch into programming.<br>
1034 <br>
1035 <a name="TheRoleOfTheDeviceDriver"></a><font color="red"><b>The Role of the Device Driver</b></font><br>
1036 <br>
1037 As a programmer, you are able to make your own choices about your driver, and
1038 choose an acceptable trade-off between the programming time required and the flexibility
1039 of the result. Though it may appear strange to say that a driver is "flexible," we
1040 like this word because it emphasizes that the role of a device driver is providing
1041 <i>mechanism</i>, not <i>policy</i>.<br>
1042 <br>
1043 The distinction between mechanism and policy is one of the best ideas behind the
1044 Unix design. Most programming problems can indeed be split into two parts: "what
1045 capabilities are to be provided" (the mechanism) and "how those capabilities can be
1046 used" (the policy). If the two issues are addressed by different parts of the program,
1047 or even by different programs altogether, the software package is much easier to
1048 develop and to adapt to particular needs.<br>
1049 <br>
1050 For example, Unix management of the graphic display is split between the X server,
1051 which knows the hardware and offers a unified interface to user programs, and the
1052 window and session managers, which implement a particular policy without knowing
1053 anything about the hardware. People can use the same window manager on different
1054 hardware, and different users can run different configurations on the same
1055 workstation. Even completely different desktop environments, such as KDE and
1056 GNOME, can coexist on the same system. Another example is the layered structure
1057 of TCP/IP networking: the operating system offers the socket abstraction, which
1058 implements no policy regarding the data to be transferred, while different servers are
1059 in charge of the services (and their associated policies). Moreover, a server like <i>ftpd
1060 </i>provides the file transfer mechanism, while users can use whatever client they prefer;
1061 both command-line and graphic clients exist, and anyone can write a new user interface
1062 to transfer files.<br>
1063 <br>
1064 Where drivers are concerned, the same separation of mechanism and policy applies.
1065 The floppy driver is policy free--its role is only to show the diskette as a continuous<br>
1066 <br>
1067 <A name="3"></a><font color="blue">PAGE 3</font><br>
1068 <br>
1069 array of data blocks. Higher levels of the system provide policies, such as who may
1070 access the floppy drive, whether the drive is accessed directly or via a filesystem, and
1071 whether users may mount filesystems on the drive. Since different environments usually
1072 need to use hardware in different ways, it's important to be as policy free as
1073 possible.<br>
1074 <br>
1075 When writing drivers, a programmer should pay particular attention to this fundamental
1076 concept: write kernel code to access the hardware, but don't force particular
1077 policies on the user, since different users have different needs. The driver should deal
1078 with making the hardware available, leaving all the issues about <i>how </i>to use the hardware
1079 to the applications. A driver, then, is flexible if it offers access to the hardware
1080 capabilities without adding constraints. Sometimes, however, some policy decisions
1081 must be made. For example, a digital I/O driver may only offer byte-wide access to
1082 the hardware in order to avoid the extra code needed to handle individual bits.<br>
1083 <br>
1084 You can also look at your driver from a different perspective: it is a software layer
1085 that lies between the applications and the actual device. This privileged role of the
1086 driver allows the driver programmer to choose exactly how the device should appear:
1087 different drivers can offer different capabilities, even for the same device. The actual
1088 driver design should be a balance between many different considerations. For
1089 instance, a single device may be used concurrently by different programs, and the
1090 driver programmer has complete freedom to determine how to handle concurrency.
1091 You could implement memory mapping on the device independently of its hardware
1092 capabilities, or you could provide a user library to help application programmers
1093 implement new policies on top of the available primitives, and so forth. One major
1094 consideration is the trade-off between the desire to present the user with as many
1095 options as possible and the time you have to write the driver, as well as the need to
1096 keep things simple so that errors don't creep in.<br>
1097 <br>
1098 Policy-free drivers have a number of typical characteristics. These include support for
1099 both synchronous and asynchronous operation, the ability to be opened multiple
1100 times, the ability to exploit the full capabilities of the hardware, and the lack of software
1101 layers to "simplify things" or provide policy-related operations. Drivers of this
1102 sort not only work better for their end users, but also turn out to be easier to write
1103 and maintain as well. Being policy-free is actually a common target for software
1104 designers.<br>
1105 <br>
1106 Many device drivers, indeed, are released together with user programs to help with
1107 configuration and access to the target device. Those programs can range from simple
1108 utilities to complete graphical applications. Examples include the <i>tunelp </i>program,
1109 which adjusts how the parallel port printer driver operates, and the graphical <i>cardctl
1110 </i>utility that is part of the PCMCIA driver package. Often a client library is provided as
1111 well, which provides capabilities that do not need to be implemented as part of the
1112 driver itself.<br>
1113 <br>
1114 <A name="4"></a><font color="blue">PAGE 4</font><br>
1115 <br>
1116 The scope of this book is the kernel, so we try not to deal with policy issues or with
1117 application programs or support libraries. Sometimes we talk about different policies
1118 and how to support them, but we won't go into much detail about programs
1119 using the device or the policies they enforce. You should understand, however, that
1120 user programs are an integral part of a software package and that even policy-free
1121 packages are distributed with configuration files that apply a default behavior to the
1122 underlying mechanisms.<br>
1123 <br>
1124 <a name="SplittingTheKernel"></a><font color="red"><b>Splitting the Kernel</b></font><br>
1125 <br>
1126 In a Unix system, several concurrent <i>processes </i>attend to different tasks. Each process
1127 asks for system resources, be it computing power, memory, network connectivity, or
1128 some other resource. The <i>kernel </i>is the big chunk of executable code in charge of handling
1129 all such requests. Although the distinction between the different kernel tasks
1130 isn't always clearly marked, the kernel's role can be split (as shown in Figure 1-1)
1131 into the following parts:<br>
1132 <br>
1133 <i>Process management</i><br>
1134 <br>
1135 The kernel is in charge of creating and destroying processes and handling their
1136 connection to the outside world (input and output). Communication among different
1137 processes (through signals, pipes, or interprocess communication primitives)
1138 is basic to the overall system functionality and is also handled by the
1139 kernel. In addition, the scheduler, which controls how processes share the CPU,
1140 is part of process management. More generally, the kernel's process management
1141 activity implements the abstraction of several processes on top of a single
1142 CPU or a few of them.<br>
1143 <br>
1144 <i>Memory management</i><br>
1145 <br>
1146 The computer's memory is a major resource, and the policy used to deal with it
1147 is a critical one for system performance. The kernel builds up a virtual addressing
1148 space for any and all processes on top of the limited available resources. The
1149 different parts of the kernel interact with the memory-management subsystem
1150 through a set of function calls, ranging from the simple <i>malloc</i>/<i>free </i>pair to much
1151 more complex functionalities.<br>
1152 <br>
1153 <i>Filesystems</i><br>
1154 <br>
1155 Unix is heavily based on the filesystem concept; almost everything in Unix can
1156 be treated as a file. The kernel builds a structured filesystem on top of unstructured
1157 hardware, and the resulting file abstraction is heavily used throughout the
1158 whole system. In addition, Linux supports multiple filesystem types, that is, different
1159 ways of organizing data on the physical medium. For example, disks may
1160 be formatted with the Linux-standard ext3 filesystem, the commonly used FAT
1161 filesystem or several others.<br>
1162 <br>
1163 <A name="5"></a><font color="blue">PAGE 5</font><br>
1164 <br>
1165 <i>Device control</i><br>
1166 <br>
1167 Almost every system operation eventually maps to a physical device. With the
1168 exception of the processor, memory, and a very few other entities, any and all
1169 device control operations are performed by code that is specific to the device
1170 being addressed. That code is called a <i>device driver</i>. The kernel must have
1171 embedded in it a device driver for every peripheral present on a system, from the
1172 hard drive to the keyboard and the tape drive. This aspect of the kernel's functions
1173 is our primary interest in this book.<br>
1174 <br>
1175 <i>Networking</i><br>
1176 <br>
1177 Networking must be managed by the operating system, because most network
1178 operations are not specific to a process: incoming packets are asynchronous
1179 events. The packets must be collected, identified, and dispatched before a process
1180 takes care of them. The system is in charge of delivering data packets across
1181 program and network interfaces, and it must control the execution of programs
1182 according to their network activity. Additionally, all the routing and address resolution
1183 issues are implemented within the kernel.<br>
1184 <br>
1185 <a name="LoadableModules"></a><font color="red"><b>Loadable Modules</b></font><br>
1186 <br>
1187 One of the good features of Linux is the ability to extend at runtime the set of features
1188 offered by the kernel. This means that you can add functionality to the kernel
1189 (and remove functionality as well) while the system is up and running.<br>
1190 <br>
1191 Each piece of code that can be added to the kernel at runtime is called a <i>module</i>. The
1192 Linux kernel offers support for quite a few different types (or classes) of modules,
1193 including, but not limited to, device drivers. Each module is made up of object code
1194 (not linked into a complete executable) that can be dynamically linked to the running
1195 kernel by the <i>insmod</i> program and can be unlinked by the <i>rmmod</i> program.<br>
1196 <br>
1197 Figure 1-1 identifies different classes of modules in charge of specific tasks--a module
1198 is said to belong to a specific class according to the functionality it offers. The
1199 placement of modules in Figure 1-1 covers the most important classes, but is far from
1200 complete because more and more functionality in Linux is being modularized.<br>
1201 <br>
1202 <a name="ClassesOfDevicesAndModules"></a><font color="red"><b>Classes of Devices and Modules</b></font><br>
1203 <br>
1204 The Linux way of looking at devices distinguishes between three fundamental device
1205 types. Each module usually implements one of these types, and thus is classifiable as a
1206 <i>char module</i>, a <i>block module</i>, or a <i>network module</i>. This division of modules into different
1207 types, or classes, is not a rigid one; the programmer can choose to build huge
1208 modules implementing different drivers in a single chunk of code. Good programmers,
1209 nonetheless, usually create a different module for each new functionality they
1210 implement, because decomposition is a key element of scalability and extendability.<br>
1211 <br>
1212 <A name="6"></a><font color="blue">PAGE 6</font><br>
1213 <br>
1214 <center>
1215 <img src="fig1-1.gif">
1216 </center>
1217 <br>
1218 <i>Figure 1-1. A split view of the kernel</i><br>
1219 <br>
1220 The three classes are:<br>
1221 <br>
1222 <i>Character devices</i><br>
1223 <br>
1224 A character (char) device is one that can be accessed as a stream of bytes (like a
1225 file); a char driver is in charge of implementing this behavior. Such a driver usually
1226 implements at least the <i>open</i>, <i>close</i>, <i>read</i>, and <i>write </i>system calls. The text
1227 console (<i>/dev/console</i>) and the serial ports (<i>/dev/ttyS0 </i>and friends) are examples
1228 of char devices, as they are well represented by the stream abstraction. Char
1229 devices are accessed by means of filesystem nodes, such as <i>/dev/tty1 </i>and <i>/dev/lp0</i>.
1230 The only relevant difference between a char device and a regular file is that you
1231 can always move back and forth in the regular file, whereas most char devices
1232 are just data channels, which you can only access sequentially. There exist,
1233 nonetheless, char devices that look like data areas, and you can move back and
1234 forth in them; for instance, this usually applies to frame grabbers, where the
1235 applications can access the whole acquired image using <i>mmap</i> or <i>lseek</i>.<br>
1236 <br>
1237 <A name="7"></a><font color="blue">PAGE 7</font><br>
1238 <br>
1239 <i>Block devices</i><br>
1240 <br>
1241 Like char devices, block devices are accessed by filesystem nodes in the <i>/dev
1242 </i>directory. A block device is a device (e.g., a disk) that can host a filesystem. In
1243 most Unix systems, a block device can only handle I/O operations that transfer
1244 one or more whole blocks, which are usually 512 bytes (or a larger power of
1245 two) bytes in length. Linux, instead, allows the application to read and write a
1246 block device like a char device--it permits the transfer of any number of bytes at
1247 a time. As a result, block and char devices differ only in the way data is managed
1248 internally by the kernel, and thus in the kernel/driver software interface. Like a
1249 char device, each block device is accessed through a filesystem node, and the difference
1250 between them is transparent to the user. Block drivers have a completely
1251 different interface to the kernel than char drivers.<br>
1252 <br>
1253 <i>Network interfaces</i><br>
1254 <br>
1255 Any network transaction is made through an interface, that is, a device that is
1256 able to exchange data with other hosts. Usually, an <i>interface </i>is a hardware
1257 device, but it might also be a pure software device, like the loopback interface. A
1258 network interface is in charge of sending and receiving data packets, driven by
1259 the network subsystem of the kernel, without knowing how individual transactions
1260 map to the actual packets being transmitted. Many network connections
1261 (especially those using TCP) are stream-oriented, but network devices are, usually,
1262 designed around the transmission and receipt of packets. A network driver
1263 knows nothing about individual connections; it only handles packets.<br>
1264 <br>
1265 Not being a stream-oriented device, a network interface isn't easily mapped to a
1266 node in the filesystem, as <i>/dev/tty1 </i>is. The Unix way to provide access to interfaces
1267 is still by assigning a unique name to them (such as eth0), but that name
1268 doesn't have a corresponding entry in the filesystem. Communication between
1269 the kernel and a network device driver is completely different from that used
1270 with char and block drivers. Instead of <i>read </i>and <i>write</i>, the kernel calls functions
1271 related to packet transmission.<br>
1272 <br>
1273 There are other ways of classifying driver modules that are orthogonal to the above
1274 device types. In general, some types of drivers work with additional layers of kernel
1275 support functions for a given type of device. For example, one can talk of universal
1276 serial bus (USB) modules, serial modules, SCSI modules, and so on. Every USB
1277 device is driven by a USB module that works with the USB subsystem, but the device
1278 itself shows up in the system as a char device (a USB serial port, say), a block device
1279 (a USB memory card reader), or a network device (a USB Ethernet interface).<br>
1280 <br>
1281 Other classes of device drivers have been added to the kernel in recent times, including
1282 FireWire drivers and I2C drivers. In the same way that they handled USB and
1283 SCSI drivers, kernel developers collected class-wide features and exported them to
1284 driver implementers to avoid duplicating work and bugs, thus simplifying and
1285 strengthening the process of writing such drivers.<br>
1286 <br>
1287 <A name="8"></a><font color="blue">PAGE 8</font><br>
1288 <br>
1289 In addition to device drivers, other functionalities, both hardware and software, are
1290 modularized in the kernel. One common example is filesystems. A filesystem type
1291 determines how information is organized on a block device in order to represent a
1292 tree of directories and files. Such an entity is not a device driver, in that there's no
1293 explicit device associated with the way the information is laid down; the filesystem
1294 type is instead a software driver, because it maps the low-level data structures to
1295 high-level data structures. It is the filesystem that determines how long a filename
1296 can be and what information about each file is stored in a directory entry. The filesystem
1297 module must implement the lowest level of the system calls that access directories
1298 and files, by mapping filenames and paths (as well as other information, such
1299 as access modes) to data structures stored in data blocks. Such an interface is completely
1300 independent of the actual data transfer to and from the disk (or other
1301 medium), which is accomplished by a block device driver.<br>
1302 <br>
1303 If you think of how strongly a Unix system depends on the underlying filesystem,
1304 you'll realize that such a software concept is vital to system operation. The ability to
1305 decode filesystem information stays at the lowest level of the kernel hierarchy and is
1306 of utmost importance; even if you write a block driver for your new CD-ROM, it is
1307 useless if you are not able to run <i>ls </i>or <i>cp </i>on the data it hosts. Linux supports the concept
1308 of a filesystem module, whose software interface declares the different operations
1309 that can be performed on a filesystem inode, directory, file, and superblock. It's
1310 quite unusual for a programmer to actually need to write a filesystem module,
1311 because the official kernel already includes code for the most important filesystem
1312 types.<br>
1313 <br>
1314 <a name="SecurityIssues"></a><font color="red"><b>Security Issues</b></font><br>
1315 <br>
1316 Security is an increasingly important concern in modern times. We will discuss security-related
1317 issues as they come up throughout the book. There are a few general concepts,
1318 however, that are worth mentioning now.<br>
1319 <br>
1320 Any security check in the system is enforced by kernel code. If the kernel has security
1321 holes, then the system as a whole has holes. In the official kernel distribution,
1322 only an authorized user can load modules; the system call <i>init_module </i>checks if the
1323 invoking process is authorized to load a module into the kernel. Thus, when running
1324 an official kernel, only the superuser,* or an intruder who has succeeded in
1325 becoming privileged, can exploit the power of privileged code.<br>
1326 <br>
1327 When possible, driver writers should avoid encoding security policy in their code.
1328 Security is a policy issue that is often best handled at higher levels within the kernel,
1329 under the control of the system administrator. There are always exceptions, however.<br>
1330 <br>
1331 * Technically, only somebody with the <font class="fixd">CAP_SYS_MODULE</font> capability
1332 can perform this operation. We discuss capabilities in Chapter 6.<br>
1333 <br>
1334 <A name="9"></a><font color="blue">PAGE 9</font><br>
1335 <br>
1336 As a device driver writer, you should be aware of situations in which some types of
1337 device access could adversely affect the system as a whole and should provide adequate
1338 controls. For example, device operations that affect global resources (such as
1339 setting an interrupt line), which could damage the hardware (loading firmware, for
1340 example), or that could affect other users (such as setting a default block size on a
1341 tape drive), are usually only available to sufficiently privileged users, and this check
1342 must be made in the driver itself.<br>
1343 <br>
1344 Driver writers must also be careful, of course, to avoid introducing security bugs.
1345 The C programming language makes it easy to make several types of errors. Many
1346 current security problems are created, for example, by <i>buffer overrun </i>errors, in which
1347 the programmer forgets to check how much data is written to a buffer, and data ends
1348 up written beyond the end of the buffer, thus overwriting unrelated data. Such errors
1349 can compromise the entire system and must be avoided. Fortunately, avoiding these
1350 errors is usually relatively easy in the device driver context, in which the interface to
1351 the user is narrowly defined and highly controlled.<br>
1352 <br>
1353 Some other general security ideas are worth keeping in mind. Any input received
1354 from user processes should be treated with great suspicion; never trust it unless you
1355 can verify it. Be careful with uninitialized memory; any memory obtained from the
1356 kernel should be zeroed or otherwise initialized before being made available to a user
1357 process or device. Otherwise, information leakage (disclosure of data, passwords,
1358 etc.) could result. If your device interprets data sent to it, be sure the user cannot
1359 send anything that could compromise the system. Finally, think about the possible
1360 effect of device operations; if there are specific operations (e.g., reloading the firmware
1361 on an adapter board or formatting a disk) that could affect the system, those
1362 operations should almost certainly be restricted to privileged users.<br>
1363 <br>
1364 Be careful, also, when receiving software from third parties, especially when the kernel
1365 is concerned: because everybody has access to the source code, everybody can
1366 break and recompile things. Although you can usually trust precompiled kernels
1367 found in your distribution, you should avoid running kernels compiled by an
1368 untrusted friend--if you wouldn't run a precompiled binary as root, then you'd better
1369 not run a precompiled kernel. For example, a maliciously modified kernel could
1370 allow anyone to load a module, thus opening an unexpected back door via <i>init_module</i>.<br>
1371 <br>
1372 Note that the Linux kernel can be compiled to have no module support whatsoever,
1373 thus closing any module-related security holes. In this case, of course, all needed
1374 drivers must be built directly into the kernel itself. It is also possible, with 2.2 and
1375 later kernels, to disable the loading of kernel modules after system boot via the capability
1376 mechanism.<br>
1377 <br>
1378 <A name="10"></a><font color="blue">PAGE 10</font><br>
1379 <br>
1380 <a name="VersionNumbering"></a><font color="red"><b>Version Numbering</b></font><br>
1381 <br>
1382 Before digging into programming, we should comment on the version numbering
1383 scheme used in Linux and which versions are covered by this book.<br>
1384 <br>
1385 First of all, note that <i>every </i>software package used in a Linux system has its own
1386 release number, and there are often interdependencies across them: you need a particular
1387 version of one package to run a particular version of another package. The
1388 creators of Linux distributions usually handle the messy problem of matching packages,
1389 and the user who installs from a prepackaged distribution doesn't need to deal
1390 with version numbers. Those who replace and upgrade system software, on the other
1391 hand, are on their own in this regard. Fortunately, almost all modern distributions
1392 support the upgrade of single packages by checking interpackage dependencies; the
1393 distribution's package manager generally does not allow an upgrade until the dependencies
1394 are satisfied.<br>
1395 <br>
1396 To run the examples we introduce during the discussion, you won't need particular
1397 versions of any tool beyond what the 2.6 kernel requires; any recent Linux distribution
1398 can be used to run our examples. We won't detail specific requirements,
1399 because the file <i>Documentation/Changes </i>in your kernel sources is the best source of
1400 such information if you experience any problems.<br>
1401 <br>
1402 As far as the kernel is concerned, the even-numbered kernel versions (i.e., 2.6.<i>x</i>) are
1403 the stable ones that are intended for general distribution. The odd versions (such as
1404 2.7.<i>x</i>), on the contrary, are development snapshots and are quite ephemeral; the latest
1405 of them represents the current status of development, but becomes obsolete in a
1406 few days or so.<br>
1407 <br>
1408 This book covers Version 2.6 of the kernel. Our focus has been to show all the features
1409 available to device driver writers in 2.6.10, the current version at the time we
1410 are writing. This edition of the book does not cover prior versions of the kernel. For
1411 those of you who are interested, the second edition covered Versions 2.0 through 2.4
1412 in detail. That edition is still available online at <a href="http://lwn.net/Kernel/LDD2/" target="_blank"><i>http://lwn.net/Kernel/LDD2/</i></a>.<br>
1413 <br>
1414 Kernel programmers should be aware that the development process changed with 2.6.
1415 The 2.6 series is now accepting changes that previously would have been considered
1416 too large for a "stable" kernel. Among other things, that means that internal kernel
1417 programming interfaces can change, thus potentially obsoleting parts of this book;
1418 for this reason, the sample code accompanying the text is known to work with 2.6.10,
1419 but some modules don't compile under earlier versions. Programmers wanting to
1420 keep up with kernel programming changes are encouraged to join the mailing lists
1421 and to make use of the web sites listed in the bibliography. There is also a web page
1422 maintained at <a href="http://lwn.net/Articles/2.6-kernel-api/" target="_blank"><i>http://lwn.net/Articles/2.6-kernel-api/</i></a>, which contains information
1423 about API changes that have happened since this book was published.<br>
1424 <br>
1425 <A name="11"></a><font color="blue">PAGE 11</font><br>
1426 <br>
1427 This text doesn't talk specifically about odd-numbered kernel versions. General users
1428 never have a reason to run development kernels. Developers experimenting with new
1429 features, however, want to be running the latest development release. They usually
1430 keep upgrading to the most recent version to pick up bug fixes and new implementations
1431 of features. Note, however, that there's no guarantee on experimental kernels,*
1432 and nobody helps you if you have problems due to a bug in a noncurrent odd-numbered
1433 kernel. Those who run odd-numbered versions of the kernel are usually skilled
1434 enough to dig in the code without the need for a textbook, which is another reason
1435 why we don't talk about development kernels here.<br>
1436 <br>
1437 Another feature of Linux is that it is a platform-independent operating system, not
1438 just "a Unix clone for PC clones" anymore: it currently supports some 20 architectures.
1439 This book is platform independent as far as possible, and all the code samples
1440 have been tested on at least the x86 and x86-64 platforms. Because the code has been
1441 tested on both 32-bit and 64-bit processors, it should compile and run on all other
1442 platforms. As you might expect, the code samples that rely on particular hardware
1443 don't work on all the supported platforms, but this is always stated in the source
1444 code.<br>
1445 <br>
1446 <a name="LicenseTerms"></a><font color="red"><b>License Terms</b></font><br>
1447 <br>
1448 Linux is licensed under Version 2 of the GNU General Public License (GPL), a document
1449 devised for the GNU project by the Free Software Foundation. The GPL allows
1450 anybody to redistribute, and even sell, a product covered by the GPL, as long as the
1451 recipient has access to the source and is able to exercise the same rights. Additionally,
1452 any software product derived from a product covered by the GPL must, if it is
1453 redistributed at all, be released under the GPL.<br>
1454 <br>
1455 The main goal of such a license is to allow the growth of knowledge by permitting
1456 everybody to modify programs at will; at the same time, people selling software to
1457 the public can still do their job. Despite this simple objective, there's a never-ending
1458 discussion about the GPL and its use. If you want to read the license, you can find it
1459 in several places in your system, including the top directory of your kernel source
1460 tree in the <i>COPYING </i>file.<br>
1461 <br>
1462 Vendors often ask whether they can distribute kernel modules in binary form only.
1463 The answer to that question has been deliberately left ambiguous. Distribution of
1464 binary modules--as long as they adhere to the published kernel interface--has been
1465 tolerated so far. But the copyrights on the kernel are held by many developers, and
1466 not all of them agree that kernel modules are not derived products. If you or your
1467 employer wish to distribute kernel modules under a nonfree license, you really need<br>
1468 <br>
1469 * Note that there's no guarantee on even-numbered kernels as well, unless you rely
1470 on a commercial provider that grants its own warranty.<br>
1471 <br>
1472 <A name="12"></a><font color="blue">PAGE 12</font><br>
1473 <br>
1474 to discuss the situation with your legal counsel. Please note also that the kernel
1475 developers have no qualms against breaking binary modules between kernel releases,
1476 even in the middle of a stable kernel series. If it is at all possible, both you and your
1477 users are better off if you release your module as free software.<br>
1478 <br>
1479 If you want your code to go into the mainline kernel, or if your code requires patches
1480 to the kernel, you <i>must </i>use a GPL-compatible license as soon as you release the code.
1481 Although personal use of your changes doesn't force the GPL on you, if you distribute
1482 your code, you must include the source code in the distribution--people acquiring
1483 your package must be allowed to rebuild the binary at will.<br>
1484 <br>
1485 As far as this book is concerned, most of the code is freely redistributable, either in
1486 source or binary form, and neither we nor O'Reilly retain any right on any derived
1487 works. All the programs are available at <br>
1488 <br>
1489 <a href="ftp://ftp.ora.com/pub/examples/linux/drivers/" target="_blank"><i>ftp://ftp.ora.com/pub/examples/linux/drivers/</i></a>,<br>
1490 <br>
1491 and the exact license terms are stated in the <i>LICENSE</i> file in the same directory.<br>
1492 <br>
1493 <a name="JoiningTheKernelDevelopmentCommunity"></a><font color="red"><b>Joining the Kernel Development Community</b></font><br>
1494 <br>
1495 As you begin writing modules for the Linux kernel, you become part of a larger community
1496 of developers. Within that community, you can find not only people engaged
1497 in similar work, but also a group of highly committed engineers working toward
1498 making Linux a better system. These people can be a source of help, ideas, and critical
1499 review as well--they will be the first people you will likely turn to when you are
1500 looking for testers for a new driver.<br>
1501 <br>
1502 The central gathering point for Linux kernel developers is the <i>linux-kernel </i>mailing
1503 list. All major kernel developers, from Linus Torvalds on down, subscribe to this list.
1504 Please note that the list is not for the faint of heart: traffic as of this writing can run
1505 up to 200 messages per day or more. Nonetheless, following this list is essential for
1506 those who are interested in kernel development; it also can be a top-quality resource
1507 for those in need of kernel development help.<br>
1508 <br>
1509 To join the linux-kernel list, follow the instructions found in the linux-kernel mailing
1510 list FAQ:<br>
1511 <br>
1512 <a href="http://www.tux.org/lkml" target="_blank"><i>http://www.tux.org/lkml</i></a>.<br>
1513 <br>
1514 Read the rest of the FAQ while you are at it;
1515 there is a great deal of useful information there. Linux kernel developers are busy
1516 people, and they are much more inclined to help people who have clearly done their
1517 homework first.<br>
1518 <br>
1519 <a name="OverviewOfTheBook"></a><font color="red"><b>Overview of the Book</b></font><br>
1520 <br>
1521 From here on, we enter the world of kernel programming. Chapter 2 introduces
1522 modularization, explaining the secrets of the art and showing the code for running
1523 modules. Chapter 3 talks about char drivers and shows the complete code for a<br>
1524 <br>
1525 <A name="13"></a><font color="blue">PAGE 13</font><br>
1526 <br>
1527 memory-based device driver that can be read and written for fun. Using memory as
1528 the hardware base for the device allows anyone to run the sample code without the
1529 need to acquire special hardware.<br>
1530 <br>
1531 Debugging techniques are vital tools for the programmer and are introduced in
1532 Chapter 4. Equally important for those who would hack on contemporary kernels is
1533 the management of concurrency and race conditions. Chapter 5 concerns itself with
1534 the problems posed by concurrent access to resources and introduces the Linux
1535 mechanisms for controlling concurrency.<br>
1536 <br>
1537 With debugging and concurrency management skills in place, we move to advanced
1538 features of char drivers, such as blocking operations, the use of <i>select</i>, and the important
1539 <i>ioctl</i> call; these topics are the subject of Chapter 6.<br>
1540 <br>
1541 Before dealing with hardware management, we dissect a few more of the kernel's
1542 software interfaces: Chapter 7 shows how time is managed in the kernel, and
1543 Chapter 8 explains memory allocation.<br>
1544 <br>
1545 Next we focus on hardware. Chapter 9 describes the management of I/O ports and
1546 memory buffers that live on the device; after that comes interrupt handling, in
1547 Chapter 10. Unfortunately, not everyone is able to run the sample code for these
1548 chapters, because some hardware support <i>is </i>actually needed to test the software
1549 interface interrupts. We've tried our best to keep required hardware support to a
1550 minimum, but you still need some simple hardware, such as a standard parallel port,
1551 to work with the sample code for these chapters.<br>
1552 <br>
1553 Chapter 11 covers the use of data types in the kernel and the writing of portable
1554 code.<br>
1555 <br>
1556 The second half of the book is dedicated to more advanced topics. We start by getting
1557 deeper into the hardware and, in particular, the functioning of specific peripheral
1558 buses. Chapter 12 covers the details of writing drivers for PCI devices, and
1559 Chapter 13 examines the API for working with USB devices.<br>
1560 <br>
1561 With an understanding of peripheral buses in place, we can take a detailed look at the
1562 Linux device model, which is the abstraction layer used by the kernel to describe the
1563 hardware and software resources it is managing. Chapter 14 is a bottom-up look at
1564 the device model infrastructure, starting with the kobject type and working up from
1565 there. It covers the integration of the device model with real hardware; it then uses
1566 that knowledge to cover topics like hot-pluggable devices and power management.<br>
1567 <br>
1568 In Chapter 15, we take a diversion into Linux memory management. This chapter
1569 shows how to map kernel memory into user space (the <i>mmap </i>system call), map user
1570 memory into kernel space (with <i>get_user_pages</i>), and how to map either kind of
1571 memory into device space (to perform direct memory access [DMA] operations).<br>
1572 <br>
1573 <A name="14"></a><font color="blue">PAGE 14</font><br>
1574 <br>
1575 Our understanding of memory will be useful for the following two chapters, which
1576 cover the other major driver classes. Chapter 16 introduces block drivers and shows
1577 how they are different from the char drivers we have worked with so far. Then
1578 Chapter 17 gets into the writing of network drivers. We finish up with a discussion
1579 of serial drivers (Chapter 18) and a bibliography.<br>
1580 <br>
1581 <A name="15"></a><font color="blue">PAGE 15</font><br>
1582 <br>
1583 <a name="CHAPTER2"></a><font color="red"><b>CHAPTER 2</b></font><br>
1584 <br>
1585 <a name="BuildingAndRunningModules"></a><font color="#7519FF" size="+1"><b>Building and Running Modules</b></font><br>
1586 <br>
1587 It's almost time to begin programming. This chapter introduces all the essential concepts
1588 about modules and kernel programming. In these few pages, we build and run
1589 a complete (if relatively useless) module, and look at some of the basic code shared
1590 by all modules. Developing such expertise is an essential foundation for any kind of
1591 modularized driver. To avoid throwing in too many concepts at once, this chapter
1592 talks only about modules, without referring to any specific device class.<br>
1593 <br>
1594 All the kernel items (functions, variables, header files, and macros) that are introduced
1595 here are described in a reference section at the end of the chapter.<br>
1596 <br>
1597 <a name="SettingUpYourTestSystem"></a><font color="red"><b>Setting Up Your Test System</b></font><br>
1598 <br>
1599 Starting with this chapter, we present example modules to demonstrate programming
1600 concepts. (All of these examples are available on O'Reilly's FTP site, as
1601 explained in Chapter 1.) Building, loading, and modifying these examples are a good
1602 way to improve your understanding of how drivers work and interact with the kernel.<br>
1603 <br>
1604 The example modules should work with almost any 2.6.x kernel, including those
1605 provided by distribution vendors. However, we recommend that you obtain a "mainline"
1606 kernel directly from the <i>kernel.org </i>mirror network, and install it on your system.
1607 Vendor kernels can be heavily patched and divergent from the mainline; at
1608 times, vendor patches can change the kernel API as seen by device drivers. If you are
1609 writing a driver that must work on a particular distribution, you will certainly want
1610 to build and test against the relevant kernels. But, for the purpose of learning about
1611 driver writing, a standard kernel is best.<br>
1612 <br>
1613 Regardless of the origin of your kernel, building modules for 2.6.x requires that you
1614 have a configured and built kernel tree on your system. This requirement is a change
1615 from previous versions of the kernel, where a current set of header files was sufficient.
1616 2.6 modules are linked against object files found in the kernel source tree; the
1617 result is a more robust module loader, but also the requirement that those object files<br>
1618 <br>
1619 <A name="16"></a><font color="blue">PAGE 16</font><br>
1620 <br>
1621 be available. So your first order of business is to come up with a kernel source tree
1622 (either from the <i>kernel.org </i>network or your distributor's kernel source package),
1623 build a new kernel, and install it on your system. For reasons we'll see later, life is
1624 generally easiest if you are actually running the target kernel when you build your
1625 modules, though this is not required.<br>
1626 <br>
1627 <div class="warn">You should also give some thought to where you do your module
1628 experimentation, development, and testing. We have done our best to
1629 make our example modules safe and correct, but the possibility of
1630 bugs is always present. Faults in kernel code can bring about the
1631 demise of a user process or, occasionally, the entire system. They do
1632 not normally create more serious problems, such as disk corruption.
1633 Nonetheless, it is advisable to do your kernel experimentation on a
1634 system that does not contain data that you cannot afford to lose, and
1635 that does not perform essential services. Kernel hackers typically keep
1636 a "sacrificial" system around for the purpose of testing new code.</div>
1637 <br>
1638 So, if you do not yet have a suitable system with a configured and built kernel source
1639 tree on disk, now would be a good time to set that up. We'll wait. Once that task is
1640 taken care of, you'll be ready to start playing with kernel modules.<br>
1641 <br>
1642 <a name="TheHelloWorldModule"></a><font color="red"><b>The Hello World Module</b></font><br>
1643 <br>
1644 Many programming books begin with a "hello world" example as a way of showing
1645 the simplest possible program. This book deals in kernel modules rather than programs;
1646 so, for the impatient reader, the following code is a complete "hello world"
1647 module:<br>
1648 <pre>
1649 #include <linux/init.h>
1650 #include <linux/module.h>
1651 MODULE_LICENSE("Dual BSD/GPL");
1653 static int hello_init(void)
1654 {
1655 printk(KERN_ALERT "Hello, world\n");
1656 return 0;
1657 }
1659 static void hello_exit(void)
1660 {
1661 printk(KERN_ALERT "Goodbye, cruel world\n");
1662 }
1664 module_init(hello_init);
1665 module_exit(hello_exit);
1666 </pre>
1667 This module defines two functions, one to be invoked when the module is loaded
1668 into the kernel (<i>hello_init</i>) and one for when the module is removed (<i>hello_exit</i>). The<br>
1669 <br>
1670 <A name="17"></a><font color="blue">PAGE 17</font><br>
1671 <br>
1672 <i>module_init </i>and <i>module_exit </i>lines use special kernel macros to indicate the role of
1673 these two functions. Another special macro <i><font class="fixd">(MODULE_LICENSE)</font></i> is used to tell the
1674 kernel that this module bears a free license; without such a declaration, the kernel
1675 complains when the module is loaded.<br>
1676 <br>
1677 The <i>printk </i>function is defined in the Linux kernel and made available to modules; it
1678 behaves similarly to the standard C library function <i>printf</i>. The kernel needs its own
1679 printing function because it runs by itself, without the help of the C library. The
1680 module can call <i>printk </i>because, after <i>insmod </i>has loaded it, the module is linked to
1681 the kernel and can access the kernel's public symbols (functions and variables, as
1682 detailed in the next section). The string <font class="fixd">KERN_ALERT</font> is the priority of the message.*
1683 We've specified a high priority in this module, because a message with the default
1684 priority might not show up anywhere useful, depending on the kernel version you
1685 are running, the version of the <i>klogd </i>daemon, and your configuration. You can
1686 ignore this issue for now; we explain it in Chapter 4.<br>
1687 <br>
1688 You can test the module with the <i>insmod </i>and <i>rmmod </i>utilities, as shown below. Note
1689 that only the superuser can load and unload a module.<br>
1690 <pre>
1691 % <b>make
1692 </b>make[1]: Entering directory `/usr/src/linux-2.6.10'
1693 CC [M] /home/ldd3/src/misc-modules/hello.o
1694 Building modules, stage 2.
1695 MODPOST
1696 CC /home/ldd3/src/misc-modules/hello.mod.o
1697 LD [M] /home/ldd3/src/misc-modules/hello.ko
1698 make[1]: Leaving directory `/usr/src/linux-2.6.10'
1699 % <b>su
1700 </b>root# <b>insmod ./hello.ko
1701 </b>Hello, world
1702 root# <b>rmmod hello
1703 </b>Goodbye, cruel world
1704 root#
1705 </pre>
1706 Please note once again that, for the above sequence of commands to work, you must
1707 have a properly configured and built kernel tree in a place where the makefile is able
1708 to find it (<i>/usr/src/linux-2.6.10 </i>in the example shown). We get into the details of how
1709 modules are built in the section "Compiling and Loading."<br>
1710 <br>
1711 According to the mechanism your system uses to deliver the message lines, your output
1712 may be different. In particular, the previous screen dump was taken from a text
1713 console; if you are running <i>insmod </i>and <i>rmmod </i>from a terminal emulator running
1714 under the window system, you won't see anything on your screen. The message goes
1715 to one of the system log files, such as <i>/var/log/messages </i>(the name of the actual file<br>
1716 <br>
1717 * The priority is just a string, such as <1>, which is prepended to the <i>printk </i>format
1718 string. Note the lack of a comma after <font class="fixd">KERN_ALERT</font>; adding a comma there is a common and annoying
1719 typo (which, fortunately, is caught by the compiler).<br>
1720 <br>
1721 <A name="18"></a><font color="blue">PAGE 18</font><br>
1722 <br>
1723 varies between Linux distributions). The mechanism used to deliver kernel messages
1724 is described in Chapter 4.<br>
1725 <br>
1726 As you can see, writing a module is not as difficult as you might expect--at least, as
1727 long as the module is not required to do anything worthwhile. The hard part is
1728 understanding your device and how to maximize performance. We go deeper into
1729 modularization throughout this chapter and leave device-specific issues for later
1730 chapters.<br>
1731 <br>
1732 <a name="KernelModulesVersusApplications"></a><font color="red"><b>Kernel Modules Versus Applications</b></font><br>
1733 <br>
1734 Before we go further, it's worth underlining the various differences between a kernel
1735 module and an application.<br>
1736 <br>
1737 While most small and medium-sized applications perform a single task from beginning
1738 to end, every kernel module just registers itself in order to serve future requests,
1739 and its initialization function terminates immediately. In other words, the task of the
1740 module's initialization function is to prepare for later invocation of the module's
1741 functions; it's as though the module were saying, "Here I am, and this is what I can
1742 do." The module's exit function (<i>hello_exit </i>in the example) gets invoked just before
1743 the module is unloaded. It should tell the kernel, "I'm not there anymore; don't ask
1744 me to do anything else." This kind of approach to programming is similar to event-driven
1745 programming, but while not all applications are event-driven, each and every
1746 kernel module is. Another major difference between event-driven applications and
1747 kernel code is in the exit function: whereas an application that terminates can be lazy
1748 in releasing resources or avoids clean up altogether, the exit function of a module
1749 must carefully undo everything the <i>init </i>function built up, or the pieces remain
1750 around until the system is rebooted.<br>
1751 <br>
1752 Incidentally, the ability to unload a module is one of the features of modularization
1753 that you'll most appreciate, because it helps cut down development time; you can
1754 test successive versions of your new driver without going through the lengthy shutdown/reboot
1755 cycle each time.<br>
1756 <br>
1757 As a programmer, you know that an application can call functions it doesn't define:
1758 the linking stage resolves external references using the appropriate library of functions.
1759 <i>printf </i>is one of those callable functions and is defined in <i>libc</i>. A module, on the
1760 other hand, is linked only to the kernel, and the only functions it can call are the
1761 ones exported by the kernel; there are no libraries to link to. The <i>printk </i>function
1762 used in <i>hello.c </i>earlier, for example, is the version of <i>printf </i>defined within the kernel
1763 and exported to modules. It behaves similarly to the original function, with a few
1764 minor differences, the main one being lack of floating-point support.<br>
1765 <br>
1766 Figure 2-1 shows how function calls and function pointers are used in a module to
1767 add new functionality to a running kernel.<br>
1768 <br>
1769 <A name="19"></a><font color="blue">PAGE 19</font><br>
1770 <br>
1771 <center>
1772 <img src="fig2-1.gif">
1773 </center>
1774 <br>
1775 <i>Figure 2-1. Linking a module to the kernel</i><br>
1776 <br>
1777 Because no library is linked to modules, source files should never include the usual
1778 header files, <i><stdarg.h> </i>and very special situations being the only exceptions. Only
1779 functions that are actually part of the kernel itself may be used in kernel modules.
1780 Anything related to the kernel is declared in headers found in the kernel source tree
1781 you have set up and configured; most of the relevant headers live in <i>include/linux </i>and
1782 <i>include/asm</i>, but other subdirectories of <i>include </i>have been added to host material
1783 associated to specific kernel subsystems.<br>
1784 <br>
1785 The role of individual kernel headers is introduced throughout the book as each of
1786 them is needed.<br>
1787 <br>
1788 Another important difference between kernel programming and application programming
1789 is in how each environment handles faults: whereas a segmentation fault
1790 is harmless during application development and a debugger can always be used to
1791 trace the error to the problem in the source code, a kernel fault kills the current process
1792 at least, if not the whole system. We see how to trace kernel errors in Chapter 4.<br>
1793 <br>
1794 <a name="UserSpaceAndKernelSpace"></a><font color="red"><b>User Space and Kernel Space</b></font><br>
1795 <br>
1796 A module runs in <i>kernel space</i>, whereas applications run in <i>user space</i>. This concept
1797 is at the base of operating systems theory.<br>
1798 <br>
1799 The role of the operating system, in practice, is to provide programs with a consistent
1800 view of the computer's hardware. In addition, the operating system must
1801 account for independent operation of programs and protection against unauthorized
1802 access to resources. This nontrivial task is possible only if the CPU enforces protection
1803 of system software from the applications.<br>
1804 <br>
1805 <A name="20"></a><font color="blue">PAGE 20</font><br>
1806 <br>
1807 Every modern processor is able to enforce this behavior. The chosen approach is to
1808 implement different operating modalities (or levels) in the CPU itself. The levels have
1809 different roles, and some operations are disallowed at the lower levels; program code
1810 can switch from one level to another only through a limited number of gates. Unix
1811 systems are designed to take advantage of this hardware feature, using two such levels.
1812 All current processors have at least two protection levels, and some, like the x86
1813 family, have more levels; when several levels exist, the highest and lowest levels are
1814 used. Under Unix, the kernel executes in the highest level (also called <i>supervisor
1815 mode</i>), where everything is allowed, whereas applications execute in the lowest level
1816 (the so-called <i>user mode</i>), where the processor regulates direct access to hardware
1817 and unauthorized access to memory.<br>
1818 <br>
1819 We usually refer to the execution modes as <i>kernel space </i>and <i>user space</i>. These terms
1820 encompass not only the different privilege levels inherent in the two modes, but also
1821 the fact that each mode can have its own memory mapping--its own address
1822 space--as well.<br>
1823 <br>
1824 Unix transfers execution from user space to kernel space whenever an application
1825 issues a system call or is suspended by a hardware interrupt. Kernel code executing a
1826 system call is working in the context of a process--it operates on behalf of the calling
1827 process and is able to access data in the process's address space. Code that handles
1828 interrupts, on the other hand, is asynchronous with respect to processes and is
1829 not related to any particular process.<br>
1830 <br>
1831 The role of a module is to extend kernel functionality; modularized code runs in kernel
1832 space. Usually a driver performs both the tasks outlined previously: some functions
1833 in the module are executed as part of system calls, and some are in charge of
1834 interrupt handling.<br>
1835 <br>
1836 <a name="ConcurrencyInTheKernel"></a><font color="red"><b>Concurrency in the Kernel</b></font><br>
1837 <br>
1838 One way in which kernel programming differs greatly from conventional application
1839 programming is the issue of concurrency. Most applications, with the notable exception
1840 of multithreading applications, typically run sequentially, from the beginning to
1841 the end, without any need to worry about what else might be happening to change
1842 their environment. Kernel code does not run in such a simple world, and even the
1843 simplest kernel modules must be written with the idea that many things can be happening
1844 at once.<br>
1845 <br>
1846 There are a few sources of concurrency in kernel programming. Naturally, Linux systems
1847 run multiple processes, more than one of which can be trying to use your driver
1848 at the same time. Most devices are capable of interrupting the processor; interrupt
1849 handlers run asynchronously and can be invoked at the same time that your driver is
1850 trying to do something else. Several software abstractions (such as kernel timers,
1851 introduced in Chapter 7) run asynchronously as well. Moreover, of course, Linux<br>
1852 <br>
1853 <A name="21"></a><font color="blue">PAGE 21</font><br>
1854 <br>
1855 can run on symmetric multiprocessor (SMP) systems, with the result that your driver
1856 could be executing concurrently on more than one CPU. Finally, in 2.6, kernel code
1857 has been made preemptible; this change causes even uniprocessor systems to have
1858 many of the same concurrency issues as multiprocessor systems.<br>
1859 <br>
1860 As a result, Linux kernel code, including driver code, must be <i>reentrant</i>--it must be
1861 capable of running in more than one context at the same time. Data structures must
1862 be carefully designed to keep multiple threads of execution separate, and the code
1863 must take care to access shared data in ways that prevent corruption of the data.
1864 Writing code that handles concurrency and avoids race conditions (situations in
1865 which an unfortunate order of execution causes undesirable behavior) requires
1866 thought and can be tricky. Proper management of concurrency is required to write
1867 correct kernel code; for that reason, every sample driver in this book has been written
1868 with concurrency in mind. The techniques used are explained as we come to
1869 them; Chapter 5 has also been dedicated to this issue and the kernel primitives available
1870 for concurrency management.<br>
1871 <br>
1872 A common mistake made by driver programmers is to assume that concurrency is
1873 not a problem as long as a particular segment of code does not go to sleep (or
1874 "block"). Even in previous kernels (which were not preemptive), this assumption
1875 was not valid on multiprocessor systems. In 2.6, kernel code can (almost) never
1876 assume that it can hold the processor over a given stretch of code. If you do not write
1877 your code with concurrency in mind, it will be subject to catastrophic failures that
1878 can be exceedingly difficult to debug.<br>
1879 <br>
1880 <a name="TheCurrentProcess"></a><font color="red"><b>The Current Process</b></font><br>
1881 <br>
1882 Although kernel modules don't execute sequentially as applications do, most actions
1883 performed by the kernel are done on behalf of a specific process. Kernel code can
1884 refer to the current process by accessing the global item current, defined in <i><asm/
1885 current.h></i>, which yields a pointer to <font class="fixd">struct task_struct</font>, defined by <i><linux/sched.h></i>.
1886 The current pointer refers to the process that is currently executing. During the execution
1887 of a system call, such as <i>open </i>or <i>read</i>, the current process is the one that
1888 invoked the call. Kernel code can use process-specific information by using current,
1889 if it needs to do so. An example of this technique is presented in Chapter 6.<br>
1890 <br>
1891 Actually, current is not truly a global variable. The need to support SMP systems
1892 forced the kernel developers to develop a mechanism that finds the current process on
1893 the relevant CPU. This mechanism must also be fast, since references to current happen
1894 frequently. The result is an architecture-dependent mechanism that, usually,
1895 hides a pointer to the <font class="fixd">task_struct</font> structure on the kernel stack. The details of the
1896 implementation remain hidden to other kernel subsystems though, and a device
1897 driver can just include <i><linux/sched.h> </i>and refer to the current process. For example,<br>
1898 <br>
1899 <A name="22"></a><font color="blue">PAGE 22</font><br>
1900 <br>
1901 the following statement prints the process ID and the command name of the current
1902 process by accessing certain fields in <font class="fixd">struct task_struct</font>:<br>
1903 <pre>
1904 printk(KERN_INFO "The process is \"%s\" (pid %i)\n",
1905 current->comm, current->pid);
1906 </pre>
1907 The command name stored in <font class="fixd">current->comm</font> is the base name of the program file
1908 (trimmed to 15 characters if need be) that is being executed by the current process.<br>
1909 <br>
1910 <a name="AFewOtherDetails"></a><font color="red"><b>A Few Other Details</b></font><br>
1911 <br>
1912 Kernel programming differs from user-space programming in many ways. We'll
1913 point things out as we get to them over the course of the book, but there are a few
1914 fundamental issues which, while not warranting a section of their own, are worth a
1915 mention. So, as you dig into the kernel, the following issues should be kept in mind.<br>
1916 <br>
1917 Applications are laid out in virtual memory with a very large stack area. The stack, of
1918 course, is used to hold the function call history and all automatic variables created by
1919 currently active functions. The kernel, instead, has a very small stack; it can be as
1920 small as a single, 4096-byte page. Your functions must share that stack with the
1921 entire kernel-space call chain. Thus, it is never a good idea to declare large automatic
1922 variables; if you need larger structures, you should allocate them dynamically
1923 at call time.<br>
1924 <br>
1925 Often, as you look at the kernel API, you will encounter function names starting with
1926 a double underscore (<font class="fixd">__</font>). Functions so marked are generally a low-level component
1927 of the interface and should be used with caution. Essentially, the double underscore
1928 says to the programmer: "If you call this function, be sure you know what you are
1929 doing."<br>
1930 <br>
1931 Kernel code cannot do floating point arithmetic. Enabling floating point would
1932 require that the kernel save and restore the floating point processor's state on each
1933 entry to, and exit from, kernel space--at least, on some architectures. Given that
1934 there really is no need for floating point in kernel code, the extra overhead is not
1935 worthwhile.<br>
1936 <br>
1937 <a name="CompilingAndLoading"></a><font color="red"><b>Compiling and Loading</b></font><br>
1938 <br>
1939 The "hello world" example at the beginning of this chapter included a brief demonstration
1940 of building a module and loading it into the system. There is, of course, a lot
1941 more to that whole process than we have seen so far. This section provides more
1942 detail on how a module author turns source code into an executing subsystem within
1943 the kernel.<br>
1944 <br>
1945 <A name="23"></a><font color="blue">PAGE 23</font><br>
1946 <br>
1947 <a name="CompilingModules"></a><font color="red"><b>Compiling Modules</b></font><br>
1948 <br>
1949 As the first step, we need to look a bit at how modules must be built. The build process
1950 for modules differs significantly from that used for user-space applications; the
1951 kernel is a large, stand alone program with detailed and explicit requirements on how
1952 its pieces are put together. The build process also differs from how things were done
1953 with previous versions of the kernel; the new build system is simpler to use and produces
1954 more correct results, but it looks very different from what came before. The
1955 kernel build system is a complex beast, and we just look at a tiny piece of it. The files
1956 found in the <i>Documentation/kbuild </i>directory in the kernel source are required reading
1957 for anybody wanting to understand all that is really going on beneath the surface.<br>
1958 <br>
1959 There are some prerequisites that you must get out of the way before you can build
1960 kernel modules. The first is to ensure that you have sufficiently current versions of the
1961 compiler, module utilities, and other necessary tools. The file <i>Documentation/Changes
1962 </i>in the kernel documentation directory always lists the required tool versions; you
1963 should consult it before going any further. Trying to build a kernel (and its modules)
1964 with the wrong tool versions can lead to no end of subtle, difficult problems. Note
1965 that, occasionally, a version of the compiler that is too new can be just as problematic
1966 as one that is too old; the kernel source makes a great many assumptions about the
1967 compiler, and new releases can sometimes break things for a while.<br>
1968 <br>
1969 If you still do not have a kernel tree handy, or have not yet configured and built that
1970 kernel, now is the time to go do it. You cannot build loadable modules for a 2.6 kernel
1971 without this tree on your filesystem. It is also helpful (though not required) to be
1972 actually running the kernel that you are building for.<br>
1973 <br>
1974 Once you have everything set up, creating a makefile for your module is straightforward.
1975 In fact, for the "hello world" example shown earlier in this chapter, a single
1976 line will suffice:<br>
1977 <pre>
1978 obj-m := hello.o
1979 </pre>
1980 Readers who are familiar with <i>make</i>, but not with the 2.6 kernel build system, are
1981 likely to be wondering how this makefile works. The above line is not how a traditional
1982 makefile looks, after all. The answer, of course, is that the kernel build system
1983 handles the rest. The assignment above (which takes advantage of the extended syntax
1984 provided by GNU <i>make</i>) states that there is one module to be built from the
1985 object file <i>hello.o</i>. The resulting module is named <i>hello.ko </i>after being built from the
1986 object file.<br>
1987 <br>
1988 If, instead, you have a module called <i>module.ko </i>that is generated from two source
1989 files (called, say, <i>file1.c</i> and <i>file2.c</i>), the correct incantation would be:<br>
1990 <pre>
1991 obj-m := module.o
1992 module-objs := file1.o file2.o
1993 </pre>
1994 For a makefile like those shown above to work, it must be invoked within the context
1995 of the larger kernel build system. If your kernel source tree is located in, say,<br>
1996 <br>
1997 <A name="24"></a><font color="blue">PAGE 24</font><br>
1998 <br>
1999 your <i>~/kernel-2.6 </i>directory, the <i>make </i>command required to build your module
2000 (typed in the directory containing the module source and makefile) would be:<br>
2001 <pre>
2002 make -C ~/kernel-2.6 M=`pwd` modules
2003 </pre>
2004 This command starts by changing its directory to the one provided with the <font class="fixd">-C</font>
2005 option (that is, your kernel source directory). There it finds the kernel's top-level
2006 makefile. The <font class="fixd">M=</font> option causes that makefile to move back into your module source
2007 directory before trying to build the <font class="fixd">modules</font> target. This target, in turn, refers to the list
2008 of modules found in the <font class="fixd">obj-m</font> variable, which we've set to <i>module.o</i> in our examples.<br>
2009 <br>
2010 Typing the previous <i>make </i>command can get tiresome after a while, so the kernel
2011 developers have developed a sort of makefile idiom, which makes life easier for those
2012 building modules outside of the kernel tree. The trick is to write your makefile as follows:<br>
2013 <pre>
2014 # If KERNELRELEASE is defined, we've been invoked from the
2015 # kernel build system and can use its language.
2016 ifneq ($(KERNELRELEASE),)
2017 obj-m := hello.o
2019 # Otherwise we were called directly from the command
2020 # line; invoke the kernel build system.
2021 else
2023 KERNELDIR ?= /lib/modules/$(shell uname -r)/build
2024 PWD := $(shell pwd)
2026 default:
2027 $(MAKE) -C $(KERNELDIR) M=$(PWD) modules
2029 endif
2030 </pre>
2031 Once again, we are seeing the extended GNU <i>make </i>syntax in action. This makefile is
2032 read twice on a typical build. When the makefile is invoked from the command line,
2033 it notices that the <font class="fixd">KERNELRELEASE</font> variable has not been set. It locates the kernel source
2034 directory by taking advantage of the fact that the symbolic link <i>build </i>in the installed
2035 modules directory points back at the kernel build tree. If you are not actually running
2036 the kernel that you are building for, you can supply a <font class="fixd">KERNELDIR=</font> option on the
2037 command line, set the <font class="fixd">KERNELDIR</font> environment variable, or rewrite the line that sets
2038 <font class="fixd">KERNELDIR</font> in the makefile. Once the kernel source tree has been found, the makefile
2039 invokes the default: target, which runs a second <i>make </i>command (parameterized in
2040 the makefile as <font class="fixd">$(MAKE))</font> to invoke the kernel build system as described previously.
2041 On the second reading, the makefile sets <font class="fixd">obj-m</font>, and the kernel makefiles take care of
2042 actually building the module.<br>
2043 <br>
2044 This mechanism for building modules may strike you as a bit unwieldy and obscure.
2045 Once you get used to it, however, you will likely appreciate the capabilities that have
2046 been programmed into the kernel build system. Do note that the above is not a complete
2047 makefile; a real makefile includes the usual sort of targets for cleaning up<br>
2048 <br>
2049 <A name="25"></a><font color="blue">PAGE 25</font><br>
2050 <br>
2051 unneeded files, installing modules, etc. See the makefiles in the example source
2052 directory for a complete example.<br>
2053 <br>
2054 <a name="LoadingAndUnloadingModules"></a><font color="red"><b>Loading and Unloading Modules</b></font><br>
2055 <br>
2056 After the module is built, the next step is loading it into the kernel. As we've already
2057 pointed out, <i>insmod </i>does the job for you. The program loads the module code and
2058 data into the kernel, which, in turn, performs a function similar to that of <i>ld</i>, in that
2059 it links any unresolved symbol in the module to the symbol table of the kernel.
2060 Unlike the linker, however, the kernel doesn't modify the module's disk file, but
2061 rather an in-memory copy. <i>insmod </i>accepts a number of command-line options (for
2062 details, see the manpage), and it can assign values to parameters in your module
2063 before linking it to the current kernel. Thus, if a module is correctly designed, it can
2064 be configured at load time; load-time configuration gives the user more flexibility
2065 than compile-time configuration, which is still used sometimes. Load-time configuration
2066 is explained in the section "Module Parameters," later in this chapter.<br>
2067 <br>
2068 Interested readers may want to look at how the kernel supports <i>insmod</i>: it relies on a
2069 system call defined in <i>kernel/module.c</i>. The function <i>sys_init_module </i>allocates kernel
2070 memory to hold a module (this memory is allocated with <i>vmalloc</i>; see the section
2071 "vmalloc and Friends" in Chapter 8); it then copies the module text into that memory
2072 region, resolves kernel references in the module via the kernel symbol table, and
2073 calls the module's initialization function to get everything going.<br>
2074 <br>
2075 If you actually look in the kernel source, you'll find that the names of the system calls
2076 are prefixed with <font class="fixd">sys_</font>. This is true for all system calls and no other functions; it's
2077 useful to keep this in mind when grepping for the system calls in the sources.<br>
2078 <br>
2079 The <i>modprobe </i>utility is worth a quick mention. <i>modprobe</i>, like <i>insmod</i>, loads a module
2080 into the kernel. It differs in that it will look at the module to be loaded to see
2081 whether it references any symbols that are not currently defined in the kernel. If any
2082 such references are found, <i>modprobe </i>looks for other modules in the current module
2083 search path that define the relevant symbols. When <i>modprobe </i>finds those modules
2084 (which are needed by the module being loaded), it loads them into the kernel as well.
2085 If you use <i>insmod </i>in this situation instead, the command fails with an "unresolved
2086 symbols" message left in the system logfile.<br>
2087 <br>
2088 As mentioned before, modules may be removed from the kernel with the <i>rmmod </i>utility.
2089 Note that module removal fails if the kernel believes that the module is still in
2090 use (e.g., a program still has an open file for a device exported by the modules), or if
2091 the kernel has been configured to disallow module removal. It is possible to configure
2092 the kernel to allow "forced" removal of modules, even when they appear to be
2093 busy. If you reach a point where you are considering using this option, however,
2094 things are likely to have gone wrong badly enough that a reboot may well be the better
2095 course of action.<br>
2096 <br>
2097 <A name="26"></a><font color="blue">PAGE 26</font><br>
2098 <br>
2099 The <i>lsmod </i>program produces a list of the modules currently loaded in the kernel.
2100 Some other information, such as any other modules making use of a specific module,
2101 is also provided. <i>lsmod </i>works by reading the <i>/proc/modules </i>virtual file. Information
2102 on currently loaded modules can also be found in the sysfs virtual filesystem
2103 under <i>/sys/module</i>.<br>
2104 <br>
2105 <a name="VersionDependency"></a><font color="red"><b>Version Dependency</b></font><br>
2106 <br>
2107 Bear in mind that your module's code has to be recompiled for each version of the
2108 kernel that it is linked to--at least, in the absence of modversions, not covered here
2109 as they are more for distribution makers than developers. Modules are strongly tied
2110 to the data structures and function prototypes defined in a particular kernel version;
2111 the interface seen by a module can change significantly from one kernel version to
2112 the next. This is especially true of development kernels, of course.<br>
2113 <br>
2114 The kernel does not just assume that a given module has been built against the
2115 proper kernel version. One of the steps in the build process is to link your module
2116 against a file (called <i>vermagic.o</i>) from the current kernel tree; this object contains a
2117 fair amount of information about the kernel the module was built for, including the
2118 target kernel version, compiler version, and the settings of a number of important
2119 configuration variables. When an attempt is made to load a module, this information
2120 can be tested for compatibility with the running kernel. If things don't match,
2121 the module is not loaded; instead, you see something like:<br>
2122 <pre>
2123 # <b>insmod hello.ko
2124 </b>Error inserting './hello.ko': -1 Invalid module format
2125 </pre>
2126 A look in the system log file (<i>/var/log/messages </i>or whatever your system is configured
2127 to use) will reveal the specific problem that caused the module to fail to load.<br>
2128 <br>
2129 If you need to compile a module for a specific kernel version, you will need to use the
2130 build system and source tree for that particular version. A simple change to the
2131 <font class="fixd">KERNELDIR</font> variable in the example makefile shown previously does the trick.<br>
2132 <br>
2133 Kernel interfaces often change between releases. If you are writing a module that is
2134 intended to work with multiple versions of the kernel (especially if it must work
2135 across major releases), you likely have to make use of macros and <font class="fixd">#ifdef</font> constructs
2136 to make your code build properly. This edition of this book only concerns itself with
2137 one major version of the kernel, so you do not often see version tests in our example
2138 code. But the need for them does occasionally arise. In such cases, you want to make
2139 use of the definitions found in <i>linux/version.h</i>. This header file defines the following macros:<br>
2140 <br>
2141 <A name="27"></a><font color="blue">PAGE 27</font><br>
2142 <br>
2143 <font class="fixd">UTS_RELEASE</font><br>
2144 <div class="bq">This macro expands to a string describing the version of this kernel tree. For
2145 example, "2.6.10".</div>
2146 <br>
2147 <font class="fixd">LINUX_VERSION_CODE</font><br>
2148 <div class="bq">This macro expands to the binary representation of the kernel version, one byte
2149 for each part of the version release number. For example, the code for 2.6.10 is
2150 132618 (i.e., 0x02060a).* With this information, you can (almost) easily determine
2151 what version of the kernel you are dealing with.</div>
2152 <br>
2153 <font class="fixd">KERNEL_VERSION(major,minor,release)</font><br>
2154 <div class="bq">This is the macro used to build an integer version code from the individual numbers
2155 that build up a version number. For example, <font class="fixd">KERNEL_VERSION(2,6,10)</font>
2156 expands to 132618. This macro is very useful when you need to compare the
2157 current version and a known checkpoint.</div>
2158 <br>
2159 Most dependencies based on the kernel version can be worked around with preprocessor
2160 conditionals by exploiting <font class="fixd">KERNEL_VERSION</font> and <font class="fixd">LINUX_VERSION_CODE</font>. Version
2161 dependency should, however, not clutter driver code with hairy <font class="fixd">#ifdef</font> conditionals;
2162 the best way to deal with incompatibilities is by confining them to a specific header
2163 file. As a general rule, code which is explicitly version (or platform) dependent
2164 should be hidden behind a low-level macro or function. High-level code can then
2165 just call those functions without concern for the low-level details. Code written in
2166 this way tends to be easier to read and more robust.<br>
2167 <br>
2168 <a name="PlatformDependency"></a><font color="red"><b>Platform Dependency</b></font><br>
2169 <br>
2170 Each computer platform has its peculiarities, and kernel designers are free to exploit
2171 all the peculiarities to achieve better performance in the target object file.<br>
2172 <br>
2173 Unlike application developers, who must link their code with precompiled libraries
2174 and stick to conventions on parameter passing, kernel developers can dedicate some
2175 processor registers to specific roles, and they have done so. Moreover, kernel code
2176 can be optimized for a specific processor in a CPU family to get the best from the target
2177 platform: unlike applications that are often distributed in binary format, a custom
2178 compilation of the kernel can be optimized for a specific computer set.<br>
2179 <br>
2180 For example, the IA32 (x86) architecture has been subdivided into several different
2181 processor types. The old 80386 processor is still supported (for now), even though
2182 its instruction set is, by modern standards, quite limited. The more modern processors
2183 in this architecture have introduced a number of new capabilities, including
2184 faster instructions for entering the kernel, interprocessor locking, copying data, etc.
2185 Newer processors can also, when operated in the correct mode, employ 36-bit (or<br>
2186 <br>
2187 * This allows up to 256 development versions between stable versions.<br>
2188 <br>
2189 <A name="28"></a><font color="blue">PAGE 28</font><br>
2190 <br>
2191 larger) physical addresses, allowing them to address more than 4 GB of physical
2192 memory. Other processor families have seen similar improvements. The kernel,
2193 depending on various configuration options, can be built to make use of these additional
2194 features.<br>
2195 <br>
2196 Clearly, if a module is to work with a given kernel, it must be built with the same
2197 understanding of the target processor as that kernel was. Once again, the <i>vermagic.o
2198 </i>object comes in to play. When a module is loaded, the kernel checks the processor specific
2199 configuration options for the module and makes sure they match the running
2200 kernel. If the module was compiled with different options, it is not loaded.<br>
2201 <br>
2202 If you are planning to write a driver for general distribution, you may well be wondering
2203 just how you can possibly support all these different variations. The best
2204 answer, of course, is to release your driver under a GPL-compatible license and contribute
2205 it to the mainline kernel. Failing that, distributing your driver in source form
2206 and a set of scripts to compile it on the user's system may be the best answer. Some
2207 vendors have released tools to make this task easier. If you must distribute your
2208 driver in binary form, you need to look at the different kernels provided by your target
2209 distributions, and provide a version of the module for each. Be sure to take into
2210 account any errata kernels that may have been released since the distribution was
2211 produced. Then, there are licensing issues to be considered, as we discussed in the
2212 section "License Terms" in Chapter 1. As a general rule, distributing things in source
2213 form is an easier way to make your way in the world.<br>
2214 <br>
2215 <a name="TheKernelSymbolTable"></a><font color="red"><b>The Kernel Symbol Table</b></font><br>
2216 <br>
2217 We've seen how <i>insmod </i>resolves undefined symbols against the table of public kernel
2218 symbols. The table contains the addresses of global kernel items--functions and
2219 variables--that are needed to implement modularized drivers. When a module is
2220 loaded, any symbol exported by the module becomes part of the kernel symbol table.
2221 In the usual case, a module implements its own functionality without the need to
2222 export any symbols at all. You need to export symbols, however, whenever other
2223 modules may benefit from using them.<br>
2224 <br>
2225 New modules can use symbols exported by your module, and you can stack new
2226 modules on top of other modules. Module stacking is implemented in the mainstream
2227 kernel sources as well: the <i>msdos </i>filesystem relies on symbols exported by the
2228 <i>fat</i> module, and each input USB device module stacks on the <i>usbcore</i> and <i>input</i> modules.<br>
2229 <br>
2230 Module stacking is useful in complex projects. If a new abstraction is implemented in
2231 the form of a device driver, it might offer a plug for hardware-specific implementations.
2232 For example, the video-for-linux set of drivers is split into a generic module that
2233 exports symbols used by lower-level device drivers for specific hardware. According to
2234 your setup, you load the generic video module and the specific module for your
2235 installed hardware. Support for parallel ports and the wide variety of attachable<br>
2236 <br>
2237 <A name="29"></a><font color="blue">PAGE 29</font><br>
2238 <br>
2239 devices is handled in the same way, as is the USB kernel subsystem. Stacking in the
2240 parallel port subsystem is shown in Figure 2-2; the arrows show the communications
2241 between the modules and with the kernel programming interface.<br>
2242 <br><br>
2243 <center>
2244 <img src="fig2-2.gif">
2245 </center>
2246 <br>
2247 <i>Figure 2-2. Stacking of parallel port driver modules</i><br>
2248 <br>
2249 When using stacked modules, it is helpful to be aware of the <i>modprobe </i>utility. As we
2250 described earlier, <i>modprobe </i>functions in much the same way as <i>insmod</i>, but it also
2251 loads any other modules that are required by the module you want to load. Thus,
2252 one <i>modprobe </i>command can sometimes replace several invocations of <i>insmod
2253 </i>(although you'll still need <i>insmod </i>when loading your own modules from the current
2254 directory, because <i>modprobe</i> looks only in the standard installed module directories).<br>
2255 <br>
2256 Using stacking to split modules into multiple layers can help reduce development
2257 time by simplifying each layer. This is similar to the separation between mechanism
2258 and policy that we discussed in Chapter 1.<br>
2259 <br>
2260 The Linux kernel header files provide a convenient way to manage the visibility of
2261 your symbols, thus reducing namespace pollution (filling the namespace with names
2262 that may conflict with those defined elsewhere in the kernel) and promoting proper
2263 information hiding. If your module needs to export symbols for other modules to
2264 use, the following macros should be used.<br>
2265 <pre>
2266 EXPORT_SYMBOL(name);
2267 EXPORT_SYMBOL_GPL(name);
2268 </pre>
2269 Either of the above macros makes the given symbol available outside the module.
2270 The <font class="fixd">_GPL</font> version makes the symbol available to GPL-licensed modules only. Symbols
2271 must be exported in the global part of the module's file, outside of any function,
2272 because the macros expand to the declaration of a special-purpose variable that
2273 is expected to be accessible globally. This variable is stored in a special part of the
2274 module executable (an "ELF section") that is used by the kernel at load time to find
2275 the variables exported by the module. (Interested readers can look at <i><linux/module.h>
2276 </i>for the details, even though the details are not needed to make things work.)<br>
2277 <br>
2278 <A name="30"></a><font color="blue">PAGE 30</font><br>
2279 <br>
2280 <a name="Preliminaries"></a><font color="red"><b>Preliminaries</b></font><br>
2281 <br>
2282 We are getting closer to looking at some actual module code. But first, we need to
2283 look at some other things that need to appear in your module source files. The kernel
2284 is a unique environment, and it imposes its own requirements on code that
2285 would interface with it.<br>
2286 <br>
2287 Most kernel code ends up including a fairly large number of header files to get definitions
2288 of functions, data types, and variables. We'll examine these files as we come to
2289 them, but there are a few that are specific to modules, and must appear in every loadable
2290 module. Thus, just about all module code has the following:<br>
2291 <pre>
2292 #include <linux/module.h>
2293 #include <linux/init.h>
2294 </pre>
2295 <i>module.h </i>contains a great many definitions of symbols and functions needed by loadable
2296 modules. You need <i>init.h </i>to specify your initialization and cleanup functions, as
2297 we saw in the "hello world" example above, and which we revisit in the next section.
2298 Most modules also include <i>moduleparam.h </i>to enable the passing of parameters
2299 to the module at load time; we will get to that shortly.<br>
2300 <br>
2301 It is not strictly necessary, but your module really should specify which license
2302 applies to its code. Doing so is just a matter of including a <font class="fixd">MODULE_LICENSE</font> line:<br>
2303 <pre>
2304 MODULE_LICENSE("GPL");
2305 </pre>
2306 The specific licenses recognized by the kernel are "GPL" (for any version of the GNU
2307 General Public License), "GPL v2" (for GPL version two only), "GPL and additional
2308 rights," "Dual BSD/GPL," "Dual MPL/GPL," and "Proprietary." Unless your module
2309 is explicitly marked as being under a free license recognized by the kernel, it is
2310 assumed to be proprietary, and the kernel is "tainted" when the module is loaded. As
2311 we mentioned in the section "License Terms" in Chapter 1, kernel developers tend to
2312 be unenthusiastic about helping users who experience problems after loading proprietary
2313 modules.<br>
2314 <br>
2315 Other descriptive definitions that can be contained within a module include
2316 <font class="fixd">MODULE_AUTHOR</font> (stating who wrote the module), <font class="fixd">MODULE_DESCRIPTION</font> (a human-readable
2317 statement of what the module does), <font class="fixd">MODULE_VERSION</font> (for a code revision number;
2318 see the comments in <i><linux/module.h> </i>for the conventions to use in creating
2319 version strings), <font class="fixd">MODULE_ALIAS</font> (another name by which this module can be known),
2320 and <font class="fixd">MODULE_DEVICE_TABLE</font> (to tell user space about which devices the module supports).
2321 We'll discuss <font class="fixd">MODULE_ALIAS</font> in Chapter 11 and <font class="fixd">MODULE_DEVICE_TABLE</font> in
2322 Chapter 12.<br>
2323 <br>
2324 The various <font class="fixd">MODULE_</font> declarations can appear anywhere within your source file outside
2325 of a function. A relatively recent convention in kernel code, however, is to put
2326 these declarations at the end of the file.<br>
2327 <br>
2328 <A name="31"></a><font color="blue">PAGE 31</font><br>
2329 <br>
2330 <a name="InitializationAndShutdown"></a><font color="red"><b>Initialization and Shutdown</b></font><br>
2331 <br>
2332 As already mentioned, the module initialization function registers any facility offered
2333 by the module. By <i>facility</i>, we mean a new functionality, be it a whole driver or a new
2334 software abstraction, that can be accessed by an application. The actual definition of
2335 the initialization function always looks like:<br>
2336 <pre>
2337 static int __init initialization_function(void)
2338 {
2339 /* Initialization code here */
2340 }
2341 module_init(initialization_function);
2342 </pre>
2343 Initialization functions should be declared static, since they are not meant to be visible
2344 outside the specific file; there is no hard rule about this, though, as no function is
2345 exported to the rest of the kernel unless explicitly requested. The <font class="fixd">__init</font> token in the
2346 definition may look a little strange; it is a hint to the kernel that the given function is
2347 used only at initialization time. The module loader drops the initialization function
2348 after the module is loaded, making its memory available for other uses. There is
2349 a similar tag (<font class="fixd">__initdata</font>) for data used only during initialization. Use of <font class="fixd">__init</font> and
2350 <font class="fixd">__initdata</font> is optional, but it is worth the trouble. Just be sure not to use them for
2351 any function (or data structure) you will be using after initialization completes. You
2352 may also encounter <font class="fixd">__devinit</font> and <font class="fixd">__devinitdata</font> in the kernel source; these translate
2353 to <font class="fixd">__init</font> and <font class="fixd">__initdata</font> only if the kernel has not been configured for hotpluggable
2354 devices. We will look at hotplug support in Chapter 14.<br>
2355 <br>
2356 The use of <i>module_init </i>is mandatory. This macro adds a special section to the module's
2357 object code stating where the module's initialization function is to be found.
2358 Without this definition, your initialization function is never called.<br>
2359 <br>
2360 Modules can register many different types of facilities, including different kinds of
2361 devices, filesystems, cryptographic transforms, and more. For each facility, there is a
2362 specific kernel function that accomplishes this registration. The arguments passed to
2363 the kernel registration functions are usually pointers to data structures describing the
2364 new facility and the name of the facility being registered. The data structure usually
2365 contains pointers to module functions, which is how functions in the module body
2366 get called.<br>
2367 <br>
2368 The items that can be registered go beyond the list of device types mentioned in
2369 Chapter 1. They include, among others, serial ports, miscellaneous devices, sysfs
2370 entries, <i>/proc </i>files, executable domains, and line disciplines. Many of those registrable
2371 items support functions that aren't directly related to hardware but remain in the
2372 "software abstractions" field. Those items can be registered, because they are integrated
2373 into the driver's functionality anyway (like <i>/proc </i>files and line disciplines for
2374 example).<br>
2375 <br>
2376 <A name="32"></a><font color="blue">PAGE 32</font><br>
2377 <br>
2378 There are other facilities that can be registered as add-ons for certain drivers, but
2379 their use is so specific that it's not worth talking about them; they use the stacking
2380 technique, as described in the section "The Kernel Symbol Table." If you want to
2381 probe further, you can grep for <font class="fixd">EXPORT_SYMBOL</font> in the kernel sources, and find the
2382 entry points offered by different drivers. Most registration functions are prefixed with
2383 <font class="fixd">register_</font>, so another possible way to find them is to grep for <font class="fixd">register_</font> in the kernel
2384 source.<br>
2385 <br>
2386 <a name="TheCleanupFunction"></a><font color="red"><b>The Cleanup Function</b></font><br>
2387 <br>
2388 Every nontrivial module also requires a cleanup function, which unregisters interfaces
2389 and returns all resources to the system before the module is removed. This
2390 function is defined as:<br>
2391 <pre>
2392 static void __exit cleanup_function(void)
2393 {
2394 /* Cleanup code here */
2395 }
2397 module_exit(cleanup_function);
2398 </pre>
2399 The cleanup function has no value to return, so it is declared void. The <font class="fixd">__exit</font> modifier
2400 marks the code as being for module unload only (by causing the compiler to
2401 place it in a special ELF section). If your module is built directly into the kernel,
2402 or if your kernel is configured to disallow the unloading of modules, functions
2403 marked <font class="fixd">__exit</font> are simply discarded. For this reason, a function marked <font class="fixd">__exit</font> can
2404 be called <i>only </i>at module unload or system shutdown time; any other use is an error.
2405 Once again, the <i>module_exit </i>declaration is necessary to enable the kernel to find your
2406 cleanup function.<br>
2407 <br>
2408 If your module does not define a cleanup function, the kernel does not allow it to be
2409 unloaded.<br>
2410 <br>
2411 <a name="ErrorHandlingDuringInitialization"></a><font color="red"><b>Error Handling During Initialization</b></font><br>
2412 <br>
2413 One thing you must always bear in mind when registering facilities with the kernel
2414 is that the registration could fail. Even the simplest action often requires memory
2415 allocation, and the required memory may not be available. So module code must
2416 always check return values, and be sure that the requested operations have actually
2417 succeeded.<br>
2418 <br>
2419 If any errors occur when you register utilities, the first order of business is to decide
2420 whether the module can continue initializing itself anyway. Often, the module can
2421 continue to operate after a registration failure, with degraded functionality if necessary.
2422 Whenever possible, your module should press forward and provide what capabilities
2423 it can after things fail.<br>
2424 <br>
2425 <A name="33"></a><font color="blue">PAGE 33</font><br>
2426 <br>
2427 If it turns out that your module simply cannot load after a particular type of failure,
2428 you must undo any registration activities performed before the failure. Linux doesn't
2429 keep a per-module registry of facilities that have been registered, so the module must
2430 back out of everything itself if initialization fails at some point. If you ever fail to
2431 unregister what you obtained, the kernel is left in an unstable state; it contains internal
2432 pointers to code that no longer exists. In such situations, the only recourse, usually,
2433 is to reboot the system. You really do want to take care to do the right thing
2434 when an initialization error occurs.<br>
2435 <br>
2436 Error recovery is sometimes best handled with the goto statement. We normally hate
2437 to use goto, but in our opinion, this is one situation where it is useful. Careful use of
2438 goto in error situations can eliminate a great deal of complicated, highly-indented,
2439 "structured" logic. Thus, in the kernel, goto is often used as shown here to deal with
2440 errors.<br>
2441 <br>
2442 The following sample code (using fictitious registration and unregistration functions)
2443 behaves correctly if initialization fails at any point:<br>
2444 <pre>
2445 int __init my_init_function(void)
2446 {
2447 int err;
2449 /* registration takes a pointer and a name */
2450 err = register_this(ptr1, "skull");
2451 if (err) goto fail_this;
2452 err = register_that(ptr2, "skull");
2453 if (err) goto fail_that;
2454 err = register_those(ptr3, "skull");
2455 if (err) goto fail_those;
2457 return 0; /* success */
2459 fail_those: unregister_that(ptr2, "skull");
2460 fail_that: unregister_this(ptr1, "skull");
2461 fail_this: return err; /* propagate the error */
2462 }
2463 </pre>
2464 This code attempts to register three (fictitious) facilities. The goto statement is used
2465 in case of failure to cause the unregistration of only the facilities that had been successfully
2466 registered before things went bad.<br>
2467 <br>
2468 Another option, requiring no hairy goto statements, is keeping track of what has
2469 been successfully registered and calling your module's cleanup function in case of
2470 any error. The cleanup function unrolls only the steps that have been successfully
2471 accomplished. This alternative, however, requires more code and more CPU time, so
2472 in fast paths you still resort to goto as the best error-recovery tool.<br>
2473 <br>
2474 The return value of <i>my_init_function</i>, err, is an error code. In the Linux kernel, error
2475 codes are negative numbers belonging to the set defined in <i><linux/errno.h></i>. If you
2476 want to generate your own error codes instead of returning what you get from other<br>
2477 <br>
2478 <A name="34"></a><font color="blue">PAGE 34</font><br>
2479 <br>
2480 functions, you should include <i><linux/errno.h> </i>in order to use symbolic values such
2481 as <font class="fixd">-ENODEV, -ENOMEM,</font> and so on. It is always good practice to return appropriate error
2482 codes, because user programs can turn them to meaningful strings using <i>perror </i>or
2483 similar means.<br>
2484 <br>
2485 Obviously, the module cleanup function must undo any registration performed by
2486 the initialization function, and it is customary (but not usually mandatory) to unregister
2487 facilities in the reverse order used to register them:<br>
2488 <pre>
2489 void __exit my_cleanup_function(void)
2490 {
2491 unregister_those(ptr3, "skull");
2492 unregister_that(ptr2, "skull");
2493 unregister_this(ptr1, "skull");
2494 return;
2495 }
2496 </pre>
2497 If your initialization and cleanup are more complex than dealing with a few items,
2498 the goto approach may become difficult to manage, because all the cleanup code
2499 must be repeated within the initialization function, with several labels intermixed.
2500 Sometimes, therefore, a different layout of the code proves more successful.<br>
2501 <br>
2502 What you'd do to minimize code duplication and keep everything streamlined is to
2503 call the cleanup function from within the initialization whenever an error occurs.
2504 The cleanup function then must check the status of each item before undoing its registration.
2505 In its simplest form, the code looks like the following:<br>
2506 <pre>
2507 struct something *item1;
2508 struct somethingelse *item2;
2509 int stuff_ok;
2511 void my_cleanup(void)
2512 {
2513 if (item1)
2514 release_thing(item1);
2515 if (item2)
2516 release_thing2(item2);
2517 if (stuff_ok)
2518 unregister_stuff( );
2519 return;
2520 }
2522 int __init my_init(void)
2523 {
2524 int err = -ENOMEM;
2526 item1 = allocate_thing(arguments);
2527 item2 = allocate_thing2(arguments2);
2528 if (!item1 || !item2)
2529 goto fail;
2530 err = register_stuff(item1, item2);
2531 if (!err)
2532 </pre>
2533 <A name="35"></a><font color="blue">PAGE 35</font>
2534 <pre>
2535 stuff_ok = 1;
2536 else
2537 goto fail;
2538 return 0; /* success */
2540 fail:
2541 my_cleanup( );
2542 return err;
2543 }
2544 </pre>
2545 As shown in this code, you may or may not need external flags to mark success of the
2546 initialization step, depending on the semantics of the registration/allocation function
2547 you call. Whether or not flags are needed, this kind of initialization scales well to a
2548 large number of items and is often better than the technique shown earlier. Note,
2549 however, that the cleanup function cannot be marked <font class="fixd">__exit</font> when it is called by
2550 nonexit code, as in the previous example.<br>
2551 <br>
2552 <a name="ModuleLoadingRaces"></a><font color="red"><b>Module-Loading Races</b></font><br>
2553 <br>
2554 Thus far, our discussion has skated over an important aspect of module loading: race
2555 conditions. If you are not careful in how you write your initialization function, you
2556 can create situations that can compromise the stability of the system as a whole. We
2557 will discuss race conditions later in this book; for now, a couple of quick points will
2558 have to suffice.<br>
2559 <br>
2560 The first is that you should always remember that some other part of the kernel can
2561 make use of any facility you register immediately after that registration has completed.
2562 It is entirely possible, in other words, that the kernel will make calls into your
2563 module while your initialization function is still running. So your code must be prepared
2564 to be called as soon as it completes its first registration. Do not register any
2565 facility until all of your internal initialization needed to support that facility has been
2566 completed.<br>
2567 <br>
2568 You must also consider what happens if your initialization function decides to fail,
2569 but some part of the kernel is already making use of a facility your module has registered.
2570 If this situation is possible for your module, you should seriously consider not
2571 failing the initialization at all. After all, the module has clearly succeeded in exporting
2572 something useful. If initialization must fail, it must carefully step around any possible
2573 operations going on elsewhere in the kernel until those operations have
2574 completed.<br>
2575 <br>
2576 <a name="ModuleParameters"></a><font color="red"><b>Module Parameters</b></font><br>
2577 <br>
2578 Several parameters that a driver needs to know can change from system to system.
2579 These can vary from the device number to use (as we'll see in the next chapter) to
2580 numerous aspects of how the driver should operate. For example, drivers for SCSI<br>
2581 <br>
2582 <A name="36"></a><font color="blue">PAGE 36</font><br>
2583 <br>
2584 adapters often have options controlling the use of tagged command queuing, and the
2585 Integrated Device Electronics (IDE) drivers allow user control of DMA operations. If
2586 your driver controls older hardware, it may also need to be told explicitly where to
2587 find that hardware's I/O ports or I/O memory addresses. The kernel supports these
2588 needs by making it possible for a driver to designate parameters that may be changed
2589 when the driver's module is loaded.<br>
2590 <br>
2591 These parameter values can be assigned at load time by <i>insmod </i>or <i>modprobe</i>; the latter
2592 can also read parameter assignment from its configuration file (<i>/etc/modprobe.
2593 conf</i>). The commands accept the specification of several types of values on the command
2594 line. As a way of demonstrating this capability, imagine a much-needed
2595 enhancement to the "hello world" module (called <i>hellop</i>) shown at the beginning of
2596 this chapter. We add two parameters: an integer value called <font class="fixd">howmany</font> and a character
2597 string called <font class="fixd">whom</font>. Our vastly more functional module then, at load time, greets <font class="fixd">whom</font>
2598 not just once, but <font class="fixd">howmany</font> times. Such a module could then be loaded with a command
2599 line such as:<br>
2600 <pre>
2601 insmod hellop howmany=10 whom="Mom"
2602 </pre>
2603 Upon being loaded that way, <i>hellop</i> would say "Hello, Mom" 10 times.<br>
2604 <br>
2605 However, before <i>insmod </i>can change module parameters, the module must make
2606 them available. Parameters are declared with the <font class="fixd">module_param</font> macro, which is
2607 defined in <i>moduleparam.h</i>. <font class="fixd">module_param</font> takes three parameters: the name of the
2608 variable, its type, and a permissions mask to be used for an accompanying sysfs
2609 entry. The macro should be placed outside of any function and is typically found
2610 near the head of the source file. So <i>hellop </i>would declare its parameters and make
2611 them available to <i>insmod</i> as follows:<br>
2612 <pre>
2613 static char *whom = "world";
2614 static int howmany = 1;
2615 module_param(howmany, int, S_IRUGO);
2616 module_param(whom, charp, S_IRUGO);
2617 </pre>
2618 Numerous types are supported for module parameters:<br>
2619 <br>
2620 <font class="fixd">bool<br>
2621 invbool</font><br>
2622 <div class="bq">A boolean (true or false) value (the associated variable should be of type <font class="fixd">int</font>).
2623 The <font class="fixd">invbool</font> type inverts the value, so that true values become false and vice
2624 versa.</div>
2625 <font class="fixd">charp</font><br>
2626 <div class="bq">A char pointer value. Memory is allocated for user-provided strings, and the
2627 pointer is set accordingly.</div>
2628 <br>
2629 <A name="37"></a><font color="blue">PAGE 37</font><br>
2630 <br>
2631 <font class="fixd">int<br>
2632 long<br>
2633 short<br>
2634 uint<br>
2635 ulong<br>
2636 ushort</font><br>
2637 <div class="bq">Basic integer values of various lengths. The versions starting with <font class="fixd">u</font> are for
2638 unsigned values.</div>
2639 <br>
2640 Array parameters, where the values are supplied as a comma-separated list, are also
2641 supported by the module loader. To declare an array parameter, use:<br>
2642 <pre>
2643 module_param_array(name,type,nump,perm);
2644 </pre>
2645 Where <font class="fixd">name</font> is the name of your array (and of the parameter), <font class="fixd">type</font> is the type of the
2646 array elements, <font class="fixd">nump</font> is a pointer to an integer variable, and <font class="fixd">perm</font> is the usual permissions value. If
2647 the array parameter is set at load time, <font class="fixd">nump</font> is set to the number of values supplied.
2648 The module loader refuses to accept more values than will fit in the array.<br>
2649 <br>
2650 If you really need a type that does not appear in the list above, there are hooks in the
2651 module code that allow you to define them; see <i>moduleparam.h </i>for details on how to
2652 do that. All module parameters should be given a default value; <i>insmod </i>changes the
2653 value only if explicitly told to by the user. The module can check for explicit parameters
2654 by testing parameters against their default values.<br>
2655 <br>
2656 The final <i>module_param </i>field is a permission value; you should use the definitions
2657 found in <i><linux/stat.h></i>. This value controls who can access the representation of the
2658 module parameter in sysfs. If perm is set to 0, there is no sysfs entry at all; otherwise,
2659 it appears under <i>/sys/module</i>* with the given set of permissions. Use <font class="fixd">S_IRUGO</font> for a
2660 parameter that can be read by the world but cannot be changed; <font class="fixd">S_IRUGO|S_IWUSR</font>
2661 allows root to change the parameter. Note that if a parameter is changed by sysfs, the
2662 value of that parameter as seen by your module changes, but your module is not
2663 notified in any other way. You should probably not make module parameters writable,
2664 unless you are prepared to detect the change and react accordingly.<br>
2665 <br>
2666 <a name="DoingItInUserSpace"></a><font color="red"><b>Doing It in User Space</b></font><br>
2667 <br>
2668 A Unix programmer who's addressing kernel issues for the first time might be nervous
2669 about writing a module. Writing a user program that reads and writes directly
2670 to the device ports may be easier.<br>
2671 <br>
2672 Indeed, there are some arguments in favor of user-space programming, and sometimes
2673 writing a so-called user-space device driver is a wise alternative to kernel hacking.
2674 In this section, we discuss some of the reasons why you might write a driver in<br>
2675 <br>
2676 * As of this writing, there is talk of moving parameters elsewhere within <font class="fixd">sysfs</font>, however.<br>
2677 <br>
2678 <A name="38"></a><font color="blue">PAGE 38</font><br>
2679 <br>
2680 user space. This book is about kernel-space drivers, however, so we do not go
2681 beyond this introductory discussion.<br>
2682 <br>
2683 The advantages of user-space drivers are:<br>
2684 <ul>
2685 <li> The full C library can be linked in. The driver can perform many exotic tasks without resorting to external programs (the utility programs implementing usage policies that are usually distributed along with the driver itself).
2686 <li> The programmer can run a conventional debugger on the driver code without having to go through contortions to debug a running kernel.
2687 <li> If a user-space driver hangs, you can simply kill it. Problems with the driver are unlikely to hang the entire system, unless the hardware being controlled is <i>really </i>misbehaving.
2688 <li> User memory is swappable, unlike kernel memory. An infrequently used device with a huge driver won't occupy RAM that other programs could be using, except when it is actually in use.
2689 <li> A well-designed driver program can still, like kernel-space drivers, allow concurrent access to a device.
2690 <li> If you must write a closed-source driver, the user-space option makes it easier for you to avoid ambiguous licensing situations and problems with changing kernel interfaces.
2691 </ul>
2692 For example, USB drivers can be written for user space; see the (still young) libusb
2693 project at libusb.sourceforge.net and "gadgetfs" in the kernel source. Another example
2694 is the X server: it knows exactly what the hardware can do and what it can't, and
2695 it offers the graphic resources to all X clients. Note, however, that there is a slow but
2696 steady drift toward frame-buffer-based graphics environments, where the X server
2697 acts only as a server based on a real kernel-space device driver for actual graphic
2698 manipulation.<br>
2699 <br>
2700 Usually, the writer of a user-space driver implements a server process, taking over
2701 from the kernel the task of being the single agent in charge of hardware control. Client
2702 applications can then connect to the server to perform actual communication
2703 with the device; therefore, a smart driver process can allow concurrent access to the
2704 device. This is exactly how the X server works.<br>
2705 <br>
2706 But the user-space approach to device driving has a number of drawbacks. The most
2707 important are:<br>
2708 <ul>
2709 <li> Interrupts are not available in user space. There are work-arounds for this limitation on some platforms, such as the <i>vm86</i> system call on the IA32 architecture.
2710 <li> Direct access to memory is possible only by <i>mmap</i>ping <i>/dev/mem</i>, and only a privileged user can do that.
2711 <li> Access to I/O ports is available only after calling <i>ioperm </i>or <i>iopl</i>. Moreover, not all platforms support these system calls, and access to <i>/dev/port </i>can be too slow
2712 </ul>
2713 <A name="39"></a><font color="blue">PAGE 39</font>
2714 <ul>
2715 to be effective. Both the system calls and the device file are reserved to a privileged user.
2716 <li> Response time is slower, because a context switch is required to transfer information or actions between the client and the hardware.
2717 <li> Worse yet, if the driver has been swapped to disk, response time is unacceptably long. Using the <i>mlock </i>system call might help, but usually you'll need to lock many memory pages, because a user-space program depends on a lot of library code. <i>mlock</i>, too, is limited to privileged users.
2718 <li> The most important devices can't be handled in user space, including, but not limited to, network interfaces and block devices.
2719 </ul>
2720 As you see, user-space drivers can't do that much after all. Interesting applications
2721 nonetheless exist: for example, support for SCSI scanner devices (implemented by
2722 the <i>SANE </i>package) and CD writers (implemented by <i>cdrecord </i>and other tools). In
2723 both cases, user-level device drivers rely on the "SCSI generic" kernel driver, which
2724 exports low-level SCSI functionality to user-space programs so they can drive their
2725 own hardware.<br>
2726 <br>
2727 One case in which working in user space might make sense is when you are beginning
2728 to deal with new and unusual hardware. This way you can learn to manage your
2729 hardware without the risk of hanging the whole system. Once you've done that,
2730 encapsulating the software in a kernel module should be a painless operation.<br>
2731 <br>
2732 <a name="QuickReference2"></a><font color="red"><b>Quick Reference</b></font><br>
2733 <br>
2734 This section summarizes the kernel functions, variables, macros, and <i>/proc </i>files that
2735 we've touched on in this chapter. It is meant to act as a reference. Each item is listed
2736 after the relevant header file, if any. A similar section appears at the end of almost
2737 every chapter from here on, summarizing the new symbols introduced in the chapter.
2738 Entries in this section generally appear in the same order in which they were
2739 introduced in the chapter:<br>
2740 <br>
2741 <i>insmod<br>
2742 modprobe<br>
2743 rmmod</i><br>
2744 <div class="bq">User-space utilities that load modules into the running kernels and remove them.</div>
2745 <br>
2746 <font class="fixd">#include <linux/init.h><br>
2747 module_init(init_function);<br>
2748 module_exit(cleanup_function);<br></font>
2749 <div class="bq">Macros that designate a module's initialization and cleanup functions.</div>
2750 <br>
2751 <A name="40"></a><font color="blue">PAGE 40</font><br>
2752 <br>
2753 <font class="fixd">__init<br>
2754 __initdata<br>
2755 __exit<br>
2756 __exitdata</font><br>
2757 <div class="bq">Markers for functions (<font class="fixd">__init</font> and <font class="fixd">__exit</font>) and data (<font class="fixd">__initdata</font> and <font class="fixd">__exitdata</font>)
2758 that are only used at module initialization or cleanup time. Items marked for initialization
2759 may be discarded once initialization completes; the exit items may be
2760 discarded if module unloading has not been configured into the kernel. These
2761 markers work by causing the relevant objects to be placed in a special ELF section
2762 in the executable file.</div>
2763 <br>
2764 <font class="fixd">#include <linux/sched.h></font><br>
2765 <div class="bq">One of the most important header files. This file contains definitions of much of
2766 the kernel API used by the driver, including functions for sleeping and numerous
2767 variable declarations.</div>
2768 <br>
2769 <font class="fixd">struct task_struct *current;</font><br>
2770 <div class="bq">The current process.</div>
2771 <br>
2772 <font class="fixd">current->pid<br>
2773 current->comm</font><br>
2774 <div class="bq">The process ID and command name for the current process.</div>
2775 <br>
2776 <font class="fixd">obj-m</font><br>
2777 <div class="bq">A makefile symbol used by the kernel build system to determine which modules
2778 should be built in the current directory.</div>
2779 <br>
2780 <i>/sys/module<br>
2781 /proc/modules</i><br>
2782 <div class="bq"><i>/sys/module </i>is a sysfs directory hierarchy containing information on currently loaded
2783 modules. <i>/proc/modules </i>is the older, single-file version of that information.
2784 Entries contain the module name, the amount of memory each module
2785 occupies, and the usage count. Extra strings are appended to each line to specify
2786 flags that are currently active for the module.</div>
2787 <br>
2788 <i>vermagic.o</i><br>
2789 <div class="bq">An object file from the kernel source directory that describes the environment a
2790 module was built for.</div>
2791 <br>
2792 <font class="fixd">#include <linux/module.h></font><br>
2793 <div class="bq">Required header. It must be included by a module source.</div>
2794 <br>
2795 <font class="fixd">#include <linux/version.h></font><br>
2796 <div class="bq">A header file containing information on the version of the kernel being built.</div>
2797 <br>
2798 <font class="fixd">LINUX_VERSION_CODE</font><br>
2799 <div class="bq">Integer macro, useful to <font class="fixd">#ifdef</font> version dependencies.</div>
2800 <br>
2801 <A name="41"></a><font color="blue">PAGE 41</font><br>
2802 <br>
2803 <font class="fixd">EXPORT_SYMBOL (symbol);<br>
2804 EXPORT_SYMBOL_GPL (symbol);</font><br>
2805 <div class="bq">Macro used to export a symbol to the kernel. The second form exports without
2806 using versioning information, and the third limits the export to GPL-licensed
2807 modules.</div>
2808 <br>
2809 <font class="fixd">MODULE_AUTHOR(author);<br>
2810 MODULE_DESCRIPTION(description);<br>
2811 MODULE_VERSION(version_string);<br>
2812 MODULE_DEVICE_TABLE(table_info);<br>
2813 MODULE_LICENSE(license);<br>
2814 MODULE_ALIAS(alternate_name);</font><br>
2815 <div class="bq">Place documentation on the module in the object file.</div>
2816 <br>
2817 <font class="fixd">module_init(init_function);<br>
2818 module_exit(exit_function);</font><br>
2819 <div class="bq">Macros that declare a module's initialization and cleanup functions.</div>
2820 <br>
2821 <font class="fixd">#include <linux/moduleparam.h><br>
2822 module_param(variable, type, perm);</font><br>
2823 <div class="bq">Macro that creates a module parameter that can be adjusted by the user when
2824 the module is loaded (or at boot time for built-in code). The type can be one of
2825 <font class="fixd">bool, charp, int, invbool, long, short, ushort, uint, ulong,</font> or <font class="fixd">intarray.</font></div>
2826 <br>
2827 <font class="fixd">#include <linux/kernel.h><br>
2828 int printk(const char * fmt, ...);</font><br>
2829 <div class="bq">The analogue of <i>printf</i> for kernel code.</div>
2830 <br>
2831 <A name="42"></a><font color="blue">PAGE 42</font><br>
2832 <br>
2833 <a name="CHAPTER3"></a><font color="red"><b>CHAPTER 3</b></font><br>
2834 <br>
2835 <a name="CharDrivers"></a><font color="#7519FF" size="+1"><b>Char Drivers</b></font><br>
2836 <br>
2837 The goal of this chapter is to write a complete char device driver. We develop a character
2838 driver because this class is suitable for most simple hardware devices. Char
2839 drivers are also easier to understand than block drivers or network drivers (which we
2840 get to in later chapters). Our ultimate aim is to write a <i>modularized </i>char driver, but
2841 we won't talk about modularization issues in this chapter.<br>
2842 <br>
2843 Throughout the chapter, we present code fragments extracted from a real device
2844 driver: <i>scull </i>(Simple Character Utility for Loading Localities). <i>scull </i>is a char driver
2845 that acts on a memory area as though it were a device. In this chapter, because of
2846 that peculiarity of <i>scull</i>, we use the word <i>device </i>interchangeably with "the memory
2847 area used by <i>scull</i>."<br>
2848 <br>
2849 The advantage of <i>scull </i>is that it isn't hardware dependent. <i>scull </i>just acts on some
2850 memory, allocated from the kernel. Anyone can compile and run <i>scull</i>, and <i>scull </i>is
2851 portable across the computer architectures on which Linux runs. On the other hand,
2852 the device doesn't do anything "useful" other than demonstrate the interface
2853 between the kernel and char drivers and allow the user to run some tests.<br>
2854 <br>
2855 <a name="TheDesignOfScull"></a><font color="red"><b>The Design of scull</b></font><br>
2856 <br>
2857 The first step of driver writing is defining the capabilities (the mechanism) the driver
2858 will offer to user programs. Since our "device" is part of the computer's memory,
2859 we're free to do what we want with it. It can be a sequential or random-access
2860 device, one device or many, and so on.<br>
2861 <br>
2862 To make <i>scull </i>useful as a template for writing real drivers for real devices, we'll show
2863 you how to implement several device abstractions on top of the computer memory,
2864 each with a different personality.<br>
2865 <br>
2866 The <i>scull </i>source implements the following devices. Each kind of device implemented
2867 by the module is referred to as a <i>type</i>.<br>
2868 <br>
2869 <A name="43"></a><font color="blue">PAGE 43</font><br>
2870 <br>
2871 <i>scull0 to scull3</i><br>
2872 <div class="bq">Four devices, each consisting of a memory area that is both global and persistent.
2873 Global means that if the device is opened multiple times, the data contained
2874 within the device is shared by all the file descriptors that opened it.
2875 Persistent means that if the device is closed and reopened, data isn't lost. This
2876 device can be fun to work with, because it can be accessed and tested using conventional
2877 commands, such as <i>cp</i>, <i>cat</i>, and shell I/O redirection.</div>
2878 <br>
2879 <i>scullpipe0 to scullpipe3</i><br>
2880 <div class="bq">Four FIFO (first-in-first-out) devices, which act like pipes. One process reads
2881 what another process writes. If multiple processes read the same device, they
2882 contend for data. The internals of <i>scullpipe </i>will show how blocking and nonblocking
2883 <i>read </i>and <i>write </i>can be implemented without having to resort to interrupts.
2884 Although real drivers synchronize with their devices using hardware
2885 interrupts, the topic of blocking and nonblocking operations is an important one
2886 and is separate from interrupt handling (covered in Chapter 10).</div>
2887 <br>
2888 <i>scullsingle<br>
2889 scullpriv<br>
2890 sculluid<br>
2891 scullwuid</i><br>
2892 <div class="bq">These devices are similar to <i>scull0 </i>but with some limitations on when an <i>open </i>is
2893 permitted. The first (<i>scullsingle</i>) allows only one process at a time to use the
2894 driver, whereas <i>scullpriv </i>is private to each virtual console (or X terminal session),
2895 because processes on each console/terminal get different memory areas.
2896 <i>sculluid </i>and <i>scullwuid </i>can be opened multiple times, but only by one user at a
2897 time; the former returns an error of "Device Busy" if another user is locking the
2898 device, whereas the latter implements blocking <i>open</i>. These variations of <i>scull
2899 </i>would appear to be confusing policy and mechanism, but they are worth looking
2900 at, because some real-life devices require this sort of management.</div>
2901 <br>
2902 Each of the <i>scull </i>devices demonstrates different features of a driver and presents different
2903 difficulties. This chapter covers the internals of <i>scull0 </i>to <i>scull3</i>; the more
2904 advanced devices are covered in Chapter 6. <i>scullpipe </i>is described in the section "A
2905 Blocking I/O Example," and the others are described in "Access Control on a Device
2906 File."<br>
2907 <br>
2908 <a name="MajorAndMinorNumbers"></a><font color="red"><b>Major and Minor Numbers</b></font><br>
2909 <br>
2910 Char devices are accessed through names in the filesystem. Those names are called
2911 special files or device files or simply nodes of the filesystem tree; they are conventionally
2912 located in the <i>/dev </i>directory. Special files for char drivers are identified by a "c"
2913 in the first column of the output of <i>ls -l</i>. Block devices appear in <i>/dev </i>as well, but
2914 they are identified by a "b." The focus of this chapter is on char devices, but much of
2915 the following information applies to block devices as well.<br>
2916 <br>
2917 <A name="44"></a><font color="blue">PAGE 44</font><br>
2918 <br>
2919 If you issue the <i>ls -l </i>command, you'll see two numbers (separated by a comma) in
2920 the device file entries before the date of the last modification, where the file length
2921 normally appears. These numbers are the major and minor device number for the
2922 particular device. The following listing shows a few devices as they appear on a typical
2923 system. Their major numbers are 1, 4, 7, and 10, while the minors are 1, 3, 5, 64,
2924 65, and 129.<br>
2925 <pre>
2926 crw-rw-rw- 1 root root 1, 3 Apr 11 2002 null
2927 crw------- 1 root root 10, 1 Apr 11 2002 psaux
2928 crw------- 1 root root 4, 1 Oct 28 03:04 tty1
2929 crw-rw-rw- 1 root tty 4, 64 Apr 11 2002 ttys0
2930 crw-rw---- 1 root uucp 4, 65 Apr 11 2002 ttyS1
2931 crw--w---- 1 vcsa tty 7, 1 Apr 11 2002 vcs1
2932 crw--w---- 1 vcsa tty 7, 129 Apr 11 2002 vcsa1
2933 crw-rw-rw- 1 root root 1, 5 Apr 11 2002 zero
2934 </pre>
2935 Traditionally, the major number identifies the driver associated with the device. For
2936 example, <i>/dev/null </i>and <i>/dev/zero </i>are both managed by driver 1, whereas virtual consoles
2937 and serial terminals are managed by driver 4; similarly, both <i>vcs1 </i>and <i>vcsa1
2938 </i>devices are managed by driver 7. Modern Linux kernels allow multiple drivers to
2939 share major numbers, but most devices that you will see are still organized on the
2940 one-major-one-driver principle.<br>
2941 <br>
2942 The minor number is used by the kernel to determine exactly which device is being
2943 referred to. Depending on how your driver is written (as we will see below), you can
2944 either get a direct pointer to your device from the kernel, or you can use the minor
2945 number yourself as an index into a local array of devices. Either way, the kernel itself
2946 knows almost nothing about minor numbers beyond the fact that they refer to
2947 devices implemented by your driver.<br>
2948 <br>
2949 <a name="TheInternalRepresentationOfDeviceNumbers"></a><font color="red"><b>The Internal Representation of Device Numbers</b></font><br>
2950 <br>
2951 Within the kernel, the <font class="fixd">dev_t</font> type (defined in <i><linux/types.h></i>) is used to hold device
2952 numbers--both the major and minor parts. As of Version 2.6.0 of the kernel, <font class="fixd">dev_t</font> is
2953 a 32-bit quantity with 12 bits set aside for the major number and 20 for the minor
2954 number. Your code should, of course, never make any assumptions about the internal
2955 organization of device numbers; it should, instead, make use of a set of macros
2956 found in <i><linux/kdev_t.h></i>. To obtain the major or minor parts of a <font class="fixd">dev_t</font>, use:<br>
2957 <pre>
2958 MAJOR(dev_t dev);
2959 MINOR(dev_t dev);
2960 </pre>
2961 If, instead, you have the major and minor numbers and need to turn them into a <font class="fixd">dev_t</font>,
2962 use:<br>
2963 <pre>
2964 MKDEV(int major, int minor);
2965 </pre>
2966 Note that the 2.6 kernel can accommodate a vast number of devices, while previous
2967 kernel versions were limited to 255 major and 255 minor numbers. One assumes<br>
2968 <br>
2969 <A name="45"></a><font color="blue">PAGE 45</font><br>
2970 <br>
2971 that the wider range will be sufficient for quite some time, but the computing field is
2972 littered with erroneous assumptions of that nature. So you should expect that the
2973 format of <font class="fixd">dev_t</font> could change again in the future; if you write your drivers carefully,
2974 however, these changes will not be a problem.<br>
2975 <br>
2976 <a name="AllocatingAndFreeingDeviceNumbers"></a><font color="red"><b>Allocating and Freeing Device Numbers</b></font><br>
2977 <br>
2978 One of the first things your driver will need to do when setting up a char device is to
2979 obtain one or more device numbers to work with. The necessary function for this
2980 task is <i>register_chrdev_region</i>, which is declared in <i><linux/fs.h></i>:<br>
2981 <pre>
2982 int register_chrdev_region(dev_t first, unsigned int count,
2983 char *name);
2984 </pre>
2985 Here, <font class="fixd">first</font> is the beginning device number of the range you would like to allocate.
2986 The minor number portion of <font class="fixd">first</font> is often 0, but there is no requirement to that
2987 effect. <font class="fixd">count</font> is the total number of contiguous device numbers you are requesting.
2988 Note that, if <font class="fixd">count</font> is large, the range you request could spill over to the next major
2989 number; but everything will still work properly as long as the number range you
2990 request is available. Finally, <font class="fixd">name</font> is the name of the device that should be associated
2991 with this number range; it will appear in <i>/proc/devices</i> and sysfs.<br>
2992 <br>
2993 As with most kernel functions, the return value from <i>register_chrdev_region </i>will be 0
2994 if the allocation was successfully performed. In case of error, a negative error code
2995 will be returned, and you will not have access to the requested region.<br>
2996 <br>
2997 <i>register_chrdev_region </i>works well if you know ahead of time exactly which device
2998 numbers you want. Often, however, you will not know which major numbers your
2999 device will use; there is a constant effort within the Linux kernel development community
3000 to move over to the use of dynamically-allocated device numbers. The kernel
3001 will happily allocate a major number for you on the fly, but you must request this
3002 allocation by using a different function:<br>
3003 <pre>
3004 int alloc_chrdev_region(dev_t *dev, unsigned int firstminor,
3005 unsigned int count, char *name);
3006 </pre>
3007 With this function, dev is an output-only parameter that will, on successful completion,
3008 hold the first number in your allocated range. <font class="fixd">firstminor</font> should be the
3009 requested first minor number to use; it is usually 0. The <font class="fixd">count</font> and <font class="fixd">name</font> parameters
3010 work like those given to <i>register_chrdev_region</i>.<br>
3011 <br>
3012 Regardless of how you allocate your device numbers, you should free them when
3013 they are no longer in use. Device numbers are freed with:<br>
3014 <pre>
3015 void unregister_chrdev_region(dev_t first, unsigned int count);
3016 </pre>
3017 The usual place to call <i>unregister_chrdev_region </i>would be in your module's cleanup
3018 function.<br>
3019 <br>
3020 <A name="46"></a><font color="blue">PAGE 46</font><br>
3021 <br>
3022 The above functions allocate device numbers for your driver's use, but they do not
3023 tell the kernel anything about what you will actually do with those numbers. Before a
3024 user-space program can access one of those device numbers, your driver needs to
3025 connect them to its internal functions that implement the device's operations. We
3026 will describe how this connection is accomplished shortly, but there are a couple of
3027 necessary digressions to take care of first.<br>
3028 <br>
3029 <a name="DynamicAllocationOfMajorNumbers"></a><font color="red"><b>Dynamic Allocation of Major Numbers</b></font><br>
3030 <br>
3031 Some major device numbers are statically assigned to the most common devices. A
3032 list of those devices can be found in <i>Documentation/devices.txt </i>within the kernel
3033 source tree. The chances of a static number having already been assigned for the use
3034 of your new driver are small, however, and new numbers are not being assigned. So,
3035 as a driver writer, you have a choice: you can simply pick a number that appears to
3036 be unused, or you can allocate major numbers in a dynamic manner. Picking a number
3037 may work as long as the only user of your driver is you; once your driver is more
3038 widely deployed, a randomly picked major number will lead to conflicts and trouble.<br>
3039 <br>
3040 Thus, for new drivers, we strongly suggest that you use dynamic allocation to obtain
3041 your major device number, rather than choosing a number randomly from the ones
3042 that are currently free. In other words, your drivers should almost certainly be using
3043 <i>alloc_chrdev_region</i> rather than <i>register_chrdev_region</i>.<br>
3044 <br>
3045 The disadvantage of dynamic assignment is that you can't create the device nodes in
3046 advance, because the major number assigned to your module will vary. For normal
3047 use of the driver, this is hardly a problem, because once the number has been
3048 assigned, you can read it from <i>/proc/devices</i>.*<br>
3049 <br>
3050 To load a driver using a dynamic major number, therefore, the invocation of <i>insmod
3051 </i>can be replaced by a simple script that, after calling <i>insmod</i>, reads <i>/proc/devices </i>in
3052 order to create the special file(s).<br>
3053 <br>
3054 A typical <i>/proc/devices</i> file looks like the following:<br>
3055 <pre>
3056 Character devices:
3057 1 mem
3058 2 pty
3059 3 ttyp
3060 4 ttyS
3061 6 lp
3062 7 vcs
3063 10 misc
3064 13 input
3065 14 sound
3066 </pre>
3067 * Even better device information can usually be obtained from sysfs, generally mounted on <i>/sys </i>on 2.6-based systems. Getting <i>scull </i>to export information via sysfs is beyond the scope of this chapter, however; we'll return to this topic in Chapter 14.<br>
3068 <br>
3069 <A name="47"></a><font color="blue">PAGE 47</font><br>
3070 <pre>
3071 21 sg
3072 180 usb
3074 Block devices:
3075 2 fd
3076 8 sd
3077 11 sr
3078 65 sd
3079 66 sd
3080 </pre>
3081 The script to load a module that has been assigned a dynamic number can, therefore,
3082 be written using a tool such as <i>awk </i>to retrieve information from <i>/proc/devices </i>in
3083 order to create the files in <i>/dev</i>.<br>
3084 <br>
3085 The following script, <i>scull_load</i>, is part of the <i>scull </i>distribution. The user of a driver
3086 that is distributed in the form of a module can invoke such a script from the system's
3087 <i>rc.local</i> file or call it manually whenever the module is needed.<br>
3088 <pre>
3089 #!/bin/sh
3090 module="scull"
3091 device="scull"
3092 mode="664"
3094 # invoke insmod with all arguments we got
3095 # and use a pathname, as newer modutils don't look in . by default
3096 /sbin/insmod ./$module.ko $* || exit 1
3098 # remove stale nodes
3099 rm -f /dev/${device}[0-3]
3101 major=$(awk "\$2= =\"$module\" {print \$1}" /proc/devices)
3103 mknod /dev/${device}0 c $major 0
3104 mknod /dev/${device}1 c $major 1
3105 mknod /dev/${device}2 c $major 2
3106 mknod /dev/${device}3 c $major 3
3108 # give appropriate group/permissions, and change the group.
3109 # Not all distributions have staff, some have "wheel" instead.
3110 group="staff"
3111 grep -q '^staff:' /etc/group || group="wheel"
3113 chgrp $group /dev/${device}[0-3]
3114 chmod $mode /dev/${device}[0-3]
3115 </pre>
3116 The script can be adapted for another driver by redefining the variables and adjusting
3117 the <i>mknod </i>lines. The script just shown creates four devices because four is the
3118 default in the <i>scull</i> sources.<br>
3119 <br>
3120 The last few lines of the script may seem obscure: why change the group and mode
3121 of a device? The reason is that the script must be run by the superuser, so newly created
3122 special files are owned by root. The permission bits default so that only root has
3123 write access, while anyone can get read access. Normally, a device node requires a<br>
3124 <br>
3125 <A name="48"></a><font color="blue">PAGE 48</font><br>
3126 <br>
3127 different access policy, so in some way or another access rights must be changed.
3128 The default in our script is to give access to a group of users, but your needs may
3129 vary. In the section "Access Control on a Device File" in Chapter 6, the code for <i>sculluid
3130 </i>demonstrates how the driver can enforce its own kind of authorization for device
3131 access.<br>
3132 <br>
3133 A <i>scull_unload </i>script is also available to clean up the <i>/dev </i>directory and remove the
3134 module.<br>
3135 <br>
3136 As an alternative to using a pair of scripts for loading and unloading, you could write
3137 an init script, ready to be placed in the directory your distribution uses for these
3138 scripts.* As part of the <i>scull </i>source, we offer a fairly complete and configurable example
3139 of an init script, called <i>scull.init</i>; it accepts the conventional arguments--start,
3140 stop, and restart--and performs the role of both <i>scull_load</i> and <i>scull_unload</i>.<br>
3141 <br>
3142 If repeatedly creating and destroying <i>/dev </i>nodes sounds like overkill, there is a useful
3143 work-around. If you are loading and unloading only a single driver, you can just use
3144 <i>rmmod </i>and <i>insmod </i>after the first time you create the special files with your script:
3145 dynamic numbers are not randomized,† and you can count on the same number
3146 being chosen each time if you don't load any other (dynamic) modules. Avoiding
3147 lengthy scripts is useful during development. But this trick, clearly, doesn't scale to
3148 more than one driver at a time.<br>
3149 <br>
3150 The best way to assign major numbers, in our opinion, is by defaulting to dynamic
3151 allocation while leaving yourself the option of specifying the major number at load
3152 time, or even at compile time. The <i>scull </i>implementation works in this way; it uses a
3153 global variable, <font class="fixd">scull_major</font>, to hold the chosen number (there is also a <font class="fixd">scull_minor</font>
3154 for the minor number). The variable is initialized to <font class="fixd">SCULL_MAJOR</font>, defined in <i>scull.h</i>.
3155 The default value of <font class="fixd">SCULL_MAJOR</font> in the distributed source is 0, which means "use
3156 dynamic assignment." The user can accept the default or choose a particular major
3157 number, either by modifying the macro before compiling or by specifying a value for
3158 <font class="fixd">scull_major</font> on the <i>insmod </i>command line. Finally, by using the <i>scull_load </i>script, the
3159 user can pass arguments to <i>insmod</i> on <i>scull_load</i>'s command line.‡<br>
3160 <br>
3161 Here's the code we use in <i>scull</i>'s source to get a major number:<br>
3162 <pre>
3163 if (scull_major) {
3164 dev = MKDEV(scull_major, scull_minor);
3165 result = register_chrdev_region(dev, scull_nr_devs, "scull");
3166 } else {
3167 result = alloc_chrdev_region(&dev, scull_minor, scull_nr_devs,
3168 </pre>
3169 * The Linux Standard Base specifies that init scripts should be placed in <i>/etc/init.d</i>, but some distributions
3170 still place them elsewhere. In addition, if your script is to be run at boot time, you need to make a link to it from
3171 the appropriate run-level directory (i.e., <i>.../rc3.d</i>).<br>
3172 <br>
3173 † Though certain kernel developers have threatened to do exactly that in the future.<br>
3174 <br>
3175 ‡The init script <i>scull.init </i>doesn't accept driver options on the command line, but it supports a configuration
3176 file, because it's designed for automatic use at boot and shutdown time.<br>
3177 <br>
3178 <A name="49"></a><font color="blue">PAGE 49</font><br>
3179 <pre>
3180 "scull");
3181 scull_major = MAJOR(dev);
3182 }
3183 if (result < 0) {
3184 printk(KERN_WARNING "scull: can't get major %d\n", scull_major);
3185 return result;
3186 }
3187 </pre>
3188 Almost all of the sample drivers used in this book use similar code for their major
3189 number assignment.<br>
3190 <br>
3191 <a name="SomeImportantDataStructures"></a><font color="red"><b>Some Important Data Structures</b></font><br>
3192 <br>
3193 As you can imagine, device number registration is just the first of many tasks that
3194 driver code must carry out. We will soon look at other important driver components,
3195 but one other digression is needed first. Most of the fundamental driver operations
3196 involve three important kernel data structures, called <font class="fixd">file_operations, file,</font>
3197 and <font class="fixd">inode.</font> A basic familiarity with these structures is required to be able to do much
3198 of anything interesting, so we will now take a quick look at each of them before getting
3199 into the details of how to implement the fundamental driver operations.<br>
3200 <br>
3201 <a name="FileOperations"></a><font color="red"><b>File Operations</b></font><br>
3202 <br>
3203 So far, we have reserved some device numbers for our use, but we have not yet connected
3204 any of our driver's operations to those numbers. The <font class="fixd">file_operations</font> structure
3205 is how a char driver sets up this connection. The structure, defined in <i><linux/fs.h></i>,
3206 is a collection of function pointers. Each open file (represented internally by a file
3207 structure, which we will examine shortly) is associated with its own set of functions
3208 (by including a field called <font class="fixd">f_op</font> that points to a <font class="fixd">file_operations</font> structure). The
3209 operations are mostly in charge of implementing the system calls and are therefore,
3210 named <i>open</i>, <i>read</i>, and so on. We can consider the file to be an "object" and the
3211 functions operating on it to be its "methods," using object-oriented programming
3212 terminology to denote actions declared by an object to act on itself. This is the first
3213 sign of object-oriented programming we see in the Linux kernel, and we'll see more
3214 in later chapters.<br>
3215 <br>
3216 Conventionally, a <font class="fixd">file_operations</font> structure or a pointer to one is called <font class="fixd">fops</font> (or
3217 some variation thereof). Each field in the structure must point to the function in the
3218 driver that implements a specific operation, or be left <font class="fixd">NULL</font> for unsupported operations.
3219 The exact behavior of the kernel when a <font class="fixd">NULL</font> pointer is specified is different
3220 for each function, as the list later in this section shows.<br>
3221 <br>
3222 The following list introduces all the operations that an application can invoke on a
3223 device. We've tried to keep the list brief so it can be used as a reference, merely summarizing
3224 each operation and the default kernel behavior when a <font class="fixd">NULL</font> pointer is used.<br>
3225 <br>
3226 <A name="50"></a><font color="blue">PAGE 50</font><br>
3227 <br>
3228 As you read through the list of <font class="fixd">file_operations</font> methods, you will note that a number
3229 of parameters include the <font class="fixd">string__user</font>. This annotation is a form of documentation,
3230 noting that a pointer is a user-space address that cannot be directly
3231 dereferenced. For normal compilation, <font class="fixd">__user</font> has no effect, but it can be used by
3232 external checking software to find misuse of user-space addresses.<br>
3233 <br>
3234 The rest of the chapter, after describing some other important data structures,
3235 explains the role of the most important operations and offers hints, caveats, and real
3236 code examples. We defer discussion of the more complex operations to later chapters,
3237 because we aren't ready to dig into topics such as memory management, blocking
3238 operations, and asynchronous notification quite yet.<br>
3239 <br>
3240 <font class="fixd">struct module *owner</font><br>
3241 <div class="bq">
3242 The first <font class="fixd">file_operations</font> field is not an operation at all; it is a pointer to the
3243 module that "owns" the structure. This field is used to prevent the module from
3244 being unloaded while its operations are in use. Almost all the time, it is simply
3245 initialized to <font class="fixd">THIS_MODULE,</font> a macro defined in <i><linux/module.h></i>.</div>
3246 <br>
3247 <font class="fixd">loff_t (*llseek) (struct file *, loff_t, int);</font><br>
3248 <div class="bq">
3249 The <i>llseek </i>method is used to change the current read/write position in a file, and
3250 the new position is returned as a (positive) return value. The <font class="fixd">loff_t</font> parameter is
3251 a "long offset" and is at least 64 bits wide even on 32-bit platforms. Errors are
3252 signaled by a negative return value. If this function pointer is <font class="fixd">NULL</font>, seek calls will
3253 modify the position counter in the file structure (described in the section "The
3254 file Structure") in potentially unpredictable ways.</div>
3255 <br>
3256 <font class="fixd">ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);</font><br>
3257 <div class="bq">
3258 Used to retrieve data from the device. A null pointer in this position causes the
3259 <i>read </i>system call to fail with <font class="fixd">-EINVAL</font> ("Invalid argument"). A nonnegative return
3260 value represents the number of bytes successfully read (the return value is a
3261 "signed size" type, usually the native integer type for the target platform).</div>
3262 <br>
3263 <font class="fixd">ssize_t (*aio_read)(struct kiocb *, char __user *, size_t, loff_t);<</font>br>
3264 <div class="bq">
3265 Initiates an asynchronous read--a read operation that might not complete
3266 before the function returns. If this method is <font class="fixd">NULL</font>, all operations will be processed
3267 (synchronously) by <i>read</i> instead.</div>
3268 <br>
3269 <font class="fixd">ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);</font><br>
3270 <div class="bq">
3271 Sends data to the device. If <font class="fixd">NULL, -EINVAL</font> is returned to the program calling the
3272 <i>write </i>system call. The return value, if nonnegative, represents the number of
3273 bytes successfully written.</div>
3274 <br>
3275 <font class="fixd">ssize_t (*aio_write)(struct kiocb *, const char __user *, size_t, loff_t *);</font><br>
3276 <div class="bq">
3277 Initiates an asynchronous write operation on the device.</div>
3278 <br>
3279 <font class="fixd">int (*readdir) (struct file *, void *, filldir_t);</font><br>
3280 <div class="bq">
3281 This field should be <font class="fixd">NULL</font> for device files; it is used for reading directories and is
3282 useful only for filesystems.</div>
3283 <br>
3284 <A name="51"></a><font color="blue">PAGE 51</font><br>
3285 <br>
3286 <font class="fixd">unsigned int (*poll) (struct file *, struct poll_table_struct *);</font><br>
3287 <div class="bq">
3288 The <i>poll </i>method is the back end of three system calls: <i>poll, epoll, </i>and <i>select</i>, all of
3289 which are used to query whether a read or write to one or more file descriptors
3290 would block. The <i>poll </i>method should return a bit mask indicating whether nonblocking
3291 reads or writes are possible, and, possibly, provide the kernel with
3292 information that can be used to put the calling process to sleep until I/O
3293 becomes possible. If a driver leaves its <i>poll </i>method <font class="fixd">NULL</font>, the device is assumed to
3294 be both readable and writable without blocking.</div>
3295 <br>
3296 <font class="fixd">int (*ioctl) (struct inode *, struct file *, unsigned int, unsigned long);</font><br>
3297 <div class="bq">
3298 The <i>ioctl </i>system call offers a way to issue device-specific commands (such as formatting
3299 a track of a floppy disk, which is neither reading nor writing). Additionally,
3300 a few <i>ioctl </i>commands are recognized by the kernel without referring to the
3301 fops table. If the device doesn't provide an <i>ioctl </i>method, the system call returns
3302 an error for any request that isn't predefined (<font class="fixd">-ENOTTY,</font> "No such ioctl for
3303 device").</div>
3304 <br>
3305 <font class="fixd">int (*mmap) (struct file *, struct vm_area_struct *);</font><br>
3306 <div class="bq">
3307 <i>mmap </i>is used to request a mapping of device memory to a process's address
3308 space. If this method is <font class="fixd">NULL</font>, the <i>mmap</i> system call returns <font class="fixd">-ENODEV.</font></div>
3309 <br>
3310 <font class="fixd">int (*open) (struct inode *, struct file *);</font><br>
3311 <div class="bq">
3312 Though this is always the first operation performed on the device file, the driver
3313 is not required to declare a corresponding method. If this entry is <font class="fixd">NULL</font>, opening
3314 the device always succeeds, but your driver isn't notified.</div>
3315 <br>
3316 <font class="fixd">int (*flush) (struct file *);</font><br>
3317 <div class="bq">
3318 The <i>flush </i>operation is invoked when a process closes its copy of a file descriptor
3319 for a device; it should execute (and wait for) any outstanding operations on the
3320 device. This must not be confused with the <i>fsync </i>operation requested by user
3321 programs. Currently, <i>flush </i>is used in very few drivers; the SCSI tape driver uses
3322 it, for example, to ensure that all data written makes it to the tape before the
3323 device is closed. If <i>flush </i>is <font class="fixd">NULL</font>, the kernel simply ignores the user application
3324 request.</div>
3325 <br>
3326 <font class="fixd">int (*release) (struct inode *, struct file *);</font><br>
3327 <div class="bq">
3328 This operation is invoked when the file structure is being released. Like <i>open</i>,
3329 <i>release</i> can be <font class="fixd">NULL</font>.*</div>
3330 <br>
3331 <font class="fixd">int (*fsync) (struct file *, struct dentry *, int);</font><br>
3332 <div class="bq">
3333 This method is the back end of the <i>fsync </i>system call, which a user calls to flush
3334 any pending data. If this pointer is <font class="fixd">NULL</font>, the system call returns <font class="fixd">-EINVAL.</font></div>
3335 <br>
3336 * Note that <i>release </i>isn't invoked every time a process calls <i>close</i>. Whenever
3337 a file structure is shared (for example, after a <i>fork </i>or a <i>dup</i>), <i>release </i>won't
3338 be invoked until all copies are closed. If you need to flush pending
3339 data when any copy is closed, you should implement the <i>flush</i> method.<br>
3340 <br>
3341 <A name="52"></a><font color="blue">PAGE 52</font><br>
3342 <br>
3343 <font class="fixd">int (*aio_fsync)(struct kiocb *, int);</font><br>
3344 <div class="bq">
3345 This is the asynchronous version of the <i>fsync</i> method.</div>
3346 <br>
3347 <font class="fixd">int (*fasync) (int, struct file *, int);</font><br>
3348 <div class="bq">
3349 This operation is used to notify the device of a change in its <font class="fixd">FASYNC</font> flag. Asynchronous
3350 notification is an advanced topic and is described in Chapter 6. The
3351 field can be <font class="fixd">NULL</font> if the driver doesn't support asynchronous notification.</div>
3352 <br>
3353 <font class="fixd">int (*lock) (struct file *, int, struct file_lock *);</font><br>
3354 <div class="bq">
3355 The <i>lock </i>method is used to implement file locking; locking is an indispensable
3356 feature for regular files but is almost never implemented by device drivers.</div>
3357 <br>
3358 <font class="fixd">ssize_t (*readv) (struct file *, const struct iovec *, unsigned long, loff_t *);<br>
3359 ssize_t (*writev) (struct file *, const struct iovec *, unsigned long, loff_t *);</font><br>
3360 <div class="bq">
3361 These methods implement scatter/gather read and write operations. Applications
3362 occasionally need to do a single read or write operation involving multiple
3363 memory areas; these system calls allow them to do so without forcing extra copy
3364 operations on the data. If these function pointers are left <font class="fixd">NULL</font>, the <i>read </i>and <i>write
3365 </i>methods are called (perhaps more than once) instead.</div>
3366 <br>
3367 <font class="fixd">ssize_t (*sendfile)(struct file *, loff_t *, size_t, read_actor_t, void *);</font><br>
3368 <div class="bq">
3369 This method implements the read side of the <i>sendfile </i>system call, which moves
3370 the data from one file descriptor to another with a minimum of copying. It is
3371 used, for example, by a web server that needs to send the contents of a file out a
3372 network connection. Device drivers usually leave <i>sendfile </i><font class="fixd">NULL</font>.</div>
3373 <br>
3374 <font class="fixd">ssize_t (*sendpage) (struct file *, struct page *, int, size_t, loff_t *, int);</font><br>
3375 <div class="bq">
3376 <i>sendpage </i>is the other half of <i>sendfile</i>; it is called by the kernel to send data, one
3377 page at a time, to the corresponding file. Device drivers do not usually implement
3378 <i>sendpage</i>.</div>
3379 <br>
3380 <font class="fixd">unsigned long (*get_unmapped_area)(struct file *, unsigned long, unsigned
3381 long, unsigned long, unsigned long);</font><br>
3382 <div class="bq">
3383 The purpose of this method is to find a suitable location in the process's address
3384 space to map in a memory segment on the underlying device. This task is normally
3385 performed by the memory management code; this method exists to allow
3386 drivers to enforce any alignment requirements a particular device may have.
3387 Most drivers can leave this method <font class="fixd">NULL</font>.</div>
3388 <br>
3389 <font class="fixd">int (*check_flags)(int)</font><br>
3390 <div class="bq">
3391 This method allows a module to check the flags passed to an <i>fcntl(F_SETFL...) </i>call.</div>
3392 <br>
3393 <font class="fixd">int (*dir_notify)(struct file *, unsigned long);</font><br>
3394 <div class="bq">
3395 This method is invoked when an application uses <i>fcntl </i>to request directory
3396 change notifications. It is useful only to filesystems; drivers need not implement
3397 <i>dir_notify</i>.</div>
3398 <br>
3399 <A name="53"></a><font color="blue">PAGE 53</font><br>
3400 <br>
3401 The <i>scull </i>device driver implements only the most important device methods. Its
3402 <font class="fixd">file_operations</font> structure is initialized as follows:<br>
3403 <pre>
3404 struct file_operations scull_fops = {
3405 .owner = THIS_MODULE,
3406 .llseek = scull_llseek,
3407 .read = scull_read,
3408 .write = scull_write,
3409 .ioctl = scull_ioctl,
3410 .open = scull_open,
3411 .release = scull_release,
3412 };
3413 </pre>
3414 This declaration uses the standard C tagged structure initialization syntax. This syntax
3415 is preferred because it makes drivers more portable across changes in the definitions
3416 of the structures and, arguably, makes the code more compact and readable.
3417 Tagged initialization allows the reordering of structure members; in some cases, substantial
3418 performance improvements have been realized by placing pointers to frequently
3419 accessed members in the same hardware cache line.<br>
3420 <br>
3421 <a name="TheFileStructure"></a><font color="red"><b>The file Structure</b></font><br>
3422 <br>
3423 <font class="fixd">struct file</font>, defined in <i><linux/fs.h></i>, is the second most important data structure
3424 used in device drivers. Note that a file has nothing to do with the FILE pointers of
3425 user-space programs. A FILE is defined in the C library and never appears in kernel
3426 code. A <font class="fixd">struct file</font>, on the other hand, is a kernel structure that never appears in
3427 user programs.<br>
3428 <br>
3429 The file structure represents an <i>open file</i>. (It is not specific to device drivers; every
3430 open file in the system has an associated <font class="fixd">struct file</font> in kernel space.) It is created by
3431 the kernel on <i>open </i>and is passed to any function that operates on the file, until
3432 the last <i>close</i>. After all instances of the file are closed, the kernel releases the data
3433 structure.<br>
3434 <br>
3435 In the kernel sources, a pointer to <font class="fixd">struct file</font> is usually called either file or <font class="fixd">filp</font>
3436 ("file pointer"). We'll consistently call the pointer <font class="fixd">filp</font> to prevent ambiguities with
3437 the structure itself. Thus, <font class="fixd">file</font> refers to the structure and <font class="fixd">filp</font> to a pointer to the
3438 structure.<br>
3439 <br>
3440 The most important fields of <font class="fixd">struct file</font> are shown here. As in the previous section,
3441 the list can be skipped on a first reading. However, later in this chapter, when we
3442 face some real C code, we'll discuss the fields in more detail.<br>
3443 <br>
3444 <font class="fixd">mode_t f_mode;</font><br>
3445 <div class="bq">
3446 The file mode identifies the file as either readable or writable (or both), by means
3447 of the bits <font class="fixd">FMODE_READ</font> and <font class="fixd">FMODE_WRITE</font>. You might want to check this field for
3448 read/write permission in your <i>open </i>or <i>ioctl </i>function, but you don't need to check
3449 permissions for <i>read </i>and <i>write</i>, because the kernel checks before invoking your</div>
3450 <br>
3451 <A name="54"></a><font color="blue">PAGE 54</font><br>
3452 <br>
3453 <div class="bq">
3454 method. An attempt to read or write when the file has not been opened for that
3455 type of access is rejected without the driver even knowing about it.</div>
3456 <br>
3457 <font class="fixd">loff_t f_pos;</font><br>
3458 <div class="bq">
3459 The current reading or writing position. <font class="fixd">loff_t</font> is a 64-bit value on all platforms
3460 (<font class="fixd">long long</font> in <i>gcc </i>terminology). The driver can read this value if it needs to know
3461 the current position in the file but should not normally change it; <i>read </i>and <i>write
3462 </i>should update a position using the pointer they receive as the last argument
3463 instead of acting on <font class="fixd">filp->f_pos</font> directly. The one exception to this rule is in the
3464 <i>llseek</i> method, the purpose of which is to change the file position.</div>
3465 <br>
3466 <font class="fixd">unsigned int f_flags;</font><br>
3467 <div class="bq">
3468 These are the file flags, such as <font class="fixd">O_RDONLY, O_NONBLOCK,</font> and <font class="fixd">O_SYNC</font>. A driver should
3469 check the <font class="fixd">O_NONBLOCK</font> flag to see if nonblocking operation has been requested (we
3470 discuss nonblocking I/O in the section "Blocking and Nonblocking Operations"
3471 in Chapter 6); the other flags are seldom used. In particular, read/write permission
3472 should be checked using <font class="fixd">f_mode</font> rather than <font class="fixd">f_flags</font>. All the flags are
3473 defined in the header <i><linux/fcntl.h></i>.</div>
3474 <br>
3475 <font class="fixd">struct file_operations *f_op;</font><br>
3476 <div class="bq">
3477 The operations associated with the file. The kernel assigns the pointer as part of
3478 its implementation of <i>open </i>and then reads it when it needs to dispatch any operations.
3479 The value in <font class="fixd">filp->f_op</font> is never saved by the kernel for later reference;
3480 this means that you can change the file operations associated with your file, and
3481 the new methods will be effective after you return to the caller. For example, the
3482 code for <i>open </i>associated with major number 1 (<i>/dev/null</i>, <i>/dev/zero</i>, and so on)
3483 substitutes the operations in <font class="fixd">filp->f_op</font> depending on the minor number being
3484 opened. This practice allows the implementation of several behaviors under the
3485 same major number without introducing overhead at each system call. The ability
3486 to replace the file operations is the kernel equivalent of "method overriding"
3487 in object-oriented programming.</div>
3488 <br>
3489 <font class="fixd">void *private_data;</font><br>
3490 <div class="bq">
3491 The <i>open </i>system call sets this pointer to <font class="fixd">NULL</font> before calling the <i>open </i>method for
3492 the driver. You are free to make its own use of the field or to ignore it; you can
3493 use the field to point to allocated data, but then you must remember to free that
3494 memory in the <i>release </i>method before the <font class="fixd">file</font> structure is destroyed by the kernel.
3495 <font class="fixd">private_data</font> is a useful resource for preserving state information across system
3496 calls and is used by most of our sample modules.</div>
3497 <br>
3498 <font class="fixd">struct dentry *f_dentry;</font><br>
3499 <div class="bq">
3500 The directory entry (<i>dentry</i>) structure associated with the file. Device driver writers
3501 normally need not concern themselves with dentry structures, other than to
3502 access the inode structure as <font class="fixd">filp->f_dentry->d_inode.</font></div>
3503 <br>
3504 <A name="55"></a><font color="blue">PAGE 55</font><br>
3505 <br>
3506 The real structure has a few more fields, but they aren't useful to device drivers. We
3507 can safely ignore those fields, because drivers never create <font class="fixd">file</font> structures; they only
3508 access structures created elsewhere.<br>
3509 <br>
3510 <a name="TheInodeStructure"></a><font color="red"><b>The inode Structure</b></font><br>
3511 <br>
3512 The <i>inode </i>structure is used by the kernel internally to represent files. Therefore, it is
3513 different from the <font class="fixd">file</font> structure that represents an open file descriptor. There can be
3514 numerous <font class="fixd">file</font> structures representing multiple open descriptors on a single file, but
3515 they all point to a single <font class="fixd">inode</font> structure.<br>
3516 <br>
3517 The <font class="fixd">inode</font> structure contains a great deal of information about the file. As a general
3518 rule, only two fields of this structure are of interest for writing driver code:<br>
3519 <br>
3520 <font class="fixd">dev_t i_rdev;</font><br>
3521 <div class="bq">
3522 For inodes that represent device files, this field contains the actual device number.</div>
3523 <br>
3524 <font class="fixd">struct cdev *i_cdev;</font><br>
3525 <div class="bq">
3526 <font class="fixd">struct cdev</font> is the kernel's internal structure that represents char devices; this
3527 field contains a pointer to that structure when the inode refers to a char device
3528 file.</div>
3529 <br>
3530 The type of <font class="fixd">i_rdev</font> changed over the course of the 2.5 development series, breaking a
3531 lot of drivers. As a way of encouraging more portable programming, the kernel developers
3532 have added two macros that can be used to obtain the major and minor number
3533 from an inode:<br>
3534 <pre>
3535 unsigned int iminor(struct inode *inode);
3536 unsigned int imajor(struct inode *inode);
3537 </pre>
3538 In the interest of not being caught by the next change, these macros should be used
3539 instead of manipulating <font class="fixd">i_rdev</font> directly.<br>
3540 <br>
3541 <a name="CharDeviceRegistration"></a><font color="red"><b>Char Device Registration</b></font><br>
3542 <br>
3543 As we mentioned, the kernel uses structures of type struct cdev to represent char
3544 devices internally. Before the kernel invokes your device's operations, you must allocate
3545 and register one or more of these structures.* To do so, your code should include
3546 <i><linux/cdev.h></i>, where the structure and its associated helper functions are defined.<br>
3547 <br>
3548 There are two ways of allocating and initializing one of these structures. If you wish
3549 to obtain a stand alone cdev structure at runtime, you may do so with code such as:<br>
3550 <pre>
3551 struct cdev *my_cdev = cdev_alloc( );
3552 my_cdev->ops = &my_fops;
3553 </pre>
3554 * There is an older mechanism that avoids the use of cdev structures (which we discuss
3555 in the section "The Older Way"). New code should use the newer technique, however.<br>
3556 <br>
3557 <A name="56"></a><font color="blue">PAGE 56</font><br>
3558 <br>
3559 Chances are, however, that you will want to embed the <font class="fixd">cdev</font> structure within a
3560 device-specific structure of your own; that is what <i>scull </i>does. In that case, you should
3561 initialize the structure that you have already allocated with:<br>
3562 <pre>
3563 void cdev_init(struct cdev *cdev, struct file_operations *fops);
3564 </pre>
3565 Either way, there is one other struct <font class="fixd">cdev</font> field that you need to initialize. Like the
3566 <font class="fixd">file_operations</font> structure, <font class="fixd">struct cdev</font> has an <font class="fixd">owner</font> field that should be set to
3567 <font class="fixd">THIS_MODULE</font>.<br>
3568 <br>
3569 Once the <font class="fixd">cdev</font> structure is set up, the final step is to tell the kernel about it with a call to:<br>
3570 <pre>
3571 int cdev_add(struct cdev *dev, dev_t num, unsigned int count);
3572 </pre>
3573 Here, dev is the <font class="fixd">cdev</font> structure, <font class="fixd">num</font> is the first device number to which this device
3574 responds, and <font class="fixd">count</font> is the number of device numbers that should be associated with
3575 the device. Often <font class="fixd">count</font> is one, but there are situations where it makes sense to have
3576 more than one device number correspond to a specific device. Consider, for example,
3577 the SCSI tape driver, which allows user space to select operating modes (such as
3578 density) by assigning multiple minor numbers to each physical device.<br>
3579 <br>
3580 There are a couple of important things to keep in mind when using <i>cdev_add</i>. The
3581 first is that this call can fail. If it returns a negative error code, your device has not
3582 been added to the system. It almost always succeeds, however, and that brings up
3583 the other point: as soon as <i>cdev_add </i>returns, your device is "live" and its operations
3584 can be called by the kernel. You should not call <i>cdev_add </i>until your driver is completely
3585 ready to handle operations on the device.<br>
3586 <br>
3587 To remove a char device from the system, call:<br>
3588 <pre>
3589 void cdev_del(struct cdev *dev);
3590 </pre>
3591 Clearly, you should not access the <font class="fixd">cdev</font> structure after passing it to <i>cdev_del</i>.<br>
3592 <br>
3593 <a name="DeviceRegistrationInScull"></a><font color="red"><b>Device Registration in scull</b></font><br>
3594 <br>
3595 Internally, <i>scull </i>represents each device with a structure of type <font class="fixd">struct scull_dev</font>. This
3596 structure is defined as:<br>
3597 <pre>
3598 struct scull_dev {
3599 struct scull_qset *data; /* Pointer to first quantum set */
3600 int quantum; /* the current quantum size */
3601 int qset; /* the current array size */
3602 unsigned long size; /* amount of data stored here */
3603 unsigned int access_key; /* used by sculluid and scullpriv */
3604 struct semaphore sem; /* mutual exclusion semaphore */
3605 struct cdev cdev; /* Char device structure */
3606 };
3607 </pre>
3608 We discuss the various fields in this structure as we come to them, but for now, we
3609 call attention to <font class="fixd">cdev</font>, the struct <font class="fixd">cdev</font> that interfaces our device to the kernel. This<br>
3610 <br>
3611 <A name="57"></a><font color="blue">PAGE 57</font><br>
3612 <br>
3613 structure must be initialized and added to the system as described above; the <i>scull
3614 </i>code that handles this task is:<br>
3615 <pre>
3616 static void scull_setup_cdev(struct scull_dev *dev, int index)
3617 {
3618 int err, devno = MKDEV(scull_major, scull_minor + index);
3620 cdev_init(&dev->cdev, &scull_fops);
3621 dev->cdev.owner = THIS_MODULE;
3622 dev->cdev.ops = &scull_fops;
3623 err = cdev_add (&dev->cdev, devno, 1);
3624 /* Fail gracefully if need be */
3625 if (err)
3626 printk(KERN_NOTICE "Error %d adding scull%d", err, index);
3627 }
3628 </pre>
3629 Since the <font class="fixd">cdev</font> structure is embedded within <font class="fixd">struct scull_dev,</font> <i>cdev_init </i>must be
3630 called to perform the initialization of that structure.<br>
3631 <br>
3632 <a name="TheOlderWay"></a><font color="red"><b>The Older Way</b></font><br>
3633 <br>
3634 If you dig through much driver code in the 2.6 kernel, you may notice that quite a
3635 few char drivers do not use the <font class="fixd">cdev</font> interface that we have just described. What you
3636 are seeing is older code that has not yet been upgraded to the 2.6 interface. Since that
3637 code works as it is, this upgrade may not happen for a long time. For completeness,
3638 we describe the older char device registration interface, but new code should not use
3639 it; this mechanism will likely go away in a future kernel.<br>
3640 <br>
3641 The classic way to register a char device driver is with:<br>
3642 <pre>
3643 int register_chrdev(unsigned int major, const char *name,
3644 struct file_operations *fops);
3645 </pre>
3646 Here, <font class="fixd">major</font> is the major number of interest, <font class="fixd">name</font> is the name of the driver (it
3647 appears in <i>/proc/devices</i>), and <font class="fixd">fops</font> is the default <font class="fixd">file_operations</font> structure. A call to
3648 <i>register_chrdev </i>registers minor numbers 0-255 for the given major,</font> and sets up a
3649 default <font class="fixd">cdev</font> structure for each. Drivers using this interface must be prepared to handle
3650 <i>open </i>calls on all 256 minor numbers (whether they correspond to real devices or
3651 not), and they cannot use major or minor numbers greater than 255.<br>
3652 <br>
3653 If you use <i>register_chrdev</i>, the proper function to remove your device(s) from the system
3654 is:<br>
3655 <pre>
3656 int unregister_chrdev(unsigned int major, const char *name);
3657 </pre>
3658 <font class="fixd">major</font> and <font class="fixd">name</font> must be the same as those passed to <i>register_chrdev</i>, or the call will
3659 fail.<br>
3660 <br>
3661 <A name="58"></a><font color="blue">PAGE 58</font><br>
3662 <br>
3663 <a name="OpenAndRelease"></a><font color="red"><b>open and release</b></font><br>
3664 <br>
3665 Now that we've taken a quick look at the fields, we start using them in real <i>scull
3666 </i>functions.<br>
3667 <br>
3668 <a name="TheOpenMethod"></a><font color="red"><b>The open Method</b></font><br>
3669 <br>
3670 The <i>open </i>method is provided for a driver to do any initialization in preparation for
3671 later operations. In most drivers, <i>open</i> should perform the following tasks:<br>
3672 <ul>
3673 <li> Check for device-specific errors (such as device-not-ready or similar hardware problems)
3674 <li> Initialize the device if it is being opened for the first time
3675 <li> Update the <font class="fixd">f_op</font> pointer, if necessary
3676 <li> Allocate and fill any data structure to be put in <font class="fixd">filp->private_data</font>
3677 </ul>
3678 The first order of business, however, is usually to identify which device is being
3679 opened. Remember that the prototype for the <i>open</i> method is:<br>
3680 <pre>
3681 int (*open)(struct inode *inode, struct file *filp);
3682 </pre>
3683 The <i>inode </i>argument has the information we need in the form of its <font class="fixd">i_cdev</font> field,
3684 which contains the <font class="fixd">cdev</font> structure we set up before. The only problem is that we do
3685 not normally want the <font class="fixd">cdev</font> structure itself, we want the <font class="fixd">scull_dev</font> structure that contains
3686 that <font class="fixd">cdev</font> structure. The C language lets programmers play all sorts of tricks to
3687 make that kind of conversion; programming such tricks is error prone, however, and
3688 leads to code that is difficult for others to read and understand. Fortunately, in this
3689 case, the kernel hackers have done the tricky stuff for us, in the form of the
3690 <i>container_of</i> macro, defined in <i><linux/kernel.h></i>:<br>
3691 <pre>
3692 container_of(pointer, container_type, container_field);
3693 </pre>
3694 This macro takes a pointer to a field named <font class="fixd">container_field,</font> within a structure of
3695 type <font class="fixd">container_type,</font> and returns a pointer to the containing structure. In <i>scull_open</i>,
3696 this macro is used to find the appropriate device structure:<br>
3697 <pre>
3698 struct scull_dev *dev; /* device information */
3700 dev = container_of(inode->i_cdev, struct scull_dev, cdev);
3701 filp->private_data = dev; /* for other methods */
3702 </pre>
3703 Once it has found the <font class="fixd">scull_dev</font> structure, <i>scull </i>stores a pointer to it in the <font class="fixd">private_data</font>
3704 field of the <font class="fixd">file</font> structure for easier access in the future.<br>
3705 <br>
3706 The other way to identify the device being opened is to look at the minor number
3707 stored in the <font class="fixd">inode</font> structure. If you register your device with <i>register_chrdev</i>, you
3708 must use this technique. Be sure to use <i>iminor </i>to obtain the minor number from the
3709 <font class="fixd">inode</font> structure, and make sure that it corresponds to a device that your driver is
3710 actually prepared to handle.<br>
3711 <br>
3712 <A name="59"></a><font color="blue">PAGE 59</font><br>
3713 <br>
3714 The (slightly simplified) code for <i>scull_open</i> is:<br>
3715 <pre>
3716 int scull_open(struct inode *inode, struct file *filp)
3717 {
3718 struct scull_dev *dev; /* device information */
3719 dev = container_of(inode->i_cdev, struct scull_dev, cdev);
3720 filp->private_data = dev; /* for other methods */
3722 /* now trim to 0 the length of the device if open was write-only */
3723 if ( (filp->f_flags & O_ACCMODE) = = O_WRONLY) {
3724 scull_trim(dev); /* ignore errors */
3725 }
3726 return 0; /* success */
3727 }
3728 </pre>
3729 The code looks pretty sparse, because it doesn't do any particular device handling
3730 when <i>open </i>is called. It doesn't need to, because the <i>scull </i>device is global and persistent
3731 by design. Specifically, there's no action such as "initializing the device on first
3732 open," because we don't keep an open count for <i>scull</i>s.<br>
3733 <br>
3734 The only real operation performed on the device is truncating it to a length of 0 when
3735 the device is opened for writing. This is performed because, by design, overwriting a
3736 <i>scull </i>device with a shorter file results in a shorter device data area. This is similar to
3737 the way opening a regular file for writing truncates it to zero length. The operation
3738 does nothing if the device is opened for reading.<br>
3739 <br>
3740 We'll see later how a real initialization works when we look at the code for the other
3741 <i>scull</i> personalities.<br>
3742 <br>
3743 <a name="TheReleaseMethod"></a><font color="red"><b>The release Method</b></font><br>
3744 <br>
3745 The role of the <i>release </i>method is the reverse of <i>open</i>. Sometimes you'll find that the
3746 method implementation is called <i>device_close</i> instead of <i>device_release.</i> Either
3747 way, the device method should perform the following tasks:<br>
3748 <ul>
3749 <li> Deallocate anything that <i>open</i> allocated in <font class="fixd">filp->private_data</font>
3750 <li> Shut down the device on last close
3751 </ul>
3752 The basic form of <i>scull </i>has no hardware to shut down, so the code required is
3753 minimal:*<br>
3754 <pre>
3755 int scull_release(struct inode *inode, struct file *filp)
3756 {
3757 return 0;
3758 }
3759 </pre>
3760 * The other flavors of the device are closed by different functions because <i>scull_open </i>substituted a different
3761 <font class="fixd">filp->f_op</font> for each device. We'll discuss these as we introduce each flavor.<br>
3762 <br>
3763 <A name="60"></a><font color="blue">PAGE 60</font><br>
3764 <br>
3765 You may be wondering what happens when a device file is closed more times than it
3766 is opened. After all, the <i>dup </i>and <i>fork </i>system calls create copies of open files without
3767 calling <i>open</i>; each of those copies is then closed at program termination. For example,
3768 most programs don't open their <i>stdin </i>file (or device), but all of them end up closing
3769 it. How does a driver know when an open device file has <i>really</i> been closed?<br>
3770 <br>
3771 The answer is simple: not every <i>close </i>system call causes the <i>release </i>method to be
3772 invoked. Only the calls that actually release the device data structure invoke the
3773 method--hence its name. The kernel keeps a counter of how many times a file
3774 structure is being used. Neither <i>fork </i>nor <i>dup </i>creates a new <font class="fixd">file</font> structure (only <i>open
3775 </i>does that); they just increment the counter in the existing structure. The <i>close </i>system
3776 call executes the <i>release </i>method only when the counter for the <font class="fixd">file</font> structure
3777 drops to 0, which happens when the structure is destroyed. This relationship
3778 between the <i>release </i>method and the <i>close </i>system call guarantees that your driver sees
3779 only one <i>release</i> call for each <i>open</i>.<br>
3780 <br>
3781 Note that the <i>flush </i>method <i>is </i>called every time an application calls <i>close</i>. However,
3782 very few drivers implement <i>flush</i>, because usually there's nothing to perform at close
3783 time unless <i>release</i> is involved.<br>
3784 <br>
3785 As you may imagine, the previous discussion applies even when the application terminates
3786 without explicitly closing its open files: the kernel automatically closes any
3787 file at process exit time by internally using the <i>close</i> system call.<br>
3788 <br>
3789 <a name="ScullsMemoryUsage"></a><font color="red"><b>scull's Memory Usage</b></font><br>
3790 <br>
3791 Before introducing the <i>read </i>and <i>write </i>operations, we'd better look at how and why
3792 <i>scull </i>performs memory allocation. "How" is needed to thoroughly understand the
3793 code, and "why" demonstrates the kind of choices a driver writer needs to make,
3794 although <i>scull</i> is definitely not typical as a device.<br>
3795 <br>
3796 This section deals only with the memory allocation policy in <i>scull </i>and doesn't show
3797 the hardware management skills you need to write real drivers. These skills are introduced
3798 in Chapters 9 and 10. Therefore, you can skip this section if you're not interested
3799 in understanding the inner workings of the memory-oriented <i>scull</i> driver.<br>
3800 <br>
3801 The region of memory used by <i>scull</i>, also called a <i>device</i>, is variable in length. The
3802 more you write, the more it grows; trimming is performed by overwriting the device
3803 with a shorter file.<br>
3804 <br>
3805 The <i>scull </i>driver introduces two core functions used to manage memory in the Linux
3806 kernel. These functions, defined in <i><linux/slab.h></i>, are:<br>
3807 <pre>
3808 void *kmalloc(size_t size, int flags);
3809 void kfree(void *ptr);
3810 </pre>
3811 A call to <i>kmalloc </i>attempts to allocate <font class="fixd">size</font> bytes of memory; the return value is a
3812 pointer to that memory or <font class="fixd">NULL</font> if the allocation fails. The flags argument is used to<br>
3813 <br>
3814 <A name="61"></a><font color="blue">PAGE 61</font><br>
3815 <br>
3816 describe how the memory should be allocated; we examine those flags in detail in
3817 Chapter 8. For now, we always use <font class="fixd">GFP_KERNEL</font>. Allocated memory should be freed
3818 with <i>kfree</i>. You should never pass anything to <i>kfree </i>that was not obtained from
3819 <i>kmalloc</i>. It is, however, legal to pass a <font class="fixd">NULL</font> pointer to <i>kfree</i>.<br>
3820 <br>
3821 <i>kmalloc </i>is not the most efficient way to allocate large areas of memory (see
3822 Chapter 8), so the implementation chosen for <i>scull </i>is not a particularly smart one.
3823 The source code for a smart implementation would be more difficult to read, and the
3824 aim of this section is to show <i>read </i>and <i>write</i>, not memory management. That's why
3825 the code just uses <i>kmalloc </i>and <i>kfree </i>without resorting to allocation of whole pages,
3826 although that approach would be more efficient.<br>
3827 <br>
3828 On the flip side, we didn't want to limit the size of the "device" area, for both a
3829 philosophical reason and a practical one. Philosophically, it's always a bad idea to
3830 put arbitrary limits on data items being managed. Practically, <i>scull </i>can be used to
3831 temporarily eat up your system's memory in order to run tests under low-memory
3832 conditions. Running such tests might help you understand the system's internals.
3833 You can use the command <i>cp /dev/zero /dev/scull0 </i>to eat all the real RAM with <i>scull</i>,
3834 and you can use the <i>dd</i> utility to choose how much data is copied to the <i>scull</i> device.<br>
3835 <br>
3836 In <i>scull</i>, each device is a linked list of pointers, each of which points to a <font class="fixd">scull_qset</font>
3837 structure. Each such structure can refer, by default, to at most four million bytes,
3838 through an array of intermediate pointers. The released source uses an array of 1000
3839 pointers to areas of 4000 bytes. We call each memory area a <i>quantum </i>and the array
3840 (or its length) a <i>quantum set</i>. A <i>scull </i>device and its memory areas are shown in
3841 Figure 3-1.<br>
3842 <br><br>
3843 <center>
3844 <img src="fig3-1.gif">
3845 </center>
3846 <br>
3847 <i>Figure 3-1. The layout of a scull device</i><br>
3848 <br>
3849 <A name="62"></a><font color="blue">PAGE 62</font><br>
3850 <br>
3851 The chosen numbers are such that writing a single byte in <i>scull </i>consumes 8000 or
3852 12,000 bytes of memory: 4000 for the quantum and 4000 or 8000 for the
3853 quantum set (according to whether a pointer is represented in 32 bits or 64 bits on
3854 the target platform). If, instead, you write a huge amount of data, the overhead of the
3855 linked list is not too bad. There is only one list element for every four megabytes of
3856 data, and the maximum size of the device is limited by the computer's memory size.<br>
3857 <br>
3858 Choosing the appropriate values for the quantum and the quantum set is a question
3859 of policy, rather than mechanism, and the optimal sizes depend on how the device is
3860 used. Thus, the <i>scull </i>driver should not force the use of any particular values for the
3861 quantum and quantum set sizes. In <i>scull</i>, the user can change the values in
3862 several ways: by changing the macros <font class="fixd">SCULL_QUANTUM</font> and <font class="fixd">SCULL_QSET</font> in <i>scull.h </i>at
3863 compile time, by setting the integer values <font class="fixd">scull_quantum</font> and <font class="fixd">scull_qset</font> at module
3864 load time, or by changing both the current and default values using <i>ioctl</i> at runtime.<br>
3865 <br>
3866 Using a macro and an integer value to allow both compile-time and load-time configuration
3867 is reminiscent of how the major number is selected. We use this technique
3868 for whatever value in the driver is arbitrary or related to policy.<br>
3869 <br>
3870 The only question left is how the default numbers have been chosen. In this particular
3871 case, the problem is finding the best balance between the waste of memory resulting
3872 from half-filled quanta and quantum sets and the overhead of allocation,
3873 deallocation, and pointer chaining that occurs if quanta and sets are small. Additionally,
3874 the internal design of <i>kmalloc </i>should be taken into account. (We won't pursue
3875 the point now, though; the innards of <i>kmalloc </i>are explored in Chapter 8.) The choice
3876 of default numbers comes from the assumption that massive amounts of data are
3877 likely to be written to <i>scull </i>while testing it, although normal use of the device will
3878 most likely transfer just a few kilobytes of data.<br>
3879 <br>
3880 We have already seen the <font class="fixd">scull_dev</font> structure that represents our device internally.
3881 That structure's quantum and qset fields hold the device's quantum and quantum set
3882 sizes, respectively. The actual data, however, is tracked by a different structure,
3883 which we call <font class="fixd">struct scull_qset</font>:<br>
3884 <pre>
3885 struct scull_qset {
3886 void **data;
3887 struct scull_qset *next;
3888 };
3889 </pre>
3890 The next code fragment shows in practice how <font class="fixd">struct scull_dev</font> and <font class="fixd">struct scull_qset</font>
3891 are used to hold data. The function <i>scull_trim </i>is in charge of freeing the whole data
3892 area and is invoked by <i>scull_open </i>when the file is opened for writing. It simply walks
3893 through the list and frees any quantum and quantum set it finds.<br>
3894 <pre>
3895 int scull_trim(struct scull_dev *dev)
3896 {
3897 struct scull_qset *next, *dptr;
3898 int qset = dev->qset; /* "dev" is not-null */
3899 int i;
3900 </pre>
3901 <A name="63"></a><font color="blue">PAGE 63</font>
3902 <pre>
3903 for (dptr = dev->data; dptr; dptr = next) { /* all the list items */
3904 if (dptr->data) {
3905 for (i = 0; i < qset; i++)
3906 kfree(dptr->data[i]);
3907 kfree(dptr->data);
3908 dptr->data = NULL;
3909 }
3910 next = dptr->next;
3911 kfree(dptr);
3912 }
3913 dev->size = 0;
3914 dev->quantum = scull_quantum;
3915 dev->qset = scull_qset;
3916 dev->data = NULL;
3917 return 0;
3918 }
3919 </pre>
3920 <i>scull_trim </i>is also used in the module cleanup function to return memory used by
3921 <i>scull</i> to the system.<br>
3922 <br>
3923 <a name="ReadAndWrite"></a><font color="red"><b>read and write</b></font><br>
3924 <br>
3925 The <i>read </i>and <i>write </i>methods both perform a similar task, that is, copying data from
3926 and to application code. Therefore, their prototypes are pretty similar, and it's worth
3927 introducing them at the same time:<br>
3928 <pre>
3929 ssize_t read(struct file *filp, char __user *buff,
3930 size_t count, loff_t *offp);
3931 ssize_t write(struct file *filp, const char __user *buff,
3932 size_t count, loff_t *offp);
3933 </pre>
3934 For both methods, <font class="fixd">filp</font> is the file pointer and <font class="fixd">count</font> is the size of the requested data
3935 transfer. The <font class="fixd">buff</font> argument points to the user buffer holding the data to be written or
3936 the empty buffer where the newly read data should be placed. Finally, <font class="fixd">offp</font> is a pointer
3937 to a "long offset type" object that indicates the file position the user is accessing. The
3938 return value is a "signed size type"; its use is discussed later.<br>
3939 <br>
3940 Let us repeat that the <font class="fixd">buff</font> argument to the <i>read </i>and <i>write </i>methods is a user-space
3941 pointer. Therefore, it cannot be directly dereferenced by kernel code. There are a few
3942 reasons for this restriction:<br>
3943 <ul>
3944 <li> Depending on which architecture your driver is running on, and how the kernel
3945 was configured, the user-space pointer may not be valid while running in kernel
3946 mode at all. There may be no mapping for that address, or it could point to some
3947 other, random data.
3948 <li> Even if the pointer does mean the same thing in kernel space, user-space memory
3949 is paged, and the memory in question might not be resident in RAM when
3950 the system call is made. Attempting to reference the user-space memory directly
3951 could generate a page fault, which is something that kernel code is not allowed
3952 </ul>
3953 <A name="64"></a><font color="blue">PAGE 64</font>
3954 <ul>
3955 to do. The result would be an "oops," which would result in the death of the
3956 process that made the system call.
3957 <li> The pointer in question has been supplied by a user program, which could be
3958 buggy or malicious. If your driver ever blindly dereferences a user-supplied
3959 pointer, it provides an open doorway allowing a user-space program to access or
3960 overwrite memory anywhere in the system. If you do not wish to be responsible
3961 for compromising the security of your users' systems, you cannot ever dereference
3962 a user-space pointer directly.
3963 </ul>
3964 Obviously, your driver must be able to access the user-space buffer in order to get its
3965 job done. This access must always be performed by special, kernel-supplied functions,
3966 however, in order to be safe. We introduce some of those functions (which are
3967 defined in <i><asm/uaccess.h></i>) here, and the rest in the section "Using the ioctl Argument"
3968 in Chapter 6; they use some special, architecture-dependent magic to ensure
3969 that data transfers between kernel and user space happen in a safe and correct way.<br>
3970 <br>
3971 The code for <i>read </i>and <i>write </i>in <i>scull </i>needs to copy a whole segment of data to or from
3972 the user address space. This capability is offered by the following kernel functions,
3973 which copy an arbitrary array of bytes and sit at the heart of most <i>read </i>and <i>write
3974 </i>implementations:<br>
3975 <pre>
3976 unsigned long copy_to_user(void __user *to,
3977 const void *from,
3978 unsigned long count);
3979 unsigned long copy_from_user(void *to,
3980 const void __user *from,
3981 unsigned long count);
3982 </pre>
3983 Although these functions behave like normal <i>memcpy </i>functions, a little extra care
3984 must be used when accessing user space from kernel code. The user pages being
3985 addressed might not be currently present in memory, and the virtual memory subsystem
3986 can put the process to sleep while the page is being transferred into place.
3987 This happens, for example, when the page must be retrieved from swap space. The
3988 net result for the driver writer is that any function that accesses user space must be
3989 reentrant, must be able to execute concurrently with other driver functions, and, in
3990 particular, must be in a position where it can legally sleep. We return to this subject
3991 in Chapter 5.<br>
3992 <br>
3993 The role of the two functions is not limited to copying data to and from user-space:
3994 they also check whether the user space pointer is valid. If the pointer is invalid, no copy
3995 is performed; if an invalid address is encountered during the copy, on the other hand,
3996 only part of the data is copied. In both cases, the return value is the amount of memory
3997 still to be copied. The <i>scull </i>code looks for this error return, and returns <font class="fixd">-EFAULT</font> to
3998 the user if it's not 0.<br>
3999 <br>
4000 The topic of user-space access and invalid user space pointers is somewhat advanced
4001 and is discussed in Chapter 6. However, it's worth noting that if you don't need to<br>
4002 <br>
4003 <A name="65"></a><font color="blue">PAGE 65</font><br>
4004 <br>
4005 check the user-space pointer you can invoke <i>__copy_to_user </i>and <i>__copy_from_user
4006 </i>instead. This is useful, for example, if you know you already checked the argument.
4007 Be careful, however; if, in fact, you do <i>not </i>check a user-space pointer that you pass to
4008 these functions, then you can create kernel crashes and/or security holes.<br>
4009 <br>
4010 As far as the actual device methods are concerned, the task of the <i>read </i>method is to
4011 copy data from the device to user space (using <i>copy_to_user</i>), while the <i>write </i>method
4012 must copy data from user space to the device (using <i>copy_from_user</i>). Each <i>read </i>or
4013 <i>write </i>system call requests transfer of a specific number of bytes, but the driver is free
4014 to transfer less data--the exact rules are slightly different for reading and writing and
4015 are described later in this chapter.<br>
4016 <br>
4017 Whatever the amount of data the methods transfer, they should generally update the
4018 file position at *offp to represent the current file position after successful completion
4019 of the system call. The kernel then propagates the file position change back into
4020 the <font class="fixd">file</font> structure when appropriate. The <i>pread </i>and <i>pwrite </i>system calls have different
4021 semantics, however; they operate from a given file offset and do not change the
4022 file position as seen by any other system calls. These calls pass in a pointer to the
4023 user-supplied position, and discard the changes that your driver makes.<br>
4024 <br><br>
4025 <center>
4026 <img src="fig3-2.gif">
4027 </center>
4028 <br>
4029 <i>Figure 3-2. The arguments to read</i><br>
4030 <br>
4031 Both the <i>read </i>and <i>write </i>methods return a negative value if an error occurs. A return
4032 value greater than or equal to 0, instead, tells the calling program how many bytes
4033 have been successfully transferred. If some data is transferred correctly and then an
4034 error happens, the return value must be the count of bytes successfully transferred,<br>
4035 <br>
4036 <A name="66"></a><font color="blue">PAGE 66</font><br>
4037 <br>
4038 and the error does not get reported until the next time the function is called. Implementing
4039 this convention requires, of course, that your driver remember that the error
4040 has occurred so that it can return the error status in the future.<br>
4041 <br>
4042 Although kernel functions return a negative number to signal an error, and the value
4043 of the number indicates the kind of error that occurred (as introduced in Chapter 2),
4044 programs that run in user space always see -1 as the error return value. They need to
4045 access the errno variable to find out what happened. The user-space behavior is dictated
4046 by the POSIX standard, but that standard does not make requirements on how
4047 the kernel operates internally.<br>
4048 <br>
4049 <a name="TheReadMethod"></a><font color="red"><b>The read Method</b></font><br>
4050 <br>
4051 The return value for <i>read</i> is interpreted by the calling application program:<br>
4052 <ul>
4053 <li> If the value equals the <font class="fixd">count</font> argument passed to the <i>read </i>system call, the
4054 requested number of bytes has been transferred. This is the optimal case.
4055 <li> If the value is positive, but smaller than <font class="fixd">count,</font> only part of the data has been
4056 transferred. This may happen for a number of reasons, depending on the device.
4057 Most often, the application program retries the read. For instance, if you read
4058 using the <i>fread </i>function, the library function reissues the system call until completion
4059 of the requested data transfer.
4060 <li> If the value is 0, end-of-file was reached (and no data was read).
4061 <li> A negative value means there was an error. The value specifies what the error
4062 was, according to <i><linux/errno.h></i>. Typical values returned on error include <font class="fixd">-EINTR</font>
4063 (interrupted system call) or <font class="fixd">-EFAULT</font> (bad address).
4064 </ul>
4065 What is missing from the preceding list is the case of "there is no data, but it may
4066 arrive later." In this case, the <i>read </i>system call should block. We'll deal with blocking
4067 input in Chapter 6.<br>
4068 <br>
4069 The <i>scull </i>code takes advantage of these rules. In particular, it takes advantage of the
4070 partial-read rule. Each invocation of <i>scull_read </i>deals only with a single data quantum,
4071 without implementing a loop to gather all the data; this makes the code shorter
4072 and easier to read. If the reading program really wants more data, it reiterates the
4073 call. If the standard I/O library (i.e., <i>fread</i>) is used to read the device, the application
4074 won't even notice the quantization of the data transfer.<br>
4075 <br>
4076 If the current read position is greater than the device size, the <i>read </i>method of <i>scull
4077 </i>returns 0 to signal that there's no data available (in other words, we're at end-of-file).
4078 This situation can happen if process A is reading the device while process B opens it
4079 for writing, thus truncating the device to a length of 0. Process A suddenly finds itself
4080 past end-of-file, and the next <i>read</i> call returns 0.<br>
4081 <br>
4082 <A name="67"></a><font color="blue">PAGE 67</font><br>
4083 <br>
4084 Here is the code for <i>read </i>(ignore the calls to <i>down_interruptible </i>and <i>up </i>for now; we
4085 will get to them in the next chapter):<br>
4086 <pre>
4087 ssize_t scull_read(struct file *filp, char __user *buf, size_t count,
4088 loff_t *f_pos)
4089 {
4090 struct scull_dev *dev = filp->private_data;
4091 struct scull_qset *dptr; /* the first listitem */
4092 int quantum = dev->quantum, qset = dev->qset;
4093 int itemsize = quantum * qset; /* how many bytes in the listitem */
4094 int item, s_pos, q_pos, rest;
4095 ssize_t retval = 0;
4097 if (down_interruptible(&dev->sem))
4098 return -ERESTARTSYS;
4099 if (*f_pos >= dev->size)
4100 goto out;
4101 if (*f_pos + count > dev->size)
4102 count = dev->size - *f_pos;
4104 /* find listitem, qset index, and offset in the quantum */
4105 item = (long)*f_pos / itemsize;
4106 rest = (long)*f_pos % itemsize;
4107 s_pos = rest / quantum; q_pos = rest % quantum;
4109 /* follow the list up to the right position (defined elsewhere) */
4110 dptr = scull_follow(dev, item);
4112 if (dptr = = NULL || !dptr->data || ! dptr->data[s_pos])
4113 goto out; /* don't fill holes */
4115 /* read only up to the end of this quantum */
4116 if (count > quantum - q_pos)
4117 count = quantum - q_pos;
4119 if (copy_to_user(buf, dptr->data[s_pos] + q_pos, count)) {
4120 retval = -EFAULT;
4121 goto out;
4122 }
4123 *f_pos += count;
4124 retval = count;
4126 out:
4127 up(&dev->sem);
4128 return retval;
4129 }
4130 </pre>
4131 <A name="68"></a><font color="blue">PAGE 68</font><br>
4132 <br>
4133 <a name="TheWriteMethod"></a><font color="red"><b>The write Method</b></font><br>
4134 <br>
4135 <i>write</i>, like <i>read</i>, can transfer less data than was requested, according to the following
4136 rules for the return value:<br>
4137 <ul>
4138 <li> If the value equals <font class="fixd">count,</font> the requested number of bytes has been transferred.
4139 <li> If the value is positive, but smaller than count, only part of the data has been
4140 transferred. The program will most likely retry writing the rest of the data.
4141 <li> If the value is 0, nothing was written. This result is not an error, and there is no
4142 reason to return an error code. Once again, the standard library retries the call to
4143 <i>write</i>. We'll examine the exact meaning of this case in Chapter 6, where blocking
4144 <i>write</i> is introduced.
4145 <li> A negative value means an error occurred; as for <i>read</i>, valid error values are
4146 those defined in <i><linux/errno.h></i>.<br>
4147 </ul>
4148 Unfortunately, there may still be misbehaving programs that issue an error message
4149 and abort when a partial transfer is performed. This happens because some programmers
4150 are accustomed to seeing <i>write </i>calls that either fail or succeed completely,
4151 which is actually what happens most of the time and should be supported by devices
4152 as well. This limitation in the <i>scull </i>implementation could be fixed, but we didn't
4153 want to complicate the code more than necessary.<br>
4154 <br>
4155 The <i>scull </i>code for <i>write </i>deals with a single quantum at a time, as the <i>read </i>method
4156 does:<br>
4157 <pre>
4158 ssize_t scull_write(struct file *filp, const char __user *buf, size_t count,
4159 loff_t *f_pos)
4160 {
4161 struct scull_dev *dev = filp->private_data;
4162 struct scull_qset *dptr;
4163 int quantum = dev->quantum, qset = dev->qset;
4164 int itemsize = quantum * qset;
4165 int item, s_pos, q_pos, rest;
4166 ssize_t retval = -ENOMEM; /* value used in "goto out" statements */
4168 if (down_interruptible(&dev->sem))
4169 return -ERESTARTSYS;
4171 /* find listitem, qset index and offset in the quantum */
4172 item = (long)*f_pos / itemsize;
4173 rest = (long)*f_pos % itemsize;
4174 s_pos = rest / quantum; q_pos = rest % quantum;
4176 /* follow the list up to the right position */
4177 dptr = scull_follow(dev, item);
4178 if (dptr = = NULL)
4179 goto out;
4180 if (!dptr->data) {
4181 dptr->data = kmalloc(qset * sizeof(char *), GFP_KERNEL);
4182 if (!dptr->data)
4183 </pre>
4184 <A name="69"></a><font color="blue">PAGE 69</font><br>
4185 <pre>
4186 goto out;
4187 memset(dptr->data, 0, qset * sizeof(char *));
4188 }
4189 if (!dptr->data[s_pos]) {
4190 dptr->data[s_pos] = kmalloc(quantum, GFP_KERNEL);
4191 if (!dptr->data[s_pos])
4192 goto out;
4193 }
4194 /* write only up to the end of this quantum */
4195 if (count > quantum - q_pos)
4196 count = quantum - q_pos;
4198 if (copy_from_user(dptr->data[s_pos]+q_pos, buf, count)) {
4199 retval = -EFAULT;
4200 goto out;
4201 }
4202 *f_pos += count;
4203 retval = count;
4205 /* update the size */
4206 if (dev->size < *f_pos)
4207 dev->size = *f_pos;
4209 out:
4210 up(&dev->sem);
4211 return retval;
4212 }
4213 </pre>
4214 <a name="ReadvAndWritev"></a><font color="red"><b>readv and writev</b></font><br>
4215 <br>
4216 Unix systems have long supported two system calls named <i>readv </i>and <i>writev</i>. These
4217 "vector" versions of <i>read </i>and <i>write </i>take an array of structures, each of which contains
4218 a pointer to a buffer and a length value. A <i>readv </i>call would then be expected to
4219 read the indicated amount into each buffer in turn. <i>writev</i>, instead, would gather
4220 together the contents of each buffer and put them out as a single write operation.<br>
4221 <br>
4222 If your driver does not supply methods to handle the vector operations, <i>readv </i>and
4223 <i>writev </i>are implemented with multiple calls to your <i>read </i>and <i>write </i>methods. In many
4224 situations, however, greater efficiency is achieved by implementing <i>readv </i>and <i>writev
4225 </i>directly.<br>
4226 <br>
4227 The prototypes for the vector operations are:<br>
4228 <pre>
4229 ssize_t (*readv) (struct file *filp, const struct iovec *iov,
4230 unsigned long count, loff_t *ppos);
4231 ssize_t (*writev) (struct file *filp, const struct iovec *iov,
4232 unsigned long count, loff_t *ppos);
4233 </pre>
4234 Here, the <font class="fixd">filp</font> and <font class="fixd">ppos</font> arguments are the same as for <i>read </i>and <i>write</i>.
4235 The <font class="fixd">iovec</font> structure, defined in <i><linux/uio.h></i>, looks like:<br>
4236 <pre>
4237 struct iovec
4238 {
4239 </pre>
4240 <A name="70"></a><font color="blue">PAGE 70</font><br>
4241 <pre>
4242 void __user *iov_base;
4243 __kernel_size_t iov_len;
4244 };
4245 </pre>
4246 Each <font class="fixd">iovec</font> describes one chunk of data to be transferred; it starts at <font class="fixd">iov_base</font> (in user
4247 space) and is <font class="fixd">iov_len</font> bytes long. The count parameter tells the method how many
4248 <font class="fixd">iovec</font> structures there are. These structures are created by the application, but the
4249 kernel copies them into kernel space before calling the driver.<br>
4250 <br>
4251 The simplest implementation of the vectored operations would be a straightforward
4252 loop that just passes the address and length out of each <font class="fixd">iovec</font> to the driver's <i>read </i>or
4253 <i>write </i>function. Often, however, efficient and correct behavior requires that the driver
4254 do something smarter. For example, a <i>writev </i>on a tape drive should write the contents
4255 of all the <font class="fixd">iovec</font> structures as a single record on the tape.<br>
4256 <br>
4257 Many drivers, however, gain no benefit from implementing these methods themselves.
4258 Therefore, <i>scull </i>omits them. The kernel emulates them with <i>read </i>and <i>write</i>,
4259 and the end result is the same.<br>
4260 <br>
4261 <a name="PlayingWithTheNewDevices"></a><font color="red"><b>Playing with the New Devices</b></font><br>
4262 <br>
4263 Once you are equipped with the four methods just described, the driver can be compiled
4264 and tested; it retains any data you write to it until you overwrite it with new
4265 data. The device acts like a data buffer whose length is limited only by the amount of
4266 real RAM available. You can try using <i>cp</i>, <i>dd</i>, and input/output redirection to test out
4267 the driver.<br>
4268 <br>
4269 The <i>free </i>command can be used to see how the amount of free memory shrinks and
4270 expands according to how much data is written into <i>scull</i>.<br>
4271 <br>
4272 To get more confident with reading and writing one quantum at a time, you can add
4273 a <i>printk </i>at an appropriate point in the driver and watch what happens while an application
4274 reads or writes large chunks of data. Alternatively, use the <i>strace </i>utility to
4275 monitor the system calls issued by a program, together with their return values. Tracing
4276 a <i>cp </i>or an <i>ls -l > /dev/scull0 </i>shows quantized reads and writes. Monitoring (and
4277 debugging) techniques are presented in detail in Chapter 4<br>
4278 <br>
4279 <a name="QuickReference3"></a><font color="red"><b>Quick Reference</b></font><br>
4280 <br>
4281 This chapter introduced the following symbols and header files. The list of the fields
4282 in <font class="fixd">struct file_operations</font> and <font class="fixd">struct file</font> is not repeated here.<br>
4283 <br>
4284 <A name="71"></a><font color="blue">PAGE 71</font><br>
4285 <br>
4286 <font class="fixd">#include <linux/types.h><br>
4287 dev_t</font><br>
4288 <div class="bq">
4289 <font class="fixd">dev_t</font> is the type used to represent device numbers within the kernel.</div>
4290 <br>
4291 <font class="fixd">int MAJOR(dev_t dev);<br>
4292 int MINOR(dev_t dev);</font><br>
4293 <div class="bq">
4294 Macros that extract the major and minor numbers from a device number.</div>
4295 <br>
4296 <font class="fixd">dev_t MKDEV(unsigned int major, unsigned int minor);</font><br>
4297 <div class="bq">
4298 Macro that builds a <font class="fixd">dev_t</font> data item from the major and minor numbers.</div>
4299 <br>
4300 <font class="fixd">#include <linux/fs.h></font><br>
4301 <div class="bq">
4302 The "filesystem" header is the header required for writing device drivers. Many
4303 important functions and data structures are declared in here.</div>
4304 <br>
4305 <font class="fixd">int register_chrdev_region(dev_t first, unsigned int count, char *name)<br>
4306 int alloc_chrdev_region(dev_t *dev, unsigned int firstminor, unsigned int count, char *name)<br>
4307 void unregister_chrdev_region(dev_t first, unsigned int count);</font><br>
4308 <div class="bq">
4309 Functions that allow a driver to allocate and free ranges of device numbers.
4310 <i>register_chrdev_region </i>should be used when the desired major number is known
4311 in advance; for dynamic allocation, use <i>alloc_chrdev_region</i> instead.</div>
4312 <br>
4313 <font class="fixd">int register_chrdev(unsigned int major, const char *name, struct file_operations *fops);</font><br>
4314 <div class="bq">
4315 The old (pre-2.6) char device registration routine. It is emulated in the 2.6 kernel
4316 but should not be used for new code. If the major number is not 0, it is used
4317 unchanged; otherwise a dynamic number is assigned for this device.</div>
4318 <br>
4319 <font class="fixd">int unregister_chrdev(unsigned int major, const char *name);</font><br>
4320 <div class="bq">
4321 Function that undoes a registration made with <i>register_chrdev</i>. Both <font class="fixd">major</font> and
4322 the <font class="fixd">name</font> string must contain the same values that were used to register the driver.</div>
4323 <br>
4324 <font class="fixd">struct file_operations;<br>
4325 struct file;<br>
4326 struct inode;</font><br>
4327 <div class="bq">
4328 Three important data structures used by most device drivers. The <font class="fixd">file_operations</font>
4329 structure holds a char driver's methods; <font class="fixd">struct file</font> represents an open file, and
4330 <font class="fixd">struct inode</font> represents a file on disk.</div>
4331 <br>
4332 <font class="fixd">#include <linux/cdev.h><br>
4333 struct cdev *cdev_alloc(void);<br>
4334 void cdev_init(struct cdev *dev, struct file_operations *fops);<br>
4335 int cdev_add(struct cdev *dev, dev_t num, unsigned int count);<br>
4336 void cdev_del(struct cdev *dev);</font><br>
4337 <div class="bq">
4338 Functions for the management of <font class="fixd">cdev</font> structures, which represent char devices
4339 within the kernel.</div>
4340 <br>
4341 <A name="72"></a><font color="blue">PAGE 72</font><br>
4342 <br>
4343 <font class="fixd">#include <linux/kernel.h><br>
4344 container_of(pointer, type, field);</font> <br>
4345 <div class="bq">
4346 A convenience macro that may be used to obtain a pointer to a structure from a
4347 pointer to some other structure contained within it.</div>
4348 <br>
4349 <font class="fixd">#include <asm/uaccess.h></font> <br>
4350 <div class="bq">
4351 This include file declares functions used by kernel code to move data to and
4352 from user space.</div>
4353 <br>
4354 <font class="fixd">unsigned long copy_from_user (void *to, const void *from, unsigned long count);<br>
4355 unsigned long copy_to_user (void *to, const void *from, unsigned long count);</font> <br>
4356 <div class="bq">
4357 Copy data between user space and kernel space.</div>
4358 <br>
4359 <A name="73"></a><font color="blue">PAGE 73</font><br>
4360 <br>
4361 <a name="CHAPTER4"></a><font color="red"><b>CHAPTER 4</b></font><br>
4362 <br>
4363 <a name="DebuggingTechniques"></a><font color="#7519FF" size="+1"><b>Debugging Techniques</b></font><br>
4364 <br>
4365 Kernel programming brings its own, unique debugging challenges. Kernel code cannot
4366 be easily executed under a debugger, nor can it be easily traced, because it is a set
4367 of functionalities not related to a specific process. Kernel code errors can also be
4368 exceedingly hard to reproduce and can bring down the entire system with them, thus
4369 destroying much of the evidence that could be used to track them down.<br>
4370 <br>
4371 This chapter introduces techniques you can use to monitor kernel code and trace
4372 errors under such trying circumstances.<br>
4373 <br>
4374 <a name="DebuggingSupportInTheKernel"></a><font color="red"><b>Debugging Support in the Kernel</b></font><br>
4375 <br>
4376 In Chapter 2, we recommended that you build and install your own kernel, rather
4377 than running the stock kernel that comes with your distribution. One of the strongest
4378 reasons for running your own kernel is that the kernel developers have built several
4379 debugging features into the kernel itself. These features can create extra output
4380 and slow performance, so they tend not to be enabled in production kernels from
4381 distributors. As a kernel developer, however, you have different priorities and will
4382 gladly accept the (minimal) overhead of the extra kernel debugging support.<br>
4383 <br>
4384 Here, we list the configuration options that should be enabled for kernels used for
4385 development. Except where specified otherwise, all of these options are found under
4386 the "kernel hacking" menu in whatever kernel configuration tool you prefer. Note
4387 that some of these options are not supported by all architectures.<br>
4388 <br>
4389 <font class="fixd">CONFIG_DEBUG_KERNEL</font><br>
4390 <div class="bq">
4391 This option just makes other debugging options available; it should be turned on
4392 but does not, by itself, enable any features.</div>
4393 <br>
4394 <font class="fixd">CONFIG_DEBUG_SLAB</font><br>
4395 <div class="bq">
4396 This crucial option turns on several types of checks in the kernel memory allocation
4397 functions; with these checks enabled, it is possible to detect a number of
4398 memory overrun and missing initialization errors. Each byte of allocated memory</div>
4399 <br>
4400 <A name="74"></a><font color="blue">PAGE 74</font><br>
4401 <br>
4402 <div class="bq">
4403 is set to 0xa5 before being handed to the caller and then set to 0x6b when it is
4404 freed. If you ever see either of those "poison" patterns repeating in output from
4405 your driver (or often in an oops listing), you'll know exactly what sort of error to
4406 look for. When debugging is enabled, the kernel also places special guard values
4407 before and after every allocated memory object; if those values ever get changed,
4408 the kernel knows that somebody has overrun a memory allocation, and it complains
4409 loudly. Various checks for more obscure errors are enabled as well.</div>
4410 <br>
4411 <font class="fixd">CONFIG_DEBUG_PAGEALLOC</font><br>
4412 <div class="bq">
4413 Full pages are removed from the kernel address space when freed. This option
4414 can slow things down significantly, but it can also quickly point out certain
4415 kinds of memory corruption errors.</div>
4416 <br>
4417 <font class="fixd">CONFIG_DEBUG_SPINLOCK</font><br>
4418 <div class="bq">
4419 With this option enabled, the kernel catches operations on uninitialized spinlocks
4420 and various other errors (such as unlocking a lock twice).</div>
4421 <br>
4422 <font class="fixd">CONFIG_DEBUG_SPINLOCK_SLEEP</font><br>
4423 <div class="bq">
4424 This option enables a check for attempts to sleep while holding a spinlock. In
4425 fact, it complains if you call a function that could potentially sleep, even if the
4426 call in question would not sleep.</div>
4427 <br>
4428 <font class="fixd">CONFIG_INIT_DEBUG</font><br>
4429 <div class="bq">
4430 Items marked with <font class="fixd">__init</font> (or <font class="fixd">__initdata</font>) are discarded after system initialization
4431 or module load time. This option enables checks for code that attempts to
4432 access initialization-time memory after initialization is complete.</div>
4433 <br>
4434 <font class="fixd">CONFIG_DEBUG_INFO</font><br>
4435 <div class="bq">
4436 This option causes the kernel to be built with full debugging information
4437 included. You'll need that information if you want to debug the kernel with <i>gdb</i>.
4438 You may also want to enable <font class="fixd">CONFIG_FRAME_POINTER</font> if you plan to use <i>gdb</i>.</div>
4439 <br>
4440 <font class="fixd">CONFIG_MAGIC_SYSRQ</font><br>
4441 <div class="bq">
4442 Enables the "magic SysRq" key. We look at this key in the section "System
4443 Hangs," later in this chapter.</div>
4444 <br>
4445 <font class="fixd">CONFIG_DEBUG_STACKOVERFLOW</font>
4446 <font class="fixd">CONFIG_DEBUG_STACK_USAGE</font><br>
4447 <div class="bq">
4448 These options can help track down kernel stack overflows. A sure sign of a stack
4449 overflow is an oops listing without any sort of reasonable back trace. The first
4450 option adds explicit overflow checks to the kernel; the second causes the kernel
4451 to monitor stack usage and make some statistics available via the magic SysRq
4452 key.</div>
4453 <br>
4454 <font class="fixd">CONFIG_KALLSYMS</font><br>
4455 <div class="bq">
4456 This option (under "General setup/Standard features") causes kernel symbol
4457 information to be built into the kernel; it is enabled by default. The symbol
4458 information is used in debugging contexts; without it, an oops listing can give
4459 you a kernel traceback only in hexadecimal, which is not very useful.</div>
4460 <br>
4461 <A name="75"></a><font color="blue">PAGE 75</font><br>
4462 <br>
4463 <font class="fixd">CONFIG_IKCONFIG</font>
4464 <font class="fixd">CONFIG_IKCONFIG_PROC</font><br>
4465 <div class="bq">
4466 These options (found in the "General setup" menu) cause the full kernel configuration
4467 state to be built into the kernel and to be made available via <i>/proc</i>. Most
4468 kernel developers know which configuration they used and do not need these
4469 options (which make the kernel bigger). They can be useful, though, if you are
4470 trying to debug a problem in a kernel built by somebody else.</div>
4471 <br>
4472 <font class="fixd">CONFIG_ACPI_DEBUG</font><br>
4473 <div class="bq">
4474 Under "Power management/ACPI." This option turns on verbose ACPI
4475 (Advanced Configuration and Power Interface) debugging information, which
4476 can be useful if you suspect a problem related to ACPI.</div>
4477 <br>
4478 <font class="fixd">CONFIG_DEBUG_DRIVER</font><br>
4479 <div class="bq">
4480 Under "Device drivers." Turns on debugging information in the driver core,
4481 which can be useful for tracking down problems in the low-level support code.
4482 We'll look at the driver core in Chapter 14.</div>
4483 <br>
4484 <font class="fixd">CONFIG_SCSI_CONSTANTS</font><br>
4485 <div class="bq">
4486 This option, found under "Device drivers/SCSI device support," builds in information
4487 for verbose SCSI error messages. If you are working on a SCSI driver, you
4488 probably want this option.</div>
4489 <br>
4490 <font class="fixd">CONFIG_INPUT_EVBUG</font><br>
4491 <div class="bq">
4492 This option (under "Device drivers/Input device support") turns on verbose logging
4493 of input events. If you are working on a driver for an input device, this
4494 option may be helpful. Be aware of the security implications of this option, however:
4495 it logs everything you type, including your passwords.</div>
4496 <br>
4497 <font class="fixd">CONFIG_PROFILING</font><br>
4498 <div class="bq">
4499 This option is found under "Profiling support." Profiling is normally used for
4500 system performance tuning, but it can also be useful for tracking down some
4501 kernel hangs and related problems.</div>
4502 <br>
4503 We will revisit some of the above options as we look at various ways of tracking
4504 down kernel problems. But first, we will look at the classic debugging technique:
4505 print statements.<br>
4506 <br>
4507 <a name="DebuggingByPrinting"></a><font color="red"><b>Debugging by Printing</b></font><br>
4508 <br>
4509 The most common debugging technique is monitoring, which in applications programming
4510 is done by calling <i>printf </i>at suitable points. When you are debugging kernel
4511 code, you can accomplish the same goal with <i>printk</i>.<br>
4512 <br>
4513 <A name="76"></a><font color="blue">PAGE 76</font><br>
4514 <br>
4515 <a name="Printk"></a><font color="red"><b>printk</b></font><br>
4516 <br>
4517 We used the <i>printk </i>function in earlier chapters with the simplifying assumption that
4518 it works like <i>printf</i>. Now it's time to introduce some of the differences.<br>
4519 <br>
4520 One of the differences is that <i>printk </i>lets you classify messages according to their
4521 severity by associating different <i>loglevels</i>, or priorities, with the messages. You usually
4522 indicate the loglevel with a macro. For example, <font class="fixd">KERN_INFO,</font> which we saw
4523 prepended to some of the earlier print statements, is one of the possible loglevels of
4524 the message. The loglevel macro expands to a string, which is concatenated to the
4525 message text at compile time; that's why there is no comma between the priority and
4526 the format string in the following examples. Here are two examples of <i>printk </i>commands,
4527 a debug message and a critical message:<br>
4528 <pre>
4529 printk(KERN_DEBUG "Here I am: %s:%i\n", __FILE__, __LINE__);
4530 printk(KERN_CRIT "I'm trashed; giving up on %p\n", ptr);
4531 </pre>
4532 There are eight possible loglevel strings, defined in the header <i><linux/kernel.h></i>; we
4533 list them in order of decreasing severity:<br>
4534 <br>
4535 <font class="fixd">KERN_EMERG</font><br>
4536 <div class="bq">
4537 Used for emergency messages, usually those that precede a crash.</div>
4538 <br>
4539 <font class="fixd">KERN_ALERT</font><br>
4540 <div class="bq">
4541 A situation requiring immediate action.</div>
4542 <br>
4543 <font class="fixd">KERN_CRIT</font><br>
4544 <div class="bq">
4545 Critical conditions, often related to serious hardware or software failures.</div>
4546 <br>
4547 <font class="fixd">KERN_ERR</font><br>
4548 <div class="bq">
4549 Used to report error conditions; device drivers often use <font class="fixd">KERN_ERR</font> to report hardware
4550 difficulties.</div>
4551 <br>
4552 <font class="fixd">KERN_WARNING</font><br>
4553 <div class="bq">
4554 Warnings about problematic situations that do not, in themselves, create serious
4555 problems with the system.</div>
4556 <br>
4557 <font class="fixd">KERN_NOTICE</font><br>
4558 <div class="bq">
4559 Situations that are normal, but still worthy of note. A number of security-related
4560 conditions are reported at this level.</div>
4561 <br>
4562 <font class="fixd">KERN_INFO</font><br>
4563 <div class="bq">
4564 Informational messages. Many drivers print information about the hardware
4565 they find at startup time at this level.</div>
4566 <br>
4567 <font class="fixd">KERN_DEBUG</font><br>
4568 <div class="bq">
4569 Used for debugging messages.</div>
4570 <br>
4571 Each string (in the macro expansion) represents an integer in angle brackets. Integers
4572 range from 0 to 7, with smaller values representing higher priorities.<br>
4573 <br>
4574 <A name="77"></a><font color="blue">PAGE 77</font><br>
4575 <br>
4576 A <i>printk </i>statement with no specified priority defaults to <font class="fixd">DEFAULT_MESSAGE_LOGLEVEL,</font>
4577 specified in <i>kernel/printk.c </i>as an integer. In the 2.6.10 kernel, <font class="fixd">DEFAULT_MESSAGE_LOGLEVEL</font>
4578 is <font class="fixd">KERN_WARNING,</font> but that has been known to change in the past.<br>
4579 <br>
4580 Based on the loglevel, the kernel may print the message to the current console, be it a
4581 text-mode terminal, a serial port, or a parallel printer. If the priority is less than the
4582 integer variable <font class="fixd">console_loglevel</font>, the message is delivered to the console one line at
4583 a time (nothing is sent unless a trailing newline is provided). If both <i>klogd </i>and <i>syslogd
4584 </i>are running on the system, kernel messages are appended to <i>/var/log/messages
4585 </i>(or otherwise treated depending on your <i>syslogd </i>configuration), independent of
4586 <font class="fixd">console_loglevel</font>. If <i>klogd </i>is not running, the message won't reach user space unless
4587 you read <i>/proc/kmsg </i>(which is often most easily done with the <i>dmesg </i>command).
4588 When using <i>klogd</i>, you should remember that it doesn't save consecutive identical
4589 lines; it only saves the first such line and, at a later time, the number of repetitions it
4590 received.<br>
4591 <br>
4592 The variable <font class="fixd">console_loglevel</font> is initialized to <font class="fixd">DEFAULT_CONSOLE_LOGLEVEL</font> and can be
4593 modified through the <i>sys_syslog </i>system call. One way to change it is by specifying
4594 the <i>-c </i>switch when invoking <i>klogd</i>, as specified in the <i>klogd </i>manpage. Note that to
4595 change the current value, you must first kill <i>klogd </i>and then restart it with the <i>-c
4596 </i>option. Alternatively, you can write a program to change the console loglevel. You'll
4597 find a version of such a program in <i>misc-progs/setlevel.c </i>in the source files provided
4598 on O'Reilly's FTP site. The new level is specified as an integer value between 1 and 8,
4599 inclusive. If it is set to 1, only messages of level 0 (<font class="fixd">KERN_EMERG</font>) reach the console; if it
4600 is set to 8, all messages, including debugging ones, are displayed.<br>
4601 <br>
4602 It is also possible to read and modify the console loglevel using the text file <i>/proc/sys/
4603 kernel/printk</i>. The file hosts four integer values: the current loglevel, the default level
4604 for messages that lack an explicit loglevel, the minimum allowed loglevel, and the
4605 boot-time default loglevel. Writing a single value to this file changes the current
4606 loglevel to that value; thus, for example, you can cause all kernel messages to appear
4607 at the console by simply entering:<br>
4608 <pre>
4609 # <b>echo 8 > /proc/sys/kernel/printk</b>
4610 </pre>
4611 It should now be apparent why the <i>hello.c </i>sample had the <font class="fixd">KERN_ALERT</font>; markers; they
4612 are there to make sure that the messages appear on the console.<br>
4613 <br>
4614 <a name="RedirectingConsoleMessages"></a><font color="red"><b>Redirecting Console Messages</b></font><br>
4615 <br>
4616 Linux allows for some flexibility in console logging policies by letting you send messages
4617 to a specific virtual console (if your console lives on the text screen). By default,
4618 the "console" is the current virtual terminal. To select a different virtual terminal to
4619 receive messages, you can issue <font class="fixd">ioctl(TIOCLINUX)</font> on any console device. The following
4620 program, <i>setconsole</i>, can be used to choose which console receives kernel messages;
4621 it must be run by the superuser and is available in the <i>misc-progs</i> directory.<br>
4622 <br>
4623 <A name="78"></a><font color="blue">PAGE 78</font><br>
4624 <br>
4625 The following is the program in its entirety. You should invoke it with a single argument
4626 specifying the number of the console that is to receive messages.<br>
4627 <pre>
4628 int main(int argc, char **argv)
4629 {
4630 char bytes[2] = {11,0}; /* 11 is the TIOCLINUX cmd number */
4632 if (argc==2) bytes[1] = atoi(argv[1]); /* the chosen console */
4633 else {
4634 fprintf(stderr, "%s: need a single arg\n",argv[0]); exit(1);
4635 }
4636 if (ioctl(STDIN_FILENO, TIOCLINUX, bytes)<0) { /* use stdin */
4637 fprintf(stderr,"%s: ioctl(stdin, TIOCLINUX): %s\n",
4638 argv[0], strerror(errno));
4639 exit(1);
4640 }
4641 exit(0);
4642 }
4643 </pre>
4644 <i>setconsole </i>uses the special <i>ioctl </i>command <font class="fixd">TIOCLINUX</font>, which implements Linux specific
4645 functions. To use <font class="fixd">TIOCLINUX</font>, you pass it an argument that is a pointer to a
4646 byte array. The first byte of the array is a number that specifies the requested subcommand,
4647 and the following bytes are subcommand specific. In <i>setconsole</i>, subcommand
4648 11 is used, and the next byte (stored in bytes[1]) identifies the virtual console.
4649 The complete description of <font class="fixd">TIOCLINUX</font> can be found in <i>drivers/char/tty_io.c</i>, in the
4650 kernel sources.<br>
4651 <br>
4652 <a name="HowMessagesGetLogged"></a><font color="red"><b>How Messages Get Logged</b></font><br>
4653 <br>
4654 The <i>printk </i>function writes messages into a circular buffer that is <font class="fixd">__LOG_BUF_LEN</font> bytes
4655 long: a value from 4 KB to 1 MB chosen while configuring the kernel. The function
4656 then wakes any process that is waiting for messages, that is, any process that is sleeping
4657 in the <i>syslog </i>system call or that is reading <i>/proc/kmsg</i>. These two interfaces to the
4658 logging engine are almost equivalent, but note that reading from <i>/proc/kmsg </i>consumes
4659 the data from the log buffer, whereas the <i>syslog </i>system call can optionally
4660 return log data while leaving it for other processes as well. In general, reading the
4661 <i>/proc </i>file is easier and is the default behavior for <i>klogd</i>. The <i>dmesg </i>command can be
4662 used to look at the content of the buffer without flushing it; actually, the command
4663 returns to <i>stdout </i>the whole content of the buffer, whether or not it has already been
4664 read.<br>
4665 <br>
4666 If you happen to read the kernel messages by hand, after stopping <i>klogd</i>, you'll find
4667 that the <i>/proc </i>file looks like a FIFO, in that the reader blocks, waiting for more data.
4668 Obviously, you can't read messages this way if <i>klogd </i>or another process is already
4669 reading the same data, because you'll contend for it.<br>
4670 <br>
4671 If the circular buffer fills up, <i>printk </i>wraps around and starts adding new data to the
4672 beginning of the buffer, overwriting the oldest data. Therefore, the logging process<br>
4673 <br>
4674 <A name="79"></a><font color="blue">PAGE 79</font><br>
4675 <br>
4676 loses the oldest data. This problem is negligible compared with the advantages of
4677 using such a circular buffer. For example, a circular buffer allows the system to run
4678 even without a logging process, while minimizing memory waste by overwriting old
4679 data should nobody read it. Another feature of the Linux approach to messaging is
4680 that <i>printk </i>can be invoked from anywhere, even from an interrupt handler, with no
4681 limit on how much data can be printed. The only disadvantage is the possibility of
4682 losing some data.<br>
4683 <br>
4684 If the <i>klogd </i>process is running, it retrieves kernel messages and dispatches them to
4685 <i>syslogd</i>, which in turn checks <i>/etc/syslog.conf </i>to find out how to deal with them. <i>syslogd
4686 </i>differentiates between messages according to a facility and a priority; allowable
4687 values for both the facility and the priority are defined in <i><sys/syslog.h></i>. Kernel messages
4688 are logged by the <font class="fixd">LOG_KERN</font> facility at a priority corresponding to the one used in
4689 <i>printk </i>(for example, <font class="fixd">LOG_ERR</font> is used for <font class="fixd">KERN_ERR</font> messages). If <i>klogd </i>isn't running,
4690 data remains in the circular buffer until someone reads it or the buffer overflows.<br>
4691 <br>
4692 If you want to avoid clobbering your system log with the monitoring messages from
4693 your driver, you can either specify the <i>-f </i>(file) option to <i>klogd </i>to instruct it to save
4694 messages to a specific file, or customize <i>/etc/syslog.conf </i>to suit your needs. Yet
4695 another possibility is to take the brute-force approach: kill <i>klogd </i>and verbosely print
4696 messages on an unused virtual terminal,* or issue the command <i>cat /proc/kmsg </i>from
4697 an unused <i>xterm</i>.<br>
4698 <br>
4699 <a name="TurningTheMessagesOnAndOff"></a><font color="red"><b>Turning the Messages On and Off</b></font><br>
4700 <br>
4701 During the early stages of driver development, <i>printk </i>can help considerably in debugging
4702 and testing new code. When you officially release the driver, on the other hand,
4703 you should remove, or at least disable, such print statements. Unfortunately, you're
4704 likely to find that as soon as you think you no longer need the messages and remove
4705 them, you implement a new feature in the driver (or somebody finds a bug), and you
4706 want to turn at least one of the messages back on. There are several ways to solve
4707 both issues, to globally enable or disable your debug messages and to turn individual
4708 messages on or off.<br>
4709 <br>
4710 Here we show one way to code <i>printk </i>calls so you can turn them on and off individually
4711 or globally; the technique depends on defining a macro that resolves to a <i>printk
4712 </i>(or <i>printf</i>) call when you want it to:<br>
4713 <ul>
4714 <li> Each print statement can be enabled or disabled by removing or adding a single letter to the macro's name.
4715 <li> All the messages can be disabled at once by changing the value of the <font class="fixd">CFLAGS</font>
4716 variable before compiling.
4717 </ul>
4718 * For example, use <i>setlevel 8; setconsole 10</i> to set up terminal 10 to display messages.<br>
4719 <br>
4720 <A name="80"></a><font color="blue">PAGE 80</font>
4721 <ul>
4722 <li> The same print statement can be used in kernel code and user-level code, so that
4723 the driver and test programs can be managed in the same way with regard to
4724 extra messages.
4725 </ul>
4726 The following code fragment implements these features and comes directly from the
4727 header <i>scull.h</i>:<br>
4728 <pre>
4729 #undef PDEBUG /* undef it, just in case */
4730 #ifdef SCULL_DEBUG
4731 # ifdef __KERNEL__
4732 /* This one if debugging is on, and kernel space */
4733 # define PDEBUG(fmt, args...) printk( KERN_DEBUG "scull: " fmt, ## args)
4734 # else
4735 /* This one for user space */
4736 # define PDEBUG(fmt, args...) fprintf(stderr, fmt, ## args)
4737 # endif
4738 #else
4739 # define PDEBUG(fmt, args...) /* not debugging: nothing */
4740 #endif
4742 #undef PDEBUGG
4743 #define PDEBUGG(fmt, args...) /* nothing: it's a placeholder */
4744 </pre>
4745 The symbol <font class="fixd">PDEBUG</font> is defined or undefined, depending on whether <font class="fixd">SCULL_DEBUG</font> is
4746 defined, and displays information in whatever manner is appropriate to the environment
4747 where the code is running: it uses the kernel call <i>printk </i>when it's in the kernel
4748 and the <i>libc </i>call <i>fprintf </i>to the standard error when run in user space. The <font class="fixd">PDEBUGG</font>
4749 symbol, on the other hand, does nothing; it can be used to easily "comment" print
4750 statements without removing them entirely.<br>
4751 <br>
4752 To simplify the process further, add the following lines to your makefile:<br>
4753 <pre>
4754 # Comment/uncomment the following line to disable/enable debugging
4755 DEBUG = y
4757 # Add your debugging flag (or not) to CFLAGS
4758 ifeq ($(DEBUG),y)
4759 DEBFLAGS = -O -g -DSCULL_DEBUG # "-O" is needed to expand inlines
4760 else
4761 DEBFLAGS = -O2
4762 endif
4764 CFLAGS += $(DEBFLAGS)
4765 </pre>
4766 The macros shown in this section depend on a <i>gcc </i>extension to the ANSI C preprocessor
4767 that supports macros with a variable number of arguments. This <i>gcc </i>dependency
4768 shouldn't be a problem, because the kernel proper depends heavily on <i>gcc
4769 </i>features anyway. In addition, the makefile depends on GNU's version of <i>make</i>; once
4770 again, the kernel already depends on GNU <i>make</i>, so this dependency is not a problem.<br>
4771 <br>
4772 <A name="81"></a><font color="blue">PAGE 81</font><br>
4773 <br>
4774 If you're familiar with the C preprocessor, you can expand on the given definitions to
4775 implement the concept of a "debug level," defining different levels and assigning an
4776 integer (or bit mask) value to each level to determine how verbose it should be.<br>
4777 <br>
4778 But every driver has its own features and monitoring needs. The art of good programming
4779 is in choosing the best trade-off between flexibility and efficiency, and we
4780 can't tell what is the best for you. Remember that preprocessor conditionals (as well
4781 as constant expressions in the code) are executed at compile time, so you must
4782 recompile to turn messages on or off. A possible alternative is to use C conditionals,
4783 which are executed at runtime and, therefore, permit you to turn messaging on and
4784 off during program execution. This is a nice feature, but it requires additional processing
4785 every time the code is executed, which can affect performance even when the
4786 messages are disabled. Sometimes this performance hit is unacceptable.<br>
4787 <br>
4788 The macros shown in this section have proven themselves useful in a number of situations,
4789 with the only disadvantage being the requirement to recompile a module after
4790 any changes to its messages.<br>
4791 <br>
4792 <a name="RateLimiting"></a><font color="red"><b>Rate Limiting</b></font><br>
4793 <br>
4794 If you are not careful, you can find yourself generating thousands of messages with
4795 <i>printk</i>, overwhelming the console and, possibly, overflowing the system log file.
4796 When using a slow console device (e.g., a serial port), an excessive message rate can
4797 also slow down the system or just make it unresponsive. It can be very hard to get a
4798 handle on what is wrong with a system when the console is spewing out data nonstop.
4799 Therefore, you should be very careful about what you print, especially in production
4800 versions of drivers and especially once initialization is complete. In general,
4801 production code should never print anything during normal operation; printed output
4802 should be an indication of an exceptional situation requiring attention.<br>
4803 <br>
4804 On the other hand, you may want to emit a log message if a device you are driving
4805 stops working. But you should be careful not to overdo things. An unintelligent process
4806 that continues forever in the face of failures can generate thousands of retries per
4807 second; if your driver prints a "my device is broken" message every time, it could create
4808 vast amounts of output and possibly hog the CPU if the console device is slow-no
4809 interrupts can be used to driver the console, even if it is a serial port or a line
4810 printer.<br>
4811 <br>
4812 In many cases, the best behavior is to set a flag saying, "I have already complained
4813 about this," and not print any further messages once the flag gets set. In others,
4814 though, there are reasons to emit an occasional "the device is still broken" notice.
4815 The kernel has provided a function that can be helpful in such cases:<br>
4816 <pre>
4817 int printk_ratelimit(void);
4818 </pre>
4819 <A name="82"></a><font color="blue">PAGE 82</font><br>
4820 <br>
4821 This function should be called before you consider printing a message that could be
4822 repeated often. If the function returns a nonzero value, go ahead and print your message,
4823 otherwise skip it. Thus, typical calls look like this:<br>
4824 <pre>
4825 if (printk_ratelimit( ))
4826 printk(KERN_NOTICE "The printer is still on fire\n");
4827 </pre>
4828 <i>printk_ratelimit </i>works by tracking how many messages are sent to the console.
4829 When the level of output exceeds a threshold, <i>printk_ratelimit </i>starts returning 0 and
4830 causing messages to be dropped.<br>
4831 <br>
4832 The behavior of <i>printk_ratelimit </i>can be customized by modifying <i>/proc/sys/kernel/
4833 <font class="fixd">printk_ratelimit</font> </i>(the number of seconds to wait before re-enabling messages) and are
4834 <i>/proc/sys/kernel/printk_ratelimit_burst </i>(the number of messages accepted before rate-limiting).<br>
4835 <br>
4836 <a name="PrintingDeviceNumbers"></a><font color="red"><b>Printing Device Numbers</b></font><br>
4837 <br>
4838 Occasionally, when printing a message from a driver, you will want to print the
4839 device number associated with the hardware of interest. It is not particularly hard
4840 to print the major and minor numbers, but, in the interest of consistency, the kernel
4841 provides a couple of utility macros (defined in <i><linux/kdev_t.h></i>) for this purpose:<br>
4842 <pre>
4843 int print_dev_t(char *buffer, dev_t dev);
4844 char *format_dev_t(char *buffer, dev_t dev);
4845 </pre>
4846 Both macros encode the device number into the given buffer; the only difference is
4847 that <i>print_dev_t </i>returns the number of characters printed, while <i>format_dev_t </i>returns
4848 buffer; therefore, it can be used as a parameter to a <i>printk </i>call directly, although one
4849 must remember that <i>printk </i>doesn't flush until a trailing newline is provided. The
4850 buffer should be large enough to hold a device number; given that 64-bit device
4851 numbers are a distinct possibility in future kernel releases, the buffer should probably
4852 be at least 20 bytes long.<br>
4853 <br>
4854 <a name="DebuggingByQuerying"></a><font color="red"><b>Debugging by Querying</b></font><br>
4855 <br>
4856 The previous section described how <i>printk </i>works and how it can be used. What it
4857 didn't talk about are its disadvantages.<br>
4858 <br>
4859 A massive use of <i>printk </i>can slow down the system noticeably, even if you lower
4860 <i>console_loglevel </i>to avoid loading the console device, because <i>syslogd </i>keeps syncing
4861 its output files; thus, every line that is printed causes a disk operation. This is the
4862 right implementation from <i>syslogd</i>'s perspective. It tries to write everything to disk in
4863 case the system crashes right after printing the message; however, you don't want to
4864 slow down your system just for the sake of debugging messages. This problem can be
4865 solved by prefixing the name of your log file as it appears in <i>/etc/syslogd.conf </i>with a<br>
4866 <br>
4867 <A name="83"></a><font color="blue">PAGE 83</font><br>
4868 <br>
4869 hyphen.* The problem with changing the configuration file is that the modification
4870 will likely remain there after you are done debugging, even though during normal
4871 system operation you do want messages to be flushed to disk as soon as possible. An
4872 alternative to such a permanent change is running a program other than <i>klogd </i>(such
4873 as <i>cat /proc/kmsg</i>, as suggested earlier), but this may not provide a suitable environment
4874 for normal system operation.<br>
4875 <br>
4876 More often than not, the best way to get relevant information is to query the system
4877 when you need the information, instead of continually producing data. In fact, every
4878 Unix system provides many tools for obtaining system information: <i>ps</i>, <i>netstat</i>,
4879 <i>vmstat</i>, and so on.<br>
4880 <br>
4881 A few techniques are available to driver developers for querying the system: creating
4882 a file in the <i>/proc </i>filesystem, using the <i>ioctl </i>driver method, and exporting attributes
4883 via <i>sysfs</i>. The use of <i>sysfs </i>requires quite some background on the driver model. It is
4884 discussed in Chapter 14.<br>
4885 <br>
4886 <a name="UsingTheProcFilesystem"></a><font color="red"><b>Using the /proc Filesystem</b></font><br>
4887 <br>
4888 The <i>/proc </i>filesystem is a special, software-created filesystem that is used by the kernel
4889 to export information to the world. Each file under <i>/proc </i>is tied to a kernel function
4890 that generates the file's "contents" on the fly when the file is read. We have
4891 already seen some of these files in action; <i>/proc/modules</i>, for example, always returns
4892 a list of the currently loaded modules.<br>
4893 <br>
4894 <i>/proc </i>is heavily used in the Linux system. Many utilities on a modern Linux distribution,
4895 such as <i>ps</i>, <i>top</i>, and <i>uptime</i>, get their information from <i>/proc</i>. Some device drivers
4896 also export information via <i>/proc</i>, and yours can do so as well. The <i>/proc
4897 </i>filesystem is dynamic, so your module can add or remove entries at any time.<br>
4898 <br>
4899 Fully featured <i>/proc </i>entries can be complicated beasts; among other things, they can
4900 be written to as well as read from. Most of the time, however, <i>/proc </i>entries are readonly
4901 files. This section concerns itself with the simple read-only case. Those who are
4902 interested in implementing something more complicated can look here for the basics;
4903 the kernel source may then be consulted for the full picture.<br>
4904 <br>
4905 Before we continue, however, we should mention that adding files under <i>/proc </i>is discouraged.
4906 The <i>/proc </i>filesystem is seen by the kernel developers as a bit of an uncontrolled
4907 mess that has gone far beyond its original purpose (which was to provide
4908 information about the processes running in the system). The recommended way of
4909 making information available in new code is via sysfs. As suggested, working with
4910 sysfs requires an understanding of the Linux device model, however, and we do not<br>
4911 <br>
4912 * The hyphen, or minus sign, is a "magic" marker to prevent <i>syslogd </i>from flushing the file to disk at every new
4913 message, documented in <i>syslog.conf(5)</i>, a manpage worth reading.<br>
4914 <br>
4915 <A name="84"></a><font color="blue">PAGE 84</font><br>
4916 <br>
4917 get to that until Chapter 14. Meanwhile, files under <i>/proc </i>are slightly easier to create,
4918 and they are entirely suitable for debugging purposes, so we cover them here.<br>
4919 <br>
4920 <a name="ImplementingFilesInProc"></a><font color="red"><b>Implementing files in /proc</b></font><br>
4921 <br>
4922 All modules that work with <i>/proc </i>should include <i><linux/proc_fs.h> </i>to define the
4923 proper functions.<br>
4924 <br>
4925 To create a read-only <i>/proc </i>file, your driver must implement a function to produce
4926 the data when the file is read. When some process reads the file (using the <i>read </i>system
4927 call), the request reaches your module by means of this function. We'll look at
4928 this function first and get to the registration interface later in this section.<br>
4929 <br>
4930 When a process reads from your <i>/proc </i>file, the kernel allocates a page of memory (i.e.,
4931 <font class="fixd">PAGE_SIZE</font> bytes) where the driver can write data to be returned to user space. That
4932 buffer is passed to your function, which is a method called <i>read_proc</i>:<br>
4933 <pre>
4934 int (*read_proc)(char *page, char **start, off_t offset, int count,
4935 int *eof, void *data);
4936 </pre>
4937 The <font class="fixd">page</font> pointer is the buffer where you'll write your data; <font class="fixd">start</font> is used by the function
4938 to say where the interesting data has been written in <font class="fixd">page</font> (more on this later);
4939 <font class="fixd">offset</font> and <font class="fixd">count</font> have the same meaning as for the <i>read </i>method. The <font class="fixd">eof</font> argument
4940 points to an integer that must be set by the driver to signal that it has no more
4941 data to return, while <font class="fixd">data</font> is a driver-specific data pointer you can use for internal
4942 bookkeeping.<br>
4943 <br>
4944 This function should return the number of bytes of data actually placed in the <font class="fixd">page</font>
4945 buffer, just like the <i>read </i>method does for other files. Other output values are <font class="fixd">*eof</font>
4946 and <font class="fixd">*start. eof</font> is a simple flag, but the use of the <font class="fixd">start</font> value is somewhat more
4947 complicated; its purpose is to help with the implementation of large (greater than
4948 one page) <i>/proc</i> files.<br>
4949 <br>
4950 The <font class="fixd">start</font> parameter has a somewhat unconventional use. Its purpose is to indicate
4951 where (within <font class="fixd">page</font>) the data to be returned to the user is found. When your <i>proc_read
4952 </i>method is called, <font class="fixd">*start</font> will be <font class="fixd">NULL</font>. If you leave it <font class="fixd">NULL</font>, the kernel assumes that the
4953 data has been put into <font class="fixd">page</font> as if <font class="fixd">offset</font> were 0; in other words, it assumes a simpleminded
4954 version of <i>proc_read</i>, which places the entire contents of the virtual file in <font class="fixd">page</font>
4955 without paying attention to the <font class="fixd">offset</font> parameter. If, instead, you <font class="fixd">set *start</font> to a nonNULL
4956 value, the kernel assumes that the data pointed to by <font class="fixd">*start</font> takes <font class="fixd">offset</font> into
4957 account and is ready to be returned directly to the user. In general, simple <i>proc_read
4958 </i>methods that return tiny amounts of data just ignore <font class="fixd">start</font>. More complex methods set
4959 <font class="fixd">*start</font> to <font class="fixd">page</font> and only place data beginning at the requested <font class="fixd">offset</font> there.<br>
4960 <br>
4961 There has long been another major issue with <i>/proc </i>files, which <font class="fixd">start</font> is meant to
4962 solve as well. Sometimes the ASCII representation of kernel data structures changes
4963 between successive calls to <i>read</i>, so the reader process could find inconsistent data
4964 from one call to the next. If <font class="fixd">*start</font> is set to a small integer value, the caller uses it to<br>
4965 <br>
4966 <A name="85"></a><font color="blue">PAGE 85</font><br>
4967 <br>
4968 increment <font class="fixd">filp->f_pos</font> independently of the amount of data you return, thus making
4969 <font class="fixd">f_pos</font> an internal record number of your <i>read_proc </i>procedure. If, for example,
4970 your <i>read_proc </i>function is returning information from a big array of structures, and
4971 five of those structures were returned in the first call, <font class="fixd">*start</font> could be set to 5. The
4972 next call provides that same value as the offset; the driver then knows to start returning
4973 data from the sixth structure in the array. This is acknowledged as a "hack" by its
4974 authors and can be seen in <i>fs/proc/generic.c</i>.<br>
4975 <br>
4976 Note that there is a better way to implement large <i>/proc </i>files; it's called <font class="fixd">seq_file,</font> and
4977 we'll discuss it shortly. First, though, it is time for an example. Here is a simple (if
4978 somewhat ugly) <i>read_proc</i> implementation for the <i>scull</i> device:<br>
4979 <pre>
4980 int scull_read_procmem(char *buf, char **start, off_t offset,
4981 int count, int *eof, void *data)
4982 {
4983 int i, j, len = 0;
4984 int limit = count - 80; /* Don't print more than this */
4986 for (i = 0; i < scull_nr_devs && len <= limit; i++) {
4987 struct scull_dev *d = &scull_devices[i];
4988 struct scull_qset *qs = d->data;
4989 if (down_interruptible(&d->sem))
4990 return -ERESTARTSYS;
4991 len += sprintf(buf+len,"\nDevice %i: qset %i, q %i, sz %li\n",
4992 i, d->qset, d->quantum, d->size);
4993 for (; qs && len <= limit; qs = qs->next) { /* scan the list */
4994 len += sprintf(buf + len, " item at %p, qset at %p\n",
4995 qs, qs->data);
4996 if (qs->data && !qs->next) /* dump only the last item */
4997 for (j = 0; j < d->qset; j++) {
4998 if (qs->data[j])
4999 len += sprintf(buf + len,
5000 " % 4i: %8p\n",
5001 j, qs->data[j]);
5002 }
5003 }
5004 up(&scull_devices[i].sem);
5005 }
5006 *eof = 1;
5007 return len;
5008 }
5009 </pre>
5010 This is a fairly typical <i>read_proc </i>implementation. It assumes that there will never be a
5011 need to generate more than one page of data and so ignores the <font class="fixd">start</font> and <font class="fixd">offset</font> values.
5012 It is, however, careful not to overrun its buffer, just in case.<br>
5013 <br>
5014 <a name="AnOlderInterface"></a><font color="red"><b>An older interface</b></font><br>
5015 <br>
5016 If you read through the kernel source, you may encounter code implementing <i>/proc
5017 </i>files with an older interface:<br>
5018 <pre>
5019 int (*get_info)(char *page, char **start, off_t offset, int count);
5020 </pre>
5021 <A name="86"></a><font color="blue">PAGE 86</font><br>
5022 <br>
5023 All of the arguments have the same meaning as they do for <i>read_proc</i>, but the <font class="fixd">eof</font>
5024 and <font class="fixd">data</font> arguments are missing. This interface is still supported, but it could go
5025 away in the future; new code should use the <i>read_proc</i> interface instead.<br>
5026 <br>
5027 <a name="CreatingYourProcFile"></a><font color="red"><b>Creating your /proc file</b></font><br>
5028 <br>
5029 Once you have a <i>read_proc </i>function defined, you need to connect it to an entry in
5030 the <i>/proc</i> hierarchy. This is done with a call to <i>create_proc_read_entry</i>:<br>
5031 <pre>
5032 struct proc_dir_entry *create_proc_read_entry(const char *name,
5033 mode_t mode, struct proc_dir_entry *base,
5034 read_proc_t *read_proc, void *data);
5035 </pre>
5036 Here, <font class="fixd">name</font> is the name of the file to create, <font class="fixd">mode</font> is the protection mask for the file (it
5037 can be passed as 0 for a system-wide default), base indicates the directory in which the
5038 file should be created (if base is <font class="fixd">NULL</font>, the file is created in the <i>/proc </i>root), <font class="fixd">read_proc</font> is
5039 the <i>read_proc </i>function that implements the file, and data is ignored by the kernel (but
5040 passed to <i>read_proc</i>). Here is the call used by <i>scull </i>to make its <i>/proc </i>function available
5041 as <i>/proc/scullmem</i>:<br>
5042 <pre>
5043 create_proc_read_entry("scullmem", 0 /* default mode */,
5044 NULL /* parent dir */, scull_read_procmem,
5045 NULL /* client data */);
5046 </pre>
5047 Here, we create a file called <i>scullmem </i>directly under <i>/proc</i>, with the default, world-readable
5048 protections.<br>
5049 <br>
5050 The directory entry pointer can be used to create entire directory hierarchies under
5051 <i>/proc</i>. Note, however, that an entry may be more easily placed in a subdirectory of
5052 <i>/proc </i>simply by giving the directory name as part of the name of the entry--as long
5053 as the directory itself already exists. For example, an (often ignored) convention says
5054 that <i>/proc </i>entries associated with device drivers should go in the subdirectory <i>driver/</i>;
5055 <i>scull</i> could place its entry there simply by giving its name as <i>driver/scullmem</i>.<br>
5056 <br>
5057 Entries in <i>/proc</i>, of course, should be removed when the module is unloaded.
5058 <i>remove_proc_entry </i>is the function that undoes what <i>create_proc_read_entry </i>already
5059 did:<br>
5060 <pre>
5061 remove_proc_entry("scullmem", NULL /* parent dir */);
5062 </pre>
5063 Failure to remove entries can result in calls at unwanted times, or, if your module has
5064 been unloaded, kernel crashes.<br>
5065 <br>
5066 When using <i>/proc </i>files as shown, you must remember a few nuisances of the implementation--no
5067 surprise its use is discouraged nowadays.<br>
5068 <br>
5069 The most important problem is with removal of <i>/proc </i>entries. Such removal may well
5070 happen while the file is in use, as there is no owner associated to <i>/proc </i>entries, so
5071 using them doesn't act on the module's reference count. This problem is simply triggered
5072 by running <i>sleep 100 < /proc/myfile</i> just before removing the module, for example.<br>
5073 <br>
5074 <A name="87"></a><font color="blue">PAGE 87</font><br>
5075 <br>
5076 Another issue is about registering two entries with the same name. The kernel trusts
5077 the driver and doesn't check if the name is already registered, so if you are not careful
5078 you might end up with two or more entries with the same name. This is a problem
5079 known to happen in classrooms, and such entries are indistinguishable, both
5080 when you access them and when you call <i>remove_proc_entry</i>.<br>
5081 <br>
5082 <a name="TheSeqfileInterface"></a><font color="red"><b>The <font class="fixd">seq_file</font> interface</b></font><br>
5083 <br>
5084 As we noted above, the implementation of large files under <i>/proc </i>is a little awkward.
5085 Over time, <i>/proc </i>methods have become notorious for buggy implementations when
5086 the amount of output grows large. As a way of cleaning up the <i>/proc </i>code and making
5087 life easier for kernel programmers, the <font class="fixd">seq_file</font> interface was added. This interface
5088 provides a simple set of functions for the implementation of large kernel virtual
5089 files.<br>
5090 <br>
5091 The <font class="fixd">seq_file</font> interface assumes that you are creating a virtual file that steps through
5092 a sequence of items that must be returned to user space. To use <font class="fixd">seq_file</font>, you must
5093 create a simple "iterator" object that can establish a position within the sequence,
5094 step forward, and output one item in the sequence. It may sound complicated, but,
5095 in fact, the process is quite simple. We'll step through the creation of a <i>/proc </i>file in
5096 the <i>scull</i> driver to show how it is done.<br>
5097 <br>
5098 The first step, inevitably, is the inclusion of <i><linux/seq_file.h></i>. Then you must create
5099 four iterator methods, called <i>start</i>, <i>next</i>, <i>stop</i>, and <i>show</i>.<br>
5100 <br>
5101 The <i>start</i> method is always called first. The prototype for this function is:<br>
5102 <pre>
5103 void *start(struct seq_file *sfile, loff_t *pos);
5104 </pre>
5105 The <font class="fixd">sfile</font> argument can almost always be ignored. <font class="fixd">pos</font> is an integer position indicating
5106 where the reading should start. The interpretation of the position is entirely up to
5107 the implementation; it need not be a byte position in the resulting file. Since <font class="fixd">seq_file</font>
5108 implementations typically step through a sequence of interesting items, the position
5109 is often interpreted as a cursor pointing to the next item in the sequence. The <i>scull
5110 </i>driver interprets each device as one item in the sequence, so the incoming <font class="fixd">pos</font> is simply
5111 an index into the <font class="fixd">scull_devices</font> array. Thus, the <i>start</i> method used in <i>scull</i> is:<br>
5112 <pre>
5113 static void *scull_seq_start(struct seq_file *s, loff_t *pos)
5114 {
5115 if (*pos >= scull_nr_devs)
5116 return NULL; /* No more to read */
5117 return scull_devices + *pos;
5118 }
5119 </pre>
5120 The return value, if <font class="fixd">non-NULL</font>, is a private value that can be used by the iterator
5121 implementation.<br>
5122 <br>
5123 The <i>next </i>function should move the iterator to the next position, returning <font class="fixd">NULL</font> if
5124 there is nothing left in the sequence. This method's prototype is:<br>
5125 <pre>
5126 void *next(struct seq_file *sfile, void *v, loff_t *pos);
5127 </pre>
5128 <A name="88"></a><font color="blue">PAGE 88</font><br>
5129 <br>
5130 Here, v is the iterator as returned from the previous call to <i>start </i>or <i>next</i>, and <font class="fixd">pos</font> is
5131 the current position in the file. <i>next </i>should increment the value pointed to by <font class="fixd">pos</font>;
5132 depending on how your iterator works, you might (though probably won't) want to
5133 increment <font class="fixd">pos</font> by more than one. Here's what <i>scull</i> does:<br>
5134 <pre>
5135 static void *scull_seq_next(struct seq_file *s, void *v, loff_t *pos)
5136 {
5137 (*pos)++;
5138 if (*pos >= scull_nr_devs)
5139 return NULL;
5140 return scull_devices + *pos;
5141 }
5142 </pre>
5143 When the kernel is done with the iterator, it calls <i>stop</i> to clean up:<br>
5144 <pre>
5145 void stop(struct seq_file *sfile, void *v);
5146 </pre>
5147 The <i>scull</i> implementation has no cleanup work to do, so its <i>stop</i> method is empty.<br>
5148 <br>
5149 It is worth noting that the <font class="fixd">seq_file</font> code, by design, does not sleep or perform other
5150 nonatomic tasks between the calls to <i>start </i>and <i>stop</i>. You are also guaranteed to see
5151 one <i>stop </i>call sometime shortly after a call to <i>start</i>. Therefore, it is safe for your <i>start
5152 </i>method to acquire semaphores or spinlocks. As long as your other <font class="fixd">seq_file</font> methods
5153 are atomic, the whole sequence of calls is atomic. (If this paragraph does not
5154 make sense to you, come back to it after you've read the next chapter.)<br>
5155 <br>
5156 In between these calls, the kernel calls the <i>show </i>method to actually output something
5157 interesting to the user space. This method's prototype is:<br>
5158 <pre>
5159 int show(struct seq_file *sfile, void *v);
5160 </pre>
5161 This method should create output for the item in the sequence indicated by the iterator
5162 <font class="fixd">v.</font> It should not use <i>printk</i>, however; instead, there is a special set of functions for
5163 <font class="fixd">seq_file</font> output:<br>
5164 <br>
5165 <font class="fixd">int seq_printf(struct seq_file *sfile, const char *fmt, ...);</font><br>
5166 <div class="bq">
5167 This is the <i>printf </i>equivalent for <font class="fixd">seq_file</font> implementations; it takes the usual format
5168 string and additional value arguments. You must also pass it the <font class="fixd">seq_file</font>
5169 structure given to the <i>show </i>function, however. If <i>seq_printf </i>returns a nonzero
5170 value, it means that the buffer has filled, and output is being discarded. Most
5171 implementations ignore the return value, however.</div>
5172 <br>
5173 <font class="fixd">int seq_putc(struct seq_file *sfile, char c);<br>
5174 int seq_puts(struct seq_file *sfile, const char *s);</font><br>
5175 <div class="bq">
5176 These are the equivalents of the user-space <i>putc</i> and <i>puts</i> functions.</div>
5177 <br>
5178 <font class="fixd">int seq_escape(struct seq_file *m, const char *s, const char *esc);</font><br>
5179 <div class="bq">
5180 This function is equivalent to <i>seq_puts </i>with the exception that any character in
5181 s that is also found in <font class="fixd">esc</font> is printed in octal format. A common value for <font class="fixd">esc</font> is
5182 " \t\n\\", which keeps embedded white space from messing up the output and
5183 possibly confusing shell scripts.</div>
5184 <br>
5185 <A name="89"></a><font color="blue">PAGE 89</font><br>
5186 <br>
5187 <font class="fixd">int seq_path(struct seq_file *sfile, struct vfsmount *m, struct dentry
5188 *dentry, char *esc);</font><br>
5189 <div class="bq">
5190 This function can be used for outputting the file name associated with a given
5191 directory entry. It is unlikely to be useful in device drivers; we have included it
5192 here for completeness.</div>
5193 <br>
5194 Getting back to our example; the <i>show</i> method used in <i>scull</i> is:<br>
5195 <pre>
5196 static int scull_seq_show(struct seq_file *s, void *v)
5197 {
5198 struct scull_dev *dev = (struct scull_dev *) v;
5199 struct scull_qset *d;
5200 int i;
5202 if (down_interruptible(&dev->sem))
5203 return -ERESTARTSYS;
5204 seq_printf(s, "\nDevice %i: qset %i, q %i, sz %li\n",
5205 (int) (dev - scull_devices), dev->qset,
5206 dev->quantum, dev->size);
5207 for (d = dev->data; d; d = d->next) { /* scan the list */
5208 seq_printf(s, " item at %p, qset at %p\n", d, d->data);
5209 if (d->data && !d->next) /* dump only the last item */
5210 for (i = 0; i < dev->qset; i++) {
5211 if (d->data[i])
5212 seq_printf(s, " % 4i: %8p\n",
5213 i, d->data[i]);
5214 }
5215 }
5216 up(&dev->sem);
5217 return 0;
5218 }
5219 </pre>
5220 Here, we finally interpret our "iterator" value, which is simply a pointer to a <font class="fixd">scull_dev</font>
5221 structure.<br>
5222 <br>
5223 Now that it has a full set of iterator operations, <i>scull </i>must package them up and
5224 connect them to a file in <i>/proc</i>. The first step is done by filling in a <font class="fixd">seq_operations</font>
5225 structure:<br>
5226 <pre>
5227 static struct seq_operations scull_seq_ops = {
5228 .start = scull_seq_start,
5229 .next = scull_seq_next,
5230 .stop = scull_seq_stop,
5231 .show = scull_seq_show
5232 };
5233 </pre>
5234 With that structure in place, we must create a file implementation that the kernel
5235 understands. We do not use the <i>read_proc </i>method described previously; when using
5236 <font class="fixd">seq_file</font>, it is best to connect in to <i>/proc </i>at a slightly lower level. That means creating
5237 a <font class="fixd">file_operations</font> structure (yes, the same structure used for char drivers) implementing
5238 all of the operations needed by the kernel to handle reads and seeks on the<br>
5239 <br>
5240 <A name="90"></a><font color="blue">PAGE 90</font><br>
5241 <br>
5242 file. Fortunately, this task is straightforward. The first step is to create an <i>open
5243 </i>method that connects the file to the <font class="fixd">seq_file</font> operations:<br>
5244 <pre>
5245 static int scull_proc_open(struct inode *inode, struct file *file)
5246 {
5247 return seq_open(file, &scull_seq_ops);
5248 }
5249 </pre>
5250 The call to <i>seq_open </i>connects the <font class="fixd">file</font> structure with our sequence operations
5251 defined above. As it turns out, <i>open </i>is the only file operation we must implement
5252 ourselves, so we can now set up our <font class="fixd">file_operations</font> structure:<br>
5253 <pre>
5254 static struct file_operations scull_proc_ops = {
5255 .owner = THIS_MODULE,
5256 .open = scull_proc_open,
5257 .read = seq_read,
5258 .llseek = seq_lseek,
5259 .release = seq_release
5260 };
5261 </pre>
5262 Here we specify our own <i>open </i>method, but use the canned methods <i>seq_read</i>, <i>seq_
5263 lseek</i>, and <i>seq_release</i> for everything else.<br>
5264 <br>
5265 The final step is to create the actual file in <i>/proc</i>:<br>
5266 <pre>
5267 entry = create_proc_entry("scullseq", 0, NULL);
5268 if (entry)
5269 entry->proc_fops = &scull_proc_ops;
5270 </pre>
5271 Rather than using <i>create_proc_read_entry</i>, we call the lower-level <i>create_proc_entry</i>,
5272 which has this prototype:<br>
5273 <pre>
5274 struct proc_dir_entry *create_proc_entry(const char *name,
5275 mode_t mode,
5276 struct proc_dir_entry *parent);
5277 </pre>
5278 The arguments are the same as their equivalents in <i>create_proc_read_entry</i>: the name
5279 of the file, its protections, and the parent directory.<br>
5280 <br>
5281 With the above code, <i>scull </i>has a new <i>/proc </i>entry that looks much like the previous
5282 one. It is superior, however, because it works regardless of how large its output
5283 becomes, it handles seeks properly, and it is generally easier to read and maintain.
5284 We recommend the use of <font class="fixd">seq_file</font> for the implementation of files that contain more
5285 than a very small number of lines of output.<br>
5286 <br>
5287 <a name="TheIoctlMethod"></a><font color="red"><b>The ioctl Method</b></font><br>
5288 <br>
5289 <i>ioctl</i>, which we show you how to use in Chapter 6, is a system call that acts on a file
5290 descriptor; it receives a number that identifies a command to be performed and
5291 (optionally) another argument, usually a pointer. As an alternative to using the <i>/proc
5292 </i>filesystem, you can implement a few <i>ioctl </i>commands tailored for debugging. These<br>
5293 <br>
5294 <A name="91"></a><font color="blue">PAGE 91</font><br>
5295 <br>
5296 commands can copy relevant data structures from the driver to user space where you
5297 can examine them.<br>
5298 <br>
5299 Using <i>ioctl </i>this way to get information is somewhat more difficult than using <i>/proc</i>,
5300 because you need another program to issue the <i>ioctl </i>and display the results. This program
5301 must be written, compiled, and kept in sync with the module you're testing.
5302 On the other hand, the driver-side code can be easier than what is needed to implement
5303 a <i>/proc</i> file.<br>
5304 <br>
5305 There are times when <i>ioctl </i>is the best way to get information, because it runs faster
5306 than reading <i>/proc</i>. If some work must be performed on the data before it's written to
5307 the screen, retrieving the data in binary form is more efficient than reading a text file.
5308 In addition, <i>ioctl</i> doesn't require splitting data into fragments smaller than a page.<br>
5309 <br>
5310 Another interesting advantage of the <i>ioctl </i>approach is that information-retrieval commands
5311 can be left in the driver even when debugging would otherwise be disabled.
5312 Unlike a <i>/proc </i>file, which is visible to anyone who looks in the directory (and too
5313 many people are likely to wonder "what that strange file is"), undocumented <i>ioctl
5314 </i>commands are likely to remain unnoticed. In addition, they will still be there should
5315 something weird happen to the driver. The only drawback is that the module will be
5316 slightly bigger.<br>
5317 <br>
5318 <a name="DebuggingByWatching"></a><font color="red"><b>Debugging by Watching</b></font><br>
5319 <br>
5320 Sometimes minor problems can be tracked down by watching the behavior of an
5321 application in user space. Watching programs can also help in building confidence
5322 that a driver is working correctly. For example, we were able to feel confident about
5323 <i>scull </i>after looking at how its <i>read </i>implementation reacted to read requests for different
5324 amounts of data.<br>
5325 <br>
5326 There are various ways to watch a user-space program working. You can run a
5327 debugger on it to step through its functions, add print statements, or run the program
5328 under <i>strace</i>. Here we'll discuss just the last technique, which is most interesting
5329 when the real goal is examining kernel code.<br>
5330 <br>
5331 The <i>strace </i>command is a powerful tool that shows all the system calls issued by a
5332 user-space program. Not only does it show the calls, but it can also show the arguments
5333 to the calls and their return values in symbolic form. When a system call fails,
5334 both the symbolic value of the error (e.g., <font class="fixd">ENOMEM</font>) and the corresponding string (<font class="fixd">Out
5335 of memory</font>) are displayed. <i>strace </i>has many command-line options; the most useful of
5336 which are <i>-t </i>to display the time <i>when </i>each call is executed, <i>-T </i>to display the time
5337 spent in the call, <i>-e </i>to limit the types of calls traced, and <i>-o </i>to redirect the output to a
5338 file. By default, <i>strace</i> prints tracing information on stderr.<br>
5339 <br>
5340 <i>strace </i>receives information from the kernel itself. This means that a program can be
5341 traced regardless of whether or not it was compiled with debugging support (the <i>-g</i><br>
5342 <br>
5343 <A name="92"></a><font color="blue">PAGE 92</font><br>
5344 <br>
5345 option to <i>gcc</i>) and whether or not it is stripped. You can also attach tracing to a running
5346 process, similar to the way a debugger can connect to a running process and
5347 control it.<br>
5348 <br>
5349 The trace information is often used to support bug reports sent to application developers,
5350 but it's also invaluable to kernel programmers. We've seen how driver code
5351 executes by reacting to system calls; <i>strace </i>allows us to check the consistency of
5352 input and output data of each call.<br>
5353 <br>
5354 For example, the following screen dump shows (most of) the last lines of running the
5355 command <i>strace ls /dev > /dev/scull0</i>:<br>
5356 <pre>
5357 open("/dev", O_RDONLY|O_NONBLOCK|O_LARGEFILE|O_DIRECTORY) = 3
5358 fstat64(3, {st_mode=S_IFDIR|0755, st_size=24576, ...}) = 0
5359 fcntl64(3, F_SETFD, FD_CLOEXEC) = 0
5360 getdents64(3, /* 141 entries */, 4096) = 4088
5361 [...]
5362 getdents64(3, /* 0 entries */, 4096) = 0
5363 close(3) = 0
5364 [...]
5365 fstat64(1, {st_mode=S_IFCHR|0664, st_rdev=makedev(254, 0), ...}) = 0
5366 write(1, "MAKEDEV\nadmmidi0\nadmmidi1\nadmmid"..., 4096) = 4000
5367 write(1, "b\nptywc\nptywd\nptywe\nptywf\nptyx0\n"..., 96) = 96
5368 write(1, "b\nptyxc\nptyxd\nptyxe\nptyxf\nptyy0\n"..., 4096) = 3904
5369 write(1, "s17\nvcs18\nvcs19\nvcs2\nvcs20\nvcs21"..., 192) = 192
5370 write(1, "\nvcs47\nvcs48\nvcs49\nvcs5\nvcs50\nvc"..., 673) = 673
5371 close(1) = 0
5372 exit_group(0) = ?
5373 </pre>
5374 It's apparent from the first <i>write </i>call that after <i>ls </i>finished looking in the target directory,
5375 it tried to write 4 KB. Strangely (for <i>ls</i>), only 4000 bytes were written, and the
5376 operation was retried. However, we know that the <i>write </i>implementation in <i>scull
5377 </i>writes a single quantum at a time, so we could have expected the partial write. After
5378 a few steps, everything sweeps through, and the program exits successfully.<br>
5379 <br>
5380 As another example, let's <i>read</i> the <i>scull</i> device (using the <i>wc</i> command):<br>
5381 <pre>
5382 [...]
5383 open("/dev/scull0", O_RDONLY|O_LARGEFILE) = 3
5384 fstat64(3, {st_mode=S_IFCHR|0664, st_rdev=makedev(254, 0), ...}) = 0
5385 read(3, "MAKEDEV\nadmmidi0\nadmmidi1\nadmmid"..., 16384) = 4000
5386 read(3, "b\nptywc\nptywd\nptywe\nptywf\nptyx0\n"..., 16384) = 4000
5387 read(3, "s17\nvcs18\nvcs19\nvcs2\nvcs20\nvcs21"..., 16384) = 865
5388 read(3, "", 16384) = 0
5389 fstat64(1, {st_mode=S_IFCHR|0620, st_rdev=makedev(136, 1), ...}) = 0
5390 write(1, "8865 /dev/scull0\n", 17) = 17
5391 close(3) = 0
5392 exit_group(0) = ?
5393 </pre>
5394 As expected, <i>read </i>is able to retrieve only 4000 bytes at a time, but the total amount
5395 of data is the same that was written in the previous example. It's interesting to note
5396 how retries are organized in this example, as opposed to the previous trace. <i>wc </i>is<br>
5397 <br>
5398 <A name="93"></a><font color="blue">PAGE 93</font><br>
5399 <br>
5400 optimized for fast reading and, therefore, bypasses the standard library, trying to
5401 read more data with a single system call. You can see from the <font class="fixd">read</font> lines in the trace
5402 how <i>wc</i> tried to read 16 KB at a time.<br>
5403 <br>
5404 Linux experts can find much useful information in the output of <i>strace</i>. If you're put
5405 off by all the symbols, you can limit yourself to watching how the file methods (<i>open</i>,
5406 <i>read</i>, and so on) work with the efile flag.<br>
5407 <br>
5408 Personally, we find <i>strace </i>most useful for pinpointing runtime errors from system
5409 calls. Often the <i>perror </i>call in the application or demo program isn't verbose enough
5410 to be useful for debugging, and being able to tell exactly which arguments to which
5411 system call triggered the error can be a great help.<br>
5412 <br>
5413 <a name="DebuggingSystemFaults"></a><font color="red"><b>Debugging System Faults</b></font><br>
5414 <br>
5415 Even if you've used all the monitoring and debugging techniques, sometimes bugs
5416 remain in the driver, and the system faults when the driver is executed. When this
5417 happens, it's important to be able to collect as much information as possible to solve
5418 the problem.<br>
5419 <br>
5420 Note that "fault" doesn't mean "panic." The Linux code is robust enough to respond
5421 gracefully to most errors: a fault usually results in the destruction of the current process
5422 while the system goes on working. The system <i>can </i>panic, and it may if a fault
5423 happens outside of a process's context or if some vital part of the system is compromised.
5424 But when the problem is due to a driver error, it usually results only in the
5425 sudden death of the process unlucky enough to be using the driver. The only unrecoverable
5426 damage when a process is destroyed is that some memory allocated to the
5427 process's context is lost; for instance, dynamic lists allocated by the driver through
5428 <i>kmalloc </i>might be lost. However, since the kernel calls the <i>close </i>operation for any
5429 open device when a process dies, your driver can release what was allocated by the
5430 <i>open</i> method.<br>
5431 <br>
5432 Even though an oops usually does not bring down the entire system, you may well
5433 find yourself needing to reboot after one happens. A buggy driver can leave hardware
5434 in an unusable state, leave kernel resources in an inconsistent state, or, in the worst
5435 case, corrupt kernel memory in random places. Often you can simply unload your
5436 buggy driver and try again after an oops. If, however, you see anything that suggests
5437 that the system as a whole is not well, your best bet is usually to reboot immediately.<br>
5438 <br>
5439 We've already said that when kernel code misbehaves, an informative message is
5440 printed on the console. The next section explains how to decode and use such messages.
5441 Even though they appear rather obscure to the novice, processor dumps are
5442 full of interesting information, often sufficient to pinpoint a program bug without the
5443 need for additional testing.<br>
5444 <br>
5445 <A name="94"></a><font color="blue">PAGE 94</font><br>
5446 <br>
5447 <a name="OopsMessages"></a><font color="red"><b>Oops Messages</b></font><br>
5448 <br>
5449 Most bugs show themselves in <font class="fixd">NULL</font> pointer dereferences or by the use of other incorrect
5450 pointer values. The usual outcome of such bugs is an oops message.<br>
5451 <br>
5452 Almost any address used by the processor is a virtual address and is mapped to physical
5453 addresses through a complex structure of page tables (the exceptions are physical
5454 addresses used with the memory management subsystem itself). When an invalid
5455 pointer is dereferenced, the paging mechanism fails to map the pointer to a physical
5456 address, and the processor signals a <i>page fault </i>to the operating system. If the address
5457 is not valid, the kernel is not able to "page in" the missing address; it (usually) generates
5458 an oops if this happens while the processor is in supervisor mode.<br>
5459 <br>
5460 An oops displays the processor status at the time of the fault, including the contents
5461 of the CPU registers and other seemingly incomprehensible information. The message
5462 is generated by <i>printk </i>statements in the fault handler (<i>arch/*/kernel/traps.c</i>) and
5463 is dispatched as described earlier in the section "printk."<br>
5464 <br>
5465 Let's look at one such message. Here's what results from dereferencing a <font class="fixd">NULL</font> pointer
5466 on a PC running Version 2.6 of the kernel. The most relevant information here is the
5467 instruction pointer (<font class="fixd">EIP</font>), the address of the faulty instruction.<br>
5468 <pre>
5469 Unable to handle kernel <font class="fixd">NULL</font> pointer dereference at virtual address 00000000
5470 printing eip:
5471 d083a064
5472 Oops: 0002 [#1]
5473 SMP
5474 CPU: 0
5475 EIP: 0060:[<d083a064>] Not tainted
5476 EFLAGS: 00010246 (2.6.6)
5477 EIP is at faulty_write+0x4/0x10 [faulty]
5478 eax: 00000000 ebx: 00000000 ecx: 00000000 edx: 00000000
5479 esi: cf8b2460 edi: cf8b2480 ebp: 00000005 esp: c31c5f74
5480 ds: 007b es: 007b ss: 0068
5481 Process bash (pid: 2086, threadinfo=c31c4000 task=cfa0a6c0)
5482 Stack: c0150558 cf8b2460 080e9408 00000005 cf8b2480 00000000 cf8b2460 cf8b2460
5483 fffffff7 080e9408 c31c4000 c0150682 cf8b2460 080e9408 00000005 cf8b2480
5484 00000000 00000001 00000005 c0103f8f 00000001 080e9408 00000005 00000005
5485 Call Trace:
5486 [<c0150558>] vfs_write+0xb8/0x130
5487 [<c0150682>] sys_write+0x42/0x70
5488 [<c0103f8f>] syscall_call+0x7/0xb
5490 Code: 89 15 00 00 00 00 c3 90 8d 74 26 00 83 ec 0c b8 00 a6 83 d0
5491 </pre>
5492 This message was generated by writing to a device owned by the <i>faulty </i>module, a
5493 module built deliberately to demonstrate failures. The implementation of the <i>write
5494 </i>method of <i>faulty.c</i> is trivial:<br>
5495 <pre>
5496 ssize_t faulty_write (struct file *filp, const char __user *buf, size_t count,
5497 loff_t *pos)
5498 {
5499 </pre>
5500 <A name="95"></a><font color="blue">PAGE 95</font><br>
5501 <pre>
5502 /* make a simple fault by dereferencing a NULL pointer */
5503 *(int *)0 = 0;
5504 return 0;
5505 }
5506 </pre>
5507 As you can see, what we do here is dereference a <font class="fixd">NULL</font> pointer. Since 0 is never a valid
5508 pointer value, a fault occurs, which the kernel turns into the oops message shown
5509 earlier. The calling process is then killed.<br>
5510 <br>
5511 The <i>faulty</i> module has a different fault condition in its <i>read</i> implementation:<br>
5512 <pre>
5513 ssize_t faulty_read(struct file *filp, char __user *buf,
5514 size_t count, loff_t *pos)
5515 {
5516 int ret;
5517 char stack_buf[4];
5519 /* Let's try a buffer overflow */
5520 memset(stack_buf, 0xff, 20);
5521 if (count > 4)
5522 count = 4; /* copy 4 bytes to the user */
5523 ret = copy_to_user(buf, stack_buf, count);
5524 if (!ret)
5525 return count;
5526 return ret;
5527 }
5528 </pre>
5529 This method copies a string into a local variable; unfortunately, the string is longer
5530 than the destination array. The resulting buffer overflow causes an oops when the
5531 function returns. Since the return instruction brings the instruction pointer to
5532 nowhere land, this kind of fault is much harder to trace, and you can get something
5533 such as the following:<br>
5534 <pre>
5535 EIP: 0010:[<00000000>]
5536 Unable to handle kernel paging request at virtual address ffffffff
5537 printing eip:
5538 ffffffff
5539 Oops: 0000 [#5]
5540 SMP
5541 CPU: 0
5542 EIP: 0060:[<ffffffff>] Not tainted
5543 EFLAGS: 00010296 (2.6.6)
5544 EIP is at 0xffffffff
5545 eax: 0000000c ebx: ffffffff ecx: 00000000 edx: bfffda7c
5546 esi: cf434f00 edi: ffffffff ebp: 00002000 esp: c27fff78
5547 ds: 007b es: 007b ss: 0068
5548 Process head (pid: 2331, threadinfo=c27fe000 task=c3226150)
5549 Stack: ffffffff bfffda70 00002000 cf434f20 00000001 00000286 cf434f00 fffffff7
5550 bfffda70 c27fe000 c0150612 cf434f00 bfffda70 00002000 cf434f20 00000000
5551 00000003 00002000 c0103f8f 00000003 bfffda70 00002000 00002000 bfffda70
5552 Call Trace:
5553 [<c0150612>] sys_read+0x42/0x70
5554 [<c0103f8f>] syscall_call+0x7/0xb
5556 Code: Bad EIP value.
5557 </pre>
5558 <A name="96"></a><font color="blue">PAGE 96</font><br>
5559 <br>
5560 In this case, we see only part of the call stack (<i>vfs_read </i>and <i>faulty_read </i>are missing),
5561 and the kernel complains about a "bad <font class="fixd">EIP</font> value." That complaint, and the offending
5562 address (<font class="fixd">ffffffff</font>) listed at the beginning are both hints that the kernel stack has
5563 been corrupted.<br>
5564 <br>
5565 In general, when you are confronted with an oops, the first thing to do is to look at
5566 the location where the problem happened, which is usually listed separately from the
5567 call stack. In the first oops shown above, the relevant line is:<br>
5568 <pre>
5569 EIP is at faulty_write+0x4/0x10 [faulty]
5570 </pre>
5571 Here we see that we were in the function <i>faulty_write</i>, which is located in the <i>faulty
5572 </i>module (which is listed in square brackets). The hex numbers indicate that the
5573 instruction pointer was 4 bytes into the function, which appears to be 10 (hex) bytes
5574 long. Often that is enough to figure out what the problem is.<br>
5575 <br>
5576 If you need more information, the call stack shows you how you got to where things
5577 fell apart. The stack itself is printed in hex form; with a bit of work, you can often
5578 determine the values of local variables and function parameters from the stack listing.
5579 Experienced kernel developers can benefit from a certain amount of pattern recognition
5580 here; for example, if we look at the stack listing from the <i>faulty_read</i> oops:<br>
5581 <pre>
5582 Stack: ffffffff bfffda70 00002000 cf434f20 00000001 00000286 cf434f00 fffffff7
5583 bfffda70 c27fe000 c0150612 cf434f00 bfffda70 00002000 cf434f20 00000000
5584 00000003 00002000 c0103f8f 00000003 bfffda70 00002000 00002000 bfffda70
5585 </pre>
5586 The <font class="fixd">ffffffff</font> at the top of the stack is part of our string that broke things. On the
5587 x86 architecture, by default, the user-space stack starts just below <font class="fixd">0xc0000000;</font> thus,
5588 the recurring value <font class="fixd">0xbfffda70</font> is probably a user-space stack address; it is, in fact,
5589 the address of the buffer passed to the <i>read </i>system call, replicated each time it is
5590 passed down the kernel call chain. On the x86 (again, by default), kernel space starts
5591 at <font class="fixd">0xc0000000,</font> so values above that are almost certainly kernel-space addresses, and
5592 so on.<br>
5593 <br>
5594 Finally, when looking at oops listings, always be on the lookout for the "slab poisoning"
5595 values discussed at the beginning of this chapter. Thus, for example, if you get a
5596 kernel oops where the offending address is <font class="fixd">0xa5a5a5a5,</font> you are almost certainly forgetting
5597 to initialize dynamic memory somewhere.<br>
5598 <br>
5599 Please note that you see a symbolic call stack (as shown above) only if your kernel is
5600 built with the <font class="fixd">CONFIG_KALLSYMS</font> option turned on. Otherwise, you see a bare, hexadecimal
5601 listing, which is far less useful until you have decoded it in other ways.<br>
5602 <br>
5603 <a name="SystemHangs"></a><font color="red"><b>System Hangs</b></font><br>
5604 <br>
5605 Although most bugs in kernel code end up as oops messages, sometimes they can
5606 completely hang the system. If the system hangs, no message is printed. For example,<br>
5607 <br>
5608 <A name="97"></a><font color="blue">PAGE 97</font><br>
5609 <br>
5610 if the code enters an endless loop, the kernel stops scheduling,* and the system doesn't
5611 respond to any action, including the magic Ctrl-Alt-Del combination. You have two
5612 choices for dealing with system hangs--either prevent them beforehand or be able to
5613 debug them after the fact.<br>
5614 <br>
5615 You can prevent an endless loop by inserting <i>schedule </i>invocations at strategic points.
5616 The <i>schedule </i>call (as you might guess) invokes the scheduler and, therefore, allows
5617 other processes to steal CPU time from the current process. If a process is looping in
5618 kernel space due to a bug in your driver, the <i>schedule </i>calls enable you to kill the process
5619 after tracing what is happening.<br>
5620 <br>
5621 You should be aware, of course, that any call to <i>schedule </i>may create an additional
5622 source of reentrant calls to your driver, since it allows other processes to run. This
5623 reentrancy should not normally be a problem, assuming that you have used suitable
5624 locking in your driver. Be sure, however, not to call <i>schedule </i>any time that your
5625 driver is holding a spinlock.<br>
5626 <br>
5627 If your driver really hangs the system, and you don't know where to insert <i>schedule
5628 </i>calls, the best way to go may be to add some print messages and write them to the
5629 console (by changing the <font class="fixd">console_loglevel</font> value if need be).<br>
5630 <br>
5631 Sometimes the system may appear to be hung, but it isn't. This can happen, for
5632 example, if the keyboard remains locked in some strange way. These false hangs can
5633 be detected by looking at the output of a program you keep running for just this purpose.
5634 A clock or system load meter on your display is a good status monitor; as long
5635 as it continues to update, the scheduler is working.<br>
5636 <br>
5637 An indispensable tool for many lockups is the "magic SysRq key," which is available
5638 on most architectures. Magic SysRq is invoked with the combination of the Alt and
5639 SysRq keys on the PC keyboard, or with other special keys on other platforms (see
5640 <i>Documentation/sysrq.txt </i>for details), and is available on the serial console as well. A
5641 third key, pressed along with these two, performs one of a number of useful actions:<br>
5642 <dl>
5643 <dt>r<dd>Turns off keyboard raw mode; useful in situations where a crashed application
5644 (such as the X server) may have left your keyboard in a strange state.
5645 <dt>k<dd>Invokes the "secure attention key" (SAK) function. SAK kills all processes running
5646 on the current console, leaving you with a clean terminal.
5647 <dt>s
5648 <dd>Performs an emergency synchronization of all disks.
5649 <dt>u
5650 <dd>Umount. Attempts to remount all disks in a read-only mode. This operation,
5651 usually invoked immediately after <i>s</i>, can save a lot of filesystem checking time in
5652 cases where the system is in serious trouble.
5653 </dl>
5654 * Actually, multiprocessor systems still schedule on the other processors, and even a uniprocessor machine
5655 might reschedule if kernel preemption is enabled. For the most common case (uniprocessor with preemption
5656 disabled), however, the system stops scheduling altogether.<br>
5657 <br>
5658 <A name="98"></a><font color="blue">PAGE 98</font>
5659 <dl>
5660 <dt>b
5661 <dd>Boot. Immediately reboots the system. Be sure to synchronize and remount the
5662 disks first.
5663 <dt>p
5664 <dd>Prints processor registers information.
5665 <dt>t
5666 <dd>Prints the current task list.
5667 <dt>m
5668 <dd>Prints memory information.
5669 </dl>
5670 Other magic SysRq functions exist; see <i>sysrq.txt </i>in the <i>Documentation </i>directory of
5671 the kernel source for the full list. Note that magic SysRq must be explicitly enabled in
5672 the kernel configuration and that most distributions do not enable it, for obvious
5673 security reasons. For a system used to develop drivers, however, enabling magic
5674 SysRq is worth the trouble of building a new kernel in itself. Magic SysRq may be
5675 disabled at runtime with a command such as the following:<br>
5676 <pre>
5677 echo 0 > /proc/sys/kernel/sysrq
5678 </pre>
5679 You should consider disabling it if unprivileged users can reach your system keyboard,
5680 to prevent accidental or willing damages. Some previous kernel versions had
5681 <i>sysrq </i>disabled by default, so you needed to enable it at runtime by writing 1 to that
5682 same <i>/proc/sys</i> file.<br>
5683 <br>
5684 The <i>sysrq </i>operations are exceedingly useful, so they have been made available to system
5685 administrators who can't reach the console. The file <i>/proc/sysrq-trigger </i>is a write only
5686 entry point, where you can trigger a specific <i>sysrq </i>action by writing the associated
5687 command character; you can then collect any output data from the kernel logs.
5688 This entry point to <i>sysrq</i> is always working, even if <i>sysrq</i> is disabled on the console.<br>
5689 <br>
5690 If you are experiencing a "live hang," in which your driver is stuck in a loop but the
5691 system as a whole is still functioning, there are a couple of techniques worth knowing.
5692 Often, the SysRq <i>p </i>function points the finger directly at the guilty routine. Failing
5693 that, you can also use the kernel profiling function. Build a kernel with profiling
5694 enabled, and boot it with <font class="fixd">profile=2</font> on the command line. Reset the profile counters
5695 with the <i>readprofile </i>utility, then send your driver into its loop. After a little while, use
5696 <i>readprofile </i>again to see where the kernel is spending its time. Another more
5697 advanced alternative is <i>oprofile</i>, that you may consider as well. The file
5698 <i>Documentation/basic_profiling.txt </i>tells you everything you need to know to get
5699 started with the profilers.<br>
5700 <br>
5701 One precaution worth using when chasing system hangs is to mount all your disks as
5702 read-only (or unmount them). If the disks are read-only or unmounted, there's no
5703 risk of damaging the filesystem or leaving it in an inconsistent state. Another possibility
5704 is using a computer that mounts all of its filesystems via NFS, the network file
5705 system. The "NFS-Root" capability must be enabled in the kernel, and special
5706 parameters must be passed at boot time. In this case, you'll avoid filesystem corruption
5707 without even resorting to SysRq, because filesystem coherence is managed by
5708 the NFS server, which is not brought down by your device driver.<br>
5709 <br>
5710 <A name="99"></a><font color="blue">PAGE 99</font><br>
5711 <br>
5712 <a name="DebuggersAndRelatedTools"></a><font color="red"><b>Debuggers and Related Tools</b></font><br>
5713 <br>
5714 The last resort in debugging modules is using a debugger to step through the code,
5715 watching the value of variables and machine registers. This approach is time-consuming
5716 and should be avoided whenever possible. Nonetheless, the fine-grained perspective
5717 on the code that is achieved through a debugger is sometimes invaluable.<br>
5718 <br>
5719 Using an interactive debugger on the kernel is a challenge. The kernel runs in its own
5720 address space on behalf of all the processes on the system. As a result, a number of
5721 common capabilities provided by user-space debuggers, such as breakpoints and single-stepping,
5722 are harder to come by in the kernel. In this section we look at several
5723 ways of debugging the kernel; each of them has advantages and disadvantages.<br>
5724 <br>
5725 <a name="UsingGdb"></a><font color="red"><b>Using gdb</b></font><br>
5726 <br>
5727 <i>gdb </i>can be quite useful for looking at the system internals. Proficient use of the
5728 debugger at this level requires some confidence with <i>gdb </i>commands, some understanding
5729 of assembly code for the target platform, and the ability to match source
5730 code and optimized assembly.<br>
5731 <br>
5732 The debugger must be invoked as though the kernel were an application. In addition
5733 to specifying the filename for the ELF kernel image, you need to provide the name of
5734 a core file on the command line. For a running kernel, that core file is the kernel core
5735 image, <i>/proc/kcore</i>. A typical invocation of <i>gdb</i> looks like the following:<br>
5736 <pre>
5737 gdb /usr/src/linux/vmlinux /proc/kcore
5738 </pre>
5739 The first argument is the name of the uncompressed ELF kernel executable, not the
5740 <i>zImage</i> or <i>bzImage</i> or anything built specifically for the boot environment.<br>
5741 <br>
5742 The second argument on the <i>gdb </i>command line is the name of the core file. Like any
5743 file in <i>/proc</i>, <i>/proc/kcore </i>is generated when it is read. When the <i>read </i>system call executes
5744 in the <i>/proc </i>filesystem, it maps to a data-generation function rather than a data retrieval
5745 one; we've already exploited this feature in the section "Using the /proc
5746 Filesystem" earlier in this chapter. <i>kcore </i>is used to represent the kernel "executable"
5747 in the format of a core file; it is a huge file, because it represents the whole kernel
5748 address space, which corresponds to all physical memory. From within <i>gdb</i>, you can
5749 look at kernel variables by issuing the standard <i>gdb </i>commands. For example, <font class="fixd">p jiffies</font>
5750 prints the number of clock ticks from system boot to the current time.<br>
5751 <br>
5752 When you print data from <i>gdb</i>, the kernel is still running, and the various data items
5753 have different values at different times; <i>gdb</i>, however, optimizes access to the core
5754 file by caching data that has already been read. If you try to look at the <font class="fixd">jiffies</font> variable
5755 once again, you'll get the same answer as before. Caching values to avoid extra
5756 disk access is a correct behavior for conventional core files but is inconvenient when
5757 a "dynamic" core image is used. The solution is to issue the command <i>core-file /proc/
5758 kcore </i>whenever you want to flush the <i>gdb </i>cache; the debugger gets ready to use a<br>
5759 <br>
5760 <A name="100"></a><font color="blue">PAGE 100</font><br>
5761 <br>
5762 new core file and discards any old information. You won't, however, always need to
5763 issue <i>core-file </i>when reading a new datum; <i>gdb </i>reads the core in chunks of a few kilobytes
5764 and caches only chunks it has already referenced.<br>
5765 <br>
5766 Numerous capabilities normally provided by <i>gdb </i>are not available when you are
5767 working with the kernel. For example, <i>gdb </i>is not able to modify kernel data; it
5768 expects to be running a program to be debugged under its own control before playing
5769 with its memory image. It is also not possible to set breakpoints or watchpoints,
5770 or to single-step through kernel functions.<br>
5771 <br>
5772 Note that, in order to have symbol information available for <i>gdb</i>, you must compile
5773 your kernel with the <font class="fixd">CONFIG_DEBUG_INFO</font> option set. The result is a far larger kernel
5774 image on disk, but, without that information, digging through kernel variables is
5775 almost impossible.<br>
5776 <br>
5777 With the debugging information available, you can learn a lot about what is going on
5778 inside the kernel. <i>gdb </i>happily prints out structures, follows pointers, etc. One thing
5779 that is harder, however, is examining modules. Since modules are not part of the
5780 <i>vmlinux </i>image passed to <i>gdb</i>, the debugger knows nothing about them. Fortunately,
5781 as of kernel 2.6.7, it is possible to teach <i>gdb </i>what it needs to know to examine loadable
5782 modules.<br>
5783 <br>
5784 Linux loadable modules are ELF-format executable images; as such, they have been
5785 divided up into numerous sections. A typical module can contain a dozen or more
5786 sections, but there are typically three that are relevant in a debugging session:<br>
5787 <br>
5788 <font class="fixd">.text</font><br>
5789 <div class="bq">
5790 This section contains the executable code for the module. The debugger must
5791 know where this section is to be able to give trace-backs or set breakpoints. (Neither
5792 of these operations is relevant when running the debugger on <i>/proc/kcore</i>,
5793 but they can useful when working with <i>kgdb</i>, described below).</div>
5794 <br>
5795 <font class="fixd">.bss<br>
5796 .data</font><br>
5797 <div class="bq">
5798 These two sections hold the module's variables. Any variable that is not initialized
5799 at compile time ends up in <font class="fixd">.bss,</font> while those that are initialized go into <font class="fixd">.data.</font></div>
5800 <br>
5801 Making <i>gdb </i>work with loadable modules requires informing the debugger about
5802 where a given module's sections have been loaded. That information is available in
5803 sysfs, under <i>/sys/module</i>. For example, after loading the <i>scull </i>module, the directory
5804 <i>/sys/module/scull/sections </i>contains files with names such as <i>.text</i>; the content of each
5805 file is the base address for that section.<br>
5806 <br>
5807 We are now in a position to issue a <i>gdb </i>command telling it about our module. The
5808 command we need is <font class="fixd">add-symbol-file;</font> this command takes as parameters the name
5809 of the module object file, the <i>.text </i>base address, and a series of optional parameters<br>
5810 <br>
5811 <A name="101"></a><font color="blue">PAGE 101</font><br>
5812 <br>
5813 describing where any other sections of interest have been put. After digging through
5814 the module section data in sysfs, we can construct a command such as:<br>
5815 <pre>
5816 (gdb) <b>add-symbol-file .../scull.ko 0xd0832000 \</b>
5817 <b> -s .bss 0xd0837100 \</b>
5818 <b> -s .data 0xd0836be0</b>
5819 </pre>
5820 We have included a small script in the sample source (<i>gdbline</i>) that can create this
5821 command for a given module.<br>
5822 <br>
5823 We can now use <i>gdb </i>to examine variables in our loadable module. Here is a quick
5824 example taken from a <i>scull</i> debugging session:<br>
5825 <pre>
5826 (gdb) <b>add-symbol-file scull.ko 0xd0832000 \</b>
5827 <b> -s .bss 0xd0837100 \</b>
5828 <b> -s .data 0xd0836be0</b>
5829 add symbol table from file "scull.ko" at
5830 .text_addr = 0xd0832000
5831 .bss_addr = 0xd0837100
5832 .data_addr = 0xd0836be0
5833 (y or n) <b>y</b>
5834 Reading symbols from scull.ko...done.(gdb)
5835 <b>p scull_devices[0]</b>
5836 $1 = {data = 0xcfd66c50,
5837 quantum = 4000,
5838 qset = 1000,
5839 size = 20881,
5840 access_key = 0,
5841 ...}
5842 </pre>
5843 Here we see that the first <i>scull </i>device currently holds 20,881 bytes. If we wanted, we
5844 could follow the <font class="fixd">data chain</font>, or look at anything else of interest in the module.<br>
5845 <br>
5846 One other useful trick worth knowing about is this:<br>
5847 <pre>
5848 (gdb) <b>print *(address)</b>
5849 </pre>
5850 Here, fill in a hex address for <font class="fixd">address;</font> the output is a file and line number for the
5851 code corresponding to that address. This technique may be useful, for example, to
5852 find out where a function pointer really points.<br>
5853 <br>
5854 We still cannot perform typical debugging tasks like setting breakpoints or modifying
5855 data; to perform those operations, we need to use a tool like <i>kdb </i>(described next)
5856 or <i>kgdb</i> (which we get to shortly).<br>
5857 <br>
5858 <a name="TheKdbKernelDebugger"></a><font color="red"><b>The kdb Kernel Debugger</b></font><br>
5859 <br>
5860 Many readers may be wondering why the kernel does not have any more advanced
5861 debugging features built into it. The answer, quite simply, is that Linus does not
5862 believe in interactive debuggers. He fears that they lead to poor fixes, those which
5863 patch up symptoms rather than addressing the real cause of problems. Thus, no
5864 built-in debuggers.<br>
5865 <br>
5866 <A name="102"></a><font color="blue">PAGE 102</font><br>
5867 <br>
5868 Other kernel developers, however, see an occasional use for interactive debugging
5869 tools. One such tool is the <i>kdb </i>built-in kernel debugger, available as a nonofficial
5870 patch from <i>oss.sgi.com</i>. To use <i>kdb</i>, you must obtain the patch (be sure to get a version
5871 that matches your kernel version), apply it, and rebuild and reinstall the kernel.
5872 Note that, as of this writing, <i>kdb </i>works only on IA-32 (x86) systems (though a version
5873 for the IA-64 existed for a while in the mainline kernel source before being
5874 removed).<br>
5875 <br>
5876 Once you are running a <i>kdb</i>-enabled kernel, there are a couple of ways to enter the
5877 debugger. Pressing the Pause (or Break) key on the console starts up the debugger.
5878 <i>kdb </i>also starts up when a kernel oops happens or when a breakpoint is hit. In any
5879 case, you see a message that looks something like this:<br>
5880 <pre>
5881 Entering kdb (0xc0347b80) on processor 0 due to Keyboard Entry
5882 [0]kdb>
5883 </pre>
5884 Note that just about everything the kernel does stops when <i>kdb </i>is running. Nothing
5885 else should be running on a system where you invoke <i>kdb</i>; in particular, you should
5886 not have networking turned on--unless, of course, you are debugging a network
5887 driver. It is generally a good idea to boot the system in single-user mode if you will be
5888 using <i>kdb</i>.<br>
5889 <br>
5890 As an example, consider a quick <i>scull </i>debugging session. Assuming that the driver is
5891 already loaded, we can tell <i>kdb</i> to set a breakpoint in <i>scull_read</i> as follows:<br>
5892 <pre>
5893 [0]kdb> <b>bp scull_read
5894 </b>Instruction(i) BP #0 at 0xcd087c5dc (scull_read)
5895 is enabled globally adjust 1
5896 [0]kdb> <b>go</b>
5897 </pre>
5898 The <i>bp </i>command tells <i>kdb </i>to stop the next time the kernel enters <i>scull_read</i>. You
5899 then type <font class="fixd"><b>go</b></font> to continue execution. After putting something into one of the <i>scull
5900 </i>devices, we can attempt to read it by running <i>cat </i>under a shell on another terminal,
5901 yielding the following:<br>
5902 <pre>
5903 Instruction(i) breakpoint #0 at 0xd087c5dc (adjusted)
5904 0xd087c5dc scull_read: int3
5906 Entering kdb (current=0xcf09f890, pid 1575) on processor 0 due to
5907 Breakpoint @ 0xd087c5dc
5908 [0]kdb>
5909 </pre>
5910 We are now positioned at the beginning of <i>scull_read</i>. To see how we got there, we
5911 can get a stack trace:<br>
5912 <pre>
5913 [0]kdb> <b>bt
5914 </b> ESP EIP Function (args)
5915 0xcdbddf74 0xd087c5dc [scull]scull_read
5916 0xcdbddf78 0xc0150718 vfs_read+0xb8
5917 0xcdbddfa4 0xc01509c2 sys_read+0x42
5918 0xcdbddfc4 0xc0103fcf syscall_call+0x7
5919 [0]kdb>
5920 </pre>
5921 <A name="103"></a><font color="blue">PAGE 103</font><br>
5922 <br>
5923 <i>kdb </i>attempts to print out the arguments to every function in the call trace. It gets
5924 confused, however, by optimization tricks used by the compiler. Therefore, it fails to
5925 print the arguments to <i>scull_read</i>.<br>
5926 <br>
5927 Time to look at some data. The <i>mds </i>command manipulates data; we can query the
5928 value of the <font class="fixd">scull_devices</font> pointer with a command such as:<br>
5929 <pre>
5930 [0]kdb> <b>mds <font class="fixd">scull_devices</font> 1
5931 </b>0xd0880de8 cf36ac00 ....
5932 </pre>
5933 Here we asked for one (4-byte) word of data starting at the location of scull_devices;
5934 the answer tells us that our device array is at the address <font class="fixd">0xd0880de8;</font> the first device
5935 structure itself is at <font class="fixd">0xcf36ac00.</font> To look at that device structure, we need to use that
5936 address:<br>
5937 <pre>
5938 [0]kdb> <b>mds cf36ac00
5939 </b>0xcf36ac00 ce137dbc ....
5940 0xcf36ac04 00000fa0 ....
5941 0xcf36ac08 000003e8 ....
5942 0xcf36ac0c 0000009b ....
5943 0xcf36ac10 00000000 ....
5944 0xcf36ac14 00000001 ....
5945 0xcf36ac18 00000000 ....
5946 0xcf36ac1c 00000001 ....
5947 </pre>
5948 The eight lines here correspond to the beginning part of the <font class="fixd">scull_dev</font> structure.
5949 Therefore, we see that the memory for the first device is allocated at <font class="fixd">0xce137dbc,</font> the
5950 quantum is 4000 (hex <font class="fixd">fa0</font>), the quantum set size is 1000 (hex <font class="fixd">3e8</font>), and there are currently
5951 155 (hex <font class="fixd">9b</font>) bytes stored in the device.<br>
5952 <br>
5953 <i>kdb </i>can change data as well. Suppose we wanted to trim some of the data from the
5954 device:<br>
5955 <pre>
5956 [0]kdb><b> mm cf36ac0c 0x50
5957 </b>0xcf26ac0c = 0x50
5958 </pre>
5959 A subsequent <i>cat</i> on the device will now return less data than before.<br>
5960 <br>
5961 <i>kdb </i>has a number of other capabilities, including single-stepping (by instructions, not
5962 lines of C source code), setting breakpoints on data access, disassembling code, stepping
5963 through linked lists, accessing register data, and more. After you have applied the
5964 <i>kdb </i>patch, a full set of manual pages can be found in the <i>Documentation/kdb </i>directory
5965 in your kernel source tree.<br>
5966 <br>
5967 <a name="TheKgdbPatches"></a><font color="red"><b>The kgdb Patches</b></font><br>
5968 <br>
5969 The two interactive debugging approaches we have looked at so far (using <i>gdb </i>on
5970 <i>/proc/kcore </i>and <i>kdb</i>) both fall short of the sort of environment that user-space application
5971 developers have become used to. Wouldn't it be nice if there were a true
5972 debugger for the kernel that supported features like changing variables, breakpoints,
5973 etc.?<br>
5974 <br>
5975 <A name="104"></a><font color="blue">PAGE 104</font><br>
5976 <br>
5977 As it turns out, such a solution does exist. There are, as of this writing, two separate
5978 patches in circulation that allow <i>gdb</i>, with full capabilities, to be run against the kernel.
5979 Confusingly, both of these patches are called <i>kgdb</i>. They work by separating the
5980 system running the test kernel from the system running the debugger; the two are
5981 typically connected via a serial cable. Therefore, the developer can run <i>gdb </i>on his or
5982 her stable desktop system, while operating on a kernel running on a sacrificial test
5983 box. Setting up <i>gdb </i>in this mode takes a little time at the outset, but that investment
5984 can pay off quickly when a difficult bug shows up.<br>
5985 <br>
5986 These patches are in a strong state of flux, and may even be merged at some point, so
5987 we avoid saying much about them beyond where they are and their basic features.
5988 Interested readers are encouraged to look and see the current state of affairs.<br>
5989 <br>
5990 The first <i>kgdb </i>patch is currently found in the <font class="fixd">-mm</font> kernel tree--the staging area for
5991 patches on their way into the 2.6 mainline. This version of the patch supports the
5992 x86, SuperH, ia64, x86_64, SPARC, and 32-bit PPC architectures. In addition to the
5993 usual mode of operation over a serial port, this version of <i>kgdb </i>can also communicate
5994 over a local-area network. It is simply a matter of enabling the Ethernet mode
5995 and booting with the <font class="fixd">kgdboe</font> parameter set to indicate the IP address from which
5996 debugging commands can originate. The documentation under <i>Documentation/i386/
5997 kgdb</i> describes how to set things up.*<br>
5998 <br>
5999 As an alternative, you can use the <i>kgdb </i>patch found on <a href="http://kgdb.sf.net/" target="_blank"><i>http://kgdb.sf.net/</i></a>. This version
6000 of the debugger does not support the network communication mode (though
6001 that is said to be under development), but it does have some built-in support for
6002 working with loadable modules. It supports the x86, x86_64, PowerPC, and S/390
6003 architectures.<br>
6004 <br>
6005 <a name="TheUserModeLinuxPort"></a><font color="red"><b>The User-Mode Linux Port</b></font><br>
6006 <br>
6007 User-Mode Linux (UML) is an interesting concept. It is structured as a separate port
6008 of the Linux kernel with its own <i>arch/um </i>subdirectory. It does not run on a new type
6009 of hardware, however; instead, it runs on a virtual machine implemented on the
6010 Linux system call interface. Thus, UML allows the Linux kernel to run as a separate,
6011 user-mode process on a Linux system.<br>
6012 <br>
6013 Having a copy of the kernel running as a user-mode process brings a number of
6014 advantages. Because it is running on a constrained, virtual processor, a buggy kernel
6015 cannot damage the "real" system. Different hardware and software configurations can
6016 be tried easily on the same box. And, perhaps most significantly for kernel developers,
6017 the user-mode kernel can be easily manipulated with <i>gdb </i>or another debugger.<br>
6018 <br>
6019 * It does neglect to point out that you should have your network adapter driver built into the kernel, however,
6020 or the debugger fails to find it at boot time and will shut itself down.<br>
6021 <br>
6022 <A name="105"></a><font color="blue">PAGE 105</font><br>
6023 <br>
6024 After all, it is just another process. UML clearly has the potential to accelerate kernel
6025 development.<br>
6026 <br>
6027 However, UML has a big shortcoming from the point of view of driver writers: the
6028 user-mode kernel has no access to the host system's hardware. Thus, while it can be
6029 useful for debugging most of the sample drivers in this book, UML is not yet useful
6030 for debugging drivers that have to deal with real hardware.<br>
6031 <br>
6032 See <a href="http://user-mode-linux.sf.net/" target="_blank"><i>http://user-mode-linux.sf.net/</i></a> for more information on UML.<br>
6033 <br>
6034 <a name="TheLinuxTraceToolkit"></a><font color="red"><b>The Linux Trace Toolkit</b></font><br>
6035 <br>
6036 The Linux Trace Toolkit (LTT) is a kernel patch and a set of related utilities that
6037 allow the tracing of events in the kernel. The trace includes timing information and
6038 can create a reasonably complete picture of what happened over a given period of
6039 time. Thus, it can be used not only for debugging but also for tracking down performance
6040 problems.<br>
6041 <br>
6042 LTT, along with extensive documentation, can be found at <a href="http://www.opersys.com/LTT" target="_blank"><i>http://www.opersys.com/LTT</i></a>.<br>
6043 <br>
6044 <a name="DynamicProbes"></a><font color="red"><b>Dynamic Probes</b></font><br>
6045 <br>
6046 Dynamic Probes (or DProbes) is a debugging tool released (under the GPL) by IBM
6047 for Linux on the IA-32 architecture. It allows the placement of a "probe" at almost
6048 any place in the system, in both user and kernel space. The probe consists of some
6049 code (written in a specialized, stack-oriented language) that is executed when control
6050 hits the given point. This code can report information back to user space, change
6051 registers, or do a number of other things. The useful feature of DProbes is that once
6052 the capability has been built into the kernel, probes can be inserted anywhere within
6053 a running system without kernel builds or reboots. DProbes can also work with the
6054 LTT to insert new tracing events at arbitrary locations.<br>
6055 <br>
6056 The DProbes tool can be downloaded from IBM's open source site: <a href="http://oss.software.ibm.com" target="_blank"><i>http://oss.software.ibm.com</i></a>.<br>
6057 <br>
6058 <A name="106"></a><font color="blue">PAGE 106</font><br>
6059 <br>
6060 <a name="CHAPTER5"></a><font color="red"><b>CHAPTER 5</b></font><br>
6061 <br>
6062 <a name="ConcurrencyAndRacebrConditions"></a><font color="#7519FF" size="+1"><b>Concurrency and Race Conditions</b></font><br>
6063 <br>
6064 Thus far, we have paid little attention to the problem of concurrency--i.e., what
6065 happens when the system tries to do more than one thing at once. The management
6066 of concurrency is, however, one of the core problems in operating systems programming.
6067 Concurrency-related bugs are some of the easiest to create and some of the
6068 hardest to find. Even expert Linux kernel programmers end up creating concurrency-related
6069 bugs on occasion.<br>
6070 <br>
6071 In early Linux kernels, there were relatively few sources of concurrency. Symmetric
6072 multiprocessing (SMP) systems were not supported by the kernel, and the only cause
6073 of concurrent execution was the servicing of hardware interrupts. That approach
6074 offers simplicity, but it no longer works in a world that prizes performance on systems
6075 with more and more processors, and that insists that the system respond to
6076 events quickly. In response to the demands of modern hardware and applications,
6077 the Linux kernel has evolved to a point where many more things are going on simultaneously.
6078 This evolution has resulted in far greater performance and scalability. It
6079 has also, however, significantly complicated the task of kernel programming. Device
6080 driver programmers must now factor concurrency into their designs from the beginning,
6081 and they must have a strong understanding of the facilities provided by the kernel
6082 for concurrency management.<br>
6083 <br>
6084 The purpose of this chapter is to begin the process of creating that understanding.
6085 To that end, we introduce facilities that are immediately applied to the <i>scull </i>driver
6086 from Chapter 3. Other facilities presented here are not put to use for some time yet.
6087 But first, we take a look at what could go wrong with our simple <i>scull </i>driver and how
6088 to avoid these potential problems.<br>
6089 <br>
6090 <A name="107"></a><font color="blue">PAGE 107</font><br>
6091 <br>
6092 <a name="PitfallsInScull"></a><font color="red"><b>Pitfalls in scull</b></font><br>
6093 <br>
6094 Let us take a quick look at a fragment of the <i>scull </i>memory management code. Deep
6095 down inside the <i>write </i>logic, <i>scull </i>must decide whether the memory it requires has
6096 been allocated yet or not. One piece of the code that handles this task is:<br>
6097 <pre>
6098 if (!dptr->data[s_pos]) {
6099 dptr->data[s_pos] = kmalloc(quantum, GFP_KERNEL);
6100 if (!dptr->data[s_pos])
6101 goto out;
6102 }
6103 </pre>
6104 Suppose for a moment that two processes (we'll call them "A" and "B") are independently
6105 attempting to write to the same offset within the same <i>scull </i>device. Each process
6106 reaches the if test in the first line of the fragment above at the same time. If the
6107 pointer in question is <font class="fixd">NULL,</font> each process will decide to allocate memory, and each
6108 will assign the resulting pointer to <font class="fixd">dptr->data[s_pos].</font> Since both processes are
6109 assigning to the same location, clearly only one of the assignments will prevail.<br>
6110 <br>
6111 What will happen, of course, is that the process that completes the assignment second
6112 will "win." If process A assigns first, its assignment will be overwritten by process
6113 B. At that point, <i>scull </i>will forget entirely about the memory that A allocated; it
6114 only has a pointer to B's memory. The memory allocated by A, thus, will be dropped
6115 and never returned to the system.<br>
6116 <br>
6117 This sequence of events is a demonstration of a <i>race condition</i>. Race conditions are a
6118 result of uncontrolled access to shared data. When the wrong access pattern happens,
6119 something unexpected results. For the race condition discussed here, the result
6120 is a memory leak. That is bad enough, but race conditions can often lead to system
6121 crashes, corrupted data, or security problems as well. Programmers can be tempted
6122 to disregard race conditions as extremely low probability events. But, in the computing
6123 world, one-in-a-million events can happen every few seconds, and the consequences
6124 can be grave.<br>
6125 <br>
6126 We will eliminate race conditions from <i>scull </i>shortly, but first we need to take a more
6127 general view of concurrency.<br>
6128 <br>
6129 <a name="ConcurrencyAndItsManagement"></a><font color="red"><b>Concurrency and Its Management</b></font><br>
6130 <br>
6131 In a modern Linux system, there are numerous sources of concurrency and, therefore,
6132 possible race conditions. Multiple user-space processes are running, and they
6133 can access your code in surprising combinations of ways. SMP systems can be executing
6134 your code simultaneously on different processors. Kernel code is preemptible;
6135 your driver's code can lose the processor at any time, and the process that replaces it
6136 could also be running in your driver. Device interrupts are asynchronous events that
6137 can cause concurrent execution of your code. The kernel also provides various mechanisms
6138 for delayed code execution, such as workqueues, tasklets, and timers, which<br>
6139 <br>
6140 <A name="108"></a><font color="blue">PAGE 108</font><br>
6141 <br>
6142 can cause your code to run at any time in ways unrelated to what the current process
6143 is doing. In the modern, hot-pluggable world, your device could simply disappear
6144 while you are in the middle of working with it.<br>
6145 <br>
6146 Avoidance of race conditions can be an intimidating task. In a world where anything
6147 can happen at any time, how does a driver programmer avoid the creation of absolute
6148 chaos? As it turns out, most race conditions can be avoided through some
6149 thought, the kernel's concurrency control primitives, and the application of a few
6150 basic principles. We'll start with the principles first, then get into the specifics of
6151 how to apply them.<br>
6152 <br>
6153 Race conditions come about as a result of shared access to resources. When two
6154 threads of execution* have a reason to work with the same data structures (or hardware
6155 resources), the potential for mixups always exists. So the first rule of thumb to
6156 keep in mind as you design your driver is to avoid shared resources whenever possible.
6157 If there is no concurrent access, there can be no race conditions. So carefully written
6158 kernel code should have a minimum of sharing. The most obvious application
6159 of this idea is to avoid the use of global variables. If you put a resource in a place
6160 where more than one thread of execution can find it, there should be a strong reason
6161 for doing so.<br>
6162 <br>
6163 The fact of the matter is, however, that such sharing is often required. Hardware
6164 resources are, by their nature, shared, and software resources also must often be
6165 available to more than one thread. Bear in mind as well that global variables are far
6166 from the only way to share data; any time your code passes a pointer to some other
6167 part of the kernel, it is potentially creating a new sharing situation. Sharing is a fact
6168 of life.<br>
6169 <br>
6170 Here is the hard rule of resource sharing: any time that a hardware or software
6171 resource is shared beyond a single thread of execution, and the possibility exists that
6172 one thread could encounter an inconsistent view of that resource, you must explicitly
6173 manage access to that resource. In the <i>scull </i>example above, process B's view of
6174 the situation is inconsistent; unaware that process A has already allocated memory
6175 for the (shared) device, it performs its own allocation and overwrites A's work. In
6176 this case, we must control access to the <i>scull </i>data structure. We need to arrange
6177 things so that the code either sees memory that has been allocated or knows that no
6178 memory has been <i>or will be </i>allocated by anybody else. The usual technique for
6179 access management is called <i>locking </i>or <i>mutual exclusion</i>--making sure that only one
6180 thread of execution can manipulate a shared resource at any time. Much of the rest
6181 of this chapter will be devoted to locking.<br>
6182 <br>
6183 * For the purposes of this chapter, a "thread" of execution is any context that is running code. Each process is
6184 clearly a thread of execution, but so is an interrupt handler or other code running in response to an asynchronous
6185 kernel event.<br>
6186 <br>
6187 <A name="109"></a><font color="blue">PAGE 109</font><br>
6188 <br>
6189 First, however, we must briefly consider one other important rule. When kernel code
6190 creates an object that will be shared with any other part of the kernel, that object
6191 must continue to exist (and function properly) until it is known that no outside references
6192 to it exist. The instant that <i>scull </i>makes its devices available, it must be prepared
6193 to handle requests on those devices. And <i>scull </i>must continue to be able to
6194 handle requests on its devices until it knows that no reference (such as open userspace
6195 files) to those devices exists. Two requirements come out of this rule: no object
6196 can be made available to the kernel until it is in a state where it can function properly,
6197 and references to such objects must be tracked. In most cases, you'll find that
6198 the kernel handles reference counting for you, but there are always exceptions.<br>
6199 <br>
6200 Following the above rules requires planning and careful attention to detail. It is easy
6201 to be surprised by concurrent access to resources you hadn't realized were shared.
6202 With some effort, however, most race conditions can be headed off before they bite
6203 you--or your users.<br>
6204 <br>
6205 <a name="SemaphoresAndMutexes"></a><font color="red"><b>Semaphores and Mutexes</b></font><br>
6206 <br>
6207 So let us look at how we can add locking to <i>scull</i>. Our goal is to make our operations
6208 on the <i>scull </i>data structure <i>atomic</i>, meaning that the entire operation happens at once
6209 as far as other threads of execution are concerned. For our memory leak example, we
6210 need to ensure that if one thread finds that a particular chunk of memory must be
6211 allocated, it has the opportunity to perform that allocation before any other thread
6212 can make that test. To this end, we must set up <i>critical sections</i>: code that can be executed
6213 by only one thread at any given time.<br>
6214 <br>
6215 Not all critical sections are the same, so the kernel provides different primitives for
6216 different needs. In this case, every access to the <i>scull </i>data structure happens in process
6217 context as a result of a direct user request; no accesses will be made from interrupt
6218 handlers or other asynchronous contexts. There are no particular latency
6219 (response time) requirements; application programmers understand that I/O
6220 requests are not usually satisfied immediately. Furthermore, the <i>scull </i>is not holding
6221 any other critical system resource while it is accessing its own data structures. What
6222 all this means is that if the <i>scull </i>driver goes to sleep while waiting for its turn to
6223 access the data structure, nobody is going to mind.<br>
6224 <br>
6225 "Go to sleep" is a well-defined term in this context. When a Linux process reaches a
6226 point where it cannot make any further processes, it goes to sleep (or "blocks"),
6227 yielding the processor to somebody else until some future time when it can get work
6228 done again. Processes often sleep when waiting for I/O to complete. As we get
6229 deeper into the kernel, we will encounter a number of situations where we cannot
6230 sleep. The <i>write </i>method in <i>scull </i>is not one of those situations, however. So we can
6231 use a locking mechanism that might cause the process to sleep while waiting for
6232 access to the critical section.<br>
6233 <br>
6234 <A name="110"></a><font color="blue">PAGE 110</font><br>
6235 <br>
6236 Just as importantly, we will be performing an operation (memory allocation with
6237 <i>kmalloc</i>) that could sleep--so sleeps are a possibility in any case. If our critical sections
6238 are to work properly, we must use a locking primitive that works when a thread
6239 that owns the locksleeps. Not all locking mechanisms can be used where sleeping is
6240 a possibility (we'll see some that don't later in this chapter). For our present needs,
6241 however, the mechanism that fits best is a <i>semaphore</i>.<br>
6242 <br>
6243 Semaphores are a well-understood concept in computer science. At its core, a semaphore
6244 is a single integer value combined with a pair of functions that are typically
6245 called <i>P </i>and <i>V</i>. A process wishing to enter a critical section will call <i>P </i>on the relevant
6246 semaphore; if the semaphore's value is greater than zero, that value is decremented
6247 by one and the process continues. If, instead, the semaphore's value is 0 (or less), the
6248 process must wait until somebody else releases the semaphore. Unlocking a semaphore
6249 is accomplished by calling <i>V</i>; this function increments the value of the semaphore
6250 and, if necessary, wakes up processes that are waiting.<br>
6251 <br>
6252 When semaphores are used for <i>mutual exclusion</i>--keeping multiple processes from
6253 running within a critical section simultaneously--their value will be initially set to 1.
6254 Such a semaphore can be held only by a single process or thread at any given time. A
6255 semaphore used in this mode is sometimes called a <i>mutex</i>, which is, of course, an
6256 abbreviation for "mutual exclusion." Almost all semaphores found in the Linux kernel
6257 are used for mutual exclusion.<br>
6258 <br>
6259 <a name="TheLinuxSemaphoreImplementation"></a><font color="red"><b>The Linux Semaphore Implementation</b></font><br>
6260 <br>
6261 The Linux kernel provides an implementation of semaphores that conforms to the
6262 above semantics, although the terminology is a little different. To use semaphores,
6263 kernel code must include <i><asm/semaphore.h></i>. The relevant type is <font class="fixd">struct semaphore;</font>
6264 actual semaphores can be declared and initialized in a few ways. One is to create a
6265 semaphore directly, then set it up with <i>sema_init</i>:<br>
6266 <pre>
6267 void sema_init(struct semaphore *sem, int val);
6268 </pre>
6269 where <font class="fixd">val</font> is the initial value to assign to a semaphore.<br>
6270 <br>
6271 Usually, however, semaphores are used in a mutex mode. To make this common
6272 case a little easier, the kernel has provided a set of helper functions and macros.
6273 Thus, a mutex can be declared and initialized with one of the following:<br>
6274 <pre>
6275 DECLARE_MUTEX(name);
6276 DECLARE_MUTEX_LOCKED(name);
6277 </pre>
6278 Here, the result is a semaphore variable (called <font class="fixd">name</font>) that is initialized to 1 (with
6279 <font class="fixd">DECLARE_MUTEX</font>) or 0 (with <font class="fixd">DECLARE_MUTEX_LOCKED</font>). In the latter case, the mutex starts
6280 out in a locked state; it will have to be explicitly unlocked before any thread will be
6281 allowed access.<br>
6282 <br>
6283 <A name="111"></a><font color="blue">PAGE 111</font><br>
6284 <br>
6285 If the mutex must be initialized at runtime (which is the case if it is allocated dynamically,
6286 for example), use one of the following:<br>
6287 <pre>
6288 void init_MUTEX(struct semaphore *sem);
6289 void init_MUTEX_LOCKED(struct semaphore *sem);
6290 </pre>
6291 In the Linux world, the <i>P </i>function is called <i>down</i>--or some variation of that name.
6292 Here, "down" refers to the fact that the function decrements the value of the semaphore
6293 and, perhaps after putting the caller to sleep for a while to wait for the semaphore
6294 to become available, grants access to the protected resources. There are three
6295 versions of <i>down</i>:<br>
6296 <pre>
6297 void down(struct semaphore *sem);
6298 int down_interruptible(struct semaphore *sem);
6299 int down_trylock(struct semaphore *sem);
6300 </pre>
6301 <i>down </i>decrements the value of the semaphore and waits as long as need
6302 be. <i>down_interruptible </i>does the same, but the operation is interruptible. The interruptible version
6303 is almost always the one you will want; it allows a user-space process that is
6304 waiting on a semaphore to be interrupted by the user. You do not, as a general rule,
6305 want to use noninterruptible operations unless there truly is no alternative. Noninterruptible
6306 operations are a good way to create unkillable processes (the dreaded
6307 "D state" seen in <i>ps</i>), and annoy your users. Using <i>down_interruptible </i>requires some
6308 extra care, however, if the operation is interrupted, the function returns a nonzero
6309 value, and the caller does <i>not </i>hold the semaphore. Proper use of <i>down_interruptible
6310 </i>requires always checking the return value and responding accordingly.<br>
6311 <br>
6312 The final version (<i>down_trylock</i>) never sleeps; if the semaphore is not available at the
6313 time of the call, <i>down_trylock</i> returns immediately with a nonzero return value.<br>
6314 <br>
6315 Once a thread has successfully called one of the versions of <i>down</i>, it is said to be
6316 "holding" the semaphore (or to have "taken out" or "acquired" the semaphore).
6317 That thread is now entitled to access the critical section protected by the semaphore.
6318 When the operations requiring mutual exclusion are complete, the semaphore must
6319 be returned. The Linux equivalent to <i>V</i> is <i>up</i>:<br>
6320 <pre>
6321 void up(struct semaphore *sem);
6322 </pre>
6323 Once <i>up</i> has been called, the caller no longer holds the semaphore.<br>
6324 <br>
6325 As you would expect, any thread that takes out a semaphore is required to release it
6326 with one (and only one) call to <i>up</i>. Special care is often required in error paths; if an
6327 error is encountered while a semaphore is held, that semaphore must be released
6328 before returning the error status to the caller. Failure to free a semaphore is an easy
6329 error to make; the result (processes hanging in seemingly unrelated places) can be
6330 hard to reproduce and track down.<br>
6331 <br>
6332 <A name="112"></a><font color="blue">PAGE 112</font><br>
6333 <br>
6334 <a name="UsingSemaphoresInScull"></a><font color="red"><b>Using Semaphores in scull</b></font><br>
6335 <br>
6336 The semaphore mechanism gives <i>scull </i>a tool that can be used to avoid race conditions
6337 while accessing the <font class="fixd">scull_dev</font> data structure. But it is up to us to use that tool
6338 correctly. The keys to proper use of locking primitives are to specify exactly which
6339 resources are to be protected and to make sure that every access to those resources
6340 uses the proper locking. In our example driver, everything of interest is contained
6341 within the <font class="fixd">scull_dev</font> structure, so that is the logical scope for our locking regime.<br>
6342 <br>
6343 Let's look again at that structure:<br>
6344 <pre>
6345 struct scull_dev {
6346 struct scull_qset *data; /* Pointer to first quantum set */
6347 int quantum; /* the current quantum size */
6348 int qset; /* the current array size */
6349 unsigned long size; /* amount of data stored here */
6350 unsigned int access_key; /* used by sculluid and scullpriv */
6351 struct semaphore sem; /* mutual exclusion semaphore */
6352 struct cdev cdev; /* Char device structure */
6353 };
6354 </pre>
6355 Toward the bottom of the structure is a member called <font class="fixd">sem</font> which is, of course, our
6356 semaphore. We have chosen to use a separate semaphore for each virtual <i>scull
6357 </i>device. It would have been equally correct to use a single, global semaphore. The various
6358 <i>scull </i>devices share no resources in common, however, and there is no reason to
6359 make one process wait while another process is working with a different <i>scull </i>device.
6360 Using a separate semaphore for each device allows operations on different devices to
6361 proceed in parallel and, therefore, improves performance.<br>
6362 <br>
6363 Semaphores must be initialized before use. <i>scull </i>performs this initialization at load
6364 time in this loop:<br>
6365 <pre>
6366 for (i = 0; i < scull_nr_devs; i++) {
6367 scull_devices[i].quantum = scull_quantum;
6368 scull_devices[i].qset = scull_qset;
6369 init_MUTEX(&scull_devices[i].sem);
6370 scull_setup_cdev(&scull_devices[i], i);
6371 }
6372 </pre>
6373 Note that the semaphore must be initialized <i>before </i>the <i>scull </i>device is made available
6374 to the rest of the system. Therefore, <i>init_MUTEX </i>is called before <i>scull_setup_cdev</i>.
6375 Performing these operations in the opposite order would create a race condition
6376 where the semaphore could be accessed before it is ready.<br>
6377 <br>
6378 Next, we must go through the code and make sure that no accesses to the <font class="fixd">scull_dev</font>
6379 data structure are made without holding the semaphore. Thus, for example, <i>scull_write
6380 </i>begins with this code:<br>
6381 <pre>
6382 if (down_interruptible(&dev->sem))
6383 return -ERESTARTSYS;
6384 </pre>
6385 <A name="113"></a><font color="blue">PAGE 113</font><br>
6386 <br>
6387 Note the check on the return value of <i>down_interruptible</i>; if it returns nonzero, the operation
6388 was interrupted. The usual thing to do in this situation is to return <font class="fixd">-ERESTARTSYS</font>.
6389 Upon seeing this return code, the higher layers of the kernel will either restart the call
6390 from the beginning or return the error to the user. If you return <font class="fixd">-ERESTARTSYS</font>, you must
6391 first undo any user-visible changes that might have been made, so that the right thing
6392 happens when the system call is retried. If you cannot undo things in this manner, you
6393 should return <font class="fixd">-EINTR</font> instead.<br>
6394 <br>
6395 <i>scull_write </i>must release the semaphore whether or not it was able to carry out its
6396 other tasks successfully. If all goes well, execution falls into the final few lines of the
6397 function:<br>
6398 <pre>
6399 out:
6400 up(&dev->sem);
6401 return retval;
6402 </pre>
6403 This code frees the semaphore and returns whatever status is called for. There are
6404 several places in <i>scull_write </i>where things can go wrong; these include memory allocation
6405 failures or a fault while trying to copy data from user space. In those cases, the
6406 code performs a <font class="fixd">goto out,</font> ensuring that the proper cleanup is done.<br>
6407 <br>
6408 <a name="ReaderWriterSemaphores"></a><font color="red"><b>Reader/Writer Semaphores</b></font><br>
6409 <br>
6410 Semaphores perform mutual exclusion for all callers, regardless of what each thread
6411 may want to do. Many tasks break down into two distinct types of work, however:
6412 tasks that only need to read the protected data structures and those that must make
6413 changes. It is often possible to allow multiple concurrent readers, as long as nobody
6414 is trying to make any changes. Doing so can optimize performance significantly;
6415 read-only tasks can get their work done in parallel without having to wait for other
6416 readers to exit the critical section.<br>
6417 <br>
6418 The Linux kernel provides a special type of semaphore called a <i>rwsem </i>(or "reader/writer
6419 semaphore") for this situation. The use of rwsems in drivers is relatively rare, but they
6420 are occasionally useful.<br>
6421 <br>
6422 Code using rwsems must include <i><linux/rwsem.h></i>. The relevant data type for
6423 reader/writer semaphores is struct rw_semaphore; an rwsem must be explicitly initialized
6424 at runtime with:<br>
6425 <pre>
6426 void init_rwsem(struct rw_semaphore *sem);
6427 </pre>
6428 A newly initialized rwsem is available for the next task(reader or writer) that comes
6429 along. The interface for code needing read-only access is:<br>
6430 <pre>
6431 void down_read(struct rw_semaphore *sem);
6432 int down_read_trylock(struct rw_semaphore *sem);
6433 void up_read(struct rw_semaphore *sem);
6434 </pre>
6435 A call to <i>down_read </i>provides read-only access to the protected resources, possibly
6436 concurrently with other readers. Note that <i>down_read </i>may put the calling process<br>
6437 <br>
6438 <A name="114"></a><font color="blue">PAGE 114</font><br>
6439 <br>
6440 into an uninterruptible sleep. <i>down_read_trylock </i>will not wait if read access is
6441 unavailable; it returns nonzero if access was granted, 0 otherwise. Note that the convention
6442 for <i>down_read_trylock </i>differs from that of most kernel functions, where success
6443 is indicated by a return value of 0. A rwsem obtained with <i>down_read </i>must
6444 eventually be freed with <i>up_read</i>.<br>
6445 <br>
6446 The interface for writers is similar:<br>
6447 <pre>
6448 void down_write(struct rw_semaphore *sem);
6449 int down_write_trylock(struct rw_semaphore *sem);
6450 void up_write(struct rw_semaphore *sem);
6451 void downgrade_write(struct rw_semaphore *sem);
6452 </pre>
6453 <i>down_write</i>, <i>down_write_trylock</i>, and <i>up_write </i>all behave just like their reader counterparts,
6454 except, of course, that they provide write access. If you have a situation
6455 where a writer lockis needed for a quick change, followed by a longer period of readonly
6456 access, you can use <i>downgrade_write </i>to allow other readers in once you have
6457 finished making changes.<br>
6458 <br>
6459 An rwsem allows either one writer or an unlimited number of readers to hold the
6460 semaphore. Writers get priority; as soon as a writer tries to enter the critical section,
6461 no readers will be allowed in until all writers have completed their work. This implementation
6462 can lead to reader <i>starvation</i>--where readers are denied access for a long
6463 time--if you have a large number of writers contending for the semaphore. For this
6464 reason, rwsems are best used when write access is required only rarely, and writer
6465 access is held for short periods of time.<br>
6466 <br>
6467 <a name="Completions"></a><font color="red"><b>Completions</b></font><br>
6468 <br>
6469 A common pattern in kernel programming involves initiating some activity outside of
6470 the current thread, then waiting for that activity to complete. This activity can be the
6471 creation of a new kernel thread or user-space process, a request to an existing process,
6472 or some sort of hardware-based action. It such cases, it can be tempting to use a
6473 semaphore for synchronization of the two tasks, with code such as:<br>
6474 <br>
6475 struct semaphore sem;<br>
6476 <pre>
6477 init_MUTEX_LOCKED(&sem);
6478 start_external_task(&sem);
6479 down(&sem);
6480 </pre>
6481 The external task can then call <font class="fixd">up(&sem)</font> when its work is done.<br>
6482 <br>
6483 As is turns out, semaphores are not the best tool to use in this situation. In normal use,
6484 code attempting to locka semaphore finds that semaphore available almost all the
6485 time; if there is significant contention for the semaphore, performance suffers and the
6486 locking scheme needs to be reviewed. So semaphores have been heavily optimized for
6487 the "available" case. When used to communicate task completion in the way shown
6488 above, however, the thread calling <i>down </i>will almost always have to wait; performance<br>
6489 <br>
6490 <A name="115"></a><font color="blue">PAGE 115</font><br>
6491 <br>
6492 will suffer accordingly. Semaphores can also be subject to a (difficult) race condition
6493 when used in this way if they are declared as automatic variables. In some cases, the
6494 semaphore could vanish before the process calling <i>up</i> is finished with it.<br>
6495 <br>
6496 These concerns inspired the addition of the "completion" interface in the 2.4.7 kernel.
6497 Completions are a lightweight mechanism with one task: allowing one thread to
6498 tell another that the job is done. To use completions, your code must include <i><linux/
6499 completion.h></i>. A completion can be created with:<br>
6500 <pre>
6501 DECLARE_COMPLETION(my_completion);
6502 </pre>
6503 Or, if the completion must be created and initialized dynamically:<br>
6504 <pre>
6505 struct completion my_completion;
6506 /* ... */
6507 init_completion(&my_completion);
6508 </pre>
6509 Waiting for the completion is a simple matter of calling:<br>
6510 <pre>
6511 void wait_for_completion(struct completion *c);
6512 </pre>
6513 Note that this function performs an uninterruptible wait. If your code calls <i>wait_for_
6514 completion </i>and nobody ever completes the task, the result will be an unkillable
6515 process.*<br>
6516 <br>
6517 On the other side, the actual completion event may be signalled by calling one of the
6518 following:<br>
6519 <pre>
6520 void complete(struct completion *c);
6521 void complete_all(struct completion *c);
6522 </pre>
6523 The two functions behave differently if more than one thread is waiting for the same
6524 completion event. <i>complete </i>wakes up only one of the waiting threads while
6525 <i>complete_all </i>allows all of them to proceed. In most cases, there is only one waiter,
6526 and the two functions will produce an identical result.<br>
6527 <br>
6528 A completion is normally a one-shot device; it is used once then discarded. It is possible,
6529 however, to reuse completion structures if proper care is taken. If <i>complete_all
6530 </i>is not used, a completion structure can be reused without any problems as long as
6531 there is no ambiguity about what event is being signalled. If you use <i>complete_all</i>,
6532 however, you must reinitialize the completion structure before reusing it. The macro:<br>
6533 <pre>
6534 INIT_COMPLETION(struct completion c);
6535 </pre>
6536 can be used to quickly perform this reinitialization.<br>
6537 <br>
6538 As an example of how completions may be used, consider the <i>complete </i>module, which
6539 is included in the example source. This module defines a device with simple semantics:
6540 any process trying to read from the device will wait (using <i>wait_for_completion</i>)<br>
6541 <br>
6542 * As of this writing, patches adding interruptible versions were in circulation but had not been merged into the mainline.<br>
6543 <br>
6544 <A name="116"></a><font color="blue">PAGE 116</font><br>
6545 <br>
6546 until some other process writes to the device. The code which implements this behavior
6547 is:<br>
6548 <pre>
6549 DECLARE_COMPLETION(comp);
6551 ssize_t complete_read (struct file *filp, char __user *buf, size_t count, loff_t
6552 *pos)
6553 {
6554 printk(KERN_DEBUG "process %i (%s) going to sleep\n",
6555 current->pid, current->comm);
6556 wait_for_completion(&comp);
6557 printk(KERN_DEBUG "awoken %i (%s)\n", current->pid, current->comm);
6558 return 0; /* EOF */
6559 }
6561 ssize_t complete_write (struct file *filp, const char __user *buf, size_t count,
6562 loff_t *pos)
6563 {
6564 printk(KERN_DEBUG "process %i (%s) awakening the readers...\n",
6565 current->pid, current->comm);
6566 complete(&comp);
6567 return count; /* succeed, to avoid retrial */
6568 }
6569 </pre>
6570 It is possible to have multiple processes "reading" from this device at the same time.
6571 Each write to the device will cause exactly one read operation to complete, but there
6572 is no way to know which one it will be.<br>
6573 <br>
6574 A typical use of the completion mechanism is with kernel thread termination at module
6575 exit time. In the prototypical case, some of the driver internal workings is performed
6576 by a kernel thread in a <font class="fixd">while (1)</font> loop. When the module is ready to be
6577 cleaned up, the exit function tells the thread to exit and then waits for completion.
6578 To this aim, the kernel includes a specific function to be used by the thread:<br>
6579 <pre>
6580 void complete_and_exit(struct completion *c, long retval);
6581 </pre>
6582 <a name="Spinlocks"></a><font color="red"><b>Spinlocks</b></font><br>
6583 <br>
6584 Semaphores are a useful tool for mutual exclusion, but they are not the only such
6585 tool provided by the kernel. Instead, most locking is implemented with a mechanism
6586 called a <i>spinlock</i>. Unlike semaphores, spinlocks may be used in code that cannot
6587 sleep, such as interrupt handlers. When properly used, spinlocks offer higher
6588 performance than semaphores in general. They do, however, bring a different set of
6589 constraints on their use.<br>
6590 <br>
6591 Spinlocks are simple in concept. A spinlock is a mutual exclusion device that can
6592 have only two values: "locked" and "unlocked." It is usually implemented as a single
6593 bit in an integer value. Code wishing to take out a particular lock tests the relevant
6594 bit. If the lockis available, the "locked" bit is set and the code continues into the critical
6595 section. If, instead, the lockhas been taken by somebody else, the code goes into<br>
6596 <br>
6597 <A name="117"></a><font color="blue">PAGE 117</font><br>
6598 <br>
6599 a tight loop where it repeatedly checks the lock until it becomes available. This loop
6600 is the "spin" part of a spinlock.<br>
6601 <br>
6602 Of course, the real implementation of a spinlock is a bit more complex than the
6603 description above. The "test and set" operation must be done in an atomic manner
6604 so that only one thread can obtain the lock, even if several are spinning at any given
6605 time. Care must also be taken to avoid deadlocks on <i>hyperthreaded </i>processors-chips
6606 that implement multiple, virtual CPUs sharing a single processor core and
6607 cache. So the actual spinlock implementation is different for every architecture that
6608 Linux supports. The core concept is the same on all systems, however, when there is
6609 contention for a spinlock, the processors that are waiting execute a tight loop and
6610 accomplish no useful work.<br>
6611 <br>
6612 Spinlocks are, by their nature, intended for use on multiprocessor systems, although
6613 a uniprocessor workstation running a preemptive kernel behaves like SMP, as far as
6614 concurrency is concerned. If a nonpreemptive uniprocessor system ever went into a
6615 spin on a lock, it would spin forever; no other thread would ever be able to obtain
6616 the CPU to release the lock. For this reason, spinlock operations on uniprocessor systems
6617 without preemption enabled are optimized to do nothing, with the exception of
6618 the ones that change the IRQ masking status. Because of preemption, even if you
6619 never expect your code to run on an SMP system, you still need to implement proper
6620 locking.<br>
6621 <br>
6622 <a name="IntroductionToTheSpinlockAPI"></a><font color="red"><b>Introduction to the Spinlock API</b></font><br>
6623 <br>
6624 The required include file for the spinlock primitives is <i><linux/spinlock.h></i>. An actual
6625 lockhas the type <font class="fixd">spinlock_t</font>. Like any other data structure, a spinlock must be initialized.
6626 This initialization may be done at compile time as follows:<br>
6627 <pre>
6628 spinlock_t my_lock = SPIN_LOCK_UNLOCKED;
6629 </pre>
6630 or at runtime with:<br>
6631 <pre>
6632 void spin_lock_init(spinlock_t *lock);
6633 </pre>
6634 Before entering a critical section, your code must obtain the requisite lock with:<br>
6635 <pre>
6636 void spin_lock(spinlock_t *lock);
6637 </pre>
6638 Note that all spinlock waits are, by their nature, uninterruptible. Once you call
6639 <i>spin_lock</i>, you will spin until the lock becomes available.<br>
6640 <br>
6641 To release a lock that you have obtained, pass it to:<br>
6642 <pre>
6643 void spin_unlock(spinlock_t *lock);
6644 </pre>
6645 There are many other spinlock-functions, and we will look at them all shortly. But
6646 none of them depart from the core idea shown by the functions listed above. There is
6647 very little that one can do with a lock, other than lock and release it. However, there<br>
6648 <br>
6649 <A name="118"></a><font color="blue">PAGE 118</font><br>
6650 <br>
6651 are a few rules about how you must work with spinlocks. We will take a moment to
6652 look at those before getting into the full spinlock interface.<br>
6653 <br>
6654 <a name="SpinlocksAndAtomicContext"></a><font color="red"><b>Spinlocks and Atomic Context</b></font><br>
6655 <br>
6656 Imagine for a moment that your driver acquires a spinlock and goes about its business
6657 within its critical section. Somewhere in the middle, your driver loses the processor.
6658 Perhaps it has called a function (<i>copy_from_user</i>, say) that puts the process to
6659 sleep. Or, perhaps, kernel preemption kicks in, and a higher-priority process pushes
6660 your code aside. Your code is now holding a lockthat it will not release any time in
6661 the foreseeable future. If some other thread tries to obtain the same lock, it will, in
6662 the best case, wait (spinning in the processor) for a very long time. In the worst case,
6663 the system could deadlock entirely.<br>
6664 <br>
6665 Most readers would agree that this scenario is best avoided. Therefore, the core rule
6666 that applies to spinlocks is that any code must, while holding a spinlock, be atomic.
6667 It cannot sleep; in fact, it cannot relinquish the processor for any reason except to
6668 service interrupts (and sometimes not even then).<br>
6669 <br>
6670 The kernel preemption case is handled by the spinlock code itself. Any time kernel
6671 code holds a spinlock, preemption is disabled on the relevant processor. Even uniprocessor
6672 systems must disable preemption in this way to avoid race conditions.
6673 That is why proper locking is required even if you never expect your code to run on a
6674 multiprocessor machine.<br>
6675 <br>
6676 Avoiding sleep while holding a lockcan be more difficult; many kernel functions can
6677 sleep, and this behavior is not always well documented. Copying data to or from user
6678 space is an obvious example: the required user-space page may need to be swapped
6679 in from the disk before the copy can proceed, and that operation clearly requires a
6680 sleep. Just about any operation that must allocate memory can sleep; <i>kmalloc </i>can
6681 decide to give up the processor, and wait for more memory to become available
6682 unless it is explicitly told not to. Sleeps can happen in surprising places; writing code
6683 that will execute under a spinlock requires paying attention to every function that
6684 you call.<br>
6685 <br>
6686 Here's another scenario: your driver is executing and has just taken out a lock that
6687 controls access to its device. While the lockis held, the device issues an interrupt,
6688 which causes your interrupt handler to run. The interrupt handler, before accessing
6689 the device, must also obtain the lock. Taking out a spinlock in an interrupt handler is
6690 a legitimate thing to do; that is one of the reasons that spinlock operations do not
6691 sleep. But what happens if the interrupt routine executes in the same processor as the
6692 code that took out the lock originally? While the interrupt handler is spinning, the
6693 noninterrupt code will not be able to run to release the lock. That processor will spin
6694 forever.<br>
6695 <br>
6696 <A name="119"></a><font color="blue">PAGE 119</font><br>
6697 <br>
6698 Avoiding this trap requires disabling interrupts (on the local CPU only) while the
6699 spinlock is held. There are variants of the spinlock functions that will disable interrupts
6700 for you (we'll see them in the next section). However, a complete discussion of
6701 interrupts must wait until Chapter 10.<br>
6702 <br>
6703 The last important rule for spinlock usage is that spinlocks must always be held for
6704 the minimum time possible. The longer you hold a lock, the longer another processor
6705 may have to spin waiting for you to release it, and the chance of it having to spin
6706 at all is greater. Long lockhold times also keep the current processor from scheduling,
6707 meaning that a higher priority process--which really should be able to get the
6708 CPU--may have to wait. The kernel developers put a great deal of effort into reducing
6709 kernel latency (the time a process may have to wait to be scheduled) in the 2.5
6710 development series. A poorly written driver can wipe out all that progress just by
6711 holding a lockfor too long. To avoid creating this sort of problem, make a point of
6712 keeping your lock-hold times short.<br>
6713 <br>
6714 <a name="TheSpinlockFunctions"></a><font color="red"><b>The Spinlock Functions</b></font><br>
6715 <br>
6716 We have already seen two functions, <i>spin_lock </i>and <i>spin_unlock</i>, that manipulate spinlocks.
6717 There are several other functions, however, with similar names and purposes.
6718 We will now present the full set. This discussion will take us into ground we will not
6719 be able to cover properly for a few chapters yet; a complete understanding of the spinlock
6720 API requires an understanding of interrupt handling and related concepts.<br>
6721 <br>
6722 There are actually four functions that can lock a spinlock:<br>
6723 <pre>
6724 void spin_lock(spinlock_t *lock);
6725 void spin_lock_irqsave(spinlock_t *lock, unsigned long flags);
6726 void spin_lock_irq(spinlock_t *lock);
6727 void spin_lock_bh(spinlock_t *lock)
6728 </pre>
6729 We have already seen how <i>spin_lock </i>works. <i>spin_lock_irqsave </i>disables interrupts (on
6730 the local processor only) before taking the spinlock; the previous interrupt state is
6731 stored in <font class="fixd">flags</font>. If you are absolutely sure nothing else might have already disabled
6732 interrupts on your processor (or, in other words, you are sure that you should enable
6733 interrupts when you release your spinlock), you can use <i>spin_lock_irq </i>instead and
6734 not have to keep track of the flags. Finally, <i>spin_lock_bh </i>disables software interrupts
6735 before taking the lock, but leaves hardware interrupts enabled.<br>
6736 <br>
6737 If you have a spinlock that can be taken by code that runs in (hardware or software)
6738 interrupt context, you must use one of the forms of <i>spin_lock </i>that disables interrupts.
6739 Doing otherwise can deadlock the system, sooner or later. If you do not access
6740 your lockin a hardware interrupt handler, but you do via software interrupts (in
6741 code that runs out of a tasklet, for example, a topic covered in Chapter 7), you can
6742 use <i>spin_lock_bh </i>to safely avoid deadlocks while still allowing hardware interrupts to
6743 be serviced.<br>
6744 <br>
6745 <A name="120"></a><font color="blue">PAGE 120</font><br>
6746 <br>
6747 There are also four ways to release a spinlock; the one you use must correspond to
6748 the function you used to take the lock:<br>
6749 <pre>
6750 void spin_unlock(spinlock_t *lock);
6751 void spin_unlock_irqrestore(spinlock_t *lock, unsigned long flags);
6752 void spin_unlock_irq(spinlock_t *lock);
6753 void spin_unlock_bh(spinlock_t *lock);
6754 </pre>
6755 Each <i>spin_unlock </i>variant undoes the work performed by the corresponding <i>spin_lock
6756 </i>function. The <font class="fixd">flags</font> argument passed to <i>spin_unlock_irqrestore </i>must be the same
6757 variable passed to <i>spin_lock_irqsave</i>. You must also call <i>spin_lock_irqsave </i>and <i>spin_
6758 <font class="fixd">unlock_irqrestore</font> </i>in the same function; otherwise, your code may break on some
6759 architectures.<br>
6760 <br>
6761 There is also a set of nonblocking spinlock operations:<br>
6762 <pre>
6763 int spin_trylock(spinlock_t *lock);
6764 int spin_trylock_bh(spinlock_t *lock);
6765 </pre>
6766 These functions return nonzero on success (the lock was obtained), 0 otherwise.
6767 There is no "try" version that disables interrupts.<br>
6768 <br>
6769 <a name="ReaderWriterSpinlocks"></a><font color="red"><b>Reader/Writer Spinlocks</b></font><br>
6770 <br>
6771 The kernel provides a reader/writer form of spinlocks that is directly analogous to
6772 the reader/writer semaphores we saw earlier in this chapter. These locks allow any
6773 number of readers into a critical section simultaneously, but writers must have exclusive
6774 access. Reader/writer locks have a type of <font class="fixd">rwlock_t</font>, defined in <i><linux/spinlock.h></i>.
6775 They can be declared and initialized in two ways:<br>
6776 <pre>
6777 rwlock_t my_rwlock = RW_LOCK_UNLOCKED; /* Static way */
6779 rwlock_t my_rwlock;
6780 rwlock_init(&my_rwlock); /* Dynamic way */
6781 </pre>
6782 The list of functions available should look reasonably familiar by now. For readers,
6783 the following functions are available:<br>
6784 <pre>
6785 void read_lock(rwlock_t *lock);
6786 void read_lock_irqsave(rwlock_t *lock, unsigned long flags);
6787 void read_lock_irq(rwlock_t *lock);
6788 void read_lock_bh(rwlock_t *lock);
6790 void read_unlock(rwlock_t *lock);
6791 void read_unlock_irqrestore(rwlock_t *lock, unsigned long flags);
6792 void read_unlock_irq(rwlock_t *lock);
6793 void read_unlock_bh(rwlock_t *lock);
6794 </pre>
6795 Interestingly, there is no <i>read_trylock</i>.<br>
6796 <br>
6797 The functions for write access are similar:<br>
6798 <pre>
6799 void write_lock(rwlock_t *lock);
6800 void write_lock_irqsave(rwlock_t *lock, unsigned long flags);
6801 </pre>
6802 <A name="121"></a><font color="blue">PAGE 121</font><br>
6803 <pre>
6804 void write_lock_irq(rwlock_t *lock);
6805 void write_lock_bh(rwlock_t *lock);
6806 int write_trylock(rwlock_t *lock);
6808 void write_unlock(rwlock_t *lock);
6809 void write_unlock_irqrestore(rwlock_t *lock, unsigned long flags);
6810 void write_unlock_irq(rwlock_t *lock);
6811 void write_unlock_bh(rwlock_t *lock);
6812 </pre>
6813 Reader/writer locks can starve readers just as rwsems can. This behavior is rarely a
6814 problem; however, if there is enough lockcontention to bring about starvation, performance
6815 is poor anyway.<br>
6816 <br>
6817 <a name="LockingTraps"></a><font color="red"><b>Locking Traps</b></font><br>
6818 <br>
6819 Many years of experience with locks--experience that predates Linux--have shown
6820 that locking can be very hard to get right. Managing concurrency is an inherently
6821 tricky undertaking, and there are many ways of making mistakes. In this section, we
6822 take a quick look at things that can go wrong.<br>
6823 <br>
6824 <a name="AmbiguousRules"></a><font color="red"><b>Ambiguous Rules</b></font><br>
6825 <br>
6826 As has already been said above, a proper locking scheme requires clear and explicit
6827 rules. When you create a resource that can be accessed concurrently, you should
6828 define which lockwill control that access. Locking should really be laid out at the
6829 beginning; it can be a hard thing to retrofit in afterward. Time taken at the outset
6830 usually is paid back generously at debugging time.<br>
6831 <br>
6832 As you write your code, you will doubtless encounter several functions that all
6833 require access to structures protected by a specific lock. At this point, you must be
6834 careful: if one function acquires a lockand then calls another function that also
6835 attempts to acquire the lock, your code deadlocks. Neither semaphores nor spinlocks
6836 allow a lockholder to acquire the locka second time; should you attempt to do
6837 so, things simply hang.<br>
6838 <br>
6839 To make your locking work properly, you have to write some functions with the
6840 assumption that their caller has already acquired the relevant lock(s). Usually, only
6841 your internal, static functions can be written in this way; functions called from outside
6842 must handle locking explicitly. When you write internal functions that make
6843 assumptions about locking, do yourself (and anybody else who works with your
6844 code) a favor and document those assumptions explicitly. It can be very hard to
6845 come back months later and figure out whether you need to hold a lockto call a particular
6846 function or not.<br>
6847 <br>
6848 In the case of <i>scull</i>, the design decision taken was to require all functions invoked
6849 directly from system calls to acquire the semaphore applying to the device structure<br>
6850 <br>
6851 <A name="122"></a><font color="blue">PAGE 122</font><br>
6852 <br>
6853 that is accessed. All internal functions, which are only called from other <i>scull </i>functions,
6854 can then assume that the semaphore has been properly acquired.<br>
6855 <br>
6856 <a name="LockOrderingRules"></a><font color="red"><b>Lock Ordering Rules</b></font><br>
6857 <br>
6858 In systems with a large number of locks (and the kernel is becoming such a system),
6859 it is not unusual for code to need to hold more than one lockat once. If some sort of
6860 computation must be performed using two different resources, each of which has its
6861 own lock, there is often no alternative to acquiring both locks.<br>
6862 <br>
6863 Taking multiple locks can be dangerous, however. If you have two locks, called
6864 <i>Lock1 </i>and <i>Lock2</i>, and code needs to acquire both at the same time, you have a
6865 potential deadlock. Just imagine one thread locking <i>Lock1 </i>while another simultaneously
6866 takes <i>Lock2</i>. Then each thread tries to get the one it doesn't have. Both
6867 threads will deadlock.<br>
6868 <br>
6869 The solution to this problem is usually simple: when multiple locks must be
6870 acquired, they should always be acquired in the same order. As long as this convention
6871 is followed, simple deadlocks like the one described above can be avoided.
6872 However, following lockordering rules can be easier said than done. It is very rare
6873 that such rules are actually written down anywhere. Often the best you can do is to
6874 see what other code does.<br>
6875 <br>
6876 A couple of rules of thumb can help. If you must obtain a lockthat is local to your
6877 code (a device lock, say) along with a lock belonging to a more central part of the
6878 kernel, take your lock first. If you have a combination of semaphores and spinlocks,
6879 you must, of course, obtain the semaphore(s) first; calling <i>down </i>(which can sleep)
6880 while holding a spinlock is a serious error. But most of all, try to avoid situations
6881 where you need more than one lock.<br>
6882 <br>
6883 <a name="FineVersusCoarseGrainedLocking"></a><font color="red"><b>Fine- Versus Coarse-Grained Locking</b></font><br>
6884 <br>
6885 The first Linux kernel that supported multiprocessor systems was 2.0; it contained
6886 exactly one spinlock. The <i>big kernel lock </i>turned the entire kernel into one large critical
6887 section; only one CPU could be executing kernel code at any given time. This
6888 locksolved the concurrency problem well enough to allow the kernel developers to
6889 address all of the other issues involved in supporting SMP. But it did not scale very
6890 well. Even a two-processor system could spend a significant amount of time simply
6891 waiting for the big kernel lock. The performance of a four-processor system was not
6892 even close to that of four independent machines.<br>
6893 <br>
6894 So, subsequent kernel releases have included finer-grained locking. In 2.2, one spinlock
6895 controlled access to the block I/O subsystem; another worked for networking,
6896 and so on. A modern kernel can contain thousands of locks, each protecting one
6897 small resource. This sort of fine-grained locking can be good for scalability; it allows<br>
6898 <br>
6899 <A name="123"></a><font color="blue">PAGE 123</font><br>
6900 <br>
6901 each processor to work on its specific task without contending for locks used by
6902 other processors. Very few people miss the big kernel lock.*<br>
6903 <br>
6904 Fine-grained locking comes at a cost, however. In a kernel with thousands of locks, it
6905 can be very hard to know which locks you need--and in which order you should
6906 acquire them--to perform a specific operation. Remember that locking bugs can be
6907 very difficult to find; more locks provide more opportunities for truly nasty locking
6908 bugs to creep into the kernel. Fine-grained locking can bring a level of complexity
6909 that, over the long term, can have a large, adverse effect on the maintainability of the
6910 kernel.<br>
6911 <br>
6912 Locking in a device driver is usually relatively straightforward; you can have a single
6913 lockthat covers everything you do, or you can create one lockfor every device you
6914 manage. As a general rule, you should start with relatively coarse locking unless you
6915 have a real reason to believe that contention could be a problem. Resist the urge to
6916 optimize prematurely; the real performance constraints often show up in unexpected
6917 places.<br>
6918 <br>
6919 If you do suspect that lockcontention is hurting performance, you may find the <i>lockmeter
6920 </i>tool useful. This patch (available at <a href="http://oss.sgi.com/projects/lockmeter/" target="_blank"><i>http://oss.sgi.com/projects/lockmeter/</i></a>)
6921 instruments the kernel to measure time spent waiting in locks. By looking at the
6922 report, you are able to determine quickly whether lock contention is truly the problem
6923 or not.<br>
6924 <br>
6925 <a name="AlternativesToLocking"></a><font color="red"><b>Alternatives to Locking</b></font><br>
6926 <br>
6927 The Linux kernel provides a number of powerful locking primitives that can be used
6928 to keep the kernel from tripping over its own feet. But, as we have seen, the design
6929 and implementation of a locking scheme is not without its pitfalls. Often there is no
6930 alternative to semaphores and spinlocks; they may be the only way to get the job
6931 done properly. There are situations, however, where atomic access can be set up
6932 without the need for full locking. This section looks at other ways of doing things.<br>
6933 <br>
6934 <a name="LockFreeAlgorithms"></a><font color="red"><b>Lock-Free Algorithms</b></font><br>
6935 <br>
6936 Sometimes, you can recast your algorithms to avoid the need for locking altogether.
6937 A number of reader/writer situations--if there is only one writer--can often workin
6938 this manner. If the writer takes care that the view of the data structure, as seen by the
6939 reader, is always consistent, it may be possible to create a lock-free data structure.<br>
6940 <br>
6941 A data structure that can often be useful for lockless producer/consumer tasks is the
6942 <i>circular buffer</i>. This algorithm involves a producer placing data into one end of an<br>
6943 <br>
6944 * This lockstill exists in 2.6, though it covers very little of the kernel now. If you stumble
6945 across a <i>lock_kernel</i> call, you have found the big kernel lock. Do not even think about
6946 using it in any new code, however.<br>
6947 <br>
6948 <A name="124"></a><font color="blue">PAGE 124</font><br>
6949 <br>
6950 array, while the consumer removes data from the other. When the end of the array is
6951 reached, the producer wraps back around to the beginning. So a circular buffer
6952 requires an array and two index values to track where the next new value goes and
6953 which value should be removed from the buffer next.<br>
6954 <br>
6955 When carefully implemented, a circular buffer requires no locking in the absence of
6956 multiple producers or consumers. The producer is the only thread that is allowed to
6957 modify the write index and the array location it points to. As long as the writer stores
6958 a new value into the buffer before updating the write index, the reader will always
6959 see a consistent view. The reader, in turn, is the only thread that can access the read
6960 index and the value it points to. With a bit of care to ensure that the two pointers do
6961 not overrun each other, the producer and the consumer can access the buffer concurrently
6962 with no race conditions.<br>
6963 <br>
6964 Figure 5-1 shows circular buffer in several states of fill. This buffer has been defined
6965 such that an empty condition is indicated by the read and write pointers being equal,
6966 while a full condition happens whenever the write pointer is immediately behind the
6967 read pointer (being careful to account for a wrap!). When carefully programmed, this
6968 buffer can be used without locks.<br>
6969 <br><br>
6970 <center>
6971 <img src="fig5-1.gif">
6972 </center>
6973 <br>
6974 <i>Figure 5-1. A circular buffer</i><br>
6975 <br>
6976 Circular buffers show up reasonably often in device drivers. Networking adaptors, in
6977 particular, often use circular buffers to exchange data (packets) with the processor.
6978 Note that, as of 2.6.10, there is a generic circular buffer implementation available in
6979 the kernel; see <i><linux/kfifo.h></i> for information on how to use it.<br>
6980 <br>
6981 <a name="AtomicVariables"></a><font color="red"><b>Atomic Variables</b></font><br>
6982 <br>
6983 Sometimes, a shared resource is a simple integer value. Suppose your driver maintains
6984 a shared variable <font class="fixd">n_op</font> that tells how many device operations are currently outstanding.
6985 Normally, even a simple operation such as:<br>
6986 <pre>
6987 n_op++;
6988 </pre>
6989 <A name="125"></a><font color="blue">PAGE 125</font><br>
6990 <br>
6991 would require locking. Some processors might perform that sort of increment in an
6992 atomic manner, but you can't count on it. But a full locking regime seems like overhead
6993 for a simple integer value. For cases like this, the kernel provides an atomic
6994 integer type called <font class="fixd">atomic_t</font>, defined in <i><asm/atomic.h></i>.<br>
6995 <br>
6996 An <font class="fixd">atomic_t</font> holds an <font class="fixd">int</font> value on all supported architectures. Because of the way
6997 this type works on some processors, however, the full integer range may not be available;
6998 thus, you should not count on an <font class="fixd">atomic_t</font> holding more than 24 bits. The following
6999 operations are defined for the type and are guaranteed to be atomic with
7000 respect to all processors of an SMP computer. The operations are very fast, because
7001 they compile to a single machine instruction whenever possible.<br>
7002 <br>
7003 <font class="fixd">void atomic_set(atomic_t *v, int i);<br>
7004 atomic_t v = ATOMIC_INIT(0);</font><br>
7005 <div class="bq">
7006 Set the atomic variable <font class="fixd">v</font> to the integer value <font class="fixd">i.</font> You can also initialize atomic values
7007 at compile time with the <font class="fixd">ATOMIC_INIT</font> macro.</div>
7008 <br>
7009 <font class="fixd">int atomic_read(atomic_t *v);</font><br>
7010 <div class="bq">
7011 Return the current value of <font class="fixd">v.</font></div>
7012 <br>
7013 <font class="fixd">void atomic_add(int i, atomic_t *v);</font><br>
7014 <div class="bq">
7015 Add <font class="fixd">i</font> to the atomic variable pointed to by <font class="fixd">v.</font> The return value is <font class="fixd">void,</font> because
7016 there is an extra cost to returning the new value, and most of the time there's no
7017 need to know it.</div>
7018 <br>
7019 <font class="fixd">void atomic_sub(int i, atomic_t *v);</font><br>
7020 <div class="bq">
7021 Subtract <font class="fixd">i</font> from <font class="fixd">*v.</font></div>
7022 <br>
7023 <font class="fixd">void atomic_inc(atomic_t *v);<br>
7024 void atomic_dec(atomic_t *v);</font><br>
7025 <div class="bq">
7026 Increment or decrement an atomic variable.</div>
7027 <br>
7028 <font class="fixd">int atomic_inc_and_test(atomic_t *v);<br>
7029 int atomic_dec_and_test(atomic_t *v);<br>
7030 int atomic_sub_and_test(int i, atomic_t *v);</font><br>
7031 <div class="bq">
7032 Perform the specified operation and test the result; if, after the operation, the
7033 atomic value is <font class="fixd">0,</font> then the return value is true; otherwise, it is false. Note that
7034 there is no <i>atomic_add_and_test</i>.</div>
7035 <br>
7036 <font class="fixd">int atomic_add_negative(int i, atomic_t *v);</font><br>
7037 <div class="bq">
7038 Add the integer variable <font class="fixd">i</font> to <font class="fixd">v.</font> The return value is true if the result is negative,
7039 false otherwise.</div>
7040 <br>
7041 <font class="fixd">int atomic_add_return(int i, atomic_t *v);<br>
7042 int atomic_sub_return(int i, atomic_t *v);<br>
7043 int atomic_inc_return(atomic_t *v);<br>
7044 int atomic_dec_return(atomic_t *v);</font><br>
7045 <div class="bq">
7046 Behave just like <i>atomic_add </i>and friends, with the exception that they return the
7047 new value of the atomic variable to the caller.</div>
7048 <br>
7049 <A name="126"></a><font color="blue">PAGE 126</font><br>
7050 <br>
7051 As stated earlier, <font class="fixd">atomic_t</font> data items must be accessed only through these functions.
7052 If you pass an atomic item to a function that expects an integer argument, you'll get
7053 a compiler error.<br>
7054 <br>
7055 You should also bear in mind that <font class="fixd">atomic_t</font> values work only when the quantity in
7056 question is truly atomic. Operations requiring multiple <font class="fixd">atomic_t</font> variables still
7057 require some other sort of locking. Consider the following code:<br>
7058 <pre>
7059 atomic_sub(amount, &first_atomic);
7060 atomic_add(amount, &second_atomic);
7061 </pre>
7062 There is a period of time where the amount has been subtracted from the first atomic
7063 value but not yet added to the second. If that state of affairs could create trouble for
7064 code that might run between the two operations, some form of locking must be
7065 employed.<br>
7066 <br>
7067 <a name="BitOperations"></a><font color="red"><b>Bit Operations</b></font><br>
7068 <br>
7069 The <font class="fixd">atomic_t</font> type is good for performing integer arithmetic. It doesn't work as well,
7070 however, when you need to manipulate individual bits in an atomic manner. For that
7071 purpose, instead, the kernel offers a set of functions that modify or test single bits
7072 atomically. Because the whole operation happens in a single step, no interrupt (or
7073 other processor) can interfere.<br>
7074 <br>
7075 Atomic bit operations are very fast, since they perform the operation using a single
7076 machine instruction without disabling interrupts whenever the underlying platform
7077 can do that. The functions are architecture dependent and are declared in <i><asm/
7078 bitops.h></i>. They are guaranteed to be atomic even on SMP computers and are useful
7079 to keep coherence across processors.<br>
7080 <br>
7081 Unfortunately, data typing in these functions is architecture dependent as well. The
7082 nr argument (describing which bit to manipulate) is usually defined as <font class="fixd">int</font> but is
7083 <font class="fixd">unsigned long</font> for a few architectures. The address to be modified is usually a pointer
7084 to <font class="fixd">unsigned long</font>, but a few architectures use <font class="fixd">void *</font> instead.<br>
7085 <br>
7086 The available bit operations are:<br>
7087 <br>
7088 <font class="fixd">void set_bit(nr, void *addr);</font><br>
7089 <div class="bq">
7090 Sets bit number <font class="fixd">nr</font> in the data item pointed to by <font class="fixd">addr.</font></div>
7091 <br>
7092 <font class="fixd">void clear_bit(nr, void *addr);</font><br>
7093 <div class="bq">
7094 Clears the specified bit in the <font class="fixd">unsigned long</font> datum that lives at <font class="fixd">addr.</font> Its semantics
7095 are otherwise the same as <i>set_bit</i>.</div>
7096 <br>
7097 <font class="fixd">void change_bit(nr, void *addr);</font><br>
7098 <div class="bq">
7099 Toggles the bit.</div>
7100 <br>
7101 <A name="127"></a><font color="blue">PAGE 127</font><br>
7102 <br>
7103 <font class="fixd">test_bit(nr, void *addr);</font><br>
7104 <div class="bq">
7105 This function is the only bit operation that doesn't need to be atomic; it simply
7106 returns the current value of the bit.</div>
7107 <br>
7108 <font class="fixd">int test_and_set_bit(nr, void *addr);<br>
7109 int test_and_clear_bit(nr, void *addr);<br>
7110 int test_and_change_bit(nr, void *addr);</font><br>
7111 <div class="bq">
7112 Behave atomically like those listed previously, except that they also return the
7113 previous value of the bit.</div>
7114 <br>
7115 When these functions are used to access and modify a shared flag, you don't have to
7116 do anything except call them; they perform their operations in an atomic manner.
7117 Using bit operations to manage a lockvariable that controls access to a shared variable,
7118 on the other hand, is a little more complicated and deserves an example. Most
7119 modern code does not use bit operations in this way, but code like the following still
7120 exists in the kernel.<br>
7121 <br>
7122 A code segment that needs to access a shared data item tries to atomically acquire a
7123 lockusing either <i>test_and_set_bit </i>or <i>test_and_clear_bit</i>. The usual implementation is
7124 shown here; it assumes that the locklives at bit <font class="fixd">nr</font> of address <font class="fixd">addr</font>. It also assumes
7125 that the bit is 0 when the lock is free or nonzero when the lock is busy.<br>
7126 <pre>
7127 /* try to set lock */
7128 while (test_and_set_bit(nr, addr) != 0)
7129 wait_for_a_while( );
7131 /* do your work */
7133 /* release lock, and check... */
7134 if (test_and_clear_bit(nr, addr) = = 0)
7135 something_went_wrong( ); /* already released: error */
7136 </pre>
7137 If you read through the kernel source, you find code that works like this example. It
7138 is, however, far better to use spinlocks in new code; spinlocks are well debugged,
7139 they handle issues like interrupts and kernel preemption, and others reading your
7140 code do not have to work to understand what you are doing.<br>
7141 <br>
7142 <a name="Seqlocks"></a><font color="red"><b>seqlocks</b></font><br>
7143 <br>
7144 The 2.6 kernel contains a couple of new mechanisms that are intended to provide
7145 fast, lockless access to a shared resource. Seqlocks work in situations where the
7146 resource to be protected is small, simple, and frequently accessed, and where write
7147 access is rare but must be fast. Essentially, they work by allowing readers free access
7148 to the resource but requiring those readers to check for collisions with writers and,
7149 when such a collision happens, retry their access. Seqlocks generally cannot be used
7150 to protect data structures involving pointers, because the reader may be following a
7151 pointer that is invalid while the writer is changing the data structure.<br>
7152 <br>
7153 <A name="128"></a><font color="blue">PAGE 128</font><br>
7154 <br>
7155 Seqlocks are defined in <i><linux/seqlock.h></i>. There are the two usual methods for initializing
7156 a seqlock (which has type <font class="fixd">seqlock_t</font>):<br>
7157 <pre>
7158 seqlock_t lock1 = SEQLOCK_UNLOCKED;
7160 seqlock_t lock2;
7161 seqlock_init(&lock2);
7162 </pre>
7163 Read access works by obtaining an (unsigned) integer sequence value on entry into
7164 the critical section. On exit, that sequence value is compared with the current value;
7165 if there is a mismatch, the read access must be retried. As a result, reader code has a
7166 form like the following:<br>
7167 <pre>
7168 unsigned int seq;
7170 do {
7171 seq = read_seqbegin(&the_lock);
7172 /* Do what you need to do */
7173 } while read_seqretry(&the_lock, seq);
7174 </pre>
7175 This sort of lockis usually used to protect some sort of simple computation that
7176 requires multiple, consistent values. If the test at the end of the computation shows
7177 that a concurrent write occurred, the results can be simply discarded and recomputed.<br>
7178 <br>
7179 If your seqlock might be accessed from an interrupt handler, you should use the
7180 IRQ-safe versions instead:<br>
7181 <pre>
7182 unsigned int read_seqbegin_irqsave(seqlock_t *lock,
7183 unsigned long flags);
7184 int read_seqretry_irqrestore(seqlock_t *lock, unsigned int seq,
7185 unsigned long flags);
7186 </pre>
7187 Writers must obtain an exclusive lockto enter the critical section protected by a
7188 seqlock. To do so, call:<br>
7189 <pre>
7190 void write_seqlock(seqlock_t *lock);
7191 </pre>
7192 The write lockis implemented with a spinlock, so all the usual constraints apply.
7193 Make a call to:<br>
7194 <pre>
7195 void write_sequnlock(seqlock_t *lock);
7196 </pre>
7197 to release the lock. Since spinlocks are used to control write access, all of the usual
7198 variants are available:<br>
7199 <pre>
7200 void write_seqlock_irqsave(seqlock_t *lock, unsigned long flags);
7201 void write_seqlock_irq(seqlock_t *lock);
7202 void write_seqlock_bh(seqlock_t *lock);
7204 void write_sequnlock_irqrestore(seqlock_t *lock, unsigned long flags);
7205 void write_sequnlock_irq(seqlock_t *lock);
7206 void write_sequnlock_bh(seqlock_t *lock);
7207 </pre>
7208 There is also a <i>write_tryseqlock</i> that returns nonzero if it was able to obtain the lock.<br>
7209 <br>
7210 <A name="129"></a><font color="blue">PAGE 129</font><br>
7211 <br>
7212 <a name="ReadCopyUpdate"></a><font color="red"><b>Read-Copy-Update</b></font><br>
7213 <br>
7214 Read-copy-update (RCU) is an advanced mutual exclusion scheme that can yield
7215 high performance in the right conditions. Its use in drivers is rare but not unknown,
7216 so it is worth a quick overview here. Those who are interested in the full details of
7217 the RCU algorithm can find them in the white paper published by its creator <br>
7218 <br>
7219 (<a href="http://www.rdrop.com/users/paulmck/rclock/intro/rclock_intro.html" target="_blank"><i>http://www.rdrop.com/users/paulmck/rclock/intro/rclock_intro.html</i></a>).<br>
7220 <br>
7221 RCU places a number of constraints on the sort of data structure that it can protect.
7222 It is optimized for situations where reads are common and writes are rare. The
7223 resources being protected should be accessed via pointers, and all references to those
7224 resources must be held only by atomic code. When the data structure needs to be
7225 changed, the writing thread makes a copy, changes the copy, then aims the relevant
7226 pointer at the new version--thus, the name of the algorithm. When the kernel is sure
7227 that no references to the old version remain, it can be freed.<br>
7228 <br>
7229 As an example of real-world use of RCU, consider the network routing tables. Every
7230 outgoing packet requires a check of the routing tables to determine which interface
7231 should be used. The check is fast, and, once the kernel has found the target interface,
7232 it no longer needs the routing table entry. RCU allows route lookups to be performed
7233 without locking, with significant performance benefits. The Starmode radio
7234 IP driver in the kernel also uses RCU to keep track of its list of devices.<br>
7235 <br>
7236 Code using RCU should include <i><linux/rcupdate.h></i>.<br>
7237 <br>
7238 On the read side, code using an RCU-protected data structure should bracket its references
7239 with calls to <i>rcu_read_lock </i>and <i>rcu_read_unlock</i>. As a result, RCU code
7240 tends to look like:<br>
7241 <pre>
7242 struct my_stuff *stuff;
7244 rcu_read_lock( );
7245 stuff = find_the_stuff(args...);
7246 do_something_with(stuff);
7247 rcu_read_unlock( );
7248 </pre>
7249 The <i>rcu_read_lock </i>call is fast; it disables kernel preemption but does not wait for
7250 anything. The code that executes while the read "lock" is held must be atomic. No
7251 reference to the protected resource may be used after the call to <i>rcu_read_unlock</i>.<br>
7252 <br>
7253 Code that needs to change the protected structure has to carry out a few steps. The
7254 first part is easy; it allocates a new structure, copies data from the old one if need be,
7255 then replaces the pointer that is seen by the read code. At this point, for the purposes
7256 of the read side, the change is complete; any code entering the critical section
7257 sees the new version of the data.<br>
7258 <br>
7259 All that remains is to free the old version. The problem, of course, is that code running
7260 on other processors may still have a reference to the older data, so it cannot be freed
7261 immediately. Instead, the write code must wait until it knows that no such reference<br>
7262 <br>
7263 <A name="130"></a><font color="blue">PAGE 130</font><br>
7264 <br>
7265 can exist. Since all code holding references to this data structure must (by the rules) be
7266 atomic, we know that once every processor on the system has been scheduled at least
7267 once, all references must be gone. So that is what RCU does; it sets aside a callback
7268 that waits until all processors have scheduled; that callback is then run to perform the
7269 cleanup work.<br>
7270 <br>
7271 Code that changes an RCU-protected data structure must get its cleanup callback by
7272 allocating a <font class="fixd">struct rcu_head,</font> although it doesn't need to initialize that structure in
7273 any way. Often, that structure is simply embedded within the larger resource that is
7274 protected by RCU. After the change to that resource is complete, a call should be
7275 made to:<br>
7276 <pre>
7277 void call_rcu(struct rcu_head *head, void (*func)(void *arg), void *arg);
7278 </pre>
7279 The given <font class="fixd">func</font> is called when it is safe to free the resource; it is passed to the same
7280 <font class="fixd">arg</font> that was passed to <i>call_rcu</i>. Usually, the only thing <font class="fixd">func</font> needs to do is to call
7281 <i>kfree</i>.<br>
7282 <br>
7283 The full RCU interface is more complex than we have seen here; it includes, for
7284 example, utility functions for working with protected linked lists. See the relevant
7285 header files for the full story.<br>
7286 <br>
7287 <a name="QuickReference5"></a><font color="red"><b>Quick Reference</b></font><br>
7288 <br>
7289 This chapter has introduced a substantial set of symbols for the management of concurrency.
7290 The most important of these are summarized here:<br>
7291 <br>
7292 <font class="fixd">#include <asm/semaphore.h></font><br>
7293 <div class="bq">
7294 The include file that defines semaphores and the operations on them.</div>
7295 <br>
7296 <font class="fixd">DECLARE_MUTEX(name);<br>
7297 DECLARE_MUTEX_LOCKED(name);</font></div>
7298 <div class="bq">
7299 Two macros for declaring and initializing a semaphore used in mutual exclusion
7300 mode.</div>
7301 <br>
7302 <font class="fixd">void init_MUTEX(struct semaphore *sem);<br>
7303 void init_MUTEX_LOCKED(struct semaphore *sem);</font><br>
7304 <div class="bq">
7305 These two functions can be used to initialize a semaphore at runtime.</div>
7306 <br>
7307 <font class="fixd">void down(struct semaphore *sem);<br>
7308 int down_interruptible(struct semaphore *sem);<br>
7309 int down_trylock(struct semaphore *sem);<br>
7310 void up(struct semaphore *sem);</font><br>
7311 <div class="bq">
7312 Lock and unlock a semaphore. <i>down </i>puts the calling process into an uninterruptible
7313 sleep if need be; <i>down_interruptible</i>, instead, can be interrupted by a signal.
7314 <i>down_trylock </i>does not sleep; instead, it returns immediately if the
7315 semaphore is unavailable. Code that locks a semaphore must eventually unlock
7316 it with <i>up</i>.</div>
7317 <br>
7318 <A name="131"></a><font color="blue">PAGE 131</font><br>
7319 <br>
7320 <font class="fixd">struct rw_semaphore;<br>
7321 init_rwsem(struct rw_semaphore *sem);</font><br>
7322 <div class="bq">
7323 The reader/writer version of semaphores and the function that initializes it.</div>
7324 <br>
7325 <font class="fixd">void down_read(struct rw_semaphore *sem);<br>
7326 int down_read_trylock(struct rw_semaphore *sem);<br>
7327 void up_read(struct rw_semaphore *sem);</font><br>
7328 <div class="bq">
7329 Functions for obtaining and releasing read access to a reader/writer semaphore.</div>
7330 <br>
7331 <font class="fixd">void down_write(struct rw_semaphore *sem)<br>
7332 int down_write_trylock(struct rw_semaphore *sem)<br>
7333 void up_write(struct rw_semaphore *sem)<br>
7334 void downgrade_write(struct rw_semaphore *sem)</font><br>
7335 <div class="bq">
7336 Functions for managing write access to a reader/writer semaphore.</div>
7337 <br>
7338 <font class="fixd">#include <linux/completion.h><br>
7339 DECLARE_COMPLETION(name);<br>
7340 init_completion(struct completion *c);<br>
7341 INIT_COMPLETION(struct completion c);</font><br>
7342 <div class="bq">
7343 The include file describing the Linux completion mechanism, and the normal
7344 methods for initializing completions. <font class="fixd">INIT_COMPLETION</font> should be used only to
7345 reinitialize a completion that has been previously used.</div>
7346 <br>
7347 <font class="fixd">void wait_for_completion(struct completion *c);</font><br>
7348 <div class="bq">
7349 Wait for a completion event to be signalled.</div>
7350 <br>
7351 <font class="fixd">void complete(struct completion *c);<br>
7352 void complete_all(struct completion *c);</font><br>
7353 <div class="bq">
7354 Signal a completion event. <i>complete </i>wakes, at most, one waiting thread, while
7355 <i>complete_all</i> wakes all waiters.</div>
7356 <br>
7357 <font class="fixd">void complete_and_exit(struct completion *c, long retval);</font><br>
7358 <div class="bq">
7359 Signals a completion event by calling <i>complete </i>and calls <i>exit </i>for the current
7360 thread.</div>
7361 <br>
7362 <font class="fixd">#include <linux/spinlock.h><br>
7363 spinlock_t lock = SPIN_LOCK_UNLOCKED;<br>
7364 spin_lock_init(spinlock_t *lock);</font><br>
7365 <div class="bq">
7366 The include file defining the spinlock interface and the two ways of initializing
7367 locks.</div>
7368 <br>
7369 <font class="fixd">void spin_lock(spinlock_t *lock);<br>
7370 void spin_lock_irqsave(spinlock_t *lock, unsigned long flags);<br>
7371 void spin_lock_irq(spinlock_t *lock);<br>
7372 void spin_lock_bh(spinlock_t *lock);</font><br>
7373 <div class="bq">
7374 The various ways of locking a spinlock and, possibly, disabling interrupts.</div>
7375 <br>
7376 <A name="132"></a><font color="blue">PAGE 132</font><br>
7377 <br>
7378 <font class="fixd">int spin_trylock(spinlock_t *lock);<br>
7379 int spin_trylock_bh(spinlock_t *lock);</font><br>
7380 <div class="bq">
7381 Nonspinning versions of the above functions; these return 0 in case of failure to
7382 obtain the lock, nonzero otherwise.</div>
7383 <br>
7384 <font class="fixd">void spin_unlock(spinlock_t *lock);<br>
7385 void spin_unlock_irqrestore(spinlock_t *lock, unsigned long flags);<br>
7386 void spin_unlock_irq(spinlock_t *lock);<br>
7387 void spin_unlock_bh(spinlock_t *lock);</font><br>
7388 <div class="bq">
7389 The corresponding ways of releasing a spinlock.</div>
7390 <br>
7391 <font class="fixd">rwlock_t lock = RW_LOCK_UNLOCKED
7392 rwlock_init(rwlock_t *lock);</font><br>
7393 <div class="bq">
7394 The two ways of initializing reader/writer locks.</div>
7395 <br>
7396 <font class="fixd">void read_lock(rwlock_t *lock);<br>
7397 void read_lock_irqsave(rwlock_t *lock, unsigned long flags);<br>
7398 void read_lock_irq(rwlock_t *lock);<br>
7399 void read_lock_bh(rwlock_t *lock);</font><br>
7400 <div class="bq">
7401 Functions for obtaining read access to a reader/writer lock.</div>
7402 <br>
7403 <font class="fixd">void read_unlock(rwlock_t *lock);<br>
7404 void read_unlock_irqrestore(rwlock_t *lock, unsigned long flags);<br>
7405 void read_unlock_irq(rwlock_t *lock);<br>
7406 void read_unlock_bh(rwlock_t *lock);</font><br>
7407 <div class="bq">
7408 Functions for releasing read access to a reader/writer spinlock.</div>
7409 <br>
7410 <font class="fixd">void write_lock(rwlock_t *lock);<br>
7411 void write_lock_irqsave(rwlock_t *lock, unsigned long flags);<br>
7412 void write_lock_irq(rwlock_t *lock);<br>
7413 void write_lock_bh(rwlock_t *lock);</font><br>
7414 <div class="bq">
7415 Functions for obtaining write access to a reader/writer lock.</div>
7416 <br>
7417 <font class="fixd">void write_unlock(rwlock_t *lock);<br>
7418 void write_unlock_irqrestore(rwlock_t *lock, unsigned long flags);<br>
7419 void write_unlock_irq(rwlock_t *lock);<br>
7420 void write_unlock_bh(rwlock_t *lock);</font><br>
7421 <div class="bq">
7422 Functions for releasing write access to a reader/writer spinlock.</div>
7423 <br>
7424 <A name="133"></a><font color="blue">PAGE 133</font><br>
7425 <br>
7426 <font class="fixd">#include <asm/atomic.h><br>
7427 atomic_t v = ATOMIC_INIT(value);<br>
7428 void atomic_set(atomic_t *v, int i);<br>
7429 int atomic_read(atomic_t *v);<br>
7430 void atomic_add(int i, atomic_t *v);<br>
7431 void atomic_sub(int i, atomic_t *v);<br>
7432 void atomic_inc(atomic_t *v);<br>
7433 void atomic_dec(atomic_t *v);<br>
7434 int atomic_inc_and_test(atomic_t *v);<br>
7435 int atomic_dec_and_test(atomic_t *v);<br>
7436 int atomic_sub_and_test(int i, atomic_t *v);<br>
7437 int atomic_add_negative(int i, atomic_t *v);<br>
7438 int atomic_add_return(int i, atomic_t *v);<br>
7439 int atomic_sub_return(int i, atomic_t *v);<br>
7440 int atomic_inc_return(atomic_t *v);<br>
7441 int atomic_dec_return(atomic_t *v);</font><br>
7442 <div class="bq">
7443 Atomically access integer variables. The <font class="fixd">atomic_t</font> variables must be accessed
7444 only through these functions.</div>
7445 <br>
7446 <font class="fixd">#include <asm/bitops.h><br>
7447 void set_bit(nr, void *addr);<br>
7448 void clear_bit(nr, void *addr);<br>
7449 void change_bit(nr, void *addr);<br>
7450 test_bit(nr, void *addr);<br>
7451 int test_and_set_bit(nr, void *addr);<br>
7452 int test_and_clear_bit(nr, void *addr);<br>
7453 int test_and_change_bit(nr, void *addr);</font><br>
7454 <div class="bq">
7455 Atomically access bit values; they can be used for <font class="fixd">flags</font> or lockvariables. Using
7456 these functions prevents any race condition related to concurrent access to the
7457 bit.</div>
7458 <br>
7459 <font class="fixd">#include <linux/seqlock.h><br>
7460 seqlock_t lock = SEQLOCK_UNLOCKED;<br>
7461 seqlock_init(seqlock_t *lock);</font><br>
7462 <div class="bq">
7463 The include file defining seqlocks and the two ways of initializing them.</div>
7464 <br>
7465 <font class="fixd">unsigned int read_seqbegin(seqlock_t *lock);<br>
7466 unsigned int read_seqbegin_irqsave(seqlock_t *lock, unsigned long flags);<br>
7467 int read_seqretry(seqlock_t *lock, unsigned int seq);<br>
7468 int read_seqretry_irqrestore(seqlock_t *lock, unsigned int seq, unsigned long flags);</font><br>
7469 <div class="bq">
7470 Functions for obtaining read access to a seqlock-protected resources.</div>
7471 <br>
7472 <A name="134"></a><font color="blue">PAGE 134</font><br>
7473 <br>
7474 <font class="fixd">void write_seqlock(seqlock_t *lock);<br>
7475 void write_seqlock_irqsave(seqlock_t *lock, unsigned long flags);<br>
7476 void write_seqlock_irq(seqlock_t *lock);<br>
7477 void write_seqlock_bh(seqlock_t *lock);<br>
7478 int write_tryseqlock(seqlock_t *lock);</font><br>
7479 <div class="bq">
7480 Functions for obtaining write access to a seqlock-protected resource.</div>
7481 <br>
7482 <font class="fixd">void write_sequnlock(seqlock_t *lock);<br>
7483 void write_sequnlock_irqrestore(seqlock_t *lock, unsigned long flags);<br>
7484 void write_sequnlock_irq(seqlock_t *lock);<br>
7485 void write_sequnlock_bh(seqlock_t *lock);</font><br>
7486 <div class="bq">
7487 Functions for releasing write access to a seqlock-protected resource.</div>
7488 <br>
7489 <font class="fixd">#include <linux/rcupdate.h></font><br>
7490 <div class="bq">
7491 The include file required to use the read-copy-update (RCU) mechanism.</div>
7492 <br>
7493 <font class="fixd">void rcu_read_lock;<br>
7494 void rcu_read_unlock;</font><br>
7495 <div class="bq">
7496 Macros for obtaining atomic read access to a resource protected by RCU.</div>
7497 <br>
7498 <font class="fixd">void call_rcu(struct rcu_head *head, void (*func)(void *arg), void *arg);</font><br>
7499 <div class="bq">
7500 Arranges for a callback to run after all processors have been scheduled and an
7501 RCU-protected resource can be safely freed.</div>
7502 <br>
7503 <A name="135"></a><font color="blue">PAGE 135</font><br>
7504 <br>
7505 <a name="CHAPTER6"></a><font color="red"><b>CHAPTER 6</b></font><br>
7506 <br>
7507 <a name="AdvancedCharDriverOperations"></a><font color="#7519FF" size="+1"><b>Advanced Char Driver Operations</b></font><br>
7508 <br>
7509 In Chapter 3, we built a complete device driver that the user can write to and read
7510 from. But a real device usually offers more functionality than synchronous <i>read </i>and
7511 <i>write</i>. Now that we're equipped with debugging tools should something go awry-and
7512 a firm understanding of concurrency issues to help keep things from going
7513 awry--we can safely go ahead and create a more advanced driver.<br>
7514 <br>
7515 This chapter examines a few concepts that you need to understand to write fully featured
7516 char device drivers. We start with implementing the <i>ioctl </i>system call, which is
7517 a common interface used for device control. Then we proceed to various ways of synchronizing
7518 with user space; by the end of this chapter you have a good idea of how to
7519 put processes to sleep (and wake them up), implement nonblocking I/O, and inform
7520 user space when your devices are available for reading or writing. We finish with a
7521 look at how to implement a few different device access policies within drivers.<br>
7522 <br>
7523 The ideas discussed here are demonstrated by way of a couple of modified versions
7524 of the <i>scull </i>driver. Once again, everything is implemented using in-memory virtual
7525 devices, so you can try out the code yourself without needing to have any particular
7526 hardware. By now, you may be wanting to get your hands dirty with real hardware,
7527 but that will have to wait until Chapter 9.<br>
7528 <br>
7529 <a name="Ioctl"></a><font color="red"><b>ioctl</b></font><br>
7530 <br>
7531 Most drivers need--in addition to the ability to read and write the device--the ability
7532 to perform various types of hardware control via the device driver. Most devices
7533 can perform operations beyond simple data transfers; user space must often be able
7534 to request, for example, that the device lock its door, eject its media, report error
7535 information, change a baud rate, or self destruct. These operations are usually supported
7536 via the <i>ioctl</i> method, which implements the system call by the same name.<br>
7537 <br>
7538 In user space, the <i>ioctl</i> system call has the following prototype:<br>
7539 <pre>
7540 int ioctl(int fd, unsigned long cmd, ...);
7541 </pre>
7542 <A name="136"></a><font color="blue">PAGE 136</font><br>
7543 <br>
7544 The prototype stands out in the list of Unix system calls because of the dots, which
7545 usually mark the function as having a variable number of arguments. In a real system,
7546 however, a system call can't actually have a variable number of arguments. System
7547 calls must have a well-defined prototype, because user programs can access
7548 them only through hardware "gates." Therefore, the dots in the prototype represent
7549 not a variable number of arguments but a single optional argument, traditionally
7550 identified as <font class="fixd">char *argp.</font> The dots are simply there to prevent type checking during
7551 compilation. The actual nature of the third argument depends on the specific control
7552 command being issued (the second argument). Some commands take no arguments,
7553 some take an integer value, and some take a pointer to other data. Using a
7554 pointer is the way to pass arbitrary data to the <i>ioctl </i>call; the device is then able to
7555 exchange any amount of data with user space.<br>
7556 <br>
7557 The unstructured nature of the <i>ioctl </i>call has caused it to fall out of favor among kernel
7558 developers. Each <i>ioctl </i>command is, essentially, a separate, usually undocumented
7559 system call, and there is no way to audit these calls in any sort of
7560 comprehensive manner. It is also difficult to make the unstructured <i>ioctl </i>arguments
7561 work identically on all systems; for example, consider 64-bit systems with a userspace
7562 process running in 32-bit mode. As a result, there is strong pressure to implement
7563 miscellaneous control operations by just about any other means. Possible alternatives
7564 include embedding commands into the data stream (we will discuss this
7565 approach later in this chapter) or using virtual filesystems, either sysfs or driver-specific
7566 filesystems. (We will look at sysfs in Chapter 14.) However, the fact remains
7567 that <i>ioctl</i> is often the easiest and most straightforward choice for true device operations.<br>
7568 <br>
7569 The <i>ioctl </i>driver method has a prototype that differs somewhat from the user-space
7570 version:<br>
7571 <pre>
7572 int (*ioctl) (struct inode *inode, struct file *filp,
7573 unsigned int cmd, unsigned long arg);
7574 </pre>
7575 The <font class="fixd">inode</font> and <font class="fixd">filp</font> pointers are the values corresponding to the file
7576 descriptor <font class="fixd">fd</font> passed on by the application and are the same parameters passed to the <i>open
7577 </i>method. The <font class="fixd">cmd</font> argument is passed from the user unchanged, and the optional arg
7578 argument is passed in the form of an <font class="fixd">unsigned long</font>, regardless of whether it was
7579 given by the user as an integer or a pointer. If the invoking program doesn't pass a
7580 third argument, the <font class="fixd">arg</font> value received by the driver operation is undefined. Because
7581 type checking is disabled on the extra argument, the compiler can't warn you if an
7582 invalid argument is passed to <i>ioctl</i>, and any associated bug would be difficult to spot.<br>
7583 <br>
7584 As you might imagine, most <i>ioctl </i>implementations consist of a <font class="fixd">big switch</font> statement
7585 that selects the correct behavior according to the <font class="fixd">cmd</font> argument. Different commands
7586 have different numeric values, which are usually given symbolic names to simplify
7587 coding. The symbolic name is assigned by a preprocessor definition. Custom drivers
7588 usually declare such symbols in their header files; <i>scull.h </i>declares them for <i>scull</i>. User<br>
7589 <br>
7590 <A name="137"></a><font color="blue">PAGE 137</font><br>
7591 <br>
7592 programs must, of course, include that header file as well to have access to those
7593 symbols.<br>
7594 <br>
7595 <a name="ChoosingTheIoctlCommands"></a><font color="red"><b>Choosing the ioctl Commands</b></font><br>
7596 <br>
7597 Before writing the code for <i>ioctl</i>, you need to choose the numbers that correspond to
7598 commands. The first instinct of many programmers is to choose a set of small numbers
7599 starting with 0 or 1 and going up from there. There are, however, good reasons
7600 for not doing things that way. The <i>ioctl </i>command numbers should be unique across
7601 the system in order to prevent errors caused by issuing the right command to the
7602 wrong device. Such a mismatch is not unlikely to happen, and a program might find
7603 itself trying to change the baud rate of a non-serial-port input stream, such as a FIFO
7604 or an audio device. If each <i>ioctl </i>number is unique, the application gets an <font class="fixd">EINVAL</font>
7605 error rather than succeeding in doing something unintended.<br>
7606 <br>
7607 To help programmers create unique <i>ioctl </i>command codes, these codes have been
7608 split up into several bitfields. The first versions of Linux used 16-bit numbers: the
7609 top eight were the "magic" numbers associated with the device, and the bottom eight
7610 were a sequential number, unique within the device. This happened because Linus
7611 was "clueless" (his own word); a better division of bitfields was conceived only later.
7612 Unfortunately, quite a few drivers still use the old convention. They have to: changing
7613 the command codes would break no end of binary programs, and that is not
7614 something the kernel developers are willing to do.<br>
7615 <br>
7616 To choose <i>ioctl </i>numbers for your driver according to the Linux kernel convention,
7617 you should first check <i>include/asm/ioctl.h </i>and <i>Documentation/ioctl-number.txt</i>. The
7618 header defines the bitfields you will be using: type (magic number), ordinal number,
7619 direction of transfer, and size of argument. The <i>ioctl-number.txt </i>file lists the magic
7620 numbers used throughout the kernel,* so you'll be able to choose your own magic
7621 number and avoid overlaps. The text file also lists the reasons why the convention
7622 should be used.<br>
7623 <br>
7624 The approved way to define <i>ioctl </i>command numbers uses four bitfields, which have
7625 the following meanings. New symbols introduced in this list are defined in <i><linux/
7626 ioctl.h></i>.<br>
7627 <br>
7628 <font class="fixd">type</font><br>
7629 <div class="bq">
7630 The magic number. Just choose one number (after consulting <i>ioctl-number.txt</i>)
7631 and use it throughout the driver. This field is eight bits wide (<font class="fixd">_IOC_TYPEBITS</font>).</div>
7632 <br>
7633 <font class="fixd">number</font><br>
7634 <div class="bq">
7635 The ordinal (sequential) number. It's eight bits (<font class="fixd">_IOC_NRBITS</font>) wide.</div>
7636 <br>
7637 * Maintenance of this file has been somewhat scarce as of late, however.<br>
7638 <br>
7639 <A name="138"></a><font color="blue">PAGE 138</font><br>
7640 <br>
7641 <font class="fixd">direction</font><br>
7642 <div class="bq">
7643 The direction of data transfer, if the particular command involves a data transfer.
7644 The possible values are <font class="fixd">_IOC_NONE</font> (no data transfer), <font class="fixd">_IOC_READ, _IOC_WRITE,</font>
7645 and <font class="fixd">_IOC_READ|_IOC_WRITE</font> (data is transferred both ways). Data transfer is seen
7646 from the application's point of view; <font class="fixd">_IOC_READ</font> means reading <i>from </i>the device,
7647 so the driver must write to user space. Note that the field is a bit mask, so <font class="fixd">_IOC_READ</font>
7648 and <font class="fixd">_IOC_WRITE</font> can be extracted using a logical AND operation.</div>
7649 <br>
7650 <font class="fixd">size</font><br>
7651 <div class="bq">
7652 The size of user data involved. The width of this field is architecture dependent,
7653 but is usually 13 or 14 bits. You can find its value for your specific architecture
7654 in the macro <font class="fixd">_IOC_SIZEBITS</font>. It's not mandatory that you use the <font class="fixd">size</font> field--the
7655 kernel does not check it--but it is a good idea. Proper use of this field can help
7656 detect user-space programming errors and enable you to implement backward
7657 compatibility if you ever need to change the size of the relevant data item. If you
7658 need larger data structures, however, you can just ignore the <font class="fixd">size</font> field. We'll see
7659 how this field is used soon.</div>
7660 <br>
7661 The header file <i><asm/ioctl.h></i>, which is included by <i><linux/ioctl.h></i>, defines macros
7662 that help set up the command numbers as follows: <font class="fixd">_IO(type,nr)</font> (for a command
7663 that has no argument), <font class="fixd">_IOR(type,nr,datatype)</font> (for reading data from the
7664 driver), <font class="fixd">_IOW(type,nr,datatype)</font> (for writing data), and <font class="fixd">_IOWR(type,nr,datatype)</font> (for
7665 bidirectional transfers). The type and number fields are passed as arguments, and the
7666 <font class="fixd">size</font> field is derived by applying <i>sizeof</i> to the datatype argument.<br>
7667 <br>
7668 The header also defines macros that may be used in your driver to decode the numbers:
7669 <font class="fixd">_IOC_DIR(nr), _IOC_TYPE(nr), _IOC_NR(nr)</font>, and <font class="fixd">_IOC_SIZE(nr).</font> We won't go
7670 into any more detail about these macros because the header file is clear, and sample
7671 code is shown later in this section.<br>
7672 <br>
7673 Here is how some <i>ioctl </i>commands are defined in <i>scull</i>. In particular, these commands
7674 set and get the driver's configurable parameters.<br>
7675 <pre>
7676 /* Use 'k' as magic number */
7677 #define SCULL_IOC_MAGIC 'k'
7678 /* Please use a different 8-bit number in your code */
7680 #define SCULL_IOCRESET _IO(SCULL_IOC_MAGIC, 0)
7682 /*
7683 * S means "Set" through a ptr,
7684 * T means "Tell" directly with the argument value
7685 * G means "Get": reply by setting through a pointer
7686 * Q means "Query": response is on the return value
7687 * X means "eXchange": switch G and S atomically
7688 * H means "sHift": switch T and Q atomically
7689 */
7690 #define SCULL_IOCSQUANTUM _IOW(SCULL_IOC_MAGIC, 1, int)
7691 #define SCULL_IOCSQSET _IOW(SCULL_IOC_MAGIC, 2, int)
7692 </pre>
7693 <A name="139"></a><font color="blue">PAGE 139</font><br>
7694 <pre>
7695 #define SCULL_IOCTQUANTUM _IO(SCULL_IOC_MAGIC, 3)
7696 #define SCULL_IOCTQSET _IO(SCULL_IOC_MAGIC, 4)
7697 #define SCULL_IOCGQUANTUM _IOR(SCULL_IOC_MAGIC, 5, int)
7698 #define SCULL_IOCGQSET _IOR(SCULL_IOC_MAGIC, 6, int)
7699 #define SCULL_IOCQQUANTUM _IO(SCULL_IOC_MAGIC, 7)
7700 #define SCULL_IOCQQSET _IO(SCULL_IOC_MAGIC, 8)
7701 #define SCULL_IOCXQUANTUM _IOWR(SCULL_IOC_MAGIC, 9, int)
7702 #define SCULL_IOCXQSET _IOWR(SCULL_IOC_MAGIC,10, int)
7703 #define SCULL_IOCHQUANTUM _IO(SCULL_IOC_MAGIC, 11)
7704 #define SCULL_IOCHQSET _IO(SCULL_IOC_MAGIC, 12)
7706 #define SCULL_IOC_MAXNR 14
7707 </pre>
7708 The actual source file defines a few extra commands that have not been shown here.<br>
7709 <br>
7710 We chose to implement both ways of passing integer arguments: by pointer and by
7711 explicit value (although, by an established convention, <i>ioctl </i>should exchange values
7712 by pointer). Similarly, both ways are used to return an integer number: by pointer or
7713 by setting the return value. This works as long as the return value is a positive integer;
7714 as you know by now, on return from any system call, a positive value is preserved
7715 (as we saw for <i>read </i>and <i>write</i>), while a negative value is considered an error
7716 and is used to set <font class="fixd">errno</font> in user space.*<br>
7717 <br>
7718 The "exchange" and "shift" operations are not particularly useful for <i>scull</i>. We
7719 implemented "exchange" to show how the driver can combine separate operations
7720 into a single atomic one, and "shift" to pair "tell" and "query." There are times when
7721 atomic test-and-set operations like these are needed, in particular, when applications
7722 need to set or release locks.<br>
7723 <br>
7724 The explicit ordinal number of the command has no specific meaning. It is used only
7725 to tell the commands apart. Actually, you could even use the same ordinal number
7726 for a read command and a write command, since the actual <i>ioctl </i>number is different
7727 in the "direction" bits, but there is no reason why you would want to do so. We
7728 chose not to use the ordinal number of the command anywhere but in the declaration,
7729 so we didn't assign a symbolic value to it. That's why explicit numbers appear
7730 in the definition given previously. The example shows one way to use the command
7731 numbers, but you are free to do it differently.<br>
7732 <br>
7733 With the exception of a small number of predefined commands (to be discussed
7734 shortly), the value of the <i>ioctl </i><font class="fixd">cmd</font> argument is not currently used by the kernel, and
7735 it's quite unlikely it will be in the future. Therefore, you could, if you were feeling
7736 lazy, avoid the complex declarations shown earlier and explicitly declare a set of scalar
7737 numbers. On the other hand, if you did, you wouldn't benefit from using the bitfields,
7738 and you would encounter difficulties if you ever submitted your code for<br>
7739 <br>
7740 * Actually, all <i>libc </i>implementations currently in use (including uClibc) consider as
7741 error codes only values in the range -4095 to -1. Unfortunately, being able to return large
7742 negative numbers but not small ones is not very useful.<br>
7743 <br>
7744 <A name="140"></a><font color="blue">PAGE 140</font><br>
7745 <br>
7746 inclusion in the mainline kernel. The header <i><linux/kd.h> </i>is an example of this old-fashioned
7747 approach, using 16-bit scalar values to define the <i>ioctl </i>commands. That
7748 source file relied on scalar numbers because it used the conventions obeyed at that
7749 time, not out of laziness. Changing it now would cause gratuitous incompatibility.<br>
7750 <br>
7751 <a name="TheReturnValue"></a><font color="red"><b>The Return Value</b></font><br>
7752 <br>
7753 The implementation of <i>ioctl </i>is usually a <font class="fixd">switch</font> statement based on the command
7754 number. But what should the <font class="fixd">default</font> selection be when the command number
7755 doesn't match a valid operation? The question is controversial. Several kernel functions
7756 return <font class="fixd">-EINVAL</font> ("Invalid argument"), which makes sense because the command
7757 argument is indeed not a valid one. The POSIX standard, however, states that
7758 if an inappropriate <i>ioctl </i>command has been issued, then <font class="fixd">-ENOTTY</font> should be returned.
7759 This error code is interpreted by the C library as "inappropriate ioctl for device,"
7760 which is usually exactly what the programmer needs to hear. It's still pretty common,
7761 though, to return <font class="fixd">-EINVAL</font> in response to an invalid <i>ioctl</i> command.<br>
7762 <br>
7763 <a name="ThePredefinedCommands"></a><font color="red"><b>The Predefined Commands</b></font><br>
7764 <br>
7765 Although the <i>ioctl </i>system call is most often used to act on devices, a few commands
7766 are recognized by the kernel. Note that these commands, when applied to your
7767 device, are decoded <i>before </i>your own file operations are called. Thus, if you choose
7768 the same number for one of your <i>ioctl </i>commands, you won't ever see any request for
7769 that command, and the application gets something unexpected because of the conflict
7770 between the <i>ioctl</i> numbers.<br>
7771 <br>
7772 The predefined commands are divided into three groups:<br>
7773 <ul>
7774 <li> Those that can be issued on any file (regular, device, FIFO, or socket)
7775 <li> Those that are issued only on regular files
7776 <li> Those specific to the filesystem type
7777 </ul>
7778 Commands in the last group are executed by the implementation of the hosting filesystem
7779 (this is how the <i>chattr </i>command works). Device driver writers are interested
7780 only in the first group of commands, whose magic number is "T." Looking at the
7781 workings of the other groups is left to the reader as an exercise; <i>ext2_ioctl </i>is a most
7782 interesting function (and easier to understand than one might expect), because it
7783 implements the append-only flag and the immutable flag.<br>
7784 <br>
7785 <A name="141"></a><font color="blue">PAGE 141</font><br>
7786 <br>
7787 The following <i>ioctl </i>commands are predefined for any file, including device-special
7788 files:<br>
7789 <br>
7790 <font class="fixd">FIOCLEX</font><br>
7791 <div class="bq">
7792 Set the close-on-exec flag (File IOctl CLose on EXec). Setting this flag causes the
7793 file descriptor to be closed when the calling process executes a new program.</div>
7794 <br>
7795 <font class="fixd">FIONCLEX</font><br>
7796 <div class="bq">
7797 Clear the close-on-exec flag (File IOctl Not CLos on EXec). The command
7798 restores the common file behavior, undoing what <font class="fixd">FIOCLEX</font> above does.</div>
7799 <br>
7800 <font class="fixd">FIOASYNC</font><br>
7801 <div class="bq">
7802 Set or reset asynchronous notification for the file (as discussed in the section
7803 "Asynchronous Notification," later in this chapter). Note that kernel versions up
7804 to Linux 2.2.4 incorrectly used this command to modify the <font class="fixd">O_SYNC</font> flag. Since
7805 both actions can be accomplished through <i>fcntl</i>, nobody actually uses the
7806 <font class="fixd">FIOASYNC</font> command, which is reported here only for completeness.</div>
7807 <br>
7808 <font class="fixd">FIOQSIZE</font><br>
7809 <div class="bq">
7810 This command returns the size of a file or directory; when applied to a device
7811 file, however, it yields an <font class="fixd">ENOTTY</font> error return.</div>
7812 <br>
7813 <font class="fixd">FIONBIO</font><br>
7814 <div class="bq">
7815 "File IOctl Non-Blocking I/O" (described in the section "Blocking and Nonblocking
7816 Operations"). This call modifies the <font class="fixd">O_NONBLOCK</font> flag in <font class="fixd">filp->f_flags</font>.
7817 The third argument to the system call is used to indicate whether the flag is to be
7818 set or cleared. (We'll look at the role of the flag later in this chapter.) Note that
7819 the usual way to change this flag is with the <i>fcntl </i>system call, using the <i><font class="fixd">F_SETFL</font>
7820 </i>command.</div>
7821 <br>
7822 The last item in the list introduced a new system call, <i>fcntl</i>, which looks like <i>ioctl</i>. In
7823 fact, the <i>fcntl </i>call is very similar to <i>ioctl </i>in that it gets a command argument and an
7824 extra (optional) argument. It is kept separate from <i>ioctl </i>mainly for historical reasons:
7825 when Unix developers faced the problem of controlling I/O operations, they decided
7826 that files and devices were different. At the time, the only devices with <i>ioctl </i>implementations
7827 were ttys, which explains why <font class="fixd">-ENOTTY</font> is the standard reply for an incorrect
7828 <i>ioctl</i> command. Things have changed, but <i>fcntl</i> remains a separate system call.<br>
7829 <br>
7830 <a name="UsingTheIoctlArgument"></a><font color="red"><b>Using the ioctl Argument</b></font><br>
7831 <br>
7832 Another point we need to cover before looking at the <i>ioctl </i>code for the <i>scull </i>driver is
7833 how to use the extra argument. If it is an integer, it's easy: it can be used directly. If it
7834 is a pointer, however, some care must be taken.<br>
7835 <br>
7836 <A name="142"></a><font color="blue">PAGE 142</font><br>
7837 <br>
7838 When a pointer is used to refer to user space, we must ensure that the user address is
7839 valid. An attempt to access an unverified user-supplied pointer can lead to incorrect
7840 behavior, a kernel oops, system corruption, or security problems. It is the driver's
7841 responsibility to make proper checks on every user-space address it uses and to
7842 return an error if it is invalid.<br>
7843 <br>
7844 In Chapter 3, we looked at the <i>copy_from_user </i>and <i>copy_to_user </i>functions, which
7845 can be used to safely move data to and from user space. Those functions can be used
7846 in <i>ioctl </i>methods as well, but <i>ioctl </i>calls often involve small data items that can be
7847 more efficiently manipulated through other means. To start, address verification
7848 (without transferring data) is implemented by the function <i>access_ok</i>, which is
7849 declared in <i><asm/uaccess.h></i>:<br>
7850 <pre>
7851 int access_ok(int type, const void *addr, unsigned long size);
7852 </pre>
7853 The first argument should be either <font class="fixd">VERIFY_READ</font> or <font class="fixd">VERIFY_WRITE</font>, depending on
7854 whether the action to be performed is reading the user-space memory area or writing
7855 it. The <font class="fixd">addr</font> argument holds a user-space address, and <font class="fixd">size</font> is a byte count. If <i>ioctl</i>,
7856 for instance, needs to read an integer value from user space, <font class="fixd">size</font> is <font class="fixd">sizeof(int).</font> If
7857 you need to both read and write at the given address, use <font class="fixd">VERIFY_WRITE</font>, since it is a
7858 superset of <font class="fixd">VERIFY_READ</font>.<br>
7859 <br>
7860 Unlike most kernel functions, <i>access_ok </i>returns a boolean value: <font class="fixd">1</font> for success (access
7861 is OK) and <font class="fixd">0</font> for failure (access is not OK). If it returns false, the driver should usually
7862 return <font class="fixd">-EFAULT</font> to the caller.<br>
7863 <br>
7864 There are a couple of interesting things to note about <i>access_ok</i>. First, it does not do
7865 the complete job of verifying memory access; it only checks to see that the memory
7866 reference is in a region of memory that the process might reasonably have access to.
7867 In particular, <i>access_ok </i>ensures that the address does not point to kernel-space memory.
7868 Second, most driver code need not actually call <i>access_ok</i>. The memory-access
7869 routines described later take care of that for you. Nonetheless, we demonstrate its
7870 use so that you can see how it is done.<br>
7871 <br>
7872 The <i>scull </i>source exploits the bitfields in the <i>ioctl </i>number to check the arguments
7873 before the <font class="fixd">switch:</font><br>
7874 <pre>
7875 int err = 0, tmp;
7876 int retval = 0;
7878 /*
7879 * extract the type and number bitfields, and don't decode
7880 * wrong cmds: return ENOTTY (inappropriate ioctl) before access_ok( )
7881 */
7882 if (_IOC_TYPE(cmd) != SCULL_IOC_MAGIC) return -ENOTTY;
7883 if (_IOC_NR(cmd) > SCULL_IOC_MAXNR) return -ENOTTY;
7885 /*
7886 * the direction is a bitmask, and VERIFY_WRITE catches R/W
7887 * transfers. `Type' is user-oriented, while
7888 </pre>
7889 <A name="143"></a><font color="blue">PAGE 143</font>
7890 <pre>
7891 * access_ok is kernel-oriented, so the concept of "read" and
7892 * "write" is reversed
7893 */
7894 if (_IOC_DIR(cmd) & _IOC_READ)
7895 err = !access_ok(VERIFY_WRITE, (void __user *)arg, _IOC_SIZE(cmd));
7896 else if (_IOC_DIR(cmd) & _IOC_WRITE)
7897 err = !access_ok(VERIFY_READ, (void __user *)arg, _IOC_SIZE(cmd));
7898 if (err) return -EFAULT;
7899 </pre>
7900 After calling <i>access_ok</i>, the driver can safely perform the actual transfer. In addition
7901 to the <i>copy_from_user </i>and <i>copy_to_user </i>functions, the programmer can exploit a set
7902 of functions that are optimized for the most used data sizes (one, two, four, and eight
7903 bytes). These functions are described in the following list and are defined in <i><asm/uaccess.h></i>:<br>
7904 <br>
7905 <font class="fixd">put_user(datum, ptr)<br>
7906 __put_user(datum, ptr)</font><br>
7907 <div class="bq">
7908 These macros write the datum to user space; they are relatively fast and should be
7909 called instead of <i>copy_to_user </i>whenever single values are being transferred. The
7910 macros have been written to allow the passing of any type of pointer to <i>put_user</i>,
7911 as long as it is a user-space address. The size of the data transfer depends on the
7912 type of the <font class="fixd">ptr</font> argument and is determined at compile time using the <font class="fixd">sizeof</font> and
7913 <font class="fixd">typeof</font> compiler builtins. As a result, if <font class="fixd">ptr</font> is a char pointer, one byte is transferred,
7914 and so on for two, four, and possibly eight bytes.<br>
7915 <br>
7916 <i>put_user </i>checks to ensure that the process is able to write to the given memory
7917 address. It returns <font class="fixd">0</font> on success, and <font class="fixd">-EFAULT</font> on error. <i>__put_user </i>performs less
7918 checking (it does not call <i>access_ok</i>), but can still fail if the memory pointed to is
7919 not writable by the user. Thus, <i>__put_user </i>should only be used if the memory
7920 region has already been verified with <i>access_ok</i>.<br>
7921 <br>
7922 As a general rule, you call <i>__put_user </i>to save a few cycles when you are implementing
7923 a <i>read </i>method, or when you copy several items and, thus, call <i>access_ok
7924 </i>just once before the first data transfer, as shown above for <i>ioctl</i>.</div>
7925 <br>
7926 <font class="fixd">get_user(local, ptr)<br>
7927 __get_user(local, ptr)</font><br>
7928 <div class="bq">
7929 These macros are used to retrieve a single datum from user space. They behave
7930 like <i>put_user </i>and <i>__put_user</i>, but transfer data in the opposite direction. The
7931 value retrieved is stored in the local variable <font class="fixd">local;</font> the return value indicates
7932 whether the operation succeeded. Again, <i>__get_user </i>should only be used if the
7933 address has already been verified with <i>access_ok</i>.</div>
7934 <br>
7935 If an attempt is made to use one of the listed functions to transfer a value that does
7936 not fit one of the specific sizes, the result is usually a strange message from the compiler,
7937 such as "conversion to non-scalar type requested." In such cases, <i>copy_to_user
7938 </i>or <i>copy_from_user</i> must be used.<br>
7939 <br>
7940 <A name="144"></a><font color="blue">PAGE 144</font><br>
7941 <br>
7942 <a name="CapabilitiesAndRestrictedOperations"></a><font color="red"><b>Capabilities and Restricted Operations</b></font><br>
7943 <br>
7944 Access to a device is controlled by the permissions on the device file(s), and the driver
7945 is not normally involved in permissions checking. There are situations, however,
7946 where any user is granted read/write permission on the device, but some control operations
7947 should still be denied. For example, not all users of a tape drive should be able
7948 to set its default block size, and a user who has been granted read/write access to a
7949 disk device should probably still be denied the ability to format it. In cases like these,
7950 the driver must perform additional checks to be sure that the user is capable of performing
7951 the requested operation.<br>
7952 <br>
7953 Unix systems have traditionally restricted privileged operations to the superuser
7954 account. This meant that privilege was an all-or-nothing thing--the superuser can do
7955 absolutely anything, but all other users are highly restricted. The Linux kernel provides
7956 a more flexible system called <i>capabilities</i>. A capability-based system leaves the
7957 all-or-nothing mode behind and breaks down privileged operations into separate
7958 subgroups. In this way, a particular user (or program) can be empowered to perform
7959 a specific privileged operation without giving away the ability to perform other, unrelated
7960 operations. The kernel uses capabilities exclusively for permissions management
7961 and exports two system calls <i>capget </i>and <i>capset</i>, to allow them to be managed
7962 from user space.<br>
7963 <br>
7964 The full set of capabilities can be found in <i><linux/capability.h></i>. These are the only
7965 capabilities known to the system; it is not possible for driver authors or system administrators
7966 to define new ones without modifying the kernel source. A subset of those
7967 capabilities that might be of interest to device driver writers includes the following:<br>
7968 <br>
7969 <font class="fixd">CAP_DAC_OVERRIDE</font><br>
7970 <div class="bq">
7971 The ability to override access restrictions (data access control, or DAC) on files
7972 and directories.</div>
7973 <br>
7974 <font class="fixd">CAP_NET_ADMIN</font></div>
7975 <div class="bq">
7976 The ability to perform network administration tasks, including those that affect
7977 network interfaces.</div>
7978 <br>
7979 <font class="fixd">CAP_SYS_MODULE</font></div>
7980 <div class="bq">
7981 The ability to load or remove kernel modules.</div>
7982 <br>
7983 <font class="fixd">CAP_SYS_RAWIO</font></div>
7984 <div class="bq">
7985 The ability to perform "raw" I/O operations. Examples include accessing device
7986 ports or communicating directly with USB devices.</div>
7987 <br>
7988 <font class="fixd">CAP_SYS_ADMIN</font></div>
7989 <div class="bq">
7990 A catch-all capability that provides access to many system administration operations.</div>
7991 <br>
7992 <font class="fixd">CAP_SYS_TTY_CONFIG</font><br>
7993 <div class="bq">
7994 The ability to perform tty configuration tasks.</div>
7995 <br>
7996 <A name="145"></a><font color="blue">PAGE 145</font><br>
7997 <br>
7998 Before performing a privileged operation, a device driver should check that the calling
7999 process has the appropriate capability; failure to do so could result user processes
8000 performing unauthorized operations with bad results on system stability or
8001 security. Capability checks are performed with the <i>capable </i>function (defined in
8002 <i><linux/sched.h></i>):<br>
8003 <pre>
8004 int capable(int capability);
8005 </pre>
8006 In the <i>scull </i>sample driver, any user is allowed to query the quantum and quantum set
8007 sizes. Only privileged users, however, may change those values, since inappropriate
8008 values could badly affect system performance. When needed, the <i>scull </i>implementation
8009 of <i>ioctl</i> checks a user's privilege level as follows:<br>
8010 <pre>
8011 if (! capable (CAP_SYS_ADMIN))
8012 return -EPERM;
8013 </pre>
8014 In the absence of a more specific capability for this task, <font class="fixd">CAP_SYS_ADMIN</font> was chosen
8015 for this test.<br>
8016 <br>
8017 <a name="TheImplementationOfTheIoctlCommands"></a><font color="red"><b>The Implementation of the ioctl Commands</b></font><br>
8018 <br>
8019 The <i>scull </i>implementation of <i>ioctl </i>only transfers the configurable parameters of the
8020 device and turns out to be as easy as the following:<br>
8021 <pre>
8022 switch(cmd) {
8024 case SCULL_IOCRESET:
8025 <font class="fixd">scull_quantum</font> = SCULL_QUANTUM;
8026 <font class="fixd">scull_qset</font> = SCULL_QSET;
8027 break;
8029 case SCULL_IOCSQUANTUM: /* Set: arg points to the value */
8030 if (! capable (CAP_SYS_ADMIN))
8031 return -EPERM;
8032 retval = __get_user(scull_quantum, (int __user *)arg);
8033 break;
8035 case SCULL_IOCTQUANTUM: /* Tell: arg is the value */
8036 if (! capable (CAP_SYS_ADMIN))
8037 return -EPERM;
8038 scull_quantum = arg;
8039 break;
8041 case SCULL_IOCGQUANTUM: /* Get: arg is pointer to result */
8042 retval = __put_user(scull_quantum, (int __user *)arg);
8043 break;
8045 case SCULL_IOCQQUANTUM: /* Query: return it (it's positive) */
8046 return scull_quantum;
8048 case SCULL_IOCXQUANTUM: /* eXchange: use arg as pointer */
8049 if (! capable (CAP_SYS_ADMIN))
8050 </pre>
8051 <A name="146"></a><font color="blue">PAGE 146</font>
8052 <pre>
8053 return -EPERM;
8054 tmp = scull_quantum;
8055 retval = __get_user(scull_quantum, (int __user *)arg);
8056 if (retval = = 0)
8057 retval = __put_user(tmp, (int __user *)arg);
8058 break;
8060 case SCULL_IOCHQUANTUM: /* sHift: like Tell + Query */
8061 if (! capable (CAP_SYS_ADMIN))
8062 return -EPERM;
8063 tmp = scull_quantum;
8064 scull_quantum = arg;
8065 return tmp;
8067 default: /* redundant, as cmd was checked against MAXNR */
8068 return -ENOTTY;
8069 }
8070 return retval;
8071 </pre>
8072 <i>scull </i>also includes six entries that act on <font class="fixd">scull_qset</font>. These entries are identical to the
8073 ones for <font class="fixd">scull_quantum</font> and are not worth showing in print.<br>
8074 <br>
8075 The six ways to pass and receive arguments look like the following from the caller's
8076 point of view (i.e., from user space):<br>
8077 <pre>
8078 int quantum;
8080 ioctl(fd,SCULL_IOCSQUANTUM, &quantum); /* Set by pointer */
8081 ioctl(fd,SCULL_IOCTQUANTUM, quantum); /* Set by value */
8083 ioctl(fd,SCULL_IOCGQUANTUM, &quantum); /* Get by pointer */
8084 quantum = ioctl(fd,SCULL_IOCQQUANTUM); /* Get by return value */
8086 ioctl(fd,SCULL_IOCXQUANTUM, &quantum); /* Exchange by pointer */
8087 quantum = ioctl(fd,SCULL_IOCHQUANTUM, quantum); /* Exchange by value */
8088 </pre>
8089 Of course, a normal driver would not implement such a mix of calling modes. We
8090 have done so here only to demonstrate the different ways in which things could be
8091 done. Normally, however, data exchanges would be consistently performed, either
8092 through pointers or by value, and mixing of the two techniques would be avoided.<br>
8093 <br>
8094 <a name="DeviceControlWithoutIoctl"></a><font color="red"><b>Device Control Without ioctl</b></font><br>
8095 <br>
8096 Sometimes controlling the device is better accomplished by writing control
8097 sequences to the device itself. For example, this technique is used in the console
8098 driver, where so-called escape sequences are used to move the cursor, change the
8099 default color, or perform other configuration tasks. The benefit of implementing
8100 device control this way is that the user can control the device just by writing data,
8101 without needing to use (or sometimes write) programs built just for configuring the
8102 device. When devices can be controlled in this manner, the program issuing commands
8103 often need not even be running on the same system as the device it is controlling.<br>
8104 <br>
8105 <A name="147"></a><font color="blue">PAGE 147</font><br>
8106 <br>
8107 For example, the <i>setterm </i>program acts on the console (or another terminal) configuration
8108 by printing escape sequences. The controlling program can live on a different
8109 computer from the controlled device, because a simple redirection of the data stream
8110 does the configuration job. This is what happens every time you run a remote tty session:
8111 escape sequences are printed remotely but affect the local tty; the technique is
8112 not restricted to ttys, though.<br>
8113 <br>
8114 The drawback of controlling by printing is that it adds policy constraints to the
8115 device; for example, it is viable only if you are sure that the control sequence can't
8116 appear in the data being written to the device during normal operation. This is only
8117 partly true for ttys. Although a text display is meant to display only ASCII characters,
8118 sometimes control characters can slip through in the data being written and
8119 can, therefore, affect the console setup. This can happen, for example, when you <i>cat
8120 </i>a binary file to the screen; the resulting mess can contain anything, and you often
8121 end up with the wrong font on your console.<br>
8122 <br>
8123 Controlling by write <i>is </i>definitely the way to go for those devices that don't transfer
8124 data but just respond to commands, such as robotic devices.<br>
8125 <br>
8126 For instance, a driver written for fun by one of your authors moves a camera on two
8127 axes. In this driver, the "device" is simply a pair of old stepper motors, which can't
8128 really be read from or written to. The concept of "sending a data stream" to a stepper
8129 motor makes little or no sense. In this case, the driver interprets what is being
8130 written as ASCII commands and converts the requests to sequences of impulses that
8131 manipulate the stepper motors. The idea is similar, somewhat, to the AT commands
8132 you send to the modem in order to set up communication, the main difference being
8133 that the serial port used to communicate with the modem must transfer real data as
8134 well. The advantage of direct device control is that you can use <i>cat </i>to move the camera
8135 without writing and compiling special code to issue the <i>ioctl</i> calls.<br>
8136 <br>
8137 When writing command-oriented drivers, there's no reason to implement the <i>ioctl
8138 </i>method. An additional command in the interpreter is easier to implement and use.<br>
8139 <br>
8140 Sometimes, though, you might choose to act the other way around: instead of turning
8141 the <i>write </i>method into an interpreter and avoiding <i>ioctl</i>, you might choose to
8142 avoid <i>write </i>altogether and use <i>ioctl </i>commands exclusively, while accompanying the
8143 driver with a specific command-line tool to send those commands to the driver. This
8144 approach moves the complexity from kernel space to user space, where it may be
8145 easier to deal with, and helps keep the driver small while denying use of simple <i>cat </i>or
8146 <i>echo</i> commands.<br>
8147 <br>
8148 <a name="BlockingIO"></a><font color="red"><b>Blocking I/O</b></font><br>
8149 <br>
8150 Back in Chapter 3, we looked at how to implement the <i>read </i>and <i>write </i>driver methods.
8151 At that point, however, we skipped over one important issue: how does a driver
8152 respond if it cannot immediately satisfy the request? A call to <i>read </i>may come when<br>
8153 <br>
8154 <A name="148"></a><font color="blue">PAGE 148</font><br>
8155 <br>
8156 no data is available, but more is expected in the future. Or a process could attempt to
8157 <i>write</i>, but your device is not ready to accept the data, because your output buffer is
8158 full. The calling process usually does not care about such issues; the programmer
8159 simply expects to call <i>read </i>or <i>write </i>and have the call return after the necessary work
8160 has been done. So, in such cases, your driver should (by default) <i>block </i>the process,
8161 putting it to sleep until the request can proceed.<br>
8162 <br>
8163 This section shows how to put a process to sleep and wake it up again later on. As
8164 usual, however, we have to explain a few concepts first.<br>
8165 <br>
8166 <a name="IntroductionToSleeping"></a><font color="red"><b>Introduction to Sleeping</b></font><br>
8167 <br>
8168 What does it mean for a process to "sleep"? When a process is put to sleep, it is
8169 marked as being in a special state and removed from the scheduler's run queue. Until
8170 something comes along to change that state, the process will not be scheduled on
8171 any CPU and, therefore, will not run. A sleeping process has been shunted off to the
8172 side of the system, waiting for some future event to happen.<br>
8173 <br>
8174 Causing a process to sleep is an easy thing for a Linux device driver to do. There are,
8175 however, a couple of rules that you must keep in mind to be able to code sleeps in a
8176 safe manner.<br>
8177 <br>
8178 The first of these rules is: never sleep when you are running in an atomic context.
8179 We got an introduction to atomic operation in Chapter 5; an atomic context is simply
8180 a state where multiple steps must be performed without any sort of concurrent
8181 access. What that means, with regard to sleeping, is that your driver cannot sleep
8182 while holding a spinlock, seqlock, or RCU lock. You also cannot sleep if you have
8183 disabled interrupts. It <i>is </i>legal to sleep while holding a semaphore, but you should
8184 look very carefully at any code that does so. If code sleeps while holding a semaphore,
8185 any other thread waiting for that semaphore also sleeps. So any sleeps that
8186 happen while holding semaphores should be short, and you should convince yourself
8187 that, by holding the semaphore, you are not blocking the process that will eventually
8188 wake you up.<br>
8189 <br>
8190 Another thing to remember with sleeping is that, when you wake up, you never
8191 know how long your process may have been out of the CPU or what may have
8192 changed in the mean time. You also do not usually know if another process may
8193 have been sleeping for the same event; that process may wake before you and grab
8194 whatever resource you were waiting for. The end result is that you can make no
8195 assumptions about the state of the system after you wake up, and you must check to
8196 ensure that the condition you were waiting for is, indeed, true.<br>
8197 <br>
8198 One other relevant point, of course, is that your process cannot sleep unless it is
8199 assured that somebody else, somewhere, will wake it up. The code doing the awakening
8200 must also be able to find your process to be able to do its job. Making sure that
8201 a wakeup happens is a matter of thinking through your code and knowing, for each<br>
8202 <br>
8203 <A name="149"></a><font color="blue">PAGE 149</font><br>
8204 <br>
8205 sleep, exactly what series of events will bring that sleep to an end. Making it possible
8206 for your sleeping process to be found is, instead, accomplished through a data structure
8207 called a <i>wait queue</i>. A wait queue is just what it sounds like: a list of processes,
8208 all waiting for a specific event.<br>
8209 <br>
8210 In Linux, a wait queue is managed by means of a "wait queue head," a structure of
8211 type <font class="fixd">wait_queue_head_t,</font> which is defined in <i><linux/wait.h></i>. A wait queue head can
8212 be defined and initialized statically with:<br>
8213 <pre>
8214 DECLARE_WAIT_QUEUE_HEAD(name);
8215 </pre>
8216 or dynamically as follows:<br>
8217 <pre>
8218 wait_queue_head_t my_queue;
8219 init_waitqueue_head(&my_queue);
8220 </pre>
8221 We will return to the structure of wait queues shortly, but we know enough now to
8222 take a first look at sleeping and waking up.<br>
8223 <br>
8224 <a name="SimpleSleeping"></a><font color="red"><b>Simple Sleeping</b></font><br>
8225 <br>
8226 When a process sleeps, it does so in expectation that some condition will become
8227 true in the future. As we noted before, any process that sleeps must check to be sure
8228 that the condition it was waiting for is really true when it wakes up again. The simplest
8229 way of sleeping in the Linux kernel is a macro called <i>wait_event </i>(with a few
8230 variants); it combines handling the details of sleeping with a check on the condition
8231 a process is waiting for. The forms of <i>wait_event</i> are:<br>
8232 <pre>
8233 wait_event(queue, condition)
8234 wait_event_interruptible(queue, condition)
8235 wait_event_timeout(queue, condition, timeout)
8236 wait_event_interruptible_timeout(queue, condition, timeout)
8237 </pre>
8238 In all of the above forms, queue is the wait queue head to use. Notice that it is passed
8239 "by value." The <font class="fixd">condition</font> is an arbitrary boolean expression that is evaluated by the
8240 macro before and after sleeping; until <font class="fixd">condition</font> evaluates to a true value, the process
8241 continues to sleep. Note that <font class="fixd">condition</font> may be evaluated an arbitrary number of
8242 times, so it should not have any side effects.<br>
8243 <br>
8244 If you use <i>wait_event</i>, your process is put into an uninterruptible sleep which, as we
8245 have mentioned before, is usually not what you want. The preferred alternative is
8246 <i>wait_event_interruptible</i>, which can be interrupted by signals. This version returns an
8247 integer value that you should check; a nonzero value means your sleep was interrupted
8248 by some sort of signal, and your driver should probably return <font class="fixd">-ERESTARTSYS</font>.
8249 The final versions (<i>wait_event_timeout </i>and <i>wait_event_interruptible_timeout</i>) wait for
8250 a limited time; after that time period (expressed in jiffies, which we will discuss in
8251 Chapter 7) expires, the macros return with a value of 0 regardless of how <font class="fixd">condition</font>
8252 evaluates.<br>
8253 <br>
8254 <A name="150"></a><font color="blue">PAGE 150</font><br>
8255 <br>
8256 The other half of the picture, of course, is waking up. Some other thread of execution
8257 (a different process, or an interrupt handler, perhaps) has to perform the
8258 wakeup for you, since your process is, of course, asleep. The basic function that
8259 wakes up sleeping processes is called <i>wake_up</i>. It comes in several forms (but we
8260 look at only two of them now):<br>
8261 <pre>
8262 void wake_up(wait_queue_head_t *queue);
8263 void wake_up_interruptible(wait_queue_head_t *queue);
8264 </pre>
8265 <i>wake_up </i>wakes up all processes waiting on the given queue (though the situation is a
8266 little more complicated than that, as we will see later). The other form (<i>wake_up_
8267 interruptible</i>) restricts itself to processes performing an interruptible sleep. In general,
8268 the two are indistinguishable (if you are using interruptible sleeps); in practice,
8269 the convention is to use <i>wake_up </i>if you are using <i>wait_event </i>and <i>wake_up_interruptible</i>
8270 if you use <i>wait_event_interruptible</i>.<br>
8271 <br>
8272 We now know enough to look at a simple example of sleeping and waking up. In the
8273 sample source, you can find a module called <i>sleepy</i>. It implements a device with simple
8274 behavior: any process that attempts to read from the device is put to sleep.
8275 Whenever a process writes to the device, all sleeping processes are awakened. This
8276 behavior is implemented with the following <i>read</i> and <i>write</i> methods:<br>
8277 <pre>
8278 static DECLARE_WAIT_QUEUE_HEAD(wq);
8279 static int flag = 0;
8281 ssize_t sleepy_read (struct file *filp, char __user *buf, size_t count, loff_t *pos)
8282 {
8283 printk(KERN_DEBUG "process %i (%s) going to sleep\n",
8284 current->pid, current->comm);
8285 wait_event_interruptible(wq, flag != 0);
8286 flag = 0;
8287 printk(KERN_DEBUG "awoken %i (%s)\n", current->pid, current->comm);
8288 return 0; /* EOF */
8289 }
8291 ssize_t sleepy_write (struct file *filp, const char __user *buf, size_t count,
8292 loff_t *pos)
8293 {
8294 printk(KERN_DEBUG "process %i (%s) awakening the readers...\n",
8295 current->pid, current->comm);
8296 flag = 1;
8297 wake_up_interruptible(&wq);
8298 return count; /* succeed, to avoid retrial */
8299 }
8300 </pre>
8301 Note the use of the <font class="fixd">flag</font> variable in this example. Since <i>wait_event_interruptible
8302 </i>checks for a condition that must become true, we use <font class="fixd">flag</font> to create that condition.<br>
8303 <br>
8304 It is interesting to consider what happens if <i>two </i>processes are waiting when <i>sleepy_write
8305 </i>is called. Since <i>sleepy_read </i>resets <font class="fixd">flag</font> to 0 once it wakes up, you might think that the
8306 second process to wake up would immediately go back to sleep. On a single-processor<br>
8307 <br>
8308 <A name="151"></a><font color="blue">PAGE 151</font><br>
8309 <br>
8310 system, that is almost always what happens. But it is important to understand why you
8311 cannot count on that behavior. The <i>wake_up_interruptible </i>call <i>will </i>cause both sleeping
8312 processes to wake up. It is entirely possible that they will both note that <font class="fixd">flag</font> is nonzero
8313 before either has the opportunity to reset it. For this trivial module, this race condition is
8314 unimportant. In a real driver, this kind of race can create rare crashes that are difficult to
8315 diagnose. If correct operation required that exactly one process see the nonzero value, it
8316 would have to be tested in an atomic manner. We will see how a real driver handles
8317 such situations shortly. But first we have to cover one other topic.<br>
8318 <br>
8319 <a name="BlockingAndNonblockingOperations"></a><font color="red"><b>Blocking and Nonblocking Operations</b></font><br>
8320 <br>
8321 One last point we need to touch on before we look at the implementation of full-featured
8322 <i>read </i>and <i>write </i>methods is deciding when to put a process to sleep. There are
8323 times when implementing proper Unix semantics requires that an operation not
8324 block, even if it cannot be completely carried out.<br>
8325 <br>
8326 There are also times when the calling process informs you that it does not <i>want </i>to
8327 block, whether or not its I/O can make any progress at all. Explicitly nonblocking I/O
8328 is indicated by the <font class="fixd">O_NONBLOCK</font> flag in <font class="fixd">filp->f_flags</font>. The flag is defined in <i><linux/
8329 fcntl.h></i>, which is automatically included by <i><linux/fs.h></i>. The flag gets its name from
8330 "open-nonblock," because it can be specified at open time (and originally could be
8331 specified only there). If you browse the source code, you find some references to an
8332 <font class="fixd">O_NDELAY</font> flag; this is an alternate name for <font class="fixd">O_NONBLOCK,</font> accepted for compatibility
8333 with System V code. The flag is cleared by default, because the normal behavior of a
8334 process waiting for data is just to sleep. In the case of a blocking operation, which is
8335 the default, the following behavior should be implemented in order to adhere to the
8336 standard semantics:<br>
8337 <ul>
8338 <li> If a process calls <i>read </i>but no data is (yet) available, the process must block. The
8339 process is awakened as soon as some data arrives, and that data is returned to
8340 the caller, even if there is less than the amount requested in the count argument
8341 to the method.
8342 <li> If a process calls <i>write </i>and there is no space in the buffer, the process must
8343 block, and it must be on a different wait queue from the one used for reading.
8344 When some data has been written to the hardware device, and space becomes
8345 free in the output buffer, the process is awakened and the <i>write </i>call succeeds,
8346 although the data may be only partially written if there isn't room in the buffer
8347 for the count bytes that were requested.
8348 </ul>
8349 Both these statements assume that there are both input and output buffers; in practice,
8350 almost every device driver has them. The input buffer is required to avoid losing
8351 data that arrives when nobody is reading. In contrast, data can't be lost on <i>write</i>,
8352 because if the system call doesn't accept data bytes, they remain in the user-space
8353 buffer. Even so, the output buffer is almost always useful for squeezing more performance
8354 out of the hardware.<br>
8355 <br>
8356 <A name="152"></a><font color="blue">PAGE 152</font><br>
8357 <br>
8358 The performance gain of implementing an output buffer in the driver results from
8359 the reduced number of context switches and user-level/kernel-level transitions.
8360 Without an output buffer (assuming a slow device), only one or a few characters are
8361 accepted by each system call, and while one process sleeps in <i>write</i>, another process
8362 runs (that's one context switch). When the first process is awakened, it resumes
8363 (another context switch), <i>write </i>returns (kernel/user transition), and the process reiterates
8364 the system call to write more data (user/kernel transition); the call blocks and
8365 the loop continues. The addition of an output buffer allows the driver to accept
8366 larger chunks of data with each <i>write </i>call, with a corresponding increase in performance.
8367 If that buffer is big enough, the <i>write </i>call succeeds on the first attempt--the
8368 buffered data will be pushed out to the device later--without control needing to go
8369 back to user space for a second or third <i>write </i>call. The choice of a suitable size for
8370 the output buffer is clearly device-specific.<br>
8371 <br>
8372 We don't use an input buffer in <i>scull</i>, because data is already available when <i>read </i>is
8373 issued. Similarly, no output buffer is used, because data is simply copied to the memory
8374 area associated with the device. Essentially, the device <i>is </i>a buffer, so the implementation
8375 of additional buffers would be superfluous. We'll see the use of buffers in
8376 Chapter 10.<br>
8377 <br>
8378 The behavior of <i>read </i>and <i>write </i>is different if <font class="fixd">O_NONBLOCK</font> is specified. In this case, the
8379 calls simply return <font class="fixd">-EAGAIN</font> ("try it again") if a process calls <i>read </i>when no data is
8380 available or if it calls <i>write</i> when there's no space in the buffer.<br>
8381 <br>
8382 As you might expect, nonblocking operations return immediately, allowing the
8383 application to poll for data. Applications must be careful when using the <i>stdio </i>functions
8384 while dealing with nonblocking files, because they can easily mistake a nonblocking
8385 return for <font class="fixd">EOF</font>. They always have to check <font class="fixd">errno</font>.<br>
8386 <br>
8387 Naturally, <font class="fixd">O_NONBLOCK</font> is meaningful in the <i>open </i>method also. This happens when the
8388 call can actually block for a long time; for example, when opening (for read access) a
8389 FIFO that has no writers (yet), or accessing a disk file with a pending lock. Usually,
8390 opening a device either succeeds or fails, without the need to wait for external
8391 events. Sometimes, however, opening the device requires a long initialization, and
8392 you may choose to support <font class="fixd">O_NONBLOCK</font> in your <i>open </i>method by returning immediately
8393 with <font class="fixd">-EAGAIN</font> if the flag is set, after starting the device initialization process. The
8394 driver may also implement a blocking <i>open </i>to support access policies in a way similar
8395 to file locks. We'll see one such implementation in the section "Blocking open as
8396 an Alternative to EBUSY" later in this chapter.<br>
8397 <br>
8398 Some drivers may also implement special semantics for <font class="fixd">O_NONBLOCK</font>; for example, an
8399 open of a tape device usually blocks until a tape has been inserted. If the tape drive is
8400 opened with <font class="fixd">O_NONBLOCK</font>, the open succeeds immediately regardless of whether the
8401 media is present or not.<br>
8402 <br>
8403 Only the <i>read</i>, <i>write</i>, and <i>open</i> file operations are affected by the nonblocking flag.<br>
8404 <br>
8405 <A name="153"></a><font color="blue">PAGE 153</font><br>
8406 <br>
8407 <a name="ABlockingIOExample"></a><font color="red"><b>A Blocking I/O Example</b></font><br>
8408 <br>
8409 Finally, we get to an example of a real driver method that implements blocking I/O.
8410 This example is taken from the <i>scullpipe </i>driver; it is a special form of <i>scull </i>that implements
8411 a pipe-like device.<br>
8412 <br>
8413 Within a driver, a process blocked in a <i>read </i>call is awakened when data arrives; usually
8414 the hardware issues an interrupt to signal such an event, and the driver awakens
8415 waiting processes as part of handling the interrupt. The <i>scullpipe </i>driver works differently,
8416 so that it can be run without requiring any particular hardware or an interrupt
8417 handler. We chose to use another process to generate the data and wake the reading
8418 process; similarly, reading processes are used to wake writer processes that are waiting
8419 for buffer space to become available.<br>
8420 <br>
8421 The device driver uses a device structure that contains two wait queues and a buffer.
8422 The size of the buffer is configurable in the usual ways (at compile time, load time, or
8423 runtime).<br>
8424 <pre>
8425 struct scull_pipe {
8426 wait_queue_head_t inq, outq; /* read and write queues */
8427 char *buffer, *end; /* begin of buf, end of buf */
8428 int buffersize; /* used in pointer arithmetic */
8429 char *rp, *wp; /* where to read, where to write */
8430 int nreaders, nwriters; /* number of openings for r/w */
8431 struct fasync_struct *async_queue; /* asynchronous readers */
8432 struct semaphore sem; /* mutual exclusion semaphore */
8433 struct cdev cdev; /* Char device structure */
8434 };
8435 </pre>
8436 The <i>read </i>implementation manages both blocking and nonblocking input and looks
8437 like this:<br>
8438 <pre>
8439 static ssize_t scull_p_read (struct file *filp, char __user *buf, size_t count,
8440 loff_t *f_pos)
8441 {
8442 struct scull_pipe *dev = filp->private_data;
8444 if (down_interruptible(&dev->sem))
8445 return -ERESTARTSYS;
8447 while (dev->rp = = dev->wp) { /* nothing to read */
8448 up(&dev->sem); /* release the lock */
8449 if (filp->f_flags & O_NONBLOCK)
8450 return -EAGAIN;
8451 PDEBUG("\"%s\" reading: going to sleep\n", current->comm);
8452 if (wait_event_interruptible(dev->inq, (dev->rp != dev->wp)))
8453 return -ERESTARTSYS; /* signal: tell the fs layer to handle it */
8454 /* otherwise loop, but first reacquire the lock */
8455 if (down_interruptible(&dev->sem))
8456 return -ERESTARTSYS;
8457 }
8458 /* ok, data is there, return something */
8459 </pre>
8460 <A name="154"></a><font color="blue">PAGE 154</font><br>
8461 <pre>
8462 if (dev->wp > dev->rp)
8463 count = min(count, (size_t)(dev->wp - dev->rp));
8464 else /* the write pointer has wrapped, return data up to dev->end */
8465 count = min(count, (size_t)(dev->end - dev->rp));
8466 if (copy_to_user(buf, dev->rp, count)) {
8467 up (&dev->sem);
8468 return -EFAULT;
8469 }
8470 dev->rp += count;
8471 if (dev->rp = = dev->end)
8472 dev->rp = dev->buffer; /* wrapped */
8473 up (&dev->sem);
8475 /* finally, awake any writers and return */
8476 wake_up_interruptible(&dev->outq);
8477 PDEBUG("\"%s\" did read %li bytes\n",current->comm, (long)count);
8478 return count;
8479 }
8480 </pre>
8481 As you can see, we left some <font class="fixd">PDEBUG</font> statements in the code. When you compile the
8482 driver, you can enable messaging to make it easier to follow the interaction of different
8483 processes.<br>
8484 <br>
8485 Let us look carefully at how <i>scull_p_read </i>handles waiting for data. The <font class="fixd">while</font> loop
8486 tests the buffer with the device semaphore held. If there is data there, we know we
8487 can return it to the user immediately without sleeping, so the entire body of the loop
8488 is skipped. If, instead, the buffer is empty, we must sleep. Before we can do that,
8489 however, we must drop the device semaphore; if we were to sleep holding it, no
8490 writer would ever have the opportunity to wake us up. Once the semaphore has been
8491 dropped, we make a quick check to see if the user has requested non-blocking I/O,
8492 and return if so. Otherwise, it is time to call <i>wait_event_interruptible</i>.<br>
8493 <br>
8494 Once we get past that call, something has woken us up, but we do not know what.
8495 One possibility is that the process received a signal. The if statement that contains
8496 the <i>wait_event_interruptible </i>call checks for this case. This statement ensures the
8497 proper and expected reaction to signals, which could have been responsible for waking
8498 up the process (since we were in an interruptible sleep). If a signal has arrived
8499 and it has not been blocked by the process, the proper behavior is to let upper layers
8500 of the kernel handle the event. To this end, the driver returns <font class="fixd">-ERESTARTSYS</font> to the
8501 caller; this value is used internally by the virtual filesystem (VFS) layer, which either
8502 restarts the system call or returns <font class="fixd">-EINTR</font> to user space. We use the same type of
8503 check to deal with signal handling for every <i>read</i> and <i>write</i> implementation.<br>
8504 <br>
8505 However, even in the absence of a signal, we do not yet know for sure that there is
8506 data there for the taking. Somebody else could have been waiting for data as well,
8507 and they might win the race and get the data first. So we must acquire the device
8508 semaphore again; only then can we test the read buffer again (in the <font class="fixd">while</font> loop) and
8509 truly know that we can return the data in the buffer to the user. The end result of all<br>
8510 <br>
8511 <A name="155"></a><font color="blue">PAGE 155</font><br>
8512 <br>
8513 this code is that, when we exit from the <font class="fixd">while</font> loop, we know that the semaphore is
8514 held and the buffer contains data that we can use.<br>
8515 <br>
8516 Just for completeness, let us note that <i>scull_p_read </i>can sleep in another spot after we
8517 take the device semaphore: the call to <i>copy_to_user</i>. If <i>scull </i>sleeps while copying data
8518 between kernel and user space, it sleeps with the device semaphore held. Holding the
8519 semaphore in this case is justified since it does not deadlock the system (we know
8520 that the kernel will perform the copy to user space and wakes us up without trying to
8521 lock the same semaphore in the process), and since it is important that the device
8522 memory array not change while the driver sleeps.<br>
8523 <br>
8524 <a name="AdvancedSleeping"></a><font color="red"><b>Advanced Sleeping</b></font><br>
8525 <br>
8526 Many drivers are able to meet their sleeping requirements with the functions we have
8527 covered so far. There are situations, however, that call for a deeper understanding of
8528 how the Linux wait queue mechanism works. Complex locking or performance
8529 requirements can force a driver to use lower-level functions to effect a sleep. In this
8530 section, we look at the lower level to get an understanding of what is really going on
8531 when a process sleeps.<br>
8532 <br>
8533 <a name="HowAProcessSleeps"></a><font color="red"><b>How a process sleeps</b></font><br>
8534 <br>
8535 If you look inside <i><linux/wait.h></i>, you see that the data structure behind
8536 the <font class="fixd">wait_queue_head_t</font> type is quite simple; it consists of a spinlock and a linked list. What goes
8537 on to that list is a wait queue entry, which is declared with the type <font class="fixd">wait_queue_t</font>. This
8538 structure contains information about the sleeping process and exactly how it would
8539 like to be woken up.<br>
8540 <br>
8541 The first step in putting a process to sleep is usually the allocation and initialization
8542 of a <font class="fixd">wait_queue_t</font> structure, followed by its addition to the proper wait queue. When
8543 everything is in place, whoever is charged with doing the wakeup will be able to find
8544 the right processes.<br>
8545 <br>
8546 The next step is to set the state of the process to mark it as being asleep. There are several
8547 task states defined in <i><linux/sched.h></i>. <font class="fixd">TASK_RUNNING</font> means that the process is able
8548 to run, although it is not necessarily executing in the processor at any specific moment.
8549 There are two states that indicate that a process is asleep: <font class="fixd">TASK_INTERRUPTIBLE</font> and
8550 <font class="fixd">TASK_UNINTERRUPTIBLE;</font> they correspond, of course, to the two types of sleep. The other
8551 states are not normally of concern to driver writers.<br>
8552 <br>
8553 In the 2.6 kernel, it is not normally necessary for driver code to manipulate the process
8554 state directly. However, should you need to do so, the call to use is:<br>
8555 <pre>
8556 void set_current_state(int new_state);
8557 </pre>
8558 In older code, you often see something like this instead:<br>
8559 <pre>
8560 current->state = TASK_INTERRUPTIBLE;
8561 </pre>
8562 <A name="156"></a><font color="blue">PAGE 156</font><br>
8563 <br>
8564 But changing current directly in that manner is discouraged; such code breaks easily
8565 when data structures change. The above code does show, however, that changing the
8566 current state of a process does not, by itself, put it to sleep. By changing the current
8567 state, you have changed the way the scheduler treats a process, but you have not yet
8568 yielded the processor.<br>
8569 <br>
8570 Giving up the processor is the final step, but there is one thing to do first: you must
8571 check the condition you are sleeping for first. Failure to do this check invites a race
8572 condition; what happens if the condition came true while you were engaged in the
8573 above process, and some other thread has just tried to wake you up? You could miss
8574 the wakeup altogether and sleep longer than you had intended. Consequently, down
8575 inside code that sleeps, you typically see something such as:<br>
8576 <pre>
8577 if (!condition)
8578 schedule( );
8579 </pre>
8580 By checking our condition <i>after </i>setting the process state, we are covered against all
8581 possible sequences of events. If the condition we are waiting for had come about
8582 before setting the process state, we notice in this check and not actually sleep. If the
8583 wakeup happens thereafter, the process is made runnable whether or not we have
8584 actually gone to sleep yet.<br>
8585 <br>
8586 The call to <i>schedule </i>is, of course, the way to invoke the scheduler and yield the CPU.
8587 Whenever you call this function, you are telling the kernel to consider which process
8588 should be running and to switch control to that process if necessary. So you never
8589 know how long it will be before <i>schedule</i> returns to your code.<br>
8590 <br>
8591 After the <font class="fixd">if test</font> and possible call to (and return from) <i>schedule</i>, there is some
8592 cleanup to be done. Since the code no longer intends to sleep, it must ensure that the
8593 task state is reset to <font class="fixd">TASK_RUNNING</font>. If the code just returned from <i>schedule</i>, this step is
8594 unnecessary; that function does not return until the process is in a runnable state.
8595 But if the call to <i>schedule </i>was skipped because it was no longer necessary to sleep,
8596 the process state will be incorrect. It is also necessary to remove the process from the
8597 wait queue, or it may be awakened more than once.<br>
8598 <br>
8599 <a name="ManualSleeps"></a><font color="red"><b>Manual sleeps</b></font><br>
8600 <br>
8601 In previous versions of the Linux kernel, nontrivial sleeps required the programmer
8602 to handle all of the above steps manually. It was a tedious process involving a fair
8603 amount of error-prone boilerplate code. Programmers can still code a manual sleep
8604 in that manner if they want to; <i><linux/sched.h> </i>contains all the requisite definitions,
8605 and the kernel source abounds with examples. There is an easier way, however.<br>
8606 <br>
8607 The first step is the creation and initialization of a wait queue entry. That is usually
8608 done with this macro:<br>
8609 <pre>
8610 DEFINE_WAIT(my_wait);
8611 </pre>
8612 <A name="157"></a><font color="blue">PAGE 157</font><br>
8613 <br>
8614 in which name is the name of the wait queue entry variable. You can also do things in
8615 two steps:<br>
8616 <pre>
8617 wait_queue_t my_wait;
8618 init_wait(&my_wait);
8619 </pre>
8620 But it is usually easier to put a <font class="fixd">DEFINE_WAIT</font> line at the top of the loop that implements
8621 your sleep.<br>
8622 <br>
8623 The next step is to add your wait queue entry to the queue, and set the process state.
8624 Both of those tasks are handled by this function:<br>
8625 <pre>
8626 void prepare_to_wait(wait_queue_head_t *queue,
8627 wait_queue_t *wait,
8628 int state);
8629 </pre>
8630 Here, <font class="fixd">queue</font> and <font class="fixd">wait</font> are the wait queue head and the process entry, respectively.
8631 <font class="fixd">state</font> is the new state for the process; it should be either <font class="fixd">TASK_INTERRUPTIBLE</font> (for
8632 interruptible sleeps, which is usually what you want) or <font class="fixd">TASK_UNINTERRUPTIBLE</font> (for
8633 uninterruptible sleeps).<br>
8634 <br>
8635 After calling <i>prepare_to_wait</i>, the process can call <i>schedule</i>--after it has checked to
8636 be sure it still needs to wait. Once <i>schedule </i>returns, it is cleanup time. That task, too,
8637 is handled by a special function:<br>
8638 <pre>
8639 void finish_wait(wait_queue_head_t *queue, wait_queue_t *wait);
8640 </pre>
8641 Thereafter, your code can test its state and see if it needs to wait again.<br>
8642 <br>
8643 We are far past due for an example. Previously we looked at the <i>read </i>method for
8644 <i>scullpipe</i>, which uses <i>wait_event</i>. The <i>write </i>method in the same driver does its waiting
8645 with <i>prepare_to_wait </i>and <i>finish_wait</i>, instead. Normally you would not mix
8646 methods within a single driver in this way, but we did so in order to be able to show
8647 both ways of handling sleeps.<br>
8648 <br>
8649 First, for completeness, let's look at the <i>write</i> method itself:<br>
8650 <pre>
8651 /* How much space is free? */
8652 static int spacefree(struct scull_pipe *dev)
8653 {
8654 if (dev->rp = = dev->wp)
8655 return dev->buffersize - 1;
8656 return ((dev->rp + dev->buffersize - dev->wp) % dev->buffersize) - 1;
8657 }
8659 static ssize_t scull_p_write(struct file *filp, const char __user *buf, size_t count,
8660 loff_t *f_pos)
8661 {
8662 struct scull_pipe *dev = filp->private_data;
8663 int result;
8665 if (down_interruptible(&dev->sem))
8666 return -ERESTARTSYS;
8667 </pre>
8668 <A name="158"></a><font color="blue">PAGE 158</font><br>
8669 <pre>
8670 /* Make sure there's space to write */
8671 result = scull_getwritespace(dev, filp);
8672 if (result)
8673 return result; /* scull_getwritespace called up(&dev->sem) */
8675 /* ok, space is there, accept something */
8676 count = min(count, (size_t)spacefree(dev));
8677 if (dev->wp >= dev->rp)
8678 count = min(count, (size_t)(dev->end - dev->wp)); /* to end-of-buf */
8679 else /* the write pointer has wrapped, fill up to rp-1 */
8680 count = min(count, (size_t)(dev->rp - dev->wp - 1));
8681 PDEBUG("Going to accept %li bytes to %p from %p\n", (long)count, dev->wp, buf);
8682 if (copy_from_user(dev->wp, buf, count)) {
8683 up (&dev->sem);
8684 return -EFAULT;
8685 }
8686 dev->wp += count;
8687 if (dev->wp = = dev->end)
8688 dev->wp = dev->buffer; /* wrapped */
8689 up(&dev->sem);
8691 /* finally, awake any reader */
8692 wake_up_interruptible(&dev->inq); /* blocked in read( ) and select( ) */
8694 /* and signal asynchronous readers, explained late in chapter 5 */
8695 if (dev->async_queue)
8696 kill_fasync(&dev->async_queue, SIGIO, POLL_IN);
8697 PDEBUG("\"%s\" did write %li bytes\n",current->comm, (long)count);
8698 return count;
8699 }
8700 </pre>
8701 This code looks similar to the <i>read </i>method, except that we have pushed the code
8702 that sleeps into a separate function called <i>scull_getwritespace</i>. Its job is to ensure that
8703 there is space in the buffer for new data, sleeping if need be until that space comes
8704 available. Once the space is there, <i>scull_p_write </i>can simply copy the user's data
8705 there, adjust the pointers, and wake up any processes that may have been waiting to
8706 read data.<br>
8707 <br>
8708 The code that handles the actual sleep is:<br>
8709 <pre>
8710 /* Wait for space for writing; caller must hold device semaphore. On
8711 * error the semaphore will be released before returning. */
8712 static int scull_getwritespace(struct scull_pipe *dev, struct file *filp)
8713 {
8714 while (spacefree(dev) = = 0) { /* full */
8715 DEFINE_WAIT(wait);
8717 up(&dev->sem);
8718 if (filp->f_flags & O_NONBLOCK)
8719 return -EAGAIN;
8720 </pre>
8721 <A name="159"></a><font color="blue">PAGE 159</font><br>
8722 <pre>
8723 PDEBUG("\"%s\" writing: going to sleep\n",current->comm);
8724 prepare_to_wait(&dev->outq, &wait, TASK_INTERRUPTIBLE);
8725 if (spacefree(dev) = = 0)
8726 schedule( );
8727 finish_wait(&dev->outq, &wait);
8728 if (signal_pending(current))
8729 return -ERESTARTSYS; /* signal: tell the fs layer to handle it */
8730 if (down_interruptible(&dev->sem))
8731 return -ERESTARTSYS;
8732 }
8733 return 0;
8734 }
8735 </pre>
8736 Note once again the containing <font class="fixd">while</font> loop. If space is available without sleeping, this
8737 function simply returns. Otherwise, it must drop the device semaphore and wait.
8738 The code uses <i><font class="fixd">DEFINE_WAIT</font> </i>to set up a wait queue entry and <i>prepare_to_wait </i>to
8739 get ready for the actual sleep. Then comes the obligatory check on the buffer; we
8740 must handle the case in which space becomes available in the buffer after we have
8741 entered the <font class="fixd">while</font> loop (and dropped the semaphore) but before we put ourselves
8742 onto the wait queue. Without that check, if the reader processes were able to completely
8743 empty the buffer in that time, we could miss the only wakeup we would ever
8744 get and sleep forever. Having satisfied ourselves that we must sleep, we can call
8745 <i>schedule</i>.<br>
8746 <br>
8747 It is worth looking again at this case: what happens if the wakeup happens between
8748 the test in the <font class="fixd">if</font> statement and the call to <i>schedule</i>? In that case, all is well. The
8749 wakeup resets the process state to <font class="fixd">TASK_RUNNING</font> and <i>schedule </i>returns--although not
8750 necessarily right away. As long as the test happens after the process has put itself on
8751 the wait queue and changed its state, things will work.<br>
8752 <br>
8753 To finish up, we call <i>finish_wait</i>. The call to <i>signal_pending </i>tells us whether we were
8754 awakened by a signal; if so, we need to return to the user and let them try again later.
8755 Otherwise, we reacquire the semaphore, and test again for free space as usual.<br>
8756 <br>
8757 <a name="ExclusiveWaits"></a><font color="red"><b>Exclusive waits</b></font><br>
8758 <br>
8759 We have seen that when a process calls <i>wake_up </i>on a wait queue, all processes waiting
8760 on that queue are made runnable. In many cases, that is the correct behavior. In
8761 others, however, it is possible to know ahead of time that only one of the processes
8762 being awakened will succeed in obtaining the desired resource, and the rest will simply
8763 have to sleep again. Each one of those processes, however, has to obtain the processor,
8764 contend for the resource (and any governing locks), and explicitly go back to
8765 sleep. If the number of processes in the wait queue is large, this "thundering herd"
8766 behavior can seriously degrade the performance of the system.<br>
8767 <br>
8768 <A name="160"></a><font color="blue">PAGE 160</font><br>
8769 <br>
8770 In response to real-world thundering herd problems, the kernel developers added an
8771 "exclusive wait" option to the kernel. An exclusive wait acts very much like a normal
8772 sleep, with two important differences:<br>
8773 <ul>
8774 <li> When a wait queue entry has the <font class="fixd">WQ_FLAG_EXCLUSIVE</font> flag set, it is added to the end
8775 of the wait queue. Entries without that flag are, instead, added to the beginning.
8776 <li> When <i>wake_up </i>is called on a wait queue, it stops after waking the first process
8777 that has the <font class="fixd">WQ_FLAG_EXCLUSIVE</font> flag set.
8778 </ul>
8779 The end result is that processes performing exclusive waits are awakened one at a
8780 time, in an orderly manner, and do not create thundering herds. The kernel still
8781 wakes up all nonexclusive waiters every time, however.<br>
8782 <br>
8783 Employing exclusive waits within a driver is worth considering if two conditions are
8784 met: you expect significant contention for a resource, and waking a single process is
8785 sufficient to completely consume the resource when it becomes available. Exclusive
8786 waits work well for the Apache web server, for example; when a new connection
8787 comes in, exactly one of the (often many) Apache processes on the system should
8788 wake up to deal with it. We did not use exclusive waits in the <i>scullpipe </i>driver, however;
8789 it is rare to see readers contending for data (or writers for buffer space), and we
8790 cannot know that one reader, once awakened, will consume all of the available data.<br>
8791 <br>
8792 Putting a process into an interruptible wait is a simple matter of calling <i>prepare_to_
8793 wait_exclusive</i>:<br>
8794 <pre>
8795 void prepare_to_wait_exclusive(wait_queue_head_t *queue,
8796 wait_queue_t *wait,
8797 int state);
8798 </pre>
8799 This call, when used in place of <i>prepare_to_wait</i>, sets the "exclusive" flag in the wait
8800 queue entry and adds the process to the end of the wait queue. Note that there is no
8801 way to perform exclusive waits with <i>wait_event</i> and its variants.<br>
8802 <br>
8803 <a name="TheDetailsOfWakingUp"></a><font color="red"><b>The details of waking up</b></font><br>
8804 <br>
8805 The view we have presented of the wakeup process is simpler than what really happens
8806 inside the kernel. The actual behavior that results when a process is awakened
8807 is controlled by a function in the wait queue entry. The default wakeup function* sets
8808 the process into a runnable state and, possibly, performs a context switch to that
8809 process if it has a higher priority. Device drivers should never need to supply a different
8810 wake function; should yours prove to be the exception, see <i><linux/wait.h> </i>for
8811 information on how to do it.<br>
8812 <br>
8813 * It has the imaginative name <i>default_wake_function</i>.<br>
8814 <br>
8815 <A name="161"></a><font color="blue">PAGE 161</font><br>
8816 <br>
8817 We have not yet seen all the variations of <i>wake_up</i>. Most driver writers never need
8818 the others, but, for completeness, here is the full set:<br>
8819 <br>
8820 <font class="fixd">wake_up(wait_queue_head_t *queue);<br>
8821 wake_up_interruptible(wait_queue_head_t *queue);</font><br>
8822 <div class="bq">
8823 <i>wake_up </i>awakens every process on the queue that is not in an exclusive wait,
8824 and exactly one exclusive waiter, if it exists. <i>wake_up_interruptible </i>does the
8825 same, with the exception that it skips over processes in an uninterruptible sleep.
8826 These functions can, before returning, cause one or more of the processes awakened
8827 to be scheduled (although this does not happen if they are called from an
8828 atomic context).</div>
8829 <br>
8830 <font class="fixd">wake_up_nr(wait_queue_head_t *queue, int nr);<br>
8831 wake_up_interruptible_nr(wait_queue_head_t *queue, int nr);</font><br>
8832 <div class="bq">
8833 These functions perform similarly to <i>wake_up</i>, except they can awaken up to <font class="fixd">nr</font>
8834 exclusive waiters, instead of just one. Note that passing 0 is interpreted as asking
8835 for <i>all</i> of the exclusive waiters to be awakened, rather than none of them.</div>
8836 <br>
8837 <font class="fixd">wake_up_all(wait_queue_head_t *queue);<br>
8838 wake_up_interruptible_all(wait_queue_head_t *queue);</font><br>
8839 <div class="bq">
8840 This form of <i>wake_up </i>awakens all processes whether they are performing an
8841 exclusive wait or not (though the interruptible form still skips processes doing
8842 uninterruptible waits).</div>
8843 <br>
8844 <font class="fixd">wake_up_interruptible_sync(wait_queue_head_t *queue);</font><br>
8845 <div class="bq">
8846 Normally, a process that is awakened may preempt the current process and be
8847 scheduled into the processor before <i>wake_up </i>returns. In other words, a call to
8848 <i>wake_up </i>may not be atomic. If the process calling <i>wake_up </i>is running in an
8849 atomic context (it holds a spinlock, for example, or is an interrupt handler), this
8850 rescheduling does not happen. Normally, that protection is adequate. If, however,
8851 you need to explicitly ask to not be scheduled out of the processor at this
8852 time, you can use the "sync" variant of <i>wake_up_interruptible</i>. This function is
8853 most often used when the caller is about to reschedule anyway, and it is more
8854 efficient to simply finish what little work remains first.</div>
8855 <br>
8856 If all of the above is not entirely clear on a first reading, don't worry. Very few drivers
8857 ever need to call anything except <i>wake_up_interruptible</i>.<br>
8858 <br>
8859 <a name="AncientHistorySleepon"></a><font color="red"><b>Ancient history: sleep_on</b></font><br>
8860 <br>
8861 If you spend any time digging through the kernel source, you will likely encounter
8862 two functions that we have neglected to discuss so far:<br>
8863 <pre>
8864 void sleep_on(wait_queue_head_t *queue);
8865 void interruptible_sleep_on(wait_queue_head_t *queue);
8866 </pre>
8867 As you might expect, these functions unconditionally put the current process to
8868 sleep on the given <font class="fixd">queue</font>. These functions are strongly deprecated, however, and you<br>
8869 <br>
8870 <A name="162"></a><font color="blue">PAGE 162</font><br>
8871 <br>
8872 should never use them. The problem is obvious if you think about it: <i>sleep_on </i>offers
8873 no way to protect against race conditions. There is always a window between when
8874 your code decides it must sleep and when <i>sleep_on </i>actually effects that sleep. A
8875 wakeup that arrives during that window is missed. For this reason, code that calls
8876 <i>sleep_on</i> is never entirely safe.<br>
8877 <br>
8878 Current plans call for <i>sleep_on </i>and its variants (there are a couple of time-out forms
8879 we haven't shown) to be removed from the kernel in the not-too-distant future.<br>
8880 <br>
8881 <a name="TestingTheScullpipeDriver"></a><font color="red"><b>Testing the Scullpipe Driver</b></font><br>
8882 <br>
8883 We have seen how the <i>scullpipe </i>driver implements blocking I/O. If you wish to try it
8884 out, the source to this driver can be found with the rest of the book examples. Blocking
8885 I/O in action can be seen by opening two windows. The first can run a command such
8886 as <font class="fixd">cat /dev/scullpipe.</font> If you then, in another window, copy a file to <i>/dev/scullpipe</i>, you
8887 should see that file's contents appear in the first window.<br>
8888 <br>
8889 Testing nonblocking activity is trickier, because the conventional programs available
8890 to a shell don't perform nonblocking operations. The <i>misc-progs </i>source directory
8891 contains the following simple program, called <i>nbtest</i>, for testing nonblocking operations.
8892 All it does is copy its input to its output, using nonblocking I/O and delaying
8893 between retries. The delay time is passed on the command line and is one second by
8894 default.<br>
8895 <pre>
8896 int main(int argc, char **argv)
8897 {
8898 int delay = 1, n, m = 0;
8900 if (argc > 1)
8901 delay=atoi(argv[1]);
8902 fcntl(0, F_SETFL, fcntl(0,F_GETFL) | O_NONBLOCK); /* stdin */
8903 fcntl(1, F_SETFL, fcntl(1,F_GETFL) | O_NONBLOCK); /* stdout */
8905 while (1) {
8906 n = read(0, buffer, 4096);
8907 if (n >= 0)
8908 m = write(1, buffer, n);
8909 if ((n < 0 || m < 0) && (errno != EAGAIN))
8910 break;
8911 sleep(delay);
8912 }
8913 perror(n < 0 ? "stdin" : "stdout");
8914 exit(1);
8915 }
8916 </pre>
8917 If you run this program under a process tracing utility such as <i>strace</i>, you can see the
8918 success or failure of each operation, depending on whether data is available when the
8919 operation is tried.<br>
8920 <br>
8921 <A name="163"></a><font color="blue">PAGE 163</font><br>
8922 <br>
8923 <a name="PollAndSelect"></a><font color="red"><b>poll and select</b></font><br>
8924 <br>
8925 Applications that use nonblocking I/O often use the <i>poll</i>, <i>select</i>, and <i>epoll </i>system
8926 calls as well. <i>poll</i>, <i>select</i>, and <i>epoll </i>have essentially the same functionality: each allow
8927 a process to determine whether it can read from or write to one or more open files
8928 without blocking. These calls can also block a process until any of a given set of file
8929 descriptors becomes available for reading or writing. Therefore, they are often used
8930 in applications that must use multiple input or output streams without getting stuck
8931 on any one of them. The same functionality is offered by multiple functions, because
8932 two were implemented in Unix almost at the same time by two different groups:
8933 <i>select </i>was introduced in BSD Unix, whereas <i>poll </i>was the System V solution. The <i>epoll
8934 </i>call* was added in 2.5.45 as a way of making the polling function scale to thousands
8935 of file descriptors.<br>
8936 <br>
8937 Support for any of these calls requires support from the device driver. This support
8938 (for all three calls) is provided through the driver's <i>poll </i>method. This method has the
8939 following prototype:<br>
8940 <pre>
8941 unsigned int (*poll) (struct file *filp, poll_table *wait);
8942 </pre>
8943 The driver method is called whenever the user-space program performs a <i>poll</i>, <i>select</i>,
8944 or <i>epoll </i>system call involving a file descriptor associated with the driver. The device
8945 method is in charge of these two steps:<br>
8946 <ol>
8947 <li>Call <i>poll_wait </i>on one or more wait queues that could indicate a change in the
8948 poll status. If no file descriptors are currently available for I/O, the kernel causes
8949 the process to wait on the wait queues for all file descriptors passed to the system call.
8950 <li>Return a bit mask describing the operations (if any) that could be immediately
8951 performed without blocking.
8952 </ol>
8953 Both of these operations are usually straightforward and tend to look very similar
8954 from one driver to the next. They rely, however, on information that only the driver
8955 can provide and, therefore, must be implemented individually by each driver.<br>
8956 <br>
8957 The <font class="fixd">poll_table</font> structure, the second argument to the <i>poll </i>method, is used within the
8958 kernel to implement the <i>poll</i>, <i>select</i>, and <i>epoll </i>calls; it is declared in <i><linux/poll.h></i>,
8959 which must be included by the driver source. Driver writers do not need to know
8960 anything about its internals and must use it as an opaque object; it is passed to the
8961 driver method so that the driver can load it with every wait queue that could wake
8962 up the process and change the status of the <i>poll </i>operation. The driver adds a wait
8963 queue to the <font class="fixd">poll_table</font> structure by calling the function <i>poll_wait</i>:<br>
8964 <pre>
8965 void poll_wait (struct file *, wait_queue_head_t *, poll_table *);
8966 </pre>
8967 * Actually, <i>epoll </i>is a set of three calls that together can be used to achieve the polling functionality. For our
8968 purposes, though, we can think of it as a single call.<br>
8969 <br>
8970 <A name="164"></a><font color="blue">PAGE 164</font><br>
8971 <br>
8972 The second task performed by the <i>poll </i>method is returning the bit mask describing
8973 which operations could be completed immediately; this is also straightforward. For
8974 example, if the device has data available, a <i>read </i>would complete without sleeping;
8975 the <i>poll </i>method should indicate this state of affairs. Several flags (defined via <i><linux/
8976 poll.h></i>) are used to indicate the possible operations:<br>
8977 <br>
8978 <font class="fixd">POLLIN</font><br>
8979 <div class="bq">
8980 This bit must be set if the device can be read without blocking.</div>
8981 <br>
8982 <font class="fixd">POLLRDNORM</font><br>
8983 <div class="bq">
8984 This bit must be set if "normal" data is available for reading. A readable device
8985 returns (<font class="fixd">POLLIN</font> | <font class="fixd">POLLRDNORM</font>).</div>
8986 <br>
8987 <font class="fixd">POLLRDBAND</font><br>
8988 <div class="bq">
8989 This bit indicates that out-of-band data is available for reading from the device.
8990 It is currently used only in one place in the Linux kernel (the DECnet code) and
8991 is not generally applicable to device drivers.</div>
8992 <br>
8993 <font class="fixd">POLLPRI</font><br>
8994 <div class="bq">
8995 High-priority data (out-of-band) can be read without blocking. This bit causes
8996 <i>select </i>to report that an exception condition occurred on the file, because <i>select
8997 </i>reports out-of-band data as an exception condition.</div>
8998 <br>
8999 <font class="fixd">POLLHUP</font><br>
9000 <div class="bq">
9001 When a process reading this device sees end-of-file, the driver must set <font class="fixd">POLLHUP</font>
9002 (hang-up). A process calling <i>select </i>is told that the device is readable, as dictated
9003 by the <i>select</i> functionality.</div>
9004 <br>
9005 <font class="fixd">POLLERR</font><br>
9006 <div class="bq">
9007 An error condition has occurred on the device. When <i>poll </i>is invoked, the device
9008 is reported as both readable and writable, since both <i>read </i>and <i>write </i>return an
9009 error code without blocking.</div>
9010 <br>
9011 <font class="fixd">POLLOUT</font><br>
9012 <div class="bq">
9013 This bit is set in the return value if the device can be written to without blocking.</div>
9014 <br>
9015 <font class="fixd">POLLWRNORM</font><br>
9016 <div class="bq">
9017 This bit has the same meaning as <font class="fixd">POLLOUT,</font> and sometimes it actually is the same number. A writable device returns (<font class="fixd">POLLOUT</font> | <font class="fixd">POLLWRNORM</font>).</div>
9018 <br>
9019 <font class="fixd">POLLWRBAND</font><br>
9020 <div class="bq">
9021 Like <font class="fixd">POLLRDBAND,</font> this bit means that data with nonzero priority can be written to
9022 the device. Only the datagram implementation of <i>poll </i>uses this bit, since a datagram
9023 can transmit out-of-band data.</div>
9024 <br>
9025 It's worth repeating that <font class="fixd">POLLRDBAND</font> and <font class="fixd">POLLWRBAND</font> are meaningful only with file
9026 descriptors associated with sockets: device drivers won't normally use these flags.<br>
9027 <br>
9028 <A name="165"></a><font color="blue">PAGE 165</font><br>
9029 <br>
9030 The description of <i>poll </i>takes up a lot of space for something that is relatively simple
9031 to use in practice. Consider the <i>scullpipe</i> implementation of the <i>poll</i> method:<br>
9032 <pre>
9033 static unsigned int scull_p_poll(struct file *filp, poll_table *wait)
9034 {
9035 struct scull_pipe *dev = filp->private_data;
9036 unsigned int mask = 0;
9038 /*
9039 * The buffer is circular; it is considered full
9040 * if "wp" is right behind "rp" and empty if the
9041 * two are equal.
9042 */
9043 down(&dev->sem);
9044 poll_wait(filp, &dev->inq, wait);
9045 poll_wait(filp, &dev->outq, wait);
9046 if (dev->rp != dev->wp)
9047 mask |= POLLIN | POLLRDNORM; /* readable */
9048 if (spacefree(dev))
9049 mask |= POLLOUT | POLLWRNORM; /* writable */
9050 up(&dev->sem);
9051 return mask;
9052 }
9053 </pre>
9054 This code simply adds the two <i>scullpipe </i>wait queues to the <font class="fixd">poll_table,</font> then sets the
9055 appropriate mask bits depending on whether data can be read or written.<br>
9056 <br>
9057 The <i>poll </i>code as shown is missing end-of-file support, because <i>scullpipe </i>does not
9058 support an end-of-file condition. For most real devices, the <i>poll </i>method should
9059 return <font class="fixd">POLLHUP</font> if no more data is (or will become) available. If the caller used the
9060 <i>select </i>system call, the file is reported as readable. Regardless of whether <i>poll </i>or <i>select
9061 </i>is used, the application knows that it can call <i>read </i>without waiting forever, and the
9062 <i>read</i> method returns, 0 to signal end-of-file.<br>
9063 <br>
9064 With real FIFOs, for example, the reader sees an end-of-file when all the writers close
9065 the file, whereas in <i>scullpipe </i>the reader never sees end-of-file. The behavior is different
9066 because a FIFO is intended to be a communication channel between two processes,
9067 while <i>scullpipe </i>is a trash can where everyone can put data as long as there's at
9068 least one reader. Moreover, it makes no sense to reimplement what is already available
9069 in the kernel, so we chose to implement a different behavior in our example.<br>
9070 <br>
9071 Implementing end-of-file in the same way as FIFOs do would mean checking
9072 <font class="fixd">dev->nwriters,</font> both in <i>read </i>and in <i>poll</i>, and reporting end-of-file (as just described) if no
9073 process has the device opened for writing. Unfortunately, though, with this implementation,
9074 if a reader opened the <i>scullpipe </i>device before the writer, it would see endof-file
9075 without having a chance to wait for data. The best way to fix this problem
9076 would be to implement blocking within <i>open </i>like real FIFOs do; this task is left as an
9077 exercise for the reader.<br>
9078 <br>
9079 <A name="166"></a><font color="blue">PAGE 166</font><br>
9080 <br>
9081 <a name="InteractionWithReadAndWrite"></a><font color="red"><b>Interaction with read and write</b></font><br>
9082 <br>
9083 The purpose of the <i>poll </i>and <i>select </i>calls is to determine in advance if an I/O operation
9084 will block. In that respect, they complement <i>read </i>and <i>write</i>. More important, <i>poll
9085 </i>and <i>select </i>are useful, because they let the application wait simultaneously for several
9086 data streams, although we are not exploiting this feature in the <i>scull</i> examples.<br>
9087 <br>
9088 A correct implementation of the three calls is essential to make applications work
9089 correctly: although the following rules have more or less already been stated, we
9090 summarize them here.<br>
9091 <br>
9092 <a name="ReadingDataFromTheDevice"></a><font color="red"><b>Reading data from the device</b></font><br>
9093 <ul>
9094 <li> If there is data in the input buffer, the <i>read </i>call should return immediately, with
9095 no noticeable delay, even if less data is available than the application requested,
9096 and the driver is sure the remaining data will arrive soon. You can always return
9097 less data than you're asked for if this is convenient for any reason (we did it in
9098 <i>scull</i>), provided you return at least one byte. In this case, <i>poll </i>should return
9099 <font class="fixd">POLLIN|POLLRDNORM.</font>
9100 <li> If there is no data in the input buffer, by default <i>read </i>must block until at least
9101 one byte is there. If <font class="fixd">O_NONBLOCK</font> is set, on the other hand, <i>read </i>returns immediately
9102 with a return value of <font class="fixd">-EAGAIN</font> (although some old versions of System V
9103 return 0 in this case). In these cases, <i>poll </i>must report that the device is unreadable
9104 until at least one byte arrives. As soon as there is some data in the buffer, we
9105 fall back to the previous case.
9106 <li> If we are at end-of-file, <i>read </i>should return immediately with a return value of 0,
9107 independent of <font class="fixd">O_NONBLOCK</font>. <i>poll</i> should report <font class="fixd">POLLHUP</font> in this case.
9108 </ul>
9109 <a name="WritingToTheDevice"></a><font color="red"><b>Writing to the device</b></font>
9110 <ul>
9111 <li> If there is space in the output buffer, <i>write </i>should return without delay. It can
9112 accept less data than the call requested, but it must accept at least one byte. In
9113 this case, <i>poll</i> reports that the device is writable by returning <font class="fixd">POLLOUT|POLLWRNORM.</font>
9114 <li> If the output buffer is full, by default <i>write </i>blocks until some space is freed. If
9115 <font class="fixd">O_NONBLOCK</font> is set, <i>write </i>returns immediately with a return value of <font class="fixd">-EAGAIN</font> (older
9116 System V Unices returned 0). In these cases, <i>poll </i>should report that the file is not
9117 writable. If, on the other hand, the device is not able to accept any more data,
9118 <i>write </i>returns <font class="fixd">-ENOSPC</font> ("No space left on device"), independently of the setting of
9119 <font class="fixd">O_NONBLOCK</font>.
9120 <li> Never make a <i>write </i>call wait for data transmission before returning, even if
9121 <font class="fixd">O_NONBLOCK</font> is clear. This is because many applications use <i>select </i>to find out
9122 whether a <i>write </i>will block. If the device is reported as writable, the call must not
9123 block. If the program using the device wants to ensure that the data it enqueues
9124 </ul>
9125 <A name="167"></a><font color="blue">PAGE 167</font><br>
9126 <ul>
9127 in the output buffer is actually transmitted, the driver must provide an <i>fsync
9128 </i>method. For instance, a removable device should have an <i>fsync</i> entry point.
9129 </ul>
9130 Although this is a good set of general rules, one should also recognize that each
9131 device is unique and that sometimes the rules must be bent slightly. For example,
9132 record-oriented devices (such as tape drives) cannot execute partial writes.<br>
9133 <br>
9134 <a name="FlushingPendingOutput"></a><font color="red"><b>Flushing pending output</b></font><br>
9135 <br>
9136 We've seen how the <i>write </i>method by itself doesn't account for all data output needs.
9137 The <i>fsync </i>function, invoked by the system call of the same name, fills the gap. This
9138 method's prototype is<br>
9139 <pre>
9140 int (*fsync) (struct file *file, struct dentry *dentry, int datasync);
9141 </pre>
9142 If some application ever needs to be assured that data has been sent to the device, the
9143 <i>fsync </i>method must be implemented regardless of whether <font class="fixd">O_NONBLOCK</font> is set. A call to
9144 <i>fsync </i>should return only when the device has been completely flushed (i.e., the output
9145 buffer is empty), even if that takes some time. The datasync argument is used to
9146 distinguish between the <i>fsync </i>and <i>fdatasync </i>system calls; as such, it is only of interest
9147 to filesystem code and can be ignored by drivers.<br>
9148 <br>
9149 The <i>fsync </i>method has no unusual features. The call isn't time critical, so every device
9150 driver can implement it to the author's taste. Most of the time, char drivers just have
9151 a <font class="fixd">NULL</font> pointer in their <font class="fixd">fops</font>. Block devices, on the other hand, always implement the
9152 method with the general-purpose <i>block_fsync</i>, which, in turn, flushes all the blocks
9153 of the device, waiting for I/O to complete.<br>
9154 <br>
9155 <a name="TheUnderlyingDataStructure"></a><font color="red"><b>The Underlying Data Structure</b></font><br>
9156 <br>
9157 The actual implementation of the <i>poll </i>and <i>select </i>system calls is reasonably simple, for
9158 those who are interested in how it works; <i>epoll </i>is a bit more complex but is built on the
9159 same mechanism. Whenever a user application calls <i>poll</i>, <i>select</i>, or <i>epoll_ctl</i>,* the kernel
9160 invokes the <i>poll </i>method of all files referenced by the system call, passing the same
9161 <font class="fixd">poll_table</font> to each of them. The <font class="fixd">poll_table</font> structure is just a wrapper around a function
9162 that builds the actual data structure. That structure, for <i>poll </i>and <i>select</i>, is a linked
9163 list of memory pages containing <font class="fixd">poll_table_entry</font> structures. Each <font class="fixd">poll_table_entry</font>
9164 holds the <font class="fixd">struct file</font> and <font class="fixd">wait_queue_head_t</font> pointers passed to <i>poll_wait</i>, along with
9165 an associated wait queue entry. The call to <i>poll_wait </i>sometimes also adds the process
9166 to the given wait queue. The whole structure must be maintained by the kernel so that
9167 the process can be removed from all of those queues before <i>poll</i> or <i>select</i> returns.<br>
9168 <br>
9169 If none of the drivers being polled indicates that I/O can occur without blocking, the
9170 <i>poll</i> call simply sleeps until one of the (perhaps many) wait queues it is on wakes it up.<br>
9171 <br>
9172 * This is the function that sets up the internal data structure for future calls to <i>epoll_wait</i>.<br>
9173 <br>
9174 <A name="168"></a><font color="blue">PAGE 168</font><br>
9175 <br>
9176 What's interesting in the implementation of <i>poll </i>is that the driver's <i>poll </i>method may
9177 be called with a <font class="fixd">NULL</font> pointer as a <font class="fixd">poll_table</font> argument. This situation can come
9178 about for a couple of reasons. If the application calling <i>poll </i>has provided a timeout
9179 value of 0 (indicating that no wait should be done), there is no reason to accumulate
9180 wait queues, and the system simply does not do it. The <font class="fixd">poll_table</font> pointer is also set
9181 to <font class="fixd">NULL</font> immediately after any driver being <i>poll</i>ed indicates that I/O is possible. Since
9182 the kernel knows at that point that no wait will occur, it does not build up a list of
9183 wait queues.<br>
9184 <br>
9185 When the <i>poll </i>call completes, the <font class="fixd">poll_table</font> structure is deallocated, and all wait
9186 queue entries previously added to the poll table (if any) are removed from the table
9187 and their wait queues.<br>
9188 <br>
9189 We tried to show the data structures involved in polling in Figure 6-1; the figure is
9190 a simplified representation of the real data structures, because it ignores the multipage
9191 nature of a poll table and disregards the file pointer that is part of each
9192 <font class="fixd">poll_table_entry</font>. The reader interested in the actual implementation is urged to
9193 look in <i><linux/poll.h></i> and <i>fs/select.c</i>.<br>
9194 <br><br>
9195 <center>
9196 <img src="fig6-1.gif">
9197 </center>
9198 <br>
9199 <i>Figure 6-1. The data structures behind poll</i><br>
9200 <br>
9201 <A name="169"></a><font color="blue">PAGE 169</font><br>
9202 <br>
9203 At this point, it is possible to understand the motivation behind the new <i>epoll </i>system
9204 call. In a typical case, a call to <i>poll </i>or <i>select </i>involves only a handful of file
9205 descriptors, so the cost of setting up the data structure is small. There are applications
9206 out there, however, that work with thousands of file descriptors. At that point,
9207 setting up and tearing down this data structure between every I/O operation
9208 becomes prohibitively expensive. The <i>epoll </i>system call family allows this sort of
9209 application to set up the internal kernel data structure exactly once and to use it
9210 many times.<br>
9211 <br>
9212 <a name="AsynchronousNotification"></a><font color="red"><b>Asynchronous Notification</b></font><br>
9213 <br>
9214 Although the combination of blocking and nonblocking operations and the <i>select
9215 </i>method are sufficient for querying the device most of the time, some situations aren't
9216 efficiently managed by the techniques we've seen so far.<br>
9217 <br>
9218 Let's imagine a process that executes a long computational loop at low priority but
9219 needs to process incoming data as soon as possible. If this process is responding to
9220 new observations available from some sort of data acquisition peripheral, it would
9221 like to know immediately when new data is available. This application could be written
9222 to call <i>poll </i>regularly to check for data, but, for many situations, there is a better
9223 way. By enabling asynchronous notification, this application can receive a signal
9224 whenever data becomes available and need not concern itself with polling.<br>
9225 <br>
9226 User programs have to execute two steps to enable asynchronous notification from
9227 an input file. First, they specify a process as the "owner" of the file. When a process
9228 invokes the <font class="fixd">F_SETOWN</font> command using the <i>fcntl </i>system call, the process ID of the
9229 owner process is saved in <font class="fixd">filp->f_owner</font> for later use. This step is necessary for the
9230 kernel to know just whom to notify. In order to actually enable asynchronous notification,
9231 the user programs must set the <font class="fixd">FASYNC</font> flag in the device by means of the
9232 <font class="fixd">F_SETFL</font> <i>fcntl</i> command.<br>
9233 <br>
9234 After these two calls have been executed, the input file can request delivery of a <font class="fixd">SIGIO</font>
9235 signal whenever new data arrives. The signal is sent to the process (or process group,
9236 if the value is negative) stored in <font class="fixd">filp->f_owner</font>.<br>
9237 <br>
9238 For example, the following lines of code in a user program enable asynchronous
9239 notification to the current process for the stdin input file:<br>
9240 <pre>
9241 signal(SIGIO, &input_handler); /* dummy sample; sigaction( ) is better */
9242 fcntl(STDIN_FILENO, F_SETOWN, getpid( ));
9243 oflags = fcntl(STDIN_FILENO, F_GETFL);
9244 fcntl(STDIN_FILENO, F_SETFL, oflags | FASYNC);
9245 </pre>
9246 The program named <i>asynctest </i>in the sources is a simple program that reads stdin as
9247 shown. It can be used to test the asynchronous capabilities of <i>scullpipe</i>. The program
9248 is similar to <i>cat </i>but doesn't terminate on end-of-file; it responds only to input, not to
9249 the absence of input.<br>
9250 <br>
9251 <A name="170"></a><font color="blue">PAGE 170</font><br>
9252 <br>
9253 Note, however, that not all the devices support asynchronous notification, and you
9254 can choose not to offer it. Applications usually assume that the asynchronous capability
9255 is available only for sockets and ttys.<br>
9256 <br>
9257 There is one remaining problem with input notification. When a process receives a
9258 <font class="fixd">SIGIO</font>, it doesn't know which input file has new input to offer. If more than one file is
9259 enabled to asynchronously notify the process of pending input, the application must
9260 still resort to <i>poll</i> or <i>select</i> to find out what happened.<br>
9261 <br>
9262 <a name="TheDriversPointOfView"></a><font color="red"><b>The Driver's Point of View</b></font><br>
9263 <br>
9264 A more relevant topic for us is how the device driver can implement asynchronous
9265 signaling. The following list details the sequence of operations from the kernel's
9266 point of view:<br>
9267 <ol>
9268 <li>When <font class="fixd">F_SETOWN</font> is invoked, nothing happens, except that a value is assigned to
9269 <font class="fixd">filp->f_owner</font>.
9270 <li>When <font class="fixd">F_SETFL</font> is executed to turn on <font class="fixd">FASYNC</font>, the driver's <i>fasync </i>method is called.
9271 This method is called whenever the value of <font class="fixd">FASYNC</font> is changed in <font class="fixd">filp->f_flags</font>
9272 to notify the driver of the change, so it can respond properly. The flag is cleared
9273 by default when the file is opened. We'll look at the standard implementation of
9274 the driver method later in this section.
9275 <li>When data arrives, all the processes registered for asynchronous notification
9276 must be sent a <font class="fixd">SIGIO</font> signal.
9277 </ol>
9278 While implementing the first step is trivial--there's nothing to do on the driver's
9279 part--the other steps involve maintaining a dynamic data structure to keep track of
9280 the different asynchronous readers; there might be several. This dynamic data structure,
9281 however, doesn't depend on the particular device involved, and the kernel
9282 offers a suitable general-purpose implementation so that you don't have to rewrite
9283 the same code in every driver.<br>
9284 <br>
9285 The general implementation offered by Linux is based on one data structure and two
9286 functions (which are called in the second and third steps described earlier). The
9287 header that declares related material is <i><linux/fs.h> </i>(nothing new here), and the data
9288 structure is called <font class="fixd">struct fasync_struct</font>. As with wait queues, we need to insert a
9289 pointer to the structure in the device-specific data structure.<br>
9290 <br>
9291 The two functions that the driver calls correspond to the following prototypes:<br>
9292 <pre>
9293 int fasync_helper(int fd, struct file *filp,
9294 int mode, struct fasync_struct **fa);
9295 void kill_fasync(struct fasync_struct **fa, int sig, int band);
9296 </pre>
9297 <font class="fixd">fasync_helper</font> is invoked to add or remove entries from the list of interested processes
9298 when the <font class="fixd">FASYNC</font> flag changes for an open file. All of its arguments except the last are
9299 provided to the <i>fasync </i>method and can be passed through directly. <font class="fixd">kill_fasync</font> is used<br>
9300 <br>
9301 <A name="171"></a><font color="blue">PAGE 171</font><br>
9302 <br>
9303 to signal the interested processes when data arrives. Its arguments are the signal to
9304 send (usually <font class="fixd">SIGIO</font>) and the band, which is almost always <font class="fixd">POLL_IN*</font> (but that may be
9305 used to send "urgent" or out-of-band data in the networking code).<br>
9306 <br>
9307 Here's how <i>scullpipe</i> implements the <i>fasync</i> method:<br>
9308 <pre>
9309 static int scull_p_fasync(int fd, struct file *filp, int mode)
9310 {
9311 struct scull_pipe *dev = filp->private_data;
9313 return fasync_helper(fd, filp, mode, &dev->async_queue);
9314 }
9315 </pre>
9316 It's clear that all the work is performed by <i>fasync_helper</i>. It wouldn't be possible,
9317 however, to implement the functionality without a method in the driver, because the
9318 helper function needs to access the correct pointer to <font class="fixd">struct fasync_struct *</font> (here
9319 <font class="fixd">&dev->async_queue</font>), and only the driver can provide the information.<br>
9320 <br>
9321 When data arrives, then, the following statement must be executed to signal asynchronous
9322 readers. Since new data for the <i>scullpipe </i>reader is generated by a process
9323 issuing a <i>write</i>, the statement appears in the <i>write</i> method of <i>scullpipe</i>.<br>
9324 <pre>
9325 if (dev->async_queue)
9326 kill_fasync(&dev->async_queue, SIGIO, POLL_IN);
9327 </pre>
9328 Note that some devices also implement asynchronous notification to indicate when
9329 the device can be written; in this case, of course, <i>kill_fasync </i>must be called with a
9330 mode of <font class="fixd">POLL_OUT</font>.<br>
9331 <br>
9332 It might appear that we're done, but there's still one thing missing. We must invoke
9333 our <i>fasync </i>method when the file is closed to remove the file from the list of active
9334 asynchronous readers. Although this call is required only if <font class="fixd">filp->f_flags</font> has <font class="fixd">FASYNC</font>
9335 set, calling the function anyway doesn't hurt and is the usual implementation. The
9336 following lines, for example, are part of the <i>release</i> method for <i>scullpipe</i>:<br>
9337 <pre>
9338 /* remove this filp from the asynchronously notified filp's */
9339 scull_p_fasync(-1, filp, 0);
9340 </pre>
9341 The data structure underlying asynchronous notification is almost identical to the
9342 structure <font class="fixd">struct wait_queue,</font> because both situations involve waiting on an event.
9343 The difference is that <font class="fixd">struct file</font> is used in place of <font class="fixd">struct task_struct</font>.
9344 The <font class="fixd">struct file</font> in the queue is then used to retrieve <font class="fixd">f_owner,</font> in order to signal the process.<br>
9345 <br>
9346 <a name="SeekingADevice"></a><font color="red"><b>Seeking a Device</b></font><br>
9347 <br>
9348 One of the last things we need to cover in this chapter is the <i>llseek </i>method, which is
9349 useful (for some devices) and easy to implement.<br>
9350 <br>
9351 <font class="fixd">* POLL_IN</font> is a symbol used in the asynchronous notification code; it is equivalent to <font class="fixd">POLLIN|POLLRDNORM.</font><br>
9352 <br>
9353 <A name="172"></a><font color="blue">PAGE 172</font><br>
9354 <br>
9355 <a name="TheLlseekImplementation"></a><font color="red"><b>The llseek Implementation</b></font><br>
9356 <br>
9357 The <i>llseek </i>method implements the <i>lseek </i>and <i>llseek </i>system calls. We have already
9358 stated that if the <i>llseek </i>method is missing from the device's operations, the default
9359 implementation in the kernel performs seeks by modifying <font class="fixd">filp->f_pos</font>, the current
9360 reading/writing position within the file. Please note that for the <i>lseek </i>system call to
9361 work correctly, the <i>read </i>and <i>write </i>methods must cooperate by using and updating
9362 the offset item they receive as an argument.<br>
9363 <br>
9364 You may need to provide your own <i>llseek </i>method if the seek operation corresponds
9365 to a physical operation on the device. A simple example can be seen in the <i>scull
9366 </i>driver:<br>
9367 <pre>
9368 loff_t scull_llseek(struct file *filp, loff_t off, int whence)
9369 {
9370 struct scull_dev *dev = filp->private_data;
9371 loff_t newpos;
9373 switch(whence) {
9374 case 0: /* SEEK_SET */
9375 newpos = off;
9376 break;
9378 case 1: /* SEEK_CUR */
9379 newpos = filp->f_pos + off;
9380 break;
9382 case 2: /* SEEK_END */
9383 newpos = dev->size + off;
9384 break;
9386 default: /* can't happen */
9387 return -EINVAL;
9388 }
9389 if (newpos < 0) return -EINVAL;
9390 filp->f_pos = newpos;
9391 return newpos;
9392 }
9393 </pre>
9394 The only device-specific operation here is retrieving the file length from the device. In
9395 <i>scull</i> the <i>read</i> and <i>write</i> methods cooperate as needed, as shown in Chapter 3.<br>
9396 <br>
9397 Although the implementation just shown makes sense for <i>scull</i>, which handles a well-defined
9398 data area, most devices offer a data flow rather than a data area (just think
9399 about the serial ports or the keyboard), and seeking those devices does not make
9400 sense. If this is the case for your device, you can't just refrain from declaring the <i>llseek
9401 </i>operation, because the default method allows seeking. Instead, you should inform the
9402 kernel that your device does not support <i>llseek </i>by calling <i>nonseekable_open </i>in your
9403 <i>open</i> method:<br>
9404 <pre>
9405 int nonseekable_open(struct inode *inode; struct file *filp);
9406 </pre>
9407 <A name="173"></a><font color="blue">PAGE 173</font><br>
9408 <br>
9409 This call marks the given <font class="fixd">filp</font> as being nonseekable; the kernel never allows an <i>lseek
9410 </i>call on such a file to succeed. By marking the file in this way, you can also be assured
9411 that no attempts will be made to seek the file by way of the <i>pread </i>and <i>pwrite </i>system
9412 calls.<br>
9413 <br>
9414 For completeness, you should also set the <i>llseek </i>method in your <font class="fixd">file_operations</font>
9415 structure to the special helper function <i>no_llseek</i>, which is defined in <i><linux/fs.h></i>.<br>
9416 <br>
9417 <a name="AccessControlOnADeviceFile"></a><font color="red"><b>Access Control on a Device File</b></font><br>
9418 <br>
9419 Offering access control is sometimes vital for the reliability of a device node. Not
9420 only should unauthorized users not be permitted to use the device (a restriction is
9421 enforced by the filesystem permission bits), but sometimes only one authorized user
9422 should be allowed to open the device at a time.<br>
9423 <br>
9424 The problem is similar to that of using ttys. In that case, the <i>login </i>process changes
9425 the ownership of the device node whenever a user logs into the system, in order to
9426 prevent other users from interfering with or sniffing the tty data flow. However, it's
9427 impractical to use a privileged program to change the ownership of a device every
9428 time it is opened just to grant unique access to it.<br>
9429 <br>
9430 None of the code shown up to now implements any access control beyond the filesystem
9431 permission bits. If the <i>open </i>system call forwards the request to the driver,
9432 <i>open </i>succeeds. We now introduce a few techniques for implementing some additional
9433 checks.<br>
9434 <br>
9435 Every device shown in this section has the same behavior as the bare <i>scull </i>device
9436 (that is, it implements a persistent memory area) but differs from <i>scull </i>in access control,
9437 which is implemented in the <i>open</i> and <i>release</i> operations.<br>
9438 <br>
9439 <a name="SingleOpenDevices"></a><font color="red"><b>Single-Open Devices</b></font><br>
9440 <br>
9441 The brute-force way to provide access control is to permit a device to be opened by
9442 only one process at a time (single openness). This technique is best avoided because it
9443 inhibits user ingenuity. A user might want to run different processes on the same
9444 device, one reading status information while the other is writing data. In some cases,
9445 users can get a lot done by running a few simple programs through a shell script, as
9446 long as they can access the device concurrently. In other words, implementing a singleopen
9447 behavior amounts to creating policy, which may get in the way of what your
9448 users want to do.<br>
9449 <br>
9450 Allowing only a single process to open a device has undesirable properties, but it is
9451 also the easiest access control to implement for a device driver, so it's shown here.
9452 The source code is extracted from a device called <i>scullsingle</i>.<br>
9453 <br>
9454 <A name="174"></a><font color="blue">PAGE 174</font><br>
9455 <br>
9456 The <i>scullsingle </i>device maintains an <font class="fixd">atomic_t</font> variable called <font class="fixd">scull_s_available;</font> that
9457 variable is initialized to a value of one, indicating that the device is indeed available.
9458 The <i>open </i>call decrements and tests <font class="fixd">scull_s_available</font> and refuses access if somebody
9459 else already has the device open:<br>
9460 <pre>
9461 static atomic_t scull_s_available = ATOMIC_INIT(1);
9463 static int scull_s_open(struct inode *inode, struct file *filp)
9464 {
9465 struct scull_dev *dev = &scull_s_device; /* device information */
9467 if (! atomic_dec_and_test (&scull_s_available)) {
9468 atomic_inc(&scull_s_available);
9469 return -EBUSY; /* already open */
9470 }
9472 /* then, everything else is copied from the bare scull device */
9473 if ( (filp->f_flags & O_ACCMODE) = = O_WRONLY)
9474 scull_trim(dev);
9475 filp->private_data = dev;
9476 return 0; /* success */
9477 }
9478 </pre>
9479 The <i>release</i> call, on the other hand, marks the device as no longer busy:<br>
9480 <pre>
9481 static int scull_s_release(struct inode *inode, struct file *filp)
9482 {
9483 atomic_inc(&scull_s_available); /* release the device */
9484 return 0;
9485 }
9486 </pre>
9487 Normally, we recommend that you put the open flag <font class="fixd">scull_s_available</font> within the
9488 device structure (<font class="fixd">Scull_Dev</font> here) because, conceptually, it belongs to the device. The
9489 <i>scull </i>driver, however, uses stand alone variables to hold the flag so it can use the same
9490 device structure and methods as the bare <i>scull</i> device and minimize code duplication.<br>
9491 <br>
9492 <a name="RestrictingAccessToASingleUserAtATime"></a><font color="red"><b>Restricting Access to a Single User at a Time</b></font><br>
9493 <br>
9494 The next step beyond a single-open device is to let a single user open a device in multiple
9495 processes but allow only one user to have the device open at a time. This solution
9496 makes it easy to test the device, since the user can read and write from several
9497 processes at once, but assumes that the user takes some responsibility for maintaining
9498 the integrity of the data during multiple accesses. This is accomplished by adding
9499 checks in the <i>open </i>method; such checks are performed <i>after </i>the normal
9500 permission checking and can only make access more restrictive than that specified by
9501 the owner and group permission bits. This is the same access policy as that used for
9502 ttys, but it doesn't resort to an external privileged program.<br>
9503 <br>
9504 Those access policies are a little trickier to implement than single-open policies. In
9505 this case, two items are needed: an open count and the uid of the "owner" of the<br>
9506 <br>
9507 <A name="175"></a><font color="blue">PAGE 175</font><br>
9508 <br>
9509 device. Once again, the best place for such items is within the device structure; our
9510 example uses global variables instead, for the reason explained earlier for <i>scullsingle</i>.
9511 The name of the device is <i>sculluid</i>.<br>
9512 <br>
9513 The <i>open </i>call grants access on first open but remembers the owner of the device.
9514 This means that a user can open the device multiple times, thus allowing cooperating
9515 processes to work concurrently on the device. At the same time, no other user
9516 can open it, thus avoiding external interference. Since this version of the function is
9517 almost identical to the preceding one, only the relevant part is reproduced here:<br>
9518 <pre>
9519 spin_lock(&scull_u_lock);
9520 if (scull_u_count &&
9521 (scull_u_owner != current->uid) && /* allow user */
9522 (scull_u_owner != current->euid) && /* allow whoever did su */
9523 !capable(CAP_DAC_OVERRIDE)) { /* still allow root */
9524 spin_unlock(&scull_u_lock);
9525 return -EBUSY; /* -EPERM would confuse the user */
9526 }
9528 if (scull_u_count = = 0)
9529 scull_u_owner = current->uid; /* grab it */
9531 scull_u_count++;
9532 spin_unlock(&scull_u_lock);
9533 </pre>
9534 Note that the <i>sculluid </i>code has two variables (<font class="fixd">scull_u_owner</font> and <font class="fixd">scull_u_count</font>)
9535 that control access to the device and that could be accessed concurrently by multiple
9536 processes. To make these variables safe, we control access to them with a spinlock
9537 (<font class="fixd">scull_u_lock</font>). Without that locking, two (or more) processes could test
9538 <font class="fixd">scull_u_count</font> at the same time, and both could conclude that they were entitled to
9539 take ownership of the device. A spinlock is indicated here, because the lock is held
9540 for a very short time, and the driver does nothing that could sleep while holding the
9541 lock.<br>
9542 <br>
9543 We chose to return <font class="fixd">-EBUSY</font> and not <font class="fixd">-EPERM,</font> even though the code is performing a permission
9544 check, in order to point a user who is denied access in the right direction.
9545 The reaction to "Permission denied" is usually to check the mode and owner of the
9546 <i>/dev </i>file, while "Device busy" correctly suggests that the user should look for a process
9547 already using the device.<br>
9548 <br>
9549 This code also checks to see if the process attempting the open has the ability to
9550 override file access permissions; if so, the open is allowed even if the opening process
9551 is not the owner of the device. The <font class="fixd">CAP_DAC_OVERRIDE</font> capability fits the task well
9552 in this case.<br>
9553 <br>
9554 The <i>release</i> method looks like the following:<br>
9555 <pre>
9556 static int scull_u_release(struct inode *inode, struct file *filp)
9557 {
9558 spin_lock(&scull_u_lock);
9559 scull_u_count--; /* nothing else */
9560 </pre>
9561 <A name="176"></a><font color="blue">PAGE 176</font><br>
9562 <pre>
9563 spin_unlock(&scull_u_lock);
9564 return 0;
9565 }
9566 </pre>
9567 Once again, we must obtain the lock prior to modifying the count to ensure that we
9568 do not race with another process.<br>
9569 <br>
9570 <a name="BlockingOpenAsAnAlternativeToEBUSY"></a><font color="red"><b>Blocking open as an Alternative to EBUSY</b></font><br>
9571 <br>
9572 When the device isn't accessible, returning an error is usually the most sensible
9573 approach, but there are situations in which the user would prefer to wait for the
9574 device.<br>
9575 <br>
9576 For example, if a data communication channel is used both to transmit reports on a
9577 regular, scheduled basis (using <i>crontab</i>) and for casual usage according to people's
9578 needs, it's much better for the scheduled operation to be slightly delayed rather than
9579 fail just because the channel is currently busy.<br>
9580 <br>
9581 This is one of the choices that the programmer must make when designing a device
9582 driver, and the right answer depends on the particular problem being solved.<br>
9583 <br>
9584 The alternative to <font class="fixd">EBUSY,</font> as you may have guessed, is to implement blocking <i>open</i>.
9585 The <i>scullwuid </i>device is a version of <i>sculluid </i>that waits for the device on <i>open </i>instead
9586 of returning <font class="fixd">-EBUSY.</font> It differs from <i>sculluid </i>only in the following part of the <i>open
9587 </i>operation:<br>
9588 <pre>
9589 spin_lock(&scull_w_lock);
9590 while (! scull_w_available( )) {
9591 spin_unlock(&scull_w_lock);
9592 if (filp->f_flags & O_NONBLOCK) return -EAGAIN;
9593 if (wait_event_interruptible (scull_w_wait, scull_w_available( )))
9594 return -ERESTARTSYS; /* tell the fs layer to handle it */
9595 spin_lock(&scull_w_lock);
9596 }
9597 if (scull_w_count = = 0)
9598 scull_w_owner = current->uid; /* grab it */
9599 scull_w_count++;
9600 spin_unlock(&scull_w_lock);
9601 </pre>
9602 The implementation is based once again on a wait queue. If the device is not currently
9603 available, the process attempting to open it is placed on the wait queue until
9604 the owning process closes the device.<br>
9605 <br>
9606 The <i>release</i> method, then, is in charge of awakening any pending process:<br>
9607 <pre>
9608 static int scull_w_release(struct inode *inode, struct file *filp)
9609 {
9610 int temp;
9612 spin_lock(&scull_w_lock);
9613 scull_w_count--;
9614 temp = scull_w_count;
9615 spin_unlock(&scull_w_lock);
9616 </pre>
9617 <A name="177"></a><font color="blue">PAGE 177</font><br>
9618 <pre>
9619 if (temp = = 0)
9620 wake_up_interruptible_sync(&scull_w_wait); /* awake other uid's */
9621 return 0;
9622 }
9623 </pre>
9624 Here is an example of where calling <i>wake_up_interruptible_sync </i>makes sense. When
9625 we do the wakeup, we are just about to return to user space, which is a natural
9626 scheduling point for the system. Rather than potentially reschedule when we do the
9627 wakeup, it is better to just call the "sync" version and finish our job.<br>
9628 <br>
9629 The problem with a blocking-open implementation is that it is really unpleasant for the
9630 interactive user, who has to keep guessing what is going wrong. The interactive user
9631 usually invokes standard commands, such as <i>cp </i>and <i>tar</i>, and can't just add <font class="fixd">O_NONBLOCK</font>
9632 to the <i>open </i>call. Someone who's making a backup using the tape drive in the next
9633 room would prefer to get a plain "device or resource busy" message instead of being
9634 left to guess why the hard drive is so silent today, while <i>tar</i> should be scanning it.<br>
9635 <br>
9636 This kind of problem (a need for different, incompatible policies for the same device)
9637 is often best solved by implementing one device node for each access policy. An
9638 example of this practice can be found in the Linux tape driver, which provides multiple
9639 device files for the same device. Different device files will, for example, cause the
9640 drive to record with or without compression, or to automatically rewind the tape
9641 when the device is closed.<br>
9642 <br>
9643 <a name="CloningTheDeviceOnOpen"></a><font color="red"><b>Cloning the Device on open</b></font><br>
9644 <br>
9645 Another technique to manage access control is to create different private copies of
9646 the device, depending on the process opening it.<br>
9647 <br>
9648 Clearly, this is possible only if the device is not bound to a hardware object; <i>scull </i>is
9649 an example of such a "software" device. The internals of <i>/dev/tty </i>use a similar technique
9650 in order to give its process a different "view" of what the <i>/dev </i>entry point represents.
9651 When copies of the device are created by the software driver, we call them
9652 <i>virtual devices</i>--just as virtual consoles use a single physical tty device.<br>
9653 <br>
9654 Although this kind of access control is rarely needed, the implementation can be
9655 enlightening in showing how easily kernel code can change the application's perspective
9656 of the surrounding world (i.e., the computer).<br>
9657 <br>
9658 The <i>/dev/scullpriv </i>device node implements virtual devices within the <i>scull </i>package.
9659 The <i>scullpriv </i>implementation uses the device number of the process's controlling tty
9660 as a key to access the virtual device. Nonetheless, you can easily modify the sources to
9661 use any integer value for the key; each choice leads to a different policy. For example,
9662 using the uid leads to a different virtual device for each user, while using a pid key creates
9663 a new device for each process accessing it.<br>
9664 <br>
9665 The decision to use the controlling terminal is meant to enable easy testing of the
9666 device using I/O redirection: the device is shared by all commands run on the same<br>
9667 <br>
9668 <A name="178"></a><font color="blue">PAGE 178</font><br>
9669 <br>
9670 virtual terminal and is kept separate from the one seen by commands run on another
9671 terminal.<br>
9672 <br>
9673 The <i>open </i>method looks like the following code. It must look for the right virtual
9674 device and possibly create one. The final part of the function is not shown because it
9675 is copied from the bare <i>scull</i>, which we've already seen.<br>
9676 <pre>
9677 /* The clone-specific data structure includes a key field */
9679 struct scull_listitem {
9680 struct scull_dev device;
9681 dev_t key;
9682 struct list_head list;
9684 };
9686 /* The list of devices, and a lock to protect it */
9687 static LIST_HEAD(scull_c_list);
9688 static spinlock_t scull_c_lock = SPIN_LOCK_UNLOCKED;
9690 /* Look for a device or create one if missing */
9691 static struct scull_dev *scull_c_lookfor_device(dev_t key)
9692 {
9693 struct scull_listitem *lptr;
9695 list_for_each_entry(lptr, &scull_c_list, list) {
9696 if (lptr->key = = key)
9697 return &(lptr->device);
9698 }
9700 /* not found */
9701 lptr = kmalloc(sizeof(struct scull_listitem), GFP_KERNEL);
9702 if (!lptr)
9703 return NULL;
9705 /* initialize the device */
9706 memset(lptr, 0, sizeof(struct scull_listitem));
9707 lptr->key = key;
9708 scull_trim(&(lptr->device)); /* initialize it */
9709 init_MUTEX(&(lptr->device.sem));
9711 /* place it in the list */
9712 list_add(&lptr->list, &scull_c_list);
9714 return &(lptr->device);
9715 }
9717 static int scull_c_open(struct inode *inode, struct file *filp)
9718 {
9719 struct scull_dev *dev;
9720 </pre>
9721 <A name="179"></a><font color="blue">PAGE 179</font><br>
9722 <pre>
9723 <font class="fixd">dev_t</font> key;
9725 if (!current->signal->tty) {
9726 PDEBUG("Process \"%s\" has no ctl tty\n", current->comm);
9727 return -EINVAL;
9728 }
9729 key = tty_devnum(current->signal->tty);
9731 /* look for a scullc device in the list */
9732 spin_lock(&scull_c_lock);
9733 dev = scull_c_lookfor_device(key);
9734 spin_unlock(&scull_c_lock);
9736 if (!dev)
9737 return -ENOMEM;
9739 /* then, everything else is copied from the bare scull device */
9740 </pre>
9741 The <i>release </i>method does nothing special. It would normally release the device on last
9742 close, but we chose not to maintain an open count in order to simplify the testing of
9743 the driver. If the device were released on last close, you wouldn't be able to read the
9744 same data after writing to the device, unless a background process were to keep it
9745 open. The sample driver takes the easier approach of keeping the data, so that at the
9746 next <i>open</i>, you'll find it there. The devices are released when <i>scull_cleanup</i> is called.<br>
9747 <br>
9748 This code uses the generic Linux linked list mechanism in preference to reimplementing
9749 the same capability from scratch. Linux lists are discussed in Chapter 11.<br>
9750 <br>
9751 Here's the <i>release </i>implementation for <i>/dev/scullpriv</i>, which closes the discussion of
9752 device methods.<br>
9753 <pre>
9754 static int scull_c_release(struct inode *inode, struct file *filp)
9755 {
9756 /*
9757 * Nothing to do, because the device is persistent.
9758 * A `real' cloned device should be freed on last close
9759 */
9760 return 0;
9761 }
9762 </pre>
9763 <a name="QuickReference6"></a><font color="red"><b>Quick Reference</b></font><br>
9764 <br>
9765 This chapter introduced the following symbols and header files:<br>
9766 <br>
9767 <font class="fixd">#include <linux/ioctl.h></font><br>
9768 <div class="bq">
9769 Declares all the macros used to define <i>ioctl </i>commands. It is currently included
9770 by <i><linux/fs.h></i>.</div>
9771 <br>
9772 <A name="180"></a><font color="blue">PAGE 180</font><br>
9773 <br>
9774 <font class="fixd">_IOC_NRBITS<br>
9775 _IOC_TYPEBITS<br>
9776 _IOC_SIZEBITS<br>
9777 _IOC_DIRBITS</font><br>
9778 <div class="bq">
9779 The number of bits available for the different bitfields of <i>ioctl </i>commands. There
9780 are also four macros that specify the <font class="fixd">MASKs</font> and four that specify the <font class="fixd">SHIFTs,</font> but
9781 they're mainly for internal use. <font class="fixd">_IOC_SIZEBITS</font> is an important value to check,
9782 because it changes across architectures.</div>
9783 <br>
9784 <font class="fixd">_IOC_NONE<br>
9785 _IOC_READ<br>
9786 _IOC_WRITE</font><br>
9787 <div class="bq">
9788 The possible values for the "direction" bitfield. "Read" and "write" are different
9789 bits and can be ORed to specify read/write. The values are 0-based.</div>
9790 <br>
9791 <font class="fixd">_IOC(dir,type,nr,size)<br>
9792 _IO(type,nr)<br>
9793 _IOR(type,nr,size)<br>
9794 _IOW(type,nr,size)<br>
9795 _IOWR(type,nr,size)</font><br>
9796 <div class="bq">
9797 Macros used to create an <i>ioctl</i> command.</div>
9798 <br>
9799 <font class="fixd">_IOC_DIR(nr)<br>
9800 _IOC_TYPE(nr)<br>
9801 _IOC_NR(nr)<br>
9802 _IOC_SIZE(nr)</font><br>
9803 <div class="bq">
9804 Macros used to decode a command. In particular, <font class="fixd">_IOC_TYPE(nr)</font> is an OR combination
9805 of <font class="fixd">_IOC_READ</font> and <font class="fixd">_IOC_WRITE</font>.</div>
9806 <br>
9807 <font class="fixd">#include <asm/uaccess.h><br>
9808 int access_ok(int type, const void *addr, unsigned long size);</font><br>
9809 <div class="bq">
9810 Checks that a pointer to user space is actually usable. <i>access_ok </i>returns a nonzero
9811 value if the access should be allowed.</div>
9812 <br>
9813 <font class="fixd">VERIFY_READ<br>
9814 VERIFY_WRITE</font><br>
9815 <div class="bq">
9816 The possible values for the type argument in <i>access_ok</i>. <font class="fixd">VERIFY_WRITE</font> is a superset
9817 of <font class="fixd">VERIFY_READ</font>.</div>
9818 <br>
9819 <font class="fixd">#include <asm/uaccess.h><br>
9820 int put_user(datum,ptr);<br>
9821 int get_user(local,ptr);<br>
9822 int __put_user(datum,ptr);<br>
9823 int __get_user(local,ptr);</font><br>
9824 <div class="bq">
9825 Macros used to store or retrieve a datum to or from user space. The number of
9826 bytes being transferred depends on <font class="fixd">sizeof(*ptr).</font> The regular versions call</div>
9827 <br>
9828 <A name="181"></a><font color="blue">PAGE 181</font><br>
9829 <br>
9830 <div class="bq">
9831 <i>access_ok </i>first, while the qualified versions (<i>__put_user </i>and <i>__get_user</i>) assume
9832 that <i>access_ok</i> has already been called.</div>
9833 <br>
9834 <font class="fixd">#include <linux/capability.h></font><br>
9835 <div class="bq">
9836 Defines the various <font class="fixd">CAP_</font> symbols describing the capabilities a user-space process
9837 may have.</div>
9838 <br>
9839 <font class="fixd">int capable(int capability);</font><br>
9840 <div class="bq">
9841 Returns nonzero if the process has the given capability.</div>
9842 <br>
9843 <font class="fixd">#include <linux/wait.h><br>
9844 typedef struct { /* ... */ } wait_queue_head_t;<br>
9845 void init_waitqueue_head(wait_queue_head_t *queue);<br>
9846 DECLARE_WAIT_QUEUE_HEAD(queue);</font><br>
9847 <div class="bq">
9848 The defined type for Linux wait queues. A <font class="fixd">wait_queue_head_t</font> must be explicitly
9849 initialized with either <i>init_waitqueue_head </i>at runtime or <i><font class="fixd">DECLARE_WAIT_</font>
9850 <font class="fixd">QUEUE_HEAD</font></i> at compile time.</div>
9851 <br>
9852 <font class="fixd">void wait_event(wait_queue_head_t q, int condition);<br>
9853 int wait_event_interruptible(wait_queue_head_t q, int condition);<br>
9854 int wait_event_timeout(wait_queue_head_t q, int condition, int time);<br>
9855 int wait_event_interruptible_timeout(wait_queue_head_t q, int condition, int time);</font><br>
9856 <div class="bq">
9857 Cause the process to sleep on the given queue until the given condition evaluates
9858 to a true value.</div>
9859 <br>
9860 <font class="fixd">void wake_up(struct wait_queue **q);<br>
9861 void wake_up_interruptible(struct wait_queue **q);<br>
9862 void wake_up_nr(struct wait_queue **q, int nr);<br>
9863 void wake_up_interruptible_nr(struct wait_queue **q, int nr);<br>
9864 void wake_up_all(struct wait_queue **q);<br>
9865 void wake_up_interruptible_all(struct wait_queue **q);<br>
9866 void wake_up_interruptible_sync(struct wait_queue **q);</font><br>
9867 <div class="bq">
9868 Wake processes that are sleeping on the queue q. The <i>_interruptible </i>form wakes
9869 only interruptible processes. Normally, only one exclusive waiter is awakened,
9870 but that behavior can be changed with the <i>_nr </i>or <i>_all </i>forms. The <i>_sync </i>version
9871 does not reschedule the CPU before returning.</div>
9872 <br>
9873 <font class="fixd">#include <linux/sched.h><br>
9874 set_current_state(int state);</font><br>
9875 <div class="bq">
9876 Sets the execution state of the current process. <font class="fixd">TASK_RUNNING</font> means it is ready to
9877 run, while the sleep states are <font class="fixd">TASK_INTERRUPTIBLE</font> and <font class="fixd">TASK_UNINTERRUPTIBLE</font>.</div>
9878 <br>
9879 <font class="fixd">void schedule(void);</font><br>
9880 <div class="bq">
9881 Selects a runnable process from the run queue. The chosen process can be
9882 current or a different one.</div>
9883 <br>
9884 <A name="182"></a><font color="blue">PAGE 182</font><br>
9885 <br>
9886 <font class="fixd">typedef struct { /* ... */ } wait_queue_t;<br>
9887 init_waitqueue_entry(wait_queue_t *entry, struct task_struct *task);</font><br>
9888 <div class="bq">
9889 The <font class="fixd">wait_queue_t</font> type is used to place a process onto a wait queue.</div>
9890 <br>
9891 <font class="fixd">void prepare_to_wait(wait_queue_head_t *queue, wait_queue_t *wait, int state);<br>
9892 void prepare_to_wait_exclusive(wait_queue_head_t *queue, wait_queue_t *wait, int state);<br>
9893 void finish_wait(wait_queue_head_t *queue, wait_queue_t *wait);</font><br>
9894 <div class="bq">
9895 Helper functions that can be used to code a manual sleep.</div>
9896 <br>
9897 <font class="fixd">void sleep_on(wiat_queue_head_t *queue);<br>
9898 void interruptible_sleep_on(wiat_queue_head_t *queue);</font><br>
9899 <div class="bq">
9900 Obsolete and deprecated functions that unconditionally put the current process
9901 to sleep.</div>
9902 <br>
9903 <font class="fixd">#include <linux/poll.h><br>
9904 void poll_wait(struct file *filp, wait_queue_head_t *q, poll_table *p)</font><br>
9905 <div class="bq">
9906 Places the current process into a wait queue without scheduling immediately. It
9907 is designed to be used by the <i>poll</i> method of device drivers.</div>
9908 <br>
9909 <font class="fixd">int fasync_helper(struct inode *inode, struct file *filp, int mode, struct
9910 fasync_struct **fa);</font><br>
9911 <div class="bq">
9912 A "helper" for implementing the <i>fasync </i>device method. The mode argument is the
9913 same value that is passed to the method, while fa points to a device-specific
9914 <font class="fixd">fasync_struct *.</font></div>
9915 <br>
9916 <font class="fixd">void kill_fasync(struct fasync_struct *fa, int sig, int band);</font><br>
9917 <div class="bq">
9918 If the driver supports asynchronous notification, this function can be used to
9919 send a signal to processes registered in fa.</div>
9920 <br>
9921 <font class="fixd">int nonseekable_open(struct inode *inode, struct file *filp);<br>
9922 loff_t no_llseek(struct file *file, loff_t offset, int whence);</font><br>
9923 <div class="bq">
9924 <i>nonseekable_open </i>should be called in the <i>open </i>method of any device that does
9925 not support seeking. Such devices should also use <i>no_llseek </i>as their <i>llseek
9926 </i>method.</div>
9927 <br>
9928 <A name="183"></a><font color="blue">PAGE 183</font><br>
9929 <br>
9930 <a name="CHAPTER7"></a><font color="red"><b>CHAPTER 7</b></font><br>
9931 <br>
9932 <a name="TimeDelaysAndDeferredWork"></a><font color="#7519FF" size="+1"><b>Time, Delays, and Deferred Work</b></font><br>
9933 <br>
9934 At this point, we know the basics of how to write a full-featured char module. Real World
9935 drivers, however, need to do more than implement the operations that control
9936 a device; they have to deal with issues such as timing, memory management, hardware
9937 access, and more. Fortunately, the kernel exports a number of facilities to ease
9938 the task of the driver writer. In the next few chapters, we'll describe some of the kernel
9939 resources you can use. This chapter leads the way by describing how timing
9940 issues are addressed. Dealing with time involves the following tasks, in order of
9941 increasing complexity:<br>
9942 <ul>
9943 <li> Measuring time lapses and comparing times
9944 <li> Knowing the current time
9945 <li> Delaying operation for a specified amount of time
9946 <li> Scheduling asynchronous functions to happen at a later time
9947 </ul>
9948 <a name="MeasuringTimeLapses"></a><font color="red"><b>Measuring Time Lapses</b></font><br>
9949 <br>
9950 The kernel keeps track of the flow of time by means of timer interrupts. Interrupts
9951 are covered in detail in Chapter 10.<br>
9952 <br>
9953 Timer interrupts are generated by the system's timing hardware at regular intervals;
9954 this interval is programmed at boot time by the kernel according to the value of <font class="fixd">HZ</font>,
9955 which is an architecture-dependent value defined in <i><linux/param.h> </i>or a subplatform
9956 file included by it. Default values in the distributed kernel source range from 50
9957 to 1200 ticks per second on real hardware, down to 24 for software simulators. Most
9958 platforms run at 100 or 1000 interrupts per second; the popular x86 PC defaults to
9959 1000, although it used to be 100 in previous versions (up to and including 2.4). As a
9960 general rule, even if you know the value of <font class="fixd">HZ</font>, you should never count on that specific
9961 value when programming.<br>
9962 <br>
9963 It is possible to change the value of <font class="fixd">HZ</font> for those who want systems with a different
9964 clock interrupt frequency. If you change <font class="fixd">HZ</font> in the header file, you need to recompile<br>
9965 <br>
9966 <A name="184"></a><font color="blue">PAGE 184</font><br>
9967 <br>
9968 the kernel and all modules with the new value. You might want to raise <font class="fixd">HZ</font> to get a
9969 more fine-grained resolution in your asynchronous tasks, if you are willing to pay the
9970 overhead of the extra timer interrupts to achieve your goals. Actually, raising <font class="fixd">HZ</font> to
9971 1000 was pretty common with x86 industrial systems using Version 2.4 or 2.2 of the
9972 kernel. With current versions, however, the best approach to the timer interrupt is to
9973 keep the default value for <font class="fixd">HZ</font>, by virtue of our complete trust in the kernel developers,
9974 who have certainly chosen the best value. Besides, some internal calculations are
9975 currently implemented only for <font class="fixd">HZ</font> in the range from 12 to 1535 (see <i><linux/timex.h>
9976 </i>and RFC-1589).<br>
9977 <br>
9978 Every time a timer interrupt occurs, the value of an internal kernel counter is incremented.
9979 The counter is initialized to 0 at system boot, so it represents the number of
9980 clock ticks since last boot. The counter is a 64-bit variable (even on 32-bit architectures)
9981 and is called <font class="fixd">jiffies_64</font>. However, driver writers normally access the <font class="fixd">jiffies</font>
9982 variable, an <font class="fixd">unsigned long</font> that is the same as either <font class="fixd">jiffies_64</font> or its least significant
9983 bits. Using <font class="fixd">jiffies</font> is usually preferred because it is faster, and accesses to the 64-bit
9984 <font class="fixd">jiffies_64</font> value are not necessarily atomic on all architectures.<br>
9985 <br>
9986 In addition to the low-resolution kernel-managed jiffy mechanism, some CPU platforms
9987 feature a high-resolution counter that software can read. Although its actual
9988 use varies somewhat across platforms, it's sometimes a very powerful tool.<br>
9989 <br>
9990 <a name="UsingTheJiffiesCounter"></a><font color="red"><b>Using the jiffies Counter</b></font><br>
9991 <br>
9992 The counter and the utility functions to read it live in <i><linux/jiffies.h></i>, although
9993 you'll usually just include <i><linux/sched.h></i>, that automatically pulls <i>jiffies.h </i>in. Needless
9994 to say, both <font class="fixd">jiffies</font> and <font class="fixd">jiffies_64</font> must be considered read-only.<br>
9995 <br>
9996 Whenever your code needs to remember the current value of <font class="fixd">jiffies</font>, it can simply
9997 access the <font class="fixd">unsigned long</font> variable, which is declared as volatile to tell the compiler
9998 not to optimize memory reads. You need to read the current counter whenever your
9999 code needs to calculate a future time stamp, as shown in the following example:<br>
10000 <pre>
10001 #include <linux/jiffies.h>
10002 unsigned long j, stamp_1, stamp_half, stamp_n;
10004 j = jiffies; /* read the current value */
10005 stamp_1 = j + HZ; /* 1 second in the future */
10006 stamp_half = j + HZ/2; /* half a second */
10007 stamp_n = j + n * HZ / 1000; /* n milliseconds */
10008 </pre>
10009 This code has no problem with <font class="fixd">jiffies</font> wrapping around, as long as different values
10010 are compared in the right way. Even though on 32-bit platforms the counter wraps
10011 around only once every 50 days when <font class="fixd">HZ</font> is 1000, your code should be prepared to
10012 face that event. To compare your cached value (like <font class="fixd">stamp_1</font> above) and the current
10013 value, you should use one of the following macros:<br>
10014 <pre>
10015 #include <linux/jiffies.h>
10016 int time_after(unsigned long a, unsigned long b);
10017 </pre>
10018 <A name="185"></a><font color="blue">PAGE 185</font><br>
10019 <pre>
10020 int time_before(unsigned long a, unsigned long b);
10021 int time_after_eq(unsigned long a, unsigned long b);
10022 int time_before_eq(unsigned long a, unsigned long b);
10023 </pre>
10024 The first evaluates true when <i>a</i>, as a snapshot of <font class="fixd">jiffies</font>, represents a time after <i>b</i>,
10025 the second evaluates true when time <i>a </i>is before time <i>b</i>, and the last two compare for
10026 "after or equal" and "before or equal." The code works by converting the values to
10027 signed long, subtracting them, and comparing the result. If you need to know the difference
10028 between two instances of <font class="fixd">jiffies</font> in a safe way, you can use the same trick:<br>
10029 <pre>
10030 <font class="fixd">diff = (long)t2 - (long)t1;</font>
10031 </pre>
10032 You can convert a jiffies difference to milliseconds trivially through:<br>
10033 <pre>
10034 msec = diff * 1000 / HZ;
10035 </pre>
10036 Sometimes, however, you need to exchange time representations with user space
10037 programs that tend to represent time values with <font class="fixd">struct timeval</font> and <font class="fixd">struct timespec.</font>
10038 The two structures represent a precise time quantity with two numbers:
10039 seconds and microseconds are used in the older and popular <font class="fixd">struct timeval,</font> and seconds
10040 and nanoseconds are used in the newer <font class="fixd">struct timespec.</font> The kernel exports
10041 four helper functions to convert time values expressed as jiffies to and from those structures:<br>
10042 <pre>
10043 #include <linux/time.h>
10045 unsigned long timespec_to_jiffies(struct timespec *value);
10046 void jiffies_to_timespec(unsigned long jiffies, struct timespec *value);
10047 unsigned long timeval_to_jiffies(struct timeval *value);
10048 void jiffies_to_timeval(unsigned long jiffies, struct timeval *value);
10049 </pre>
10050 Accessing the 64-bit jiffy count is not as straightforward as accessing <font class="fixd">jiffies</font>. While
10051 on 64-bit computer architectures the two variables are actually one, access to the
10052 value is not atomic for 32-bit processors. This means you might read the wrong value
10053 if both halves of the variable get updated while you are reading them. It's extremely
10054 unlikely you'll ever need to read the 64-bit counter, but in case you do, you'll be glad
10055 to know that the kernel exports a specific helper function that does the proper locking
10056 for you:<br>
10057 <pre>
10058 #include <linux/jiffies.h>
10059 u64 get_jiffies_64(void);
10060 </pre>
10061 In the above prototype, the <font class="fixd">u64</font> type is used. This is one of the types defined by
10062 <i><linux/types.h></i>, discussed in Chapter 11, and represents an unsigned 64-bit type.<br>
10063 <br>
10064 If you're wondering how 32-bit platforms update both the 32-bit and 64-bit counters
10065 at the same time, read the linker script for your platform (look for a file whose name
10066 matches <i>vmlinux*.lds*</i>). There, the <font class="fixd">jiffies</font> symbol is defined to access the least significant
10067 word of the 64-bit value, according to whether the platform is little-endian
10068 or big-endian. Actually, the same trick is used for 64-bit platforms, so that the
10069 <font class="fixd">unsigned long</font> and <font class="fixd">u64</font> variables are accessed at the same address.<br>
10070 <br>
10071 <A name="186"></a><font color="blue">PAGE 186</font><br>
10072 <br>
10073 Finally, note that the actual clock frequency is almost completely hidden from user
10074 space. The macro <font class="fixd">HZ</font> always expands to 100 when user-space programs include
10075 <i>param.h</i>, and every counter reported to user space is converted accordingly. This
10076 applies to <i>clock(3)</i>, <i>times(2)</i>, and any related function. The only evidence available to
10077 users of the <font class="fixd">HZ</font> value is how fast timer interrupts happen, as shown in <i>/proc/
10078 interrupts</i>. For example, you can obtain <font class="fixd">HZ</font> by dividing this count by the system
10079 uptime reported in <i>/proc/uptime</i>.<br>
10080 <br>
10081 <a name="ProcessorSpecificRegisters"></a><font color="red"><b>Processor-Specific Registers</b></font><br>
10082 <br>
10083 If you need to measure very short time intervals or you need extremely high precision
10084 in your figures, you can resort to platform-dependent resources, a choice of precision
10085 over portability.<br>
10086 <br>
10087 In modern processors, the pressing demand for empirical performance figures is
10088 thwarted by the intrinsic unpredictability of instruction timing in most CPU designs
10089 due to cache memories, instruction scheduling, and branch prediction. As a
10090 response, CPU manufacturers introduced a way to count clock cycles as an easy and
10091 reliable way to measure time lapses. Therefore, most modern processors include a
10092 counter register that is steadily incremented once at each clock cycle. Nowadays, this
10093 clock counter is the only reliable way to carry out high-resolution timekeeping tasks.<br>
10094 <br>
10095 The details differ from platform to platform: the register may or may not be readable
10096 from user space, it may or may not be writable, and it may be 64 or 32 bits wide. In
10097 the last case, you must be prepared to handle overflows just like we did with the jiffy
10098 counter. The register may even not exist for your platform, or it can be implemented
10099 in an external device by the hardware designer, if the CPU lacks the feature and you
10100 are dealing with a special-purpose computer.<br>
10101 <br>
10102 Whether or not the register can be zeroed, we strongly discourage resetting it, even
10103 when hardware permits. You might not, after all, be the only user of the counter at
10104 any given time; on some platforms supporting SMP, for example, the kernel depends
10105 on such a counter to be synchronized across processors. Since you can always measure
10106 differences between values, as long as that difference doesn't exceed the overflow
10107 time, you can get the work done without claiming exclusive ownership of the
10108 register by modifying its current value.<br>
10109 <br>
10110 The most renowned counter register is the TSC (timestamp counter), introduced in
10111 x86 processors with the Pentium and present in all CPU designs ever since--including
10112 the x86_64 platform. It is a 64-bit register that counts CPU clock cycles; it can be
10113 read from both kernel space and user space.<br>
10114 <br>
10115 After including <i><asm/msr.h> </i>(an x86-specific header whose name stands for
10116 "machine-specific registers"), you can use one of these macros:<br>
10117 <pre>
10118 rdtsc(low32,high32);
10119 rdtscl(low32);
10120 rdtscll(var64);
10121 </pre>
10122 <A name="187"></a><font color="blue">PAGE 187</font><br>
10123 <br>
10124 The first macro atomically reads the 64-bit value into two 32-bit variables; the next
10125 one ("read low half") reads the low half of the register into a 32-bit variable, discarding
10126 the high half; the last reads the 64-bit value into a <font class="fixd">long long</font> variable, hence, the
10127 name. All of these macros store values into their arguments.<br>
10128 <br>
10129 Reading the low half of the counter is enough for most common uses of the TSC. A
10130 1-GHz CPU overflows it only once every 4.2 seconds, so you won't need to deal with
10131 multiregister variables if the time lapse you are benchmarking reliably takes less time.
10132 However, as CPU frequencies rise over time and as timing requirements increase,
10133 you'll most likely need to read the 64-bit counter more often in the future.<br>
10134 <br>
10135 As an example using only the low half of the register, the following lines measure the
10136 execution of the instruction itself:<br>
10137 <pre>
10138 unsigned long ini, end;
10139 rdtscl(ini); rdtscl(end);
10140 printk("time lapse: %li\n", end - ini);
10141 </pre>
10142 Some of the other platforms offer similar functionality, and kernel headers offer an
10143 architecture-independent function that you can use instead of <i>rdtsc</i>. It is called <i>get_cycles</i>,
10144 defined in <i><asm/timex.h></i> (included by <i><linux/timex.h></i>). Its prototype is:<br>
10145 <pre>
10146 #include <linux/timex.h>
10147 cycles_t get_cycles(void);
10148 </pre>
10149 This function is defined for every platform, and it always returns 0 on the platforms
10150 that have no cycle-counter register. The <font class="fixd">cycles_t</font> type is an appropriate unsigned
10151 type to hold the value read.<br>
10152 <br>
10153 Despite the availability of an architecture-independent function, we'd like to take the
10154 opportunity to show an example of inline assembly code. To this aim, we implement
10155 a <i>rdtscl </i>function for MIPS processors that works in the same way as the x86
10156 one.<br>
10157 <br>
10158 We base the example on MIPS because most MIPS processors feature a 32-bit
10159 counter as register 9 of their internal "coprocessor 0." To access the register, readable
10160 only from kernel space, you can define the following macro that executes a
10161 "move from coprocessor 0" assembly instruction:*<br>
10162 <pre>
10163 #define rdtscl(dest) \
10164 <font class="fixd">__asm__</font> __volatile__("mfc0 %0,$9; nop" : "=r" (dest))
10165 </pre>
10166 With this macro in place, the MIPS processor can execute the same code shown earlier
10167 for the x86.<br>
10168 <br>
10169 * The trailing <i>nop </i>instruction is required to prevent the compiler from accessing the target register in the
10170 instruction immediately following <i>mfc0</i>. This kind of interlock is typical of RISC processors, and the compiler
10171 can still schedule useful instructions in the delay slots. In this case, we use <i>nop </i>because inline assembly
10172 is a black box for the compiler and no optimization can be performed.<br>
10173 <br>
10174 <A name="188"></a><font color="blue">PAGE 188</font><br>
10175 <br>
10176 With <i>gcc </i>inline assembly, the allocation of general-purpose registers is left to the
10177 compiler. The macro just shown uses %0 as a placeholder for "argument 0," which is
10178 later specified as "any register (<font class="fixd">r</font>) used as output (<font class="fixd">=</font>)." The macro also states that the
10179 output register must correspond to the C expression <font class="fixd">dest</font>. The syntax for inline
10180 assembly is very powerful but somewhat complex, especially for architectures that
10181 have constraints on what each register can do (namely, the x86 family). The syntax is
10182 described in the <i>gcc</i> documentation, usually available in the <i>info</i> documentation tree.<br>
10183 <br>
10184 The short C-code fragment shown in this section has been run on a K7-class x86 processor
10185 and a MIPS VR4181 (using the macro just described). The former reported a
10186 time lapse of 11 clock ticks and the latter just 2 clock ticks. The small figure was
10187 expected, since RISC processors usually execute one instruction per clock cycle.<br>
10188 <br>
10189 There is one other thing worth knowing about timestamp counters: they are not necessarily
10190 synchronized across processors in an SMP system. To be sure of getting a
10191 coherent value, you should disable preemption for code that is querying the counter.<br>
10192 <br>
10193 <a name="KnowingTheCurrentTime"></a><font color="red"><b>Knowing the Current Time</b></font><br>
10194 <br>
10195 Kernel code can always retrieve a representation of the current time by looking at the
10196 value of <font class="fixd">jiffies</font>. Usually, the fact that the value represents only the time since the
10197 last boot is not relevant to the driver, because its life is limited to the system uptime.
10198 As shown, drivers can use the current value of <font class="fixd">jiffies</font> to calculate time intervals
10199 across events (for example, to tell double-clicks from single-clicks in input device
10200 drivers or calculate timeouts). In short, looking at <font class="fixd">jiffies</font> is almost always sufficient
10201 when you need to measure time intervals. If you need very precise measurements for
10202 short time lapses, processor-specific registers come to the rescue (although they bring
10203 in serious portability issues).<br>
10204 <br>
10205 It's quite unlikely that a driver will ever need to know the wall-clock time, expressed
10206 in months, days, and hours; the information is usually needed only by user programs
10207 such as <i>cron </i>and <i>syslogd</i>. Dealing with real-world time is usually best left to
10208 user space, where the C library offers better support; besides, such code is often too
10209 policy-related to belong in the kernel. There <i>is </i>a kernel function that turns a wallclock
10210 time into a <font class="fixd">jiffies</font> value, however:<br>
10211 <pre>
10212 #include <linux/time.h>
10213 unsigned long mktime (unsigned int year, unsigned int mon,
10214 unsigned int day, unsigned int hour,
10215 unsigned int min, unsigned int sec);
10216 </pre>
10217 To repeat: dealing directly with wall-clock time in a driver is often a sign that policy
10218 is being implemented and should therefore be questioned.<br>
10219 <br>
10220 While you won't have to deal with human-readable representations of the time,
10221 sometimes you need to deal with absolute timestamp even in kernel space. To this
10222 aim, <<i>linux/time.h> </i>exports the <i>do_gettimeofday </i>function. When called, it fills a<br>
10223 <br>
10224 <A name="189"></a><font color="blue">PAGE 189</font><br>
10225 <br>
10226 <font class="fixd">struct timeval</font> pointer--the same one used in the <i>gettimeofday </i>system call--with the
10227 familiar seconds and microseconds values. The prototype for <i>do_gettimeofday</i> is:<br>
10228 <pre>
10229 #include <linux/time.h>
10230 void do_gettimeofday(struct timeval *tv);
10231 </pre>
10232 The source states that <i>do_gettimeofday </i>has "near microsecond resolution," because it
10233 asks the timing hardware what fraction of the current jiffy has already elapsed. The
10234 precision varies from one architecture to another, however, since it depends on the
10235 actual hardware mechanisms in use. For example, some <i>m68knommu </i>processors,
10236 Sun3 systems, and other <i>m68k </i>systems cannot offer more than jiffy resolution. Pentium
10237 systems, on the other hand, offer very fast and precise subtick measures by
10238 reading the timestamp counter described earlier in this chapter.<br>
10239 <br>
10240 The current time is also available (though with jiffy granularity) from the <font class="fixd">xtime</font> variable,
10241 a <font class="fixd">struct timespec</font> value. Direct use of this variable is discouraged because it is
10242 difficult to atomically access both the fields. Therefore, the kernel offers the utility
10243 function <i>current_kernel_time</i>:<br>
10244 <pre>
10245 #include <linux/time.h>
10246 struct timespec current_kernel_time(void);
10247 </pre>
10248 Code for retrieving the current time in the various ways it is available within the <i>jit
10249 </i>("just in time") module in the source files provided on O'Reilly's FTP site. <i>jit </i>creates
10250 a file called <i>/proc/currentime</i>, which returns the following items in ASCII when read:<br>
10251 <ul>
10252 <li> The current <font class="fixd">jiffies</font> and <font class="fixd">jiffies_64</font> values as hex numbers
10253 <li> The current time as returned by <i>do_gettimeofday</i>
10254 <li> The <font class="fixd">timespec</font> returned by <i>current_kernel_time</i>
10255 </ul>
10256 We chose to use a dynamic <i>/proc </i>file to keep the boilerplate code to a minimum--it's
10257 not worth creating a whole device just to return a little textual information.<br>
10258 <br>
10259 The file returns text lines continuously as long as the module is loaded; each <i>read
10260 </i>system call collects and returns one set of data, organized in two lines for better readability.
10261 Whenever you read multiple data sets in less than a timer tick, you'll see the
10262 difference between <i>do_gettimeofday</i>, which queries the hardware, and the other values
10263 that are updated only when the timer ticks.<br>
10264 <pre>
10265 phon% <b>head -8 /proc/currentime
10266 </b>0x00bdbc1f 0x0000000100bdbc1f 1062370899.630126
10267 1062370899.629161488
10268 0x00bdbc1f 0x0000000100bdbc1f 1062370899.630150
10269 1062370899.629161488
10270 0x00bdbc20 0x0000000100bdbc20 1062370899.630208
10271 1062370899.630161336
10272 0x00bdbc20 0x0000000100bdbc20 1062370899.630233
10273 1062370899.630161336
10274 </pre>
10275 In the screenshot above, there are two interesting things to note. First, the <i>current_kernel_time</i> value,
10276 though expressed in nanoseconds, has only clock-tick granularity;<br>
10277 <br>
10278 <A name="190"></a><font color="blue">PAGE 190</font><br>
10279 <br>
10280 <i>do_gettimeofday </i>consistently reports a later time but not later than the next timer
10281 tick. Second, the 64-bit jiffies counter has the least-significant bit of the upper 32-bit
10282 word set. This happens because the default value for <font class="fixd">INITIAL_JIFFIES,</font> used at boot
10283 time to initialize the counter, forces a low-word overflow a few minutes after boot
10284 time to help detect problems related to that very overflow. This initial bias in the
10285 counter has no effect, because <font class="fixd">jiffies</font> is unrelated to wall-clock time. In <i>/proc/
10286 uptime</i>, where the kernel extracts the uptime from the counter, the initial bias is
10287 removed before conversion.<br>
10288 <br>
10289 <a name="DelayingExecution"></a><font color="red"><b>Delaying Execution</b></font><br>
10290 <br>
10291 Device drivers often need to delay the execution of a particular piece of code for a
10292 period of time, usually to allow the hardware to accomplish some task. In this section
10293 we cover a number of different techniques for achieving delays. The circumstances
10294 of each situation determine which technique is best to use; we go over them
10295 all, and point out the advantages and disadvantages of each.<br>
10296 <br>
10297 One important thing to consider is how the delay you need compares with the clock
10298 tick, considering the range of <font class="fixd">HZ</font> across the various platforms. Delays that are reliably
10299 longer than the clock tick, and don't suffer from its coarse granularity, can make use
10300 of the system clock. Very short delays typically must be implemented with software
10301 loops. In between these two cases lies a gray area. In this chapter, we use the phrase
10302 "long" delay to refer to a multiple-jiffy delay, which can be as low as a few milliseconds
10303 on some platforms, but is still long as seen by the CPU and the kernel.<br>
10304 <br>
10305 The following sections talk about the different delays by taking a somewhat long
10306 path from various intuitive but inappropriate solutions to the right solution. We
10307 chose this path because it allows a more in-depth discussion of kernel issues related
10308 to timing. If you are eager to find the right code, just skim through the section.<br>
10309 <br>
10310 <a name="LongDelays"></a><font color="red"><b>Long Delays</b></font><br>
10311 <br>
10312 Occasionally a driver needs to delay execution for relatively long periods--more than
10313 one clock tick. There are a few ways of accomplishing this sort of delay; we start with
10314 the simplest technique, then proceed to the more advanced techniques.<br>
10315 <br>
10316 <a name="BusyWaiting"></a><font color="red"><b>Busy waiting</b></font><br>
10317 <br>
10318 If you want to delay execution by a multiple of the clock tick, allowing some slack in
10319 the value, the easiest (though not recommended) implementation is a loop that monitors
10320 the jiffy counter. The <i>busy-waiting </i>implementation usually looks like the following
10321 code, where <font class="fixd">j1</font> is the value of <font class="fixd">jiffies</font> at the expiration of the delay:<br>
10322 <pre>
10323 while (time_before(jiffies, j1))
10324 cpu_relax( );
10325 </pre>
10326 <A name="191"></a><font color="blue">PAGE 191</font><br>
10327 <br>
10328 The call to <i>cpu_relax </i>invokes an architecture-specific way of saying that you're not
10329 doing much with the processor at the moment. On many systems it does nothing at
10330 all; on symmetric multithreaded ("hyperthreaded") systems, it may yield the core to
10331 the other thread. In any case, this approach should definitely be avoided whenever
10332 possible. We show it here because on occasion you might want to run this code to
10333 better understand the internals of other code.<br>
10334 <br>
10335 So let's look at how this code works. The loop is guaranteed to work because <font class="fixd">jiffies</font>
10336 is declared as <font class="fixd">volatile</font> by the kernel headers and, therefore, is fetched from memory
10337 any time some C code accesses it. Although technically correct (in that it works as
10338 designed), this busy loop severely degrades system performance. If you didn't configure
10339 your kernel for preemptive operation, the loop completely locks the processor for
10340 the duration of the delay; the scheduler never preempts a process that is running in
10341 kernel space, and the computer looks completely dead until time <font class="fixd">j1</font> is reached. The
10342 problem is less serious if you are running a preemptive kernel, because, unless the
10343 code is holding a lock, some of the processor's time can be recovered for other uses.
10344 Busy waits are still expensive on preemptive systems, however.<br>
10345 <br>
10346 Still worse, if interrupts happen to be disabled when you enter the loop, <font class="fixd">jiffies</font>
10347 won't be updated, and the <font class="fixd">while</font> condition remains true forever. Running a preemptive
10348 kernel won't help either, and you'll be forced to hit the big red button.<br>
10349 <br>
10350 This implementation of delaying code is available, like the following ones, in the <i>jit
10351 </i>module. The <i>/proc/jit* </i>files created by the module delay a whole second each time
10352 you read a line of text, and lines are guaranteed to be 20 bytes each. If you want to
10353 test the busy-wait code, you can read <i>/proc/jitbusy</i>, which busy-loops for one second
10354 for each line it returns.<br>
10355 <br>
10356 <div class="warn">Be sure to read, at most, one line (or a few lines) at a time from <i>/proc/
10357 jitbusy</i>. The simplified kernel mechanism to register <i>/proc </i>files invokes
10358 the <i>read </i>method over and over to fill the data buffer the user
10359 requested. Therefore, a command such as <i>cat /proc/jitbusy</i>, if it reads 4
10360 KB at a time, freezes the computer for 205 seconds.</div>
10361 <br>
10362 The suggested command to read <i>/proc/jitbusy </i>is <i>dd bs=20 < /proc/jitbusy</i>, optionally
10363 specifying the number of blocks as well. Each 20-byte line returned by the file represents
10364 the value the jiffy counter had before and after the delay. This is a sample run
10365 on an otherwise unloaded computer:<br>
10366 <pre>
10367 phon% <b>dd bs=20 count=5 < /proc/jitbusy</b>
10368 1686518 1687518
10369 1687519 1688519
10370 1688520 1689520
10371 1689520 1690520
10372 1690521 1691521
10373 </pre>
10374 <A name="192"></a><font color="blue">PAGE 192</font><br>
10375 <br>
10376 All looks good: delays are exactly one second (1000 jiffies), and the next <i>read </i>system
10377 call starts immediately after the previous one is over. But let's see what happens on a
10378 system with a large number of CPU-intensive processes running (and nonpreemptive
10379 kernel):<br>
10380 <pre>
10381 phon% <b>dd bs=20 count=5 < /proc/jitbusy</b>
10382 1911226 1912226
10383 1913323 1914323
10384 1919529 1920529
10385 1925632 1926632
10386 1931835 1932835
10387 </pre>
10388 Here, each <i>read </i>system call delays exactly one second, but the kernel can take more
10389 than 5 seconds before scheduling the <i>dd </i>process so it can issue the next system call.
10390 That's expected in a multitasking system; CPU time is shared between all running
10391 processes, and a CPU-intensive process has its dynamic priority reduced. (A discussion
10392 of scheduling policies is outside the scope of this book.)<br>
10393 <br>
10394 The test under load shown above has been performed while running the <i>load50 </i>sample
10395 program. This program forks a number of processes that do nothing, but do it in
10396 a CPU-intensive way. The program is part of the sample files accompanying this
10397 book, and forks 50 processes by default, although the number can be specified on
10398 the command line. In this chapter, and elsewhere in the book, the tests with a loaded
10399 system have been performed with <i>load50</i> running in an otherwise idle computer.<br>
10400 <br>
10401 If you repeat the command while running a preemptible kernel, you'll find no noticeable
10402 difference on an otherwise idle CPU and the following behavior under load:<br>
10403 <pre>
10404 phon% <b>dd bs=20 count=5 < /proc/jitbusy</b>
10405 14940680 14942777
10406 14942778 14945430
10407 14945431 14948491
10408 14948492 14951960
10409 14951961 14955840
10410 </pre>
10411 Here, there is no significant delay between the end of a system call and the beginning
10412 of the next one, but the individual delays are far longer than one second: up to
10413 3.8 seconds in the example shown and increasing over time. These values demonstrate
10414 that the process has been interrupted during its delay, scheduling other processes.
10415 The gap between system calls is not the only scheduling option for this
10416 process, so no special delay can be seen there.<br>
10417 <br>
10418 <a name="YieldingTheProcessor"></a><font color="red"><b>Yielding the processor</b></font><br>
10419 <br>
10420 As we have seen, busy waiting imposes a heavy load on the system as a whole; we
10421 would like to find a better technique. The first change that comes to mind is to<br>
10422 <br>
10423 <A name="193"></a><font color="blue">PAGE 193</font><br>
10424 <br>
10425 explicitly release the CPU when we're not interested in it. This is accomplished by
10426 calling the <i>schedule</i> function, declared in <i><linux/sched.h></i>:<br>
10427 <pre>
10428 while (time_before(jiffies, j1)) {
10429 schedule( );
10430 }
10431 </pre>
10432 This loop can be tested by reading <i>/proc/jitsched </i>as we read <i>/proc/jitbusy </i>above. However,
10433 is still isn't optimal. The current process does nothing but release the CPU, but
10434 it remains in the run queue. If it is the only runnable process, it actually runs (it calls
10435 the scheduler, which selects the same process, which calls the scheduler, which...).
10436 In other words, the load of the machine (the average number of running processes) is
10437 at least one, and the idle task (process number 0, also called <i>swapper </i>for historical
10438 reasons) never runs. Though this issue may seem irrelevant, running the idle task
10439 when the computer is idle relieves the processor's workload, decreasing its temperature
10440 and increasing its lifetime, as well as the duration of the batteries if the computer
10441 happens to be your laptop. Moreover, since the process is actually executing
10442 during the delay, it is accountable for all the time it consumes.<br>
10443 <br>
10444 The behavior of <i>/proc/jitsched </i>is actually similar to running <i>/proc/jitbusy </i>under a preemptive
10445 kernel. This is a sample run, on an unloaded system:<br>
10446 <pre>
10447 phon% <b>dd bs=20 count=5 < /proc/jitsched</b>
10448 1760205 1761207
10449 1761209 1762211
10450 1762212 1763212
10451 1763213 1764213
10452 1764214 1765217
10453 </pre>
10454 It's interesting to note that each <i>read </i>sometimes ends up waiting a few clock ticks
10455 more than requested. This problem gets worse and worse as the system gets busy,
10456 and the driver could end up waiting longer than expected. Once a process releases
10457 the processor with <i>schedule</i>, there are no guarantees that the process will get the processor
10458 back anytime soon. Therefore, calling <i>schedule </i>in this manner is not a safe
10459 solution to the driver's needs, in addition to being bad for the computing system as a
10460 whole. If you test <i>jitsched </i>while running <i>load50</i>, you can see that the delay associated
10461 to each line is extended by a few seconds, because other processes are using the
10462 CPU when the timeout expires.<br>
10463 <br>
10464 <a name="Timeouts"></a><font color="red"><b>Timeouts</b></font><br>
10465 <br>
10466 The suboptimal delay loops shown up to now work by watching the jiffy counter
10467 without telling anyone. But the best way to implement a delay, as you may imagine,
10468 is usually to ask the kernel to do it for you. There are two ways of setting up jiffy-based
10469 timeouts, depending on whether your driver is waiting for other events or not.<br>
10470 <br>
10471 <A name="194"></a><font color="blue">PAGE 194</font><br>
10472 <br>
10473 If your driver uses a wait queue to wait for some other event, but you also want to be
10474 sure that it runs within a certain period of time, it can use <i>wait_event_timeout </i>or
10475 <i>wait_event_interruptible_timeout</i>:<br>
10476 <pre>
10477 #include <linux/wait.h>
10478 long wait_event_timeout(wait_queue_head_t q, condition, long timeout);
10479 long wait_event_interruptible_timeout(wait_queue_head_t q,
10480 condition, long timeout);
10481 </pre>
10482 These functions sleep on the given wait queue, but they return after the timeout
10483 (expressed in <font class="fixd">jiffies</font>) expires. Thus, they implement a bounded sleep that does not go
10484 on forever. Note that the timeout value represents the number of <font class="fixd">jiffies</font> to wait, not
10485 an absolute time value. The value is represented by a signed number, because it
10486 sometimes is the result of a subtraction, although the functions complain through a
10487 <i>printk </i>statement if the provided timeout is negative. If the timeout expires, the functions
10488 return 0; if the process is awakened by another event, it returns the remaining
10489 delay expressed in <font class="fixd">jiffies</font>. The return value is never negative, even if the delay is
10490 greater than expected because of system load.<br>
10491 <br>
10492 The <i>/proc/jitqueue </i>file shows a delay based on <i>wait_event_interruptible_timeout</i>,
10493 although the module has no event to wait for, and uses 0 as a condition:<br>
10494 <pre>
10495 wait_queue_head_t wait;
10496 init_waitqueue_head (&wait);
10497 wait_event_interruptible_timeout(wait, 0, delay);
10498 </pre>
10499 The observed behaviour, when reading <i>/proc/jitqueue</i>, is nearly optimal, even under
10500 load:<br>
10501 <pre>
10502 phon% <b>dd bs=20 count=5 < /proc/jitqueue</b>
10503 2027024 2028024
10504 2028025 2029025
10505 2029026 2030026
10506 2030027 2031027
10507 2031028 2032028
10508 </pre>
10509 Since the reading process (<i>dd </i>above) is not in the run queue while waiting for the
10510 timeout, you see no difference in behavior whether the code is run in a preemptive
10511 kernel or not.<br>
10512 <br>
10513 <i>wait_event_timeout </i>and <i>wait_event_interruptible_timeout </i>were designed with a hardware
10514 driver in mind, where execution could be resumed in either of two ways: either
10515 somebody calls <i>wake_up </i>on the wait queue, or the timeout expires. This doesn't
10516 apply to <i>jitqueue</i>, as nobody ever calls <i>wake_up </i>on the wait queue (after all, no other
10517 code even knows about it), so the process always wakes up when the timeout
10518 expires. To accommodate for this very situation, where you want to delay execution
10519 waiting for no specific event, the kernel offers the <i>schedule_timeout </i>function so you
10520 can avoid declaring and using a superfluous wait queue head:<br>
10521 <pre>
10522 #include <linux/sched.h>
10523 signed long schedule_timeout(signed long timeout);
10524 </pre>
10525 <A name="195"></a><font color="blue">PAGE 195</font><br>
10526 <br>
10527 Here, <font class="fixd">timeout</font> is the number of jiffies to delay. The return value is 0 unless the function
10528 returns before the given timeout has elapsed (in response to a signal). <i>schedule_timeout
10529 </i>requires that the caller first set the current process state, so a typical call looks like:<br>
10530 <pre>
10531 set_current_state(TASK_INTERRUPTIBLE);
10532 schedule_timeout (delay);
10533 </pre>
10534 The previous lines (from <i>/proc/jitschedto</i>) cause the process to sleep until the given
10535 time has passed. Since <i>wait_event_interruptible_timeout </i>relies on <i>schedule_timeout
10536 </i>internally, we won't bother showing the numbers <i>jitschedto </i>returns, because they are
10537 the same as those of <i>jitqueue</i>. Once again, it is worth noting that an extra time interval
10538 could pass between the expiration of the timeout and when your process is actually
10539 scheduled to execute.<br>
10540 <br>
10541 In the example just shown, the first line calls <i>set_current_state </i>to set things up so that
10542 the scheduler won't run the current process again until the timeout places it back in
10543 <font class="fixd">TASK_RUNNING</font> state. To achieve an uninterruptible delay, use <font class="fixd">TASK_UNINTERRUPTIBLE</font>
10544 instead. If you forget to change the state of the current process, a call to <i>schedule_
10545 timeout </i>behaves like a call to <i>schedule </i>(i.e., the <i>jitsched </i>behavior), setting up a timer
10546 that is not used.<br>
10547 <br>
10548 If you want to play with the four <i>jit </i>files under different system situations or different
10549 kernels, or try other ways to delay execution, you may want to configure the
10550 amount of the delay when loading the module by setting the <i>delay</i> module parameter.<br>
10551 <br>
10552 <a name="ShortDelays"></a><font color="red"><b>Short Delays</b></font><br>
10553 <br>
10554 When a device driver needs to deal with latencies in its hardware, the delays involved
10555 are usually a few dozen microseconds at most. In this case, relying on the clock tick
10556 is definitely not the way to go.<br>
10557 <br>
10558 The kernel functions <i>ndelay</i>, <i>udelay</i>, and <i>mdelay </i>serve well for short delays, delaying
10559 execution for the specified number of nanoseconds, microseconds, or milliseconds
10560 respectively.* Their prototypes are:<br>
10561 <pre>
10562 #include <linux/delay.h>
10563 void ndelay(unsigned long nsecs);
10564 void udelay(unsigned long usecs);
10565 void mdelay(unsigned long msecs);
10566 </pre>
10567 The actual implementations of the functions are in <i><asm/delay.h></i>, being architecture-specific,
10568 and sometimes build on an external function. Every architecture implements
10569 <i>udelay</i>, but the other functions may or may not be defined; if they are not,
10570 <i><linux/delay.h> </i>offers a default version based on <i>udelay</i>. In all cases, the delay
10571 achieved is at least the requested value but could be more; actually, no platform currently
10572 achieves nanosecond precision, although several ones offer submicrosecond<br>
10573 <br>
10574 * The u in <i>udelay</i> represents the Greek letter mu and stands for <i>micro</i>.<br>
10575 <br>
10576 <A name="196"></a><font color="blue">PAGE 196</font><br>
10577 <br>
10578 precision. Delaying more than the requested value is usually not a problem, as short
10579 delays in a driver are usually needed to wait for the hardware, and the requirements
10580 are to wait for <i>at least</i> a given time lapse.<br>
10581 <br>
10582 The implementation of <i>udelay </i>(and possibly <i>ndelay </i>too) uses a software loop based on
10583 the processor speed calculated at boot time, using the integer variable <font class="fixd">loops_per_jiffy</font>.
10584 If you want to look at the actual code, however, be aware that the <i>x86 </i>implementation
10585 is quite a complex one because of the different timing sources it uses, based on what
10586 CPU type is running the code.<br>
10587 <br>
10588 To avoid integer overflows in loop calculations, <i>udelay </i>and <i>ndelay </i>impose an upper
10589 bound in the value passed to them. If your module fails to load and displays an unresolved
10590 symbol, <i>__bad_udelay</i>, it means you called <i>udelay </i>with too large an argument.
10591 Note, however, that the compile-time check can be performed only on
10592 constant values and that not all platforms implement it. As a general rule, if you are
10593 trying to delay for thousands of nanoseconds, you should be using <i>udelay </i>rather than
10594 <i>ndelay</i>; similarly, millisecond-scale delays should be done with <i>mdelay </i>and not one
10595 of the finer-grained functions.<br>
10596 <br>
10597 It's important to remember that the three delay functions are busy-waiting; other
10598 tasks can't be run during the time lapse. Thus, they replicate, though on a different
10599 scale, the behavior of <i>jitbusy</i>. Thus, these functions should only be used when there
10600 is no practical alternative.<br>
10601 <br>
10602 There is another way of achieving millisecond (and longer) delays that does not
10603 involve busy waiting. The file <i><linux/delay.h></i> declares these functions:<br>
10604 <pre>
10605 void msleep(unsigned int millisecs);
10606 unsigned long msleep_interruptible(unsigned int millisecs);
10607 void ssleep(unsigned int seconds)
10608 </pre>
10609 The first two functions puts the calling process to sleep for the given number of
10610 <font class="fixd">millisecs.</font> A call to <i>msleep </i>is uninterruptible; you can be sure that the process sleeps
10611 for at least the given number of milliseconds. If your driver is sitting on a wait queue
10612 and you want a wakeup to break the sleep, use <i>msleep_interruptible</i>. The return value
10613 from <i>msleep_interruptible </i>is normally 0; if, however, the process is awakened early,
10614 the return value is the number of milliseconds remaining in the originally requested
10615 sleep period. A call to <i>ssleep </i>puts the process into an uninterruptible sleep for the
10616 given number of seconds.<br>
10617 <br>
10618 In general, if you can tolerate longer delays than requested, you should use
10619 <i>schedule_timeout</i>, <i>msleep</i>, or <i>ssleep</i>.<br>
10620 <br>
10621 <a name="KernelTimers"></a><font color="red"><b>Kernel Timers</b></font><br>
10622 <br>
10623 Whenever you need to schedule an action to happen later, without blocking the current
10624 process until that time arrives, kernel timers are the tool for you. These timers<br>
10625 <br>
10626 <A name="197"></a><font color="blue">PAGE 197</font><br>
10627 <br>
10628 are used to schedule execution of a function at a particular time in the future, based
10629 on the clock tick, and can be used for a variety of tasks; for example, polling a device
10630 by checking its state at regular intervals when the hardware can't fire interrupts.
10631 Other typical uses of kernel timers are turning off the floppy motor or finishing
10632 another lengthy shut down operation. In such cases, delaying the return from <i>close
10633 </i>would impose an unnecessary (and surprising) cost on the application program.
10634 Finally, the kernel itself uses the timers in several situations, including the implementation
10635 of <i>schedule_timeout</i>.<br>
10636 <br>
10637 A kernel timer is a data structure that instructs the kernel to execute a user-defined
10638 function with a user-defined argument at a user-defined time. The implementation
10639 resides in <i><linux/timer.h> </i>and <i>kernel/timer.c </i>and is described in detail in the section
10640 "The Implementation of Kernel Timers."<br>
10641 <br>
10642 The functions scheduled to run almost certainly do <i>not </i>run while the process that
10643 registered them is executing. They are, instead, run asynchronously. Until now,
10644 everything we have done in our sample drivers has run in the context of a process
10645 executing system calls. When a timer runs, however, the process that scheduled it
10646 could be asleep, executing on a different processor, or quite possibly has exited
10647 altogether.<br>
10648 <br>
10649 This asynchronous execution resembles what happens when a hardware interrupt
10650 happens (which is discussed in detail in Chapter 10). In fact, kernel timers are run as
10651 the result of a "software interrupt." When running in this sort of atomic context,
10652 your code is subject to a number of constraints. Timer functions must be atomic in
10653 all the ways we discussed in the section "Spinlocks and Atomic Context" in
10654 Chapter 1, but there are some additional issues brought about by the lack of a process
10655 context. We will introduce these constraints now; they will be seen again in several
10656 places in later chapters. Repetition is called for because the rules for atomic
10657 contexts must be followed assiduously, or the system will find itself in deep trouble.<br>
10658 <br>
10659 A number of actions require the context of a process in order to be executed. When
10660 you are outside of process context (i.e., in interrupt context), you must observe the
10661 following rules:<br>
10662 <ul>
10663 <li> No access to user space is allowed. Because there is no process context, there is
10664 no path to the user space associated with any particular process.
10665 <li> The <font class="fixd">current</font> pointer is not meaningful in atomic mode and cannot be used since
10666 the relevant code has no connection with the process that has been interrupted.
10667 <li> No sleeping or scheduling may be performed. Atomic code may not call <i>schedule </i>or
10668 a form of <i>wait_event</i>, nor may it call any other function that could sleep.
10669 For example, calling <i>kmalloc(..., GFP_KERNEL) </i>is against the rules. Semaphores
10670 also must not be used since they can sleep.
10671 </ul>
10672 <A name="198"></a><font color="blue">PAGE 198</font><br>
10673 <br>
10674 Kernel code can tell if it is running in interrupt context by calling the function <i>in_interrupt( )</i>,
10675 which takes no parameters and returns nonzero if the processor is currently
10676 running in interrupt context, either hardware interrupt or software interrupt.<br>
10677 <br>
10678 A function related to <i>in_interrupt( ) </i>is <i>in_atomic( )</i>. Its return value is nonzero whenever
10679 scheduling is not allowed; this includes hardware and software interrupt contexts
10680 as well as any time when a spinlock is held. In the latter case, current may be valid, but
10681 access to user space is forbidden, since it can cause scheduling to happen. Whenever
10682 you are using <i>in_interrupt( )</i>, you should really consider whether <i>in_atomic( ) </i>is what
10683 you actually mean. Both functions are declared in <i><asm/hardirq.h></i><br>
10684 <br>
10685 One other important feature of kernel timers is that a task can reregister itself to run
10686 again at a later time. This is possible because each <font class="fixd">timer_list</font> structure is unlinked
10687 from the list of active timers before being run and can, therefore, be immediately relinked
10688 elsewhere. Although rescheduling the same task over and over might appear
10689 to be a pointless operation, it is sometimes useful. For example, it can be used to
10690 implement the polling of devices.<br>
10691 <br>
10692 It's also worth knowing that in an SMP system, the timer function is executed by the
10693 same CPU that registered it, to achieve better cache locality whenever possible.
10694 Therefore, a timer that reregisters itself always runs on the same CPU.<br>
10695 <br>
10696 An important feature of timers that should not be forgotten, though, is that they are
10697 a potential source of race conditions, even on uniprocessor systems. This is a direct
10698 result of their being asynchronous with other code. Therefore, any data structures
10699 accessed by the timer function should be protected from concurrent access, either by
10700 being atomic types (discussed in the section "Atomic Variables" in Chapter 1) or by
10701 using spinlocks (discussed in Chapter 5).<br>
10702 <br>
10703 <a name="TheTimerAPI"></a><font color="red"><b>The Timer API</b></font><br>
10704 <br>
10705 The kernel provides drivers with a number of functions to declare, register, and
10706 remove kernel timers. The following excerpt shows the basic building blocks:<br>
10707 <pre>
10708 #include <linux/timer.h>
10709 struct timer_list {
10710 /* ... */
10711 unsigned long expires;
10712 void (*function)(unsigned long);
10713 unsigned long data;
10714 };
10716 void init_timer(struct timer_list *timer);
10717 struct timer_list TIMER_INITIALIZER(_function, _expires, _data);
10719 void add_timer(struct timer_list * timer);
10720 int del_timer(struct timer_list * timer);
10721 </pre>
10722 <A name="199"></a><font color="blue">PAGE 199</font><br>
10723 <br>
10724 The data structure includes more fields than the ones shown, but those three are the
10725 ones that are meant to be accessed from outside the timer code iteslf. The <font class="fixd">expires</font>
10726 field represents the <font class="fixd">jiffies</font> value when the timer is expected to run; at that time, the
10727 function <i>function </i>is called with <font class="fixd">data</font> as an argument. If you need to pass multiple
10728 items in the argument, you can bundle them as a single data structure and pass a
10729 pointer cast to <font class="fixd">unsigned long</font>, a safe practice on all supported architectures and
10730 pretty common in memory management (as discussed in Chapter 15). The <font class="fixd">expires</font>
10731 value is not a <font class="fixd">jiffies_64</font> item because timers are not expected to expire very far in
10732 the future, and 64-bit operations are slow on 32-bit platforms.<br>
10733 <br>
10734 The structure must be initialized before use. This step ensures that all the fields are
10735 properly set up, including the ones that are opaque to the caller. Initialization can be
10736 performed by calling <i>init_timer </i>or assigning <font class="fixd">TIMER_INITIALIZER</font> to a static structure,
10737 according to your needs. After initialization, you can change the three public fields
10738 before calling <i>add_timer</i>. To disable a registered timer before it expires, call <i>del_timer</i>.<br>
10739 <br>
10740 The <i>jit </i>module includes a sample file, <i>/proc/jitimer </i>(for "just in timer"), that returns
10741 one header line and six data lines. The data lines represent the current environment
10742 where the code is running; the first one is generated by the <i>read </i>file operation and
10743 the others by a timer. The following output was recorded while compiling a kernel:<br>
10744 <pre>
10745 phon% <b>cat /proc/jitimer
10746 </b> time delta inirq pid cpu command
10747 33565837 0 0 1269 0 cat
10748 33565847 10 1 1271 0 sh
10749 33565857 10 1 1273 0 cpp0
10750 33565867 10 1 1273 0 cpp0
10751 33565877 10 1 1274 0 cc1
10752 33565887 10 1 1274 0 cc1
10753 </pre>
10754 In this output, the time field is the value of <font class="fixd">jiffies</font> when the code runs, delta is the
10755 change in <font class="fixd">jiffies</font> since the previous line, <font class="fixd">inirq</font> is the Boolean value returned by <i>in_interrupt</i>,
10756 <font class="fixd">pid</font> and <font class="fixd">command</font> refer to the current process, and <font class="fixd">cpu</font> is the number of the
10757 CPU being used (always 0 on uniprocessor systems).<br>
10758 <br>
10759 If you read <i>/proc/jitimer </i>while the system is unloaded, you'll find that the context of
10760 the timer is process 0, the idle task, which is called "swapper" mainly for historical
10761 reasons.<br>
10762 <br>
10763 The timer used to generate <i>/proc/jitimer </i>data is run every 10 <font class="fixd">jiffies</font> by default, but you
10764 can change the value by setting the tdelay (timer delay) parameter when loading the
10765 module.<br>
10766 <br>
10767 The following code excerpt shows the part of <i>jit </i>related to the <i>jitimer </i>timer. When a
10768 process attempts to read our file, we set up the timer as follows:<br>
10769 <pre>
10770 unsigned long j = jiffies;
10772 /* fill the data for our timer function */
10773 data->prevjiffies = j;
10774 </pre>
10775 <A name="200"></a><font color="blue">PAGE 200</font><br>
10776 <pre>
10777 data->buf = buf2;
10778 data->loops = JIT_ASYNC_LOOPS;
10780 /* register the timer */
10781 data->timer.data = (unsigned long)data;
10782 data->timer.function = jit_timer_fn;
10783 data->timer.expires = j + tdelay; /* parameter */
10784 add_timer(&data->timer);
10786 /* wait for the buffer to fill */
10787 wait_event_interruptible(data->wait, !data->loops);
10788 </pre>
10789 The actual timer function looks like this:<br>
10790 <pre>
10791 void jit_timer_fn(unsigned long arg)
10792 {
10793 struct jit_data *data = (struct jit_data *)arg;
10794 unsigned long j = jiffies;
10795 data->buf += sprintf(data->buf, "%9li %3li %i %6i %i %s\n",
10796 j, j - data->prevjiffies, in_interrupt( ) ? 1 : 0,
10797 current->pid, smp_processor_id( ), current->comm);
10799 if (--data->loops) {
10800 data->timer.expires += tdelay;
10801 data->prevjiffies = j;
10802 add_timer(&data->timer);
10803 } else {
10804 wake_up_interruptible(&data->wait);
10805 }
10806 }
10807 </pre>
10808 The timer API includes a few more functions than the ones introduced above. The
10809 following set completes the list of kernel offerings:<br>
10810 <br>
10811 <font class="fixd">int mod_timer(struct timer_list *timer, unsigned long expires);</font><br>
10812 <div class="bq">
10813 Updates the expiration time of a timer, a common task for which a timeout
10814 timer is used (again, the motor-off floppy timer is a typical example). <i>mod_timer
10815 </i>can be called on inactive timers as well, where you normally use <i>add_timer</i>.</div>
10816 <br>
10817 <font class="fixd">int del_timer_sync(struct timer_list *timer);</font><br>
10818 <div class="bq">
10819 Works like <i>del_timer</i>, but also guarantees that when it returns, the timer function
10820 is not running on any CPU. <i>del_timer_sync </i>is used to avoid race conditions
10821 on SMP systems and is the same as <i>del_timer </i>in UP kernels. This function should
10822 be preferred over <i>del_timer </i>in most situations. This function can sleep if it is
10823 called from a nonatomic context but busy waits in other situations. Be very careful
10824 about calling <i>del_timer_sync </i>while holding locks; if the timer function
10825 attempts to obtain the same lock, the system can deadlock. If the timer function
10826 reregisters itself, the caller must first ensure that this reregistration will not happen;
10827 this is usually accomplished by setting a "shutting down" flag, which is
10828 checked by the timer function.</div>
10829 <br>
10830 <A name="201"></a><font color="blue">PAGE 201</font><br>
10831 <br>
10832 <font class="fixd">int timer_pending(const struct timer_list * timer);</font><br>
10833 <div class="bq">
10834 Returns true or false to indicate whether the timer is currently scheduled to run
10835 by reading one of the opaque fields of the structure.</div>
10836 <br>
10837 <a name="TheImplementationOfKernelTimers"></a><font color="red"><b>The Implementation of Kernel Timers</b></font><br>
10838 <br>
10839 Although you won't need to know how kernel timers are implemented in order to
10840 use them, the implementation is interesting, and a look at its internals is worthwhile.<br>
10841 <br>
10842 The implementation of the timers has been designed to meet the following requirements
10843 and assumptions:<br>
10844 <ul>
10845 <li> Timer management must be as lightweight as possible.
10846 <li> The design should scale well as the number of active timers increases.
10847 <li> Most timers expire within a few seconds or minutes at most, while timers with
10848 long delays are pretty rare.
10849 <li> A timer should run on the same CPU that registered it.
10850 </ul>
10851 The solution devised by kernel developers is based on a per-CPU data structure. The
10852 <i>timer_list </i>structure includes a pointer to that data structure in its <font class="fixd">base</font> field. If <font class="fixd">base</font> is
10853 <font class="fixd">NULL</font>, the timer is not scheduled to run; otherwise, the pointer tells which data structure
10854 (and, therefore, which CPU) runs it. Per-CPU data items are described in the
10855 section "Per-CPU Variables" in Chapter 8.<br>
10856 <br>
10857 Whenever kernel code registers a timer (via <i>add_timer </i>or <i>mod_timer</i>), the operation
10858 is eventually performed by <i>internal_add_timer </i>(in <font class="fixd">kernel/timer.c</font>) which, in turn,
10859 adds the new timer to a double-linked list of timers within a "cascading table" associated
10860 to the current CPU.<br>
10861 <br>
10862 The cascading table works like this: if the timer expires in the next 0 to 255 <font class="fixd">jiffies</font>, it
10863 is added to one of the 256 lists devoted to short-range timers using the least significant
10864 bits of the <font class="fixd">expires</font> field. If it expires farther in the future (but before 16,384 <font class="fixd">jiffies</font>),
10865 it is added to one of 64 lists based on bits 9-14 of the <font class="fixd">expires</font> field. For timers
10866 expiring even farther, the same trick is used for bits 15-20, 21-26, and 27-31. Timers
10867 with an expire field pointing still farther in the future (something that can happen
10868 only on 64-bit platforms) are hashed with a delay value of <font class="fixd">0xffffffff</font>, and
10869 timers with <font class="fixd">expires</font> in the past are scheduled to run at the next timer tick. (A timer
10870 that is already expired may sometimes be registered in high-load situations, especially
10871 if you run a preemptible kernel.)<br>
10872 <br>
10873 When <i>__run_timers </i>is fired, it executes all pending timers for the current timer tick.
10874 If <font class="fixd">jiffies</font> is currently a multiple of 256, the function also rehashes one of the next level
10875 lists of timers into the 256 short-term lists, possibly cascading one or more of
10876 the other levels as well, according to the bit representation of <font class="fixd">jiffies</font>.<br>
10877 <br>
10878 <A name="202"></a><font color="blue">PAGE 202</font><br>
10879 <br>
10880 This approach, while exceedingly complex at first sight, performs very well both with
10881 few timers and with a large number of them. The time required to manage each
10882 active timer is independent of the number of timers already registered and is limited
10883 to a few logic operations on the binary representation of its <font class="fixd">expires</font> field. The only
10884 cost associated with this implementation is the memory for the 512 list heads (256
10885 short-term lists and 4 groups of 64 more lists)--i.e., 4 KB of storage.<br>
10886 <br>
10887 The function <i>__run_timers</i>, as shown by <i>/proc/jitimer</i>, is run in atomic context. In
10888 addition to the limitations we already described, this brings in an interesting feature:
10889 the timer expires at just the right time, even if you are not running a preemptible kernel,
10890 and the CPU is busy in kernel space. You can see what happens when you read
10891 <i>/proc/jitbusy </i>in the background and <i>/proc/jitimer </i>in the foreground. Although the system
10892 appears to be locked solid by the busy-waiting system call, the kernel timers still
10893 work fine.<br>
10894 <br>
10895 Keep in mind, however, that a kernel timer is far from perfect, as it suffers from jitter
10896 and other artifacts induced by hardware interrupts, as well as other timers and other
10897 asynchronous tasks. While a timer associated with simple digital I/O can be enough
10898 for simple tasks like running a stepper motor or other amateur electronics, it is usually
10899 not suitable for production systems in industrial environments. For such tasks,
10900 you'll most likely need to resort to a real-time kernel extension.<br>
10901 <br>
10902 <a name="Tasklets"></a><font color="red"><b>Tasklets</b></font><br>
10903 <br>
10904 Another kernel facility related to timing issues is the <i>tasklet </i>mechanism. It is mostly
10905 used in interrupt management (we'll see it again in Chapter 10.)<br>
10906 <br>
10907 Tasklets resemble kernel timers in some ways. They are always run at interrupt time,
10908 they always run on the same CPU that schedules them, and they receive an <font class="fixd">unsigned long</font>
10909 argument. Unlike kernel timers, however, you can't ask to execute the function
10910 at a specific time. By scheduling a tasklet, you simply ask for it to be executed at a
10911 later time chosen by the kernel. This behavior is especially useful with interrupt handlers,
10912 where the hardware interrupt must be managed as quickly as possible, but
10913 most of the data management can be safely delayed to a later time. Actually, a
10914 tasklet, just like a kernel timer, is executed (in atomic mode) in the context of a "soft
10915 interrupt," a kernel mechanism that executes asynchronous tasks with hardware
10916 interrupts enabled.<br>
10917 <br>
10918 A tasklet exists as a data structure that must be initialized before use. Initialization
10919 can be performed by calling a specific function or by declaring the structure using
10920 certain macros:<br>
10921 <pre>
10922 #include <linux/interrupt.h>
10924 struct tasklet_struct {
10925 /* ... */
10926 </pre>
10927 <A name="203"></a><font color="blue">PAGE 203</font><br>
10928 <pre>
10929 void (*func)(unsigned long);
10930 unsigned long data;
10931 };
10933 void tasklet_init(struct tasklet_struct *t,
10934 void (*func)(unsigned long), unsigned long data);
10935 DECLARE_TASKLET(name, func, data);
10936 DECLARE_TASKLET_DISABLED(name, func, data);
10937 </pre>
10938 Tasklets offer a number of interesting features:<br>
10939 <ul>
10940 <li> A tasklet can be disabled and re-enabled later; it won't be executed until it is
10941 enabled as many times as it has been disabled.
10942 <li> Just like timers, a tasklet can reregister itself.
10943 <li> A tasklet can be scheduled to execute at normal priority or high priority. The latter group is always executed first.
10944 <li> Tasklets may be run immediately if the system is not under heavy load but never
10945 later than the next timer tick.
10946 <li> A tasklets can be concurrent with other tasklets but is strictly serialized with
10947 respect to itself--the same tasklet never runs simultaneously on more than one
10948 processor. Also, as already noted, a tasklet always runs on the same CPU that
10949 schedules it.
10950 </ul>
10951 The <i>jit </i>module includes two files, <i>/proc/jitasklet </i>and <i>/proc/jitasklethi</i>, that return the
10952 same data as <i>/proc/jitimer</i>, introduced in the section "Kernel Timers." When you
10953 read one of the files, you get back a header and six data lines. The first data line
10954 describes the context of the calling process, and the other lines describe the context
10955 of successive runs of a tasklet procedure. This is a sample run while compiling a kernel:<br>
10956 <pre>
10957 phon% <b>cat /proc/jitasklet
10958 </b> time delta inirq pid cpu command
10959 6076139 0 0 4370 0 cat
10960 6076140 1 1 4368 0 cc1
10961 6076141 1 1 4368 0 cc1
10962 6076141 0 1 2 0 ksoftirqd/0
10963 6076141 0 1 2 0 ksoftirqd/0
10964 6076141 0 1 2 0 ksoftirqd/0
10965 </pre>
10966 As confirmed by the above data, the tasklet is run at the next timer tick as long as the
10967 CPU is busy running a process, but it is run immediately when the CPU is otherwise
10968 idle. The kernel provides a set of <i>ksoftirqd </i>kernel threads, one per CPU, just to run
10969 "soft interrupt" handlers, such as the <i>tasklet_action </i>function. Thus, the final three
10970 runs of the tasklet take place in the context of the <i>ksoftirqd </i>kernel thread associated
10971 to CPU 0. The <i>jitasklethi </i>implementation uses a high-priority tasklet, explained in an
10972 upcoming list of functions.<br>
10973 <br>
10974 The actual code in <i>jit </i>that implements <i>/proc/jitasklet </i>and <i>/proc/jitasklethi </i>is almost
10975 identical to the code that implements <i>/proc/jitimer</i>, but it uses the tasklet calls instead<br>
10976 <br>
10977 <A name="204"></a><font color="blue">PAGE 204</font><br>
10978 <br>
10979 of the timer ones. The following list lays out in detail the kernel interface to tasklets
10980 after the tasklet structure has been initialized:<br>
10981 <br>
10982 <font class="fixd">void tasklet_disable(struct tasklet_struct *t);</font><br>
10983 <div class="bq">
10984 This function disables the given tasklet. The tasklet may still be scheduled with
10985 <i>tasklet_schedule</i>, but its execution is deferred until the tasklet has been enabled
10986 again. If the tasklet is currently running, this function busy-waits until the tasklet
10987 exits; thus, after calling <i>tasklet_disable</i>, you can be sure that the tasklet is not
10988 running anywhere in the system.</div>
10989 <br>
10990 <font class="fixd">void tasklet_disable_nosync(struct tasklet_struct *t);</font><br>
10991 <div class="bq">
10992 Disable the tasklet, but without waiting for any currently-running function to
10993 exit. When it returns, the tasklet is disabled and won't be scheduled in the future
10994 until re-enabled, but it may be still running on another CPU when the function
10995 returns.</div>
10996 <br>
10997 <font class="fixd">void tasklet_enable(struct tasklet_struct *t);</font><br>
10998 <div class="bq">
10999 Enables a tasklet that had been previously disabled. If the tasklet has already
11000 been scheduled, it will run soon. A call to <i>tasklet_enable </i>must match each call to
11001 <i>tasklet_disable</i>, as the kernel keeps track of the "disable count" for each tasklet.</div>
11002 <br>
11003 <font class="fixd">void tasklet_schedule(struct tasklet_struct *t);</font><br>
11004 <div class="bq">
11005 Schedule the tasklet for execution. If a tasklet is scheduled again before it has a
11006 chance to run, it runs only once. However, if it is scheduled <i>while </i>it runs, it runs
11007 again after it completes; this ensures that events occurring while other events are
11008 being processed receive due attention. This behavior also allows a tasklet to
11009 reschedule itself.</div>
11010 <br>
11011 <font class="fixd">void tasklet_hi_schedule(struct tasklet_struct *t);</font><br>
11012 <div class="bq">
11013 Schedule the tasklet for execution with higher priority. When the soft interrupt
11014 handler runs, it deals with high-priority tasklets before other soft interrupt tasks,
11015 including "normal" tasklets. Ideally, only tasks with low-latency requirements
11016 (such as filling the audio buffer) should use this function, to avoid the additional
11017 latencies introduced by other soft interrupt handlers. Actually, <i>/proc/
11018 jitasklethi</i> shows no human-visible difference from <i>/proc/jitasklet</i>.</div>
11019 <br>
11020 <font class="fixd">void tasklet_kill(struct tasklet_struct *t);</font><br>
11021 <div class="bq">
11022 This function ensures that the tasklet is not scheduled to run again; it is usually
11023 called when a device is being closed or the module removed. If the tasklet is
11024 scheduled to run, the function waits until it has executed. If the tasklet reschedules
11025 itself, you must prevent it from rescheduling itself before calling <i>tasklet_kill</i>,
11026 as with <i>del_timer_sync</i>.</div>
11027 <br>
11028 Tasklets are implemented in <i>kernel/softirq.c</i>. The two tasklet lists (normal and high priority)
11029 are declared as per-CPU data structures, using the same CPU-affinity mechanism
11030 used by kernel timers. The data structure used in tasklet management is a simple
11031 linked list, because tasklets have none of the sorting requirements of kernel
11032 timers.<br>
11033 <br>
11034 <A name="205"></a><font color="blue">PAGE 205</font><br>
11035 <br>
11036 <a name="Workqueues"></a><font color="red"><b>Workqueues</b></font><br>
11037 <br>
11038 <i>Workqueues </i>are, superficially, similar to tasklets; they allow kernel code to request
11039 that a function be called at some future time. There are, however, some significant
11040 differences between the two, including:<br>
11041 <ul>
11042 <li> Tasklets run in software interrupt context with the result that all tasklet code
11043 must be atomic. Instead, workqueue functions run in the context of a special
11044 kernel process; as a result, they have more flexibility. In particular, workqueue
11045 functions can sleep.
11046 <li> Tasklets always run on the processor from which they were originally submitted.
11047 Work-queues work in the same way, by default.
11048 <li> Kernel code can request that the execution of workqueue functions be delayed
11049 for an explicit interval.
11050 </ul>
11051 The key difference between the two is that tasklets execute quickly, for a short period
11052 of time, and in atomic mode, while workqueue functions may have higher latency but
11053 need not be atomic. Each mechanism has situations where it is appropriate.<br>
11054 <br>
11055 Workqueues have a type of struct <font class="fixd">workqueue_struct,</font> which is defined in <i><linux/
11056 workqueue.h></i>. A workqueue must be explicitly created before use, using one of the
11057 following two functions:<br>
11058 <pre>
11059 struct workqueue_struct *create_workqueue(const char *name);
11060 struct workqueue_struct *create_singlethread_workqueue(const char *name);
11061 </pre>
11062 Each workqueue has one or more dedicated processes ("kernel threads"), which run
11063 functions submitted to the queue. If you use <i>create_workqueue</i>, you get a workqueue
11064 that has a dedicated thread for each processor on the system. In many cases,
11065 all those threads are simply overkill; if a single worker thread will suffice, create the
11066 workqueue with <i>create_singlethread_workqueue</i> instead.<br>
11067 <br>
11068 To submit a task to a workqueue, you need to fill in a <font class="fixd">work_struct</font> structure. This
11069 can be done at compile time as follows:<br>
11070 <pre>
11071 DECLARE_WORK(name, void (*function)(void *), void *data);
11072 </pre>
11073 Where name is the name of the structure to be declared, function is the function that is
11074 to be called from the workqueue, and data is a value to pass to that function. If you
11075 need to set up the <font class="fixd">work_struct</font> structure at runtime, use the following two macros:<br>
11076 <pre>
11077 INIT_WORK(struct work_struct *work, void (*function)(void *), void *data);
11078 PREPARE_WORK(struct work_struct *work, void (*function)(void *), void *data);
11079 </pre>
11080 <i><font class="fixd">INIT_WORK</font> </i>does a more thorough job of initializing the structure; you should use
11081 it the first time that structure is set up. <i><font class="fixd">PREPARE_WORK</font> </i>does almost the same job,
11082 but it does not initialize the pointers used to link the <font class="fixd">work_struct</font> structure into the
11083 workqueue. If there is any possibility that the structure may currently be submitted<br>
11084 <br>
11085 <A name="206"></a><font color="blue">PAGE 206</font><br>
11086 <br>
11087 to a workqueue, and you need to change that structure, use <i>PREPARE_WORK</i>
11088 rather than <i>INIT_WORK</i>.<br>
11089 <br>
11090 There are two functions for submitting work to a workqueue:<br>
11091 <pre>
11092 int queue_work(struct workqueue_struct *queue, struct work_struct *work);
11093 int queue_delayed_work(struct workqueue_struct *queue,
11094 struct work_struct *work, unsigned long delay);
11095 </pre>
11096 Either one adds work to the given <font class="fixd">queue.</font> If <i>queue_delayed_work </i>is used, however, the
11097 actual work is not performed until at least <font class="fixd">delay</font> jiffies have passed. The return value
11098 from these functions is 0 if the work was successfully added to the queue; a nonzero
11099 result means that this <font class="fixd">work_struct</font> structure was already waiting in the queue, and
11100 was not added a second time.<br>
11101 <br>
11102 At some time in the future, the work function will be called with the given data
11103 value. The function will be running in the context of the worker thread, so it can
11104 sleep if need be--although you should be aware of how that sleep might affect any
11105 other tasks submitted to the same workqueue. What the function cannot do, however,
11106 is access user space. Since it is running inside a kernel thread, there simply is no
11107 user space to access.<br>
11108 <br>
11109 Should you need to cancel a pending workqueue entry, you may call:<br>
11110 <pre>
11111 int cancel_delayed_work(struct work_struct *work);
11112 </pre>
11113 The return value is nonzero if the entry was canceled before it began execution. The
11114 kernel guarantees that execution of the given entry will not be initiated after a call to
11115 <i>cancel_delayed_work</i>. If <i>cancel_delayed_work </i>returns 0, however, the entry may have
11116 already been running on a different processor, and might still be running after a call
11117 to <i>cancel_delayed_work</i>. To be absolutely sure that the work function is not running
11118 anywhere in the system after <i>cancel_delayed_work </i>returns 0, you must follow that
11119 call with a call to:<br>
11120 <pre>
11121 void flush_workqueue(struct workqueue_struct *queue);
11122 </pre>
11123 After <i>flush_workqueue </i>returns, no work function submitted prior to the call is running
11124 anywhere in the system.<br>
11125 <br>
11126 When you are done with a workqueue, you can get rid of it with:<br>
11127 <pre>
11128 void destroy_workqueue(struct workqueue_struct *queue);
11129 </pre>
11130 <a name="TheSharedQueue"></a><font color="red"><b>The Shared Queue</b></font><br>
11131 <br>
11132 A device driver, in many cases, does not need its own workqueue. If you only submit
11133 tasks to the queue occasionally, it may be more efficient to simply use the shared,
11134 default workqueue that is provided by the kernel. If you use this queue, however,
11135 you must be aware that you will be sharing it with others. Among other things, that
11136 means that you should not monopolize the queue for long periods of time (no long
11137 sleeps), and it may take longer for your tasks to get their turn in the processor.<br>
11138 <br>
11139 <A name="207"></a><font color="blue">PAGE 207</font><br>
11140 <br>
11141 The <i>jiq </i>("just in queue") module exports two files that demonstrate the use of the
11142 shared workqueue. They use a single <font class="fixd">work_struct</font> structure, which is set up this way:<br>
11143 <pre>
11144 static struct work_struct jiq_work;
11146 /* this line is in jiq_init( ) */
11147 INIT_WORK(&jiq_work, jiq_print_wq, &jiq_data);
11148 </pre>
11149 When a process reads <i>/proc/jiqwq</i>, the module initiates a series of trips through the
11150 shared workqueue with no delay. The function it uses is:<br>
11151 <pre>
11152 int schedule_work(struct work_struct *work);
11153 </pre>
11154 Note that a different function is used when working with the shared queue; it
11155 requires only the <font class="fixd">work_struct</font> structure for an argument. The actual code in <i>jiq </i>looks
11156 like this:<br>
11157 <pre>
11158 prepare_to_wait(&jiq_wait, &wait, TASK_INTERRUPTIBLE);
11159 schedule_work(&jiq_work);
11160 schedule( );
11161 finish_wait(&jiq_wait, &wait);
11162 </pre>
11163 The actual work function prints out a line just like the <i>jit </i>module does, then, if need
11164 be, resubmits the <font class="fixd">work_struct</font> structure into the workqueue. Here is <i>jiq_print_wq </i>in
11165 its entirety:<br>
11166 <pre>
11167 static void jiq_print_wq(void *ptr)
11168 {
11169 struct clientdata *data = (struct clientdata *) ptr;
11171 if (! <font class="fixd">jiq_print</font> (ptr))
11172 return;
11174 if (data->delay)
11175 schedule_delayed_work(&jiq_work, data->delay);
11176 else
11177 schedule_work(&jiq_work);
11178 }
11179 </pre>
11180 If the user is reading the delayed device (<i>/proc/jiqwqdelay</i>), the work function resubmits
11181 itself in the delayed mode with <i>schedule_delayed_work</i>:<br>
11182 <pre>
11183 int schedule_delayed_work(struct work_struct *work, unsigned long delay);
11184 </pre>
11185 If you look at the output from these two devices, it looks something like:<br>
11186 <pre>
11187 % <b>cat /proc/jiqwq
11188 </b> time delta preempt pid cpu command
11189 1113043 0 0 7 1 events/1
11190 1113043 0 0 7 1 events/1
11191 1113043 0 0 7 1 events/1
11192 1113043 0 0 7 1 events/1
11193 1113043 0 0 7 1 events/1
11194 % <b>cat /proc/jiqwqdelay
11195 </b> time delta preempt pid cpu command
11196 1122066 1 0 6 0 events/0
11197 </pre>
11198 <A name="208"></a><font color="blue">PAGE 208</font><br>
11199 <pre>
11200 1122067 1 0 6 0 events/0
11201 1122068 1 0 6 0 events/0
11202 1122069 1 0 6 0 events/0
11203 1122070 1 0 6 0 events/0
11204 </pre>
11205 When <i>/proc/jiqwq </i>is read, there is no obvious delay between the printing of each line.
11206 When, instead, <i>/proc/jiqwqdelay </i>is read, there is a delay of exactly one jiffy between
11207 each line. In either case, we see the same process name printed; it is the name of the
11208 kernel thread that implements the shared workqueue. The CPU number is printed
11209 after the slash; we never know which CPU will be running when the <i>/proc </i>file is read,
11210 but the work function will always run on the same processor thereafter.<br>
11211 <br>
11212 If you need to cancel a work entry submitted to the shared queue, you may use
11213 <i>cancel_delayed_work</i>, as described above. Flushing the shared workqueue requires a
11214 separate function, however:<br>
11215 <pre>
11216 void flush_scheduled_work(void);
11217 </pre>
11218 Since you do not know who else might be using this queue, you never really know
11219 how long it might take for <i>flush_scheduled_work</i> to return.<br>
11220 <br>
11221 <a name="QuickReference7"></a><font color="red"><b>Quick Reference</b></font><br>
11222 <br>
11223 This chapter introduced the following symbols.<br>
11224 <br>
11225 <a name="Timekeeping"></a><font color="red"><b>Timekeeping</b></font><br>
11226 <br>
11227 <font class="fixd">#include <linux/param.h><br>
11228 HZ</font><br>
11229 <div class="bq">
11230 The <font class="fixd">HZ</font> symbol specifies the number of clock ticks generated per second.</div>
11231 <br>
11232 <font class="fixd">#include <linux/jiffies.h><br>
11233 volatile unsigned long jiffies<br>
11234 u64 jiffies_64</font><br>
11235 <div class="bq">
11236 The <font class="fixd">jiffies_64</font> variable is incremented once for each clock tick; thus, it's incremented
11237 <font class="fixd">HZ</font> times per second. Kernel code most often refers to <font class="fixd">jiffies</font>, which is
11238 the same as <font class="fixd">jiffies_64</font> on 64-bit platforms and the least significant half of it on
11239 32-bit platforms.</div>
11240 <br>
11241 <font class="fixd">int time_after(unsigned long a, unsigned long b);<br>
11242 int time_before(unsigned long a, unsigned long b);<br>
11243 int time_after_eq(unsigned long a, unsigned long b);<br>
11244 int time_before_eq(unsigned long a, unsigned long b);</font><br>
11245 <div class="bq">
11246 These Boolean expressions compare jiffies in a safe way, without problems in
11247 case of counter overflow and without the need to access <font class="fixd">jiffies_64</font>.</div>
11248 <br>
11249 <font class="fixd">u64 get_jiffies_64(void);</font><br>
11250 <div class="bq">
11251 Retrieves <font class="fixd">jiffies_64</font> without race conditions.</div>
11252 <br>
11253 <A name="209"></a><font color="blue">PAGE 209</font><br>
11254 <br>
11255 <font class="fixd">#include <linux/time.h><br>
11256 unsigned long timespec_to_jiffies(struct timespec *value);<br>
11257 void jiffies_to_timespec(unsigned long jiffies, struct timespec *value);<br>
11258 unsigned long timeval_to_jiffies(struct timeval *value);<br>
11259 void jiffies_to_timeval(unsigned long jiffies, struct timeval *value);</font><br>
11260 <div class="bq">
11261 Converts time representations between jiffies and other representations.</div>
11262 <br>
11263 <font class="fixd">#include <asm/msr.h><br>
11264 rdtsc(low32,high32);<br>
11265 rdtscl(low32);<br>
11266 rdtscll(var32);</font><br>
11267 <div class="bq">
11268 x86-specific macros to read the timestamp counter. They read it as two 32-bit
11269 halves, read only the lower half, or read all of it into a <font class="fixd">long long</font> variable.</div>
11270 <br>
11271 <font class="fixd">#include <linux/timex.h><br>
11272 cycles_t get_cycles(void);</font><br>
11273 <div class="bq">
11274 Returns the timestamp counter in a platform-independent way. If the CPU offers
11275 no timestamp feature, 0 is returned.</div>
11276 <br>
11277 <font class="fixd">#include <linux/time.h><br>
11278 unsigned long mktime(year, mon, day, h, m, s);</font><br>
11279 <div class="bq">
11280 Returns the number of seconds since the Epoch, based on the six <font class="fixd">unsigned int</font>
11281 arguments.</div>
11282 <br>
11283 <font class="fixd">void do_gettimeofday(struct timeval *tv);</font><br>
11284 <div class="bq">
11285 Returns the current time, as seconds and microseconds since the Epoch, with the
11286 best resolution the hardware can offer. On most platforms the resolution is one
11287 microsecond or better, although some platforms offer only jiffies resolution.</div>
11288 <br>
11289 <font class="fixd">struct timespec current_kernel_time(void);</font><br>
11290 <div class="bq">
11291 Returns the current time with the resolution of one jiffy.</div>
11292 <br>
11293 <a name="Delays"></a><font color="red"><b>Delays</b></font><br>
11294 <br>
11295 <font class="fixd">#include <linux/wait.h><br>
11296 long wait_event_interruptible_timeout(wait_queue_head_t *q, condition, signed long timeout);</font><br>
11297 <div class="bq">
11298 Puts the current process to sleep on the wait queue, installing a timeout value
11299 expressed in jiffies. Use <i>schedule_timeout</i> (below) for noninterruptible sleeps.</div>
11300 <br>
11301 <font class="fixd">#include <linux/sched.h><br>
11302 signed long schedule_timeout(signed long timeout);</font><br>
11303 <div class="bq">
11304 Calls the scheduler after ensuring that the current process is awakened at timeout
11305 expiration. The caller must invoke <i>set_current_state </i>first to put itself in an
11306 interruptible or noninterruptible sleep state.</div>
11307 <br>
11308 <A name="210"></a><font color="blue">PAGE 210</font><br>
11309 <br>
11310 <font class="fixd">#include <linux/delay.h><br>
11311 void ndelay(unsigned long nsecs);<br>
11312 void udelay(unsigned long usecs);<br>
11313 void mdelay(unsigned long msecs);</font><br>
11314 <div class="bq">
11315 Introduces delays of an integer number of nanoseconds, microseconds, and milliseconds.
11316 The delay achieved is at least the requested value, but it can be more.
11317 The argument to each function must not exceed a platform-specific limit (usually
11318 a few thousands).</div>
11319 <br>
11320 <font class="fixd">void msleep(unsigned int millisecs);<br>
11321 unsigned long msleep_interruptible(unsigned int millisecs);<br>
11322 void ssleep(unsigned int seconds);</font><br>
11323 <div class="bq">
11324 Puts the process to sleep for the given number of milliseconds (or seconds, in the
11325 case of <i>ssleep</i>).</div>
11326 <br>
11327 <a name="KernelTimers2"></a><font color="red"><b>Kernel Timers</b></font><br>
11328 <br>
11329 <font class="fixd">#include <asm/hardirq.h><br>
11330 int in_interrupt(void);<br>
11331 int in_atomic(void);</font><br>
11332 <div class="bq">
11333 Returns a Boolean value telling whether the calling code is executing in interrupt
11334 context or atomic context. Interrupt context is outside of a process context,
11335 either during hardware or software interrupt processing. Atomic context is
11336 when you can't schedule either an interrupt context or a process's context with a
11337 spinlock held.</div>
11338 <br>
11339 <font class="fixd">#include <linux/timer.h><br>
11340 void init_timer(struct timer_list * timer);<br>
11341 struct timer_list TIMER_INITIALIZER(_function, _expires, _data);</font><br>
11342 <div class="bq">
11343 This function and the static declaration of the timer structure are the two ways
11344 to initialize a <font class="fixd">timer_list</font> data structure.</div>
11345 <br>
11346 <font class="fixd">void add_timer(struct timer_list * timer);</font><br>
11347 <div class="bq">
11348 Registers the timer structure to run on the current CPU.</div>
11349 <br>
11350 <font class="fixd">int mod_timer(struct timer_list *timer, unsigned long expires);</font><br>
11351 <div class="bq">
11352 Changes the expiration time of an already scheduled timer structure. It can also
11353 act as an alternative to <i>add_timer</i>.</div>
11354 <br>
11355 <font class="fixd">int timer_pending(struct timer_list * timer);</font><br>
11356 <div class="bq">
11357 Macro that returns a Boolean value stating whether the timer structure is already
11358 registered to run.</div>
11359 <br>
11360 <font class="fixd">void del_timer(struct timer_list * timer);<br>
11361 void del_timer_sync(struct timer_list * timer);</font><br>
11362 <div class="bq">
11363 Removes a timer from the list of active timers. The latter function ensures that
11364 the timer is not currently running on another CPU.</div>
11365 <br>
11366 <A name="211"></a><font color="blue">PAGE 211</font><br>
11367 <br>
11368 <a name="Tasklets2"></a><font color="red"><b>Tasklets</b></font><br>
11369 <br>
11370 <font class="fixd">#include <linux/interrupt.h>
11371 DECLARE_TASKLET(name, func, data);<br>
11372 DECLARE_TASKLET_DISABLED(name, func, data);<br>
11373 void tasklet_init(struct tasklet_struct *t, void (*func)(unsigned long), unsigned long data);</font><br>
11374 <div class="bq">
11375 The first two macros declare a tasklet structure, while the <i>tasklet_init </i>function
11376 initializes a tasklet structure that has been obtained by allocation or other
11377 means. The second <font class="fixd">DECLARE</font> macro marks the tasklet as disabled.</div>
11378 <br>
11379 <font class="fixd">void tasklet_disable(struct tasklet_struct *t);<br>
11380 void tasklet_disable_nosync(struct tasklet_struct *t);<br>
11381 void tasklet_enable(struct tasklet_struct *t);</font><br>
11382 <div class="bq">
11383 Disables and reenables a tasklet. Each <i>disable </i>must be matched with an <i>enable
11384 </i>(you can disable the tasklet even if it's already disabled). The function <i>tasklet_
11385 disable </i>waits for the tasklet to terminate if it is running on another CPU. The
11386 <i>nosync</i> version doesn't take this extra step.</div>
11387 <br>
11388 <font class="fixd">void tasklet_schedule(struct tasklet_struct *t);<br>
11389 void tasklet_hi_schedule(struct tasklet_struct *t);</font><br>
11390 <div class="bq">
11391 Schedules a tasklet to run, either as a "normal" tasklet or a high-priority one.
11392 When soft interrupts are executed, high-priority tasklets are dealt with first,
11393 while normal tasklets run last.</div>
11394 <br>
11395 <font class="fixd">void tasklet_kill(struct tasklet_struct *t);</font><br>
11396 <div class="bq">
11397 Removes the tasklet from the list of active ones, if it's scheduled to run. Like
11398 <i>tasklet_disable</i>, the function may block on SMP systems waiting for the tasklet to
11399 terminate if it's currently running on another CPU.</div>
11400 <br>
11401 <a name="Workqueues2"></a><font color="red"><b>Workqueues</b></font><br>
11402 <br>
11403 <font class="fixd">#include <linux/workqueue.h><br>
11404 struct workqueue_struct;<br>
11405 struct work_struct;</font><br>
11406 <div class="bq">
11407 The structures representing a workqueue and a work entry, respectively.</div>
11408 <br>
11409 <font class="fixd">struct workqueue_struct *create_workqueue(const char *name);<br>
11410 struct workqueue_struct *create_singlethread_workqueue(const char *name);<br>
11411 void destroy_workqueue(struct workqueue_struct *queue);</font><br>
11412 <div class="bq">
11413 Functions for creating and destroying workqueues. A call to <i>create_workqueue
11414 </i>creates a queue with a worker thread on each processor in the system;
11415 instead, <i>create_singlethread_workqueue </i>creates a workqueue with a single
11416 worker process.</div>
11417 <br>
11418 <A name="212"></a><font color="blue">PAGE 212</font><br>
11419 <br>
11420 <font class="fixd">DECLARE_WORK(name, void (*function)(void *), void *data);<br>
11421 INIT_WORK(struct work_struct *work, void (*function)(void *), void *data);<br>
11422 PREPARE_WORK(struct work_struct *work, void (*function)(void *), void *data);</font><br>
11423 <div class="bq">
11424 Macros that declare and initialize workqueue entries.</div>
11425 <br>
11426 <font class="fixd">int queue_work(struct workqueue_struct *queue, struct work_struct *work);<br>
11427 int queue_delayed_work(struct workqueue_struct *queue, struct work_struct *work, unsigned long delay);</font><br>
11428 <div class="bq">
11429 Functions that queue work for execution from a workqueue.</div>
11430 <br>
11431 <font class="fixd">int cancel_delayed_work(struct work_struct *work);<br>
11432 void flush_workqueue(struct workqueue_struct *queue);</font><br>
11433 <div class="bq">
11434 Use <i>cancel_delayed_work </i>to remove an entry from a workqueue; <i>flush_workqueue
11435 </i>ensures that no workqueue entries are running anywhere in the system.</div>
11436 <br>
11437 <font class="fixd">int schedule_work(struct work_struct *work);<br>
11438 int schedule_delayed_work(struct work_struct *work, unsigned long delay);<br>
11439 void flush_scheduled_work(void);</font><br>
11440 <div class="bq">
11441 Functions for working with the shared workqueue.</div>
11442 <br>
11443 <A name="213"></a><font color="blue">PAGE 213</font><br>
11444 <br>
11445 <a name="CHAPTER8"></a><font color="red"><b>CHAPTER 8</b></font><br>
11446 <br>
11447 <a name="AllocatingMemory"></a><font color="#7519FF" size="+1"><b>Allocating Memory</b></font><br>
11448 <br>
11449 Thus far, we have used <i>kmalloc </i>and <i>kfree </i>for the allocation and freeing of memory.
11450 The Linux kernel offers a richer set of memory allocation primitives, however. In this
11451 chapter, we look at other ways of using memory in device drivers and how to optimize
11452 your system's memory resources. We do not get into how the different architectures
11453 actually administer memory. Modules are not involved in issues of
11454 segmentation, paging, and so on, since the kernel offers a unified memory management
11455 interface to the drivers. In addition, we won't describe the internal details of
11456 memory management in this chapter, but defer it to Chapter 15.<br>
11457 <br>
11458 <a name="TheRealStoryOfKmalloc"></a><font color="red"><b>The Real Story of kmalloc</b></font><br>
11459 <br>
11460 The <i>kmalloc </i>allocation engine is a powerful tool and easily learned because of its
11461 similarity to <i>malloc</i>. The function is fast (unless it blocks) and doesn't clear the memory
11462 it obtains; the allocated region still holds its previous content.* The allocated
11463 region is also contiguous in physical memory. In the next few sections, we talk in
11464 detail about <i>kmalloc</i>, so you can compare it with the memory allocation techniques
11465 that we discuss later.<br>
11466 <br>
11467 <a name="TheFlagsArgument"></a><font color="red"><b>The Flags Argument</b></font><br>
11468 <br>
11469 Remember that the prototype for <i>kmalloc</i> is:<br>
11470 <pre>
11471 #include <linux/slab.h>
11473 void *kmalloc(size_t size, int flags);
11474 </pre>
11475 * Among other things, this implies that you should explicitly clear any memory that might be exposed to user
11476 space or written to a device; otherwise, you risk disclosing information that should be kept private.<br>
11477 <br>
11478 <A name="214"></a><font color="blue">PAGE 214</font><br>
11479 <br>
11480 The first argument to <i>kmalloc </i>is the size of the block to be allocated. The second
11481 argument, the allocation flags, is much more interesting, because it controls the
11482 behavior of <i>kmalloc</i> in a number of ways.<br>
11483 <br>
11484 The most commonly used flag, <font class="fixd">GFP_KERNEL,</font> means that the allocation (internally performed
11485 by calling, eventually, <i>__get_free_pages</i>, which is the source of the <font class="fixd">GFP_</font> prefix)
11486 is performed on behalf of a process running in kernel space. In other words, this
11487 means that the calling function is executing a system call on behalf of a process.
11488 Using <font class="fixd">GFP_KERNEL</font> means that <i>kmalloc </i>can put the current process to sleep waiting for
11489 a page when called in low-memory situations. A function that allocates memory
11490 using <font class="fixd">GFP_KERNEL</font> must, therefore, be reentrant and cannot be running in atomic context.
11491 While the current process sleeps, the kernel takes proper action to locate some
11492 free memory, either by flushing buffers to disk or by swapping out memory from a
11493 user process.<br>
11494 <br>
11495 <font class="fixd">GFP_KERNEL</font> isn't always the right allocation flag to use; sometimes <i>kmalloc </i>is called
11496 from outside a process's context. This type of call can happen, for instance, in interrupt
11497 handlers, tasklets, and kernel timers. In this case, the current process should
11498 not be put to sleep, and the driver should use a flag of <font class="fixd">GFP_ATOMIC</font> instead. The kernel
11499 normally tries to keep some free pages around in order to fulfill atomic allocation.
11500 When <font class="fixd">GFP_ATOMIC</font> is used, <i>kmalloc </i>can use even the last free page. If that last
11501 page does not exist, however, the allocation fails.<br>
11502 <br>
11503 Other flags can be used in place of or in addition to <font class="fixd">GFP_KERNEL</font> and <font class="fixd">GFP_ATOMIC,</font>
11504 although those two cover most of the needs of device drivers. All the flags are defined
11505 in <i><linux/gfp.h></i>, and individual flags are prefixed with a double underscore, such
11506 as <font class="fixd">__GFP_DMA</font>. In addition, there are symbols that represent frequently used combinations
11507 of flags; these lack the prefix and are sometimes called <i>allocation priorities</i>. The
11508 latter include:<br>
11509 <br>
11510 <font class="fixd">GFP_ATOMIC</font><br>
11511 <div class="bq">
11512 Used to allocate memory from interrupt handlers and other code outside of a
11513 process context. Never sleeps.</div>
11514 <br>
11515 <font class="fixd">GFP_KERNEL</font><br>
11516 <div class="bq">
11517 Normal allocation of kernel memory. May sleep.</div>
11518 <br>
11519 <font class="fixd">GFP_USER</font><br>
11520 <div class="bq">
11521 Used to allocate memory for user-space pages; it may sleep.</div>
11522 <br>
11523 <font class="fixd">GFP_HIGHUSER</font><br>
11524 <div class="bq">
11525 Like <font class="fixd">GFP_USER,</font> but allocates from high memory, if any. High memory is
11526 described in the next subsection.</div>
11527 <br>
11528 <font class="fixd">GFP_NOIO<br>
11529 GFP_NOFS</font><br>
11530 <div class="bq">
11531 These flags function like <font class="fixd">GFP_KERNEL,</font> but they add restrictions on what the kernel
11532 can do to satisfy the request. A <font class="fixd">GFP_NOFS</font> allocation is not allowed to perform</div>
11533 <br>
11534 <A name="215"></a><font color="blue">PAGE 215</font><br>
11535 <br>
11536 <div class="bq">
11537 any filesystem calls, while <font class="fixd">GFP_NOIO</font> disallows the initiation of any I/O at all.
11538 They are used primarily in the filesystem and virtual memory code where an allocation
11539 may be allowed to sleep, but recursive filesystem calls would be a bad
11540 idea.</div>
11541 <br>
11542 The allocation flags listed above can be augmented by an ORing in any of the following
11543 flags, which change how the allocation is carried out:<br>
11544 <br>
11545 <font class="fixd">__GFP_DMA</font><br>
11546 <div class="bq">
11547 This flag requests allocation to happen in the DMA-capable memory zone. The
11548 exact meaning is platform-dependent and is explained in the following section.</div>
11549 <br>
11550 <font class="fixd">__GFP_HIGHMEM</font><br>
11551 <div class="bq">
11552 This flag indicates that the allocated memory may be located in high memory.</div>
11553 <br>
11554 <font class="fixd">__GFP_COLD</font><br>
11555 <div class="bq">
11556 Normally, the memory allocator tries to return "cache warm" pages--pages that
11557 are likely to be found in the processor cache. Instead, this flag requests a "cold"
11558 page, which has not been used in some time. It is useful for allocating pages for
11559 DMA reads, where presence in the processor cache is not useful. See the section
11560 "Direct Memory Access" in Chapter 1 for a full discussion of how to allocate
11561 DMA buffers.</div>
11562 <br>
11563 <font class="fixd">__GFP_NOWARN</font><br>
11564 <div class="bq">
11565 This rarely used flag prevents the kernel from issuing warnings (with <i>printk</i>)
11566 when an allocation cannot be satisfied.</div>
11567 <br>
11568 <font class="fixd">__GFP_HIGH</font><br>
11569 <div class="bq">
11570 This flag marks a high-priority request, which is allowed to consume even the
11571 last pages of memory set aside by the kernel for emergencies.</div>
11572 <br>
11573 <font class="fixd">__GFP_REPEAT<br>
11574 __GFP_NOFAIL<br>
11575 __GFP_NORETRY</font><br>
11576 <div class="bq">
11577 These flags modify how the allocator behaves when it has difficulty satisfying an
11578 allocation. <font class="fixd">__GFP_REPEAT</font> means "try a little harder" by repeating the attempt-but
11579 the allocation can still fail. The <font class="fixd">__GFP_NOFAIL</font> flag tells the allocator never to
11580 fail; it works as hard as needed to satisfy the request. Use of <font class="fixd">__GFP_NOFAIL</font> is very
11581 strongly discouraged; there will probably never be a valid reason to use it in a
11582 device driver. Finally, <font class="fixd">__GFP_NORETRY</font> tells the allocator to give up immediately if
11583 the requested memory is not available.</div>
11584 <br>
11585 <a name="MemoryZones"></a><font color="red"><b>Memory zones</b></font><br>
11586 <br>
11587 Both <font class="fixd">__GFP_DMA</font> and <font class="fixd">__GFP_HIGHMEM</font> have a platform-dependent role, although their
11588 use is valid for all platforms.<br>
11589 <br>
11590 The Linux kernel knows about a minimum of three <i>memory zones</i>: DMA-capable
11591 memory, normal memory, and high memory. While allocation normally happens in<br>
11592 <br>
11593 <A name="216"></a><font color="blue">PAGE 216</font><br>
11594 <br>
11595 the <i>normal </i>zone, setting either of the bits just mentioned requires memory to be allocated
11596 from a different zone. The idea is that every computer platform that must
11597 know about special memory ranges (instead of considering all RAM equivalents) will
11598 fall into this abstraction.<br>
11599 <br>
11600 <i>DMA-capable memory </i>is memory that lives in a preferential address range, where
11601 peripherals can perform DMA access. On most sane platforms, all memory lives in
11602 this zone. On the x86, the DMA zone is used for the first 16 MB of RAM, where legacy
11603 ISA devices can perform DMA; PCI devices have no such limit.<br>
11604 <br>
11605 <i>High memory </i>is a mechanism used to allow access to (relatively) large amounts of
11606 memory on 32-bit platforms. This memory cannot be directly accessed from the kernel
11607 without first setting up a special mapping and is generally harder to work with. If
11608 your driver uses large amounts of memory, however, it will work better on large systems
11609 if it can use high memory. See the section "High and Low Memory" in
11610 Chapter 1 for a detailed description of how high memory works and how to use it.<br>
11611 <br>
11612 Whenever a new page is allocated to fulfill a memory allocation request, the kernel
11613 builds a list of zones that can be used in the search. If <font class="fixd">__GFP_DMA</font> is specified, only the
11614 DMA zone is searched: if no memory is available at low addresses, allocation fails. If no
11615 special flag is present, both normal and DMA memory are searched; if <font class="fixd">__GFP_HIGHMEM</font> is
11616 set, all three zones are used to search a free page. (Note, however, that <i>kmalloc </i>cannot
11617 allocate high memory.)<br>
11618 <br>
11619 The situation is more complicated on nonuniform memory access (NUMA) systems.
11620 As a general rule, the allocator attempts to locate memory local to the processor performing
11621 the allocation, although there are ways of changing that behavior.<br>
11622 <br>
11623 The mechanism behind memory zones is implemented in <i>mm/page_alloc.c</i>, while initialization
11624 of the zone resides in platform-specific files, usually in <i>mm/init.c </i>within
11625 the <i>arch</i> tree. We'll revisit these topics in Chapter 15.<br>
11626 <br>
11627 <a name="TheSizeArgument"></a><font color="red"><b>The Size Argument</b></font><br>
11628 <br>
11629 The kernel manages the system's <i>physical </i>memory, which is available only in pagesized
11630 chunks. As a result, <i>kmalloc </i>looks rather different from a typical user-space
11631 <i>malloc </i>implementation. A simple, heap-oriented allocation technique would quickly
11632 run into trouble; it would have a hard time working around the page boundaries.
11633 Thus, the kernel uses a special page-oriented allocation technique to get the best use
11634 from the system's RAM.<br>
11635 <br>
11636 Linux handles memory allocation by creating a set of pools of memory objects of
11637 fixed sizes. Allocation requests are handled by going to a pool that holds sufficiently
11638 large objects and handing an entire memory chunk back to the requester. The memory
11639 management scheme is quite complex, and the details of it are not normally all
11640 that interesting to device driver writers.<br>
11641 <br>
11642 <A name="217"></a><font color="blue">PAGE 217</font><br>
11643 <br>
11644 The one thing driver developers should keep in mind, though, is that the kernel can
11645 allocate only certain predefined, fixed-size byte arrays. If you ask for an arbitrary
11646 amount of memory, you're likely to get slightly more than you asked for, up to twice
11647 as much. Also, programmers should remember that the smallest allocation that
11648 <i>kmalloc </i>can handle is as big as 32 or 64 bytes, depending on the page size used by
11649 the system's architecture.<br>
11650 <br>
11651 There is an upper limit to the size of memory chunks that can be allocated by <i>kmalloc</i>.
11652 That limit varies depending on architecture and kernel configuration options. If
11653 your code is to be completely portable, it cannot count on being able to allocate anything
11654 larger than 128 KB. If you need more than a few kilobytes, however, there are
11655 better ways than <i>kmalloc</i> to obtain memory, which we describe later in this chapter.<br>
11656 <br>
11657 <a name="LookasideCaches"></a><font color="red"><b>Lookaside Caches</b></font><br>
11658 <br>
11659 A device driver often ends up allocating many objects of the same size, over and over.
11660 Given that the kernel already maintains a set of memory pools of objects that are all
11661 the same size, why not add some special pools for these high-volume objects? In fact,
11662 the kernel does implement a facility to create this sort of pool, which is often called a
11663 <i>lookaside cache</i>. Device drivers normally do not exhibit the sort of memory behavior
11664 that justifies using a lookaside cache, but there can be exceptions; the USB and SCSI
11665 drivers in Linux 2.6 use caches.<br>
11666 <br>
11667 The cache manager in the Linux kernel is sometimes called the "slab allocator." For
11668 that reason, its functions and types are declared in <i><linux/slab.h></i>. The slab allocator
11669 implements caches that have a type of <font class="fixd">kmem_cache_t;</font> they are created with a call to
11670 <i>kmem_cache_create</i>:<br>
11671 <pre>
11672 kmem_cache_t *kmem_cache_create(const char *name, size_t size,
11673 size_t offset,
11674 unsigned long flags,
11675 void (*constructor)(void *, kmem_cache_t *,
11676 unsigned long flags),
11677 void (*destructor)(void *, kmem_cache_t *,
11678 unsigned long flags));
11679 </pre>
11680 The function creates a new cache object that can host any number of memory areas
11681 all of the same <font class="fixd">size,</font> specified by the size argument. The <font class="fixd">name</font> argument is associated
11682 with this cache and functions as housekeeping information usable in tracking problems;
11683 usually, it is set to the name of the type of structure that is cached. The cache
11684 keeps a pointer to the name, rather than copying it, so the driver should pass in a
11685 pointer to a name in static storage (usually the name is just a literal string). The name
11686 cannot contain blanks.<br>
11687 <br>
11688 The <font class="fixd">offset</font> is the offset of the first object in the page; it can be used to ensure a particular
11689 alignment for the allocated objects, but you most likely will use 0 to request<br>
11690 <br>
11691 <A name="218"></a><font color="blue">PAGE 218</font><br>
11692 <br>
11693 the default value. <font class="fixd">flags</font> controls how allocation is done and is a bit mask of the following
11694 flags:<br>
11695 <br>
11696 <font class="fixd">SLAB_NO_REAP</font><br>
11697 <div class="bq">
11698 Setting this flag protects the cache from being reduced when the system is looking
11699 for memory. Setting this flag is normally a bad idea; it is important to avoid
11700 restricting the memory allocator's freedom of action unnecessarily.</div>
11701 <br>
11702 <font class="fixd">SLAB_HWCACHE_ALIGN</font><br>
11703 <div class="bq">
11704 This flag requires each data object to be aligned to a cache line; actual alignment
11705 depends on the cache layout of the host platform. This option can be a good
11706 choice if your cache contains items that are frequently accessed on SMP
11707 machines. The padding required to achieve cache line alignment can end up
11708 wasting significant amounts of memory, however.</div>
11709 <br>
11710 <font class="fixd">SLAB_CACHE_DMA</font><br>
11711 <div class="bq">
11712 This flag requires each data object to be allocated in the DMA memory zone.</div>
11713 <br>
11714 There is also a set of flags that can be used during the debugging of cache allocations;
11715 see <i>mm/slab.c </i>for the details. Usually, however, these flags are set globally via a
11716 kernel configuration option on systems used for development.<br>
11717 <br>
11718 The <font class="fixd">constructor</font> and <font class="fixd">destructor</font> arguments to the function are optional functions
11719 (but there can be no destructor without a constructor); the former can be used to initialize
11720 newly allocated objects, and the latter can be used to "clean up" objects prior
11721 to their memory being released back to the system as a whole.<br>
11722 <br>
11723 Constructors and destructors can be useful, but there are a few constraints that you
11724 should keep in mind. A constructor is called when the memory for a set of objects is
11725 allocated; because that memory may hold several objects, the constructor may be
11726 called multiple times. You cannot assume that the constructor will be called as an
11727 immediate effect of allocating an object. Similarly, destructors can be called at some
11728 unknown future time, not immediately after an object has been freed. Constructors
11729 and destructors may or may not be allowed to sleep, according to whether they are
11730 passed the <font class="fixd">SLAB_CTOR_ATOMIC</font> flag (where <font class="fixd">CTOR</font> is short for <i>constructor</i>).<br>
11731 <br>
11732 For convenience, a programmer can use the same function for both the constructor
11733 and destructor; the slab allocator always passes the <font class="fixd">SLAB_CTOR_CONSTRUCTOR</font> flag when
11734 the callee is a constructor.<br>
11735 <br>
11736 Once a cache of objects is created, you can allocate objects from it by calling
11737 <i>kmem_cache_alloc</i>:<br>
11738 <pre>
11739 void *kmem_cache_alloc(kmem_cache_t *cache, int flags);
11740 </pre>
11741 Here, the <font class="fixd">cache</font> argument is the cache you have created previously; the flags are the
11742 same as you would pass to <i>kmalloc </i>and are consulted if <i>kmem_cache_alloc </i>needs to
11743 go out and allocate more memory itself.<br>
11744 <br>
11745 To free an object, use <i>kmem_cache_free</i>:<br>
11746 <pre>
11747 void kmem_cache_free(kmem_cache_t *cache, const void *obj);
11748 </pre>
11749 <A name="219"></a><font color="blue">PAGE 219</font><br>
11750 <br>
11751 When driver code is finished with the cache, typically when the module is unloaded,
11752 it should free its cache as follows:<br>
11753 <pre>
11754 int kmem_cache_destroy(kmem_cache_t *cache);
11755 </pre>
11756 The destroy operation succeeds only if all objects allocated from the cache have
11757 been returned to it. Therefore, a module should check the return status from
11758 <i>kmem_cache_destroy</i>; a failure indicates some sort of memory leak within the module
11759 (since some of the objects have been dropped).<br>
11760 <br>
11761 One side benefit to using lookaside caches is that the kernel maintains statistics on
11762 cache usage. These statistics may be obtained from <i>/proc/slabinfo</i>.<br>
11763 <br>
11764 <a name="AScullBasedOnTheSlabCachesScullc"></a><font color="red"><b>A scull Based on the Slab Caches: scullc</b></font><br>
11765 <br>
11766 Time for an example. <i>scullc </i>is a cut-down version of the <i>scull </i>module that implements
11767 only the bare device--the persistent memory region. Unlike <i>scull</i>, which uses
11768 <i>kmalloc</i>, <i>scullc </i>uses memory caches. The size of the quantum can be modified at
11769 compile time and at load time, but not at runtime--that would require creating a
11770 new memory cache, and we didn't want to deal with these unneeded details.<br>
11771 <br>
11772 <i>scullc </i>is a complete example that can be used to try out the slab allocator. It differs
11773 from <i>scull</i> only in a few lines of code. First, we must declare our own slab cache:<br>
11774 <pre>
11775 /* declare one cache pointer: use it for all devices */
11776 kmem_cache_t *scullc_cache;
11777 </pre>
11778 The creation of the slab cache is handled (at module load time) in this way:<br>
11779 <pre>
11780 /* scullc_init: create a cache for our quanta */
11781 scullc_cache = kmem_cache_create("scullc", scullc_quantum,
11782 0, SLAB_HWCACHE_ALIGN, NULL, NULL); /* no ctor/dtor */
11783 if (!scullc_cache) {
11784 scullc_cleanup( );
11785 return -ENOMEM;
11786 }
11787 </pre>
11788 This is how it allocates memory quanta:<br>
11789 <pre>
11790 /* Allocate a quantum using the memory cache */
11791 if (!dptr->data[s_pos]) {
11792 dptr->data[s_pos] = kmem_cache_alloc(scullc_cache, GFP_KERNEL);
11793 if (!dptr->data[s_pos])
11794 goto nomem;
11795 memset(dptr->data[s_pos], 0, scullc_quantum);
11796 }
11797 </pre>
11798 And these lines release memory:<br>
11799 <pre>
11800 for (i = 0; i < qset; i++)
11801 if (dptr->data[i])
11802 kmem_cache_free(scullc_cache, dptr->data[i]);
11803 </pre>
11804 <A name="220"></a><font color="blue">PAGE 220</font><br>
11805 <br>
11806 Finally, at module unload time, we have to return the cache to the system:<br>
11807 <pre>
11808 /* scullc_cleanup: release the cache of our quanta */
11809 if (scullc_cache)
11810 kmem_cache_destroy(scullc_cache);
11811 </pre>
11812 The main differences in passing from <i>scull </i>to <i>scullc </i>are a slight speed improvement
11813 and better memory use. Since quanta are allocated from a pool of memory fragments
11814 of exactly the right size, their placement in memory is as dense as possible, as
11815 opposed to <i>scull</i> quanta, which bring in an unpredictable memory fragmentation.<br>
11816 <br>
11817 <a name="MemoryPools"></a><font color="red"><b>Memory Pools</b></font><br>
11818 <br>
11819 There are places in the kernel where memory allocations cannot be allowed to fail.
11820 As a way of guaranteeing allocations in those situations, the kernel developers created
11821 an abstraction known as a <i>memory pool </i>(or "mempool"). A memory pool is
11822 really just a form of a lookaside cache that tries to always keep a list of free memory
11823 around for use in emergencies.<br>
11824 <br>
11825 A memory pool has a type of <font class="fixd">mempool_t</font> (defined in <i><linux/mempool.h></i>); you can create
11826 one with <i>mempool_create</i>:<br>
11827 <pre>
11828 mempool_t *mempool_create(int min_nr,
11829 mempool_alloc_t *alloc_fn,
11830 mempool_free_t *free_fn,
11831 void *pool_data);
11832 </pre>
11833 The <font class="fixd">min_nr</font> argument is the minimum number of allocated objects that the pool
11834 should always keep around. The actual allocation and freeing of objects is handled
11835 by <font class="fixd">alloc_fn</font> and <font class="fixd">free_fn</font>, which have these prototypes:<br>
11836 <pre>
11837 typedef void *(mempool_alloc_t)(int gfp_mask, void *pool_data);
11838 typedef void (mempool_free_t)(void *element, void *pool_data);
11839 </pre>
11840 The final parameter to <i>mempool_create</i> (<font class="fixd">pool_data</font>) is passed to <font class="fixd">alloc_fn</font> and <font class="fixd">free_fn</font>.<br>
11841 <br>
11842 If need be, you can write special-purpose functions to handle memory allocations for
11843 mempools. Usually, however, you just want to let the kernel slab allocator handle that
11844 task for you. There are two functions (<i>mempool_alloc_slab </i>and <i>mempool_free_slab</i>)
11845 that perform the impedance matching between the memory pool allocation prototypes
11846 and <i>kmem_cache_alloc </i>and <i>kmem_cache_free</i>. Thus, code that sets up memory
11847 pools often looks like the following:<br>
11848 <pre>
11849 cache = kmem_cache_create(. . .);
11850 pool = mempool_create(MY_POOL_MINIMUM,
11851 mempool_alloc_slab, mempool_free_slab,
11852 cache);
11853 </pre>
11854 Once the pool has been created, objects can be allocated and freed with:<br>
11855 <pre>
11856 void *mempool_alloc(mempool_t *pool, int gfp_mask);
11857 void mempool_free(void *element, mempool_t *pool);
11858 </pre>
11859 <A name="221"></a><font color="blue">PAGE 221</font><br>
11860 <br>
11861 When the mempool is created, the allocation function will be called enough times to
11862 create a pool of preallocated objects. Thereafter, calls to <i>mempool_alloc </i>attempt to
11863 acquire additional objects from the allocation function; should that allocation fail,
11864 one of the preallocated objects (if any remain) is returned. When an object is freed
11865 with <i>mempool_free</i>, it is kept in the pool if the number of preallocated objects is currently
11866 below the minimum; otherwise, it is to be returned to the system.<br>
11867 <br>
11868 A mempool can be resized with:<br>
11869 <pre>
11870 int mempool_resize(mempool_t *pool, int new_min_nr, int gfp_mask);
11871 </pre>
11872 This call, if successful, resizes the pool to have at least <font class="fixd">new_min_nr</font> objects.<br>
11873 <br>
11874 If you no longer need a memory pool, return it to the system with:<br>
11875 <pre>
11876 void mempool_destroy(mempool_t *pool);
11877 </pre>
11878 You must return all allocated objects before destroying the mempool, or a kernel
11879 oops results.<br>
11880 <br>
11881 If you are considering using a mempool in your driver, please keep one thing in
11882 mind: mempools allocate a chunk of memory that sits in a list, idle and unavailable
11883 for any real use. It is easy to consume a great deal of memory with mempools. In
11884 almost every case, the preferred alternative is to do without the mempool and simply
11885 deal with the possibility of allocation failures instead. If there is any way for your
11886 driver to respond to an allocation failure in a way that does not endanger the integrity
11887 of the system, do things that way. Use of mempools in driver code should be
11888 rare.<br>
11889 <br>
11890 <a name="GetfreepageAndFriends"></a><font color="red"><b>get_free_page and Friends</b></font><br>
11891 <br>
11892 If a module needs to allocate big chunks of memory, it is usually better to use a pageoriented
11893 technique. Requesting whole pages also has other advantages, which are
11894 introduced in Chapter 15.<br>
11895 <br>
11896 To allocate pages, the following functions are available:<br>
11897 <br>
11898 <font class="fixd">get_zeroed_page(unsigned int flags);</font><br>
11899 <div class="bq">
11900 Returns a pointer to a new page and fills the page with zeros.</div>
11901 <br>
11902 <font class="fixd">__get_free_page(unsigned int flags);</font><br>
11903 <div class="bq">
11904 Similar to <i>get_zeroed_page</i>, but doesn't clear the page.</div>
11905 <br>
11906 <font class="fixd">__get_free_pages(unsigned int flags, unsigned int order);</font><br>
11907 <div class="bq">
11908 Allocates and returns a pointer to the first byte of a memory area that is potentially
11909 several (physically contiguous) pages long but doesn't zero the area.</div>
11910 <br>
11911 The flags argument works in the same way as with <i>kmalloc</i>; usually either <font class="fixd">GFP_KERNEL</font>
11912 or <font class="fixd">GFP_ATOMIC</font> is used, perhaps with the addition of the <font class="fixd">__GFP_DMA</font> flag (for memory
11913 that can be used for ISA direct-memory-access operations) or <font class="fixd">__GFP_HIGHMEM</font> when<br>
11914 <br>
11915 <A name="222"></a><font color="blue">PAGE 222</font><br>
11916 <br>
11917 high memory can be used.* order is the base-two logarithm of the number of pages
11918 you are requesting or freeing (i.e., log2<i>N</i>). For example, order is 0 if you want one
11919 page and 3 if you request eight pages. If order is too big (no contiguous area of that
11920 size is available), the page allocation fails. The <i>get_order </i>function, which takes an integer
11921 argument, can be used to extract the order from a size (that must be a power of
11922 two) for the hosting platform. The maximum allowed value for order is 10 or 11 (corresponding
11923 to 1024 or 2048 pages), depending on the architecture. The chances of an
11924 order-10 allocation succeeding on anything other than a freshly booted system with a
11925 lot of memory are small, however.<br>
11926 <br>
11927 If you are curious, <i>/proc/buddyinfo </i>tells you how many blocks of each order are available
11928 for each memory zone on the system.<br>
11929 <br>
11930 When a program is done with the pages, it can free them with one of the following
11931 functions. The first function is a macro that falls back on the second:<br>
11932 <pre>
11933 void free_page(unsigned long addr);
11934 void free_pages(unsigned long addr, unsigned long order);
11935 </pre>
11936 If you try to free a different number of pages from what you allocated, the memory
11937 map becomes corrupted, and the system gets in trouble at a later time.<br>
11938 <br>
11939 It's worth stressing that <i>__get_free_pages </i>and the other functions can be called at any
11940 time, subject to the same rules we saw for <i>kmalloc</i>. The functions can fail to allocate
11941 memory in certain circumstances, particularly when <font class="fixd">GFP_ATOMIC</font> is used. Therefore,
11942 the program calling these allocation functions must be prepared to handle an allocation
11943 failure.<br>
11944 <br>
11945 Although <font class="fixd">kmalloc(GFP_KERNEL)</font> sometimes fails when there is no available memory,
11946 the kernel does its best to fulfill allocation requests. Therefore, it's easy to degrade
11947 system responsiveness by allocating too much memory. For example, you can bring
11948 the computer down by pushing too much data into a <i>scull </i>device; the system starts
11949 crawling while it tries to swap out as much as possible in order to fulfill the <i>kmalloc
11950 </i>request. Since every resource is being sucked up by the growing device, the computer
11951 is soon rendered unusable; at that point, you can no longer even start a new
11952 process to try to deal with the problem. We don't address this issue in <i>scull</i>, since it
11953 is just a sample module and not a real tool to put into a multiuser system. As a programmer,
11954 you must be careful nonetheless, because a module is privileged code and
11955 can open new security holes in the system (the most likely is a denial-of-service hole
11956 like the one just outlined).<br>
11957 <br>
11958 * Although <i>alloc_pages </i>(described shortly) should really be used for allocating high-memory pages,
11959 for reasons we can't really get into until Chapter 15.<br>
11960 <br>
11961 <A name="223"></a><font color="blue">PAGE 223</font><br>
11962 <br>
11963 <a name="AScullUsingWholePagesScullp"></a><font color="red"><b>A scull Using Whole Pages: scullp</b></font><br>
11964 <br>
11965 In order to test page allocation for real, we have released the <i>scullp </i>module together
11966 with other sample code. It is a reduced <i>scull</i>, just like <i>scullc</i> introduced earlier.<br>
11967 <br>
11968 Memory quanta allocated by <i>scullp </i>are whole pages or page sets: the <font class="fixd">scullp_order</font>
11969 variable defaults to 0 but can be changed at either compile or load time.<br>
11970 <br>
11971 The following lines show how it allocates memory:<br>
11972 <pre>
11973 /* Here's the allocation of a single quantum */
11974 if (!dptr->data[s_pos]) {
11975 dptr->data[s_pos] =
11976 (void *)__get_free_pages(GFP_KERNEL, dptr->order);
11977 if (!dptr->data[s_pos])
11978 goto nomem;
11979 memset(dptr->data[s_pos], 0, PAGE_SIZE << dptr->order);
11980 }
11981 </pre>
11982 The code to deallocate memory in <i>scullp</i> looks like this:<br>
11983 <pre>
11984 /* This code frees a whole quantum-set */
11985 for (i = 0; i < qset; i++)
11986 if (dptr->data[i])
11987 free_pages((unsigned long)(dptr->data[i]),
11988 dptr->order);
11989 </pre>
11990 At the user level, the perceived difference is primarily a speed improvement and better
11991 memory use, because there is no internal fragmentation of memory. We ran some
11992 tests copying 4 MB from <i>scull0 </i>to <i>scull1 </i>and then from <i>scullp0 </i>to <i>scullp1</i>; the results
11993 showed a slight improvement in kernel-space processor usage.<br>
11994 <br>
11995 The performance improvement is not dramatic, because <i>kmalloc </i>is designed to be
11996 fast. The main advantage of page-level allocation isn't actually speed, but rather
11997 more efficient memory usage. Allocating by pages wastes no memory, whereas using
11998 <i>kmalloc</i> wastes an unpredictable amount of memory because of allocation granularity.<br>
11999 <br>
12000 But the biggest advantage of the <i>__get_free_page </i>functions is that the pages obtained
12001 are completely yours, and you could, in theory, assemble the pages into a linear area
12002 by appropriate tweaking of the page tables. For example, you can allow a user process
12003 to <i>mmap </i>memory areas obtained as single unrelated pages. We discuss this kind
12004 of operation in Chapter 15, where we show how <i>scullp </i>offers memory mapping,
12005 something that <i>scull</i> cannot offer.<br>
12006 <br>
12007 <a name="TheAllocpagesInterface"></a><font color="red"><b>The <font class="fixd">alloc_pages</font> Interface</b></font><br>
12008 <br>
12009 For completeness, we introduce another interface for memory allocation, even
12010 though we will not be prepared to use it until after Chapter 15. For now, suffice it to
12011 say that struct page is an internal kernel structure that describes a page of memory.
12012 As we will see, there are many places in the kernel where it is necessary to work with<br>
12013 <br>
12014 <A name="224"></a><font color="blue">PAGE 224</font><br>
12015 <br>
12016 <font class="fixd">page</font> structures; they are especially useful in any situation where you might be dealing
12017 with high memory, which does not have a constant address in kernel space.<br>
12018 <br>
12019 The <i>real</i> core of the Linux page allocator is a function called <i>alloc_pages_node</i>:<br>
12020 <pre>
12021 struct page *alloc_pages_node(int nid, unsigned int flags,
12022 unsigned int order);
12023 </pre>
12024 This function also has two variants (which are simply macros); these are the versions
12025 that you will most likely use:<br>
12026 <pre>
12027 struct page *alloc_pages(unsigned int flags, unsigned int order);
12028 struct page *alloc_page(unsigned int flags);
12029 </pre>
12030 The core function, <i>alloc_pages_node</i>, takes three arguments. <font class="fixd">nid</font> is the NUMA node
12031 ID* whose memory should be allocated, <font class="fixd">flags</font> is the usual <font class="fixd">GFP_</font> allocation flags, and
12032 <font class="fixd">order</font> is the size of the allocation. The return value is a pointer to the first of (possibly
12033 many) page structures describing the allocated memory, or, as usual, <font class="fixd">NULL</font> on failure.<br>
12034 <br>
12035 <i>alloc_pages </i>simplifies the situation by allocating the memory on the current NUMA
12036 node (it calls <i>alloc_pages_node </i>with the return value from <i>numa_node_id </i>as the <font class="fixd">nid</font>
12037 parameter). And, of course, <i>alloc_page </i>omits the order parameter and allocates a single
12038 page.<br>
12039 <br>
12040 To release pages allocated in this manner, you should use one of the following:<br>
12041 <pre>
12042 void __free_page(struct page *page);
12043 void __free_pages(struct page *page, unsigned int order);
12044 void free_hot_page(struct page *page);
12045 void free_cold_page(struct page *page);
12046 </pre>
12047 If you have specific knowledge of whether a single page's contents are likely to be
12048 resident in the processor cache, you should communicate that to the kernel with
12049 <i>free_hot_page </i>(for cache-resident pages) or <i>free_cold_page</i>. This information helps
12050 the memory allocator optimize its use of memory across the system.<br>
12051 <br>
12052 <a name="VmallocAndFriends"></a><font color="red"><b>vmalloc and Friends</b></font><br>
12053 <br>
12054 The next memory allocation function that we show you is <i>vmalloc</i>, which allocates a
12055 contiguous memory region in the <i>virtual </i>address space. Although the pages are not consecutive
12056 in physical memory (each page is retrieved with a separate call to <i>alloc_page</i>),
12057 the kernel sees them as a contiguous range of addresses. <i>vmalloc </i>returns 0 (the <font class="fixd">NULL</font>
12058 address) if an error occurs, otherwise, it returns a pointer to a linear memory area of size
12059 at least size.<br>
12060 <br>
12061 * NUMA (nonuniform memory access) computers are multiprocessor systems where memory is "local" to
12062 specific groups of processors ("nodes"). Access to local memory is faster than access to nonlocal memory.
12063 On such systems, allocating memory on the correct node is important. Driver authors do not normally have
12064 to worry about NUMA issues, however.<br>
12065 <br>
12066 <A name="225"></a><font color="blue">PAGE 225</font><br>
12067 <br>
12068 We describe <i>vmalloc </i>here because it is one of the fundamental Linux memory allocation
12069 mechanisms. We should note, however, that use of <i>vmalloc </i>is discouraged in
12070 most situations. Memory obtained from <i>vmalloc </i>is slightly less efficient to work with,
12071 and, on some architectures, the amount of address space set aside for <i>vmalloc </i>is relatively
12072 small. Code that uses <i>vmalloc </i>is likely to get a chilly reception if submitted for
12073 inclusion in the kernel. If possible, you should work directly with individual pages
12074 rather than trying to smooth things over with <i>vmalloc</i>.<br>
12075 <br>
12076 That said, let's see how <i>vmalloc </i>works. The prototypes of the function and its relatives
12077 (<i>ioremap</i>, which is not strictly an allocation function, is discussed later in this
12078 section) are as follows:<br>
12079 <pre>
12080 #include <linux/vmalloc.h>
12082 void *vmalloc(unsigned long size);
12083 void vfree(void * addr);
12084 void *ioremap(unsigned long offset, unsigned long size);
12085 void iounmap(void * addr);
12086 </pre>
12087 It's worth stressing that memory addresses returned by <i>kmalloc </i>and <i>_get_free_pages
12088 </i>are also virtual addresses. Their actual value is still massaged by the MMU (the memory
12089 management unit, usually part of the CPU) before it is used to address physical
12090 memory.* <i>vmalloc </i>is not different in how it uses the hardware, but rather in how the
12091 kernel performs the allocation task.<br>
12092 <br>
12093 The (virtual) address range used by <i>kmalloc </i>and <i>__get_free_pages </i>features a one-toone
12094 mapping to physical memory, possibly shifted by a constant <font class="fixd">PAGE_OFFSET</font> value;
12095 the functions don't need to modify the page tables for that address range. The
12096 address range used by <i>vmalloc </i>and <i>ioremap</i>, on the other hand, is completely synthetic,
12097 and each allocation builds the (virtual) memory area by suitably setting up the
12098 page tables.<br>
12099 <br>
12100 This difference can be perceived by comparing the pointers returned by the allocation
12101 functions. On some platforms (for example, the x86), addresses returned by
12102 <i>vmalloc </i>are just beyond the addresses that <i>kmalloc </i>uses. On other platforms (for
12103 example, MIPS, IA-64, and x86_64), they belong to a completely different address
12104 range. Addresses available for <i>vmalloc </i>are in the range from <font class="fixd">VMALLOC_START</font> to
12105 <font class="fixd">VMALLOC_END</font>. Both symbols are defined in <i><asm/pgtable.h></i>.<br>
12106 <br>
12107 Addresses allocated by <i>vmalloc </i>can't be used outside of the microprocessor, because
12108 they make sense only on top of the processor's MMU. When a driver needs a real
12109 physical address (such as a DMA address, used by peripheral hardware to drive the
12110 system's bus), you can't easily use <i>vmalloc</i>. The right time to call <i>vmalloc </i>is when<br>
12111 <br>
12112 * Actually, some architectures define ranges of "virtual" addresses as reserved to address physical memory.
12113 When this happens, the Linux kernel takes advantage of the feature, and both the kernel and <i>__get_free_pages
12114 </i>addresses lie in one of those memory ranges. The difference is transparent to device drivers and other code
12115 that is not directly involved with the memory-management kernel subsystem.<br>
12116 <br>
12117 <A name="226"></a><font color="blue">PAGE 226</font><br>
12118 <br>
12119 you are allocating memory for a large sequential buffer that exists only in software.
12120 It's important to note that <i>vmalloc </i>has more overhead than <i>__get_free_pages</i>,
12121 because it must both retrieve the memory and build the page tables. Therefore, it
12122 doesn't make sense to call <i>vmalloc</i> to allocate just one page.<br>
12123 <br>
12124 An example of a function in the kernel that uses <i>vmalloc </i>is the <i>create_module </i>system
12125 call, which uses <i>vmalloc </i>to get space for the module being created. Code and data of
12126 the module are later copied to the allocated space using <i>copy_from_user</i>. In this way,
12127 the module appears to be loaded into contiguous memory. You can verify, by looking
12128 in <i>/proc/kallsyms</i>, that kernel symbols exported by modules lie in a different
12129 memory range from symbols exported by the kernel proper.<br>
12130 <br>
12131 Memory allocated with <i>vmalloc </i>is released by <i>vfree</i>, in the same way that <i>kfree
12132 </i>releases memory allocated by <i>kmalloc</i>.<br>
12133 <br>
12134 Like <i>vmalloc</i>, <i>ioremap </i>builds new page tables; unlike <i>vmalloc</i>, however, it doesn't
12135 actually allocate any memory. The return value of <i>ioremap </i>is a special virtual address
12136 that can be used to access the specified physical address range; the virtual address
12137 obtained is eventually released by calling <i>iounmap</i>.<br>
12138 <br>
12139 <i>ioremap </i>is most useful for mapping the (physical) address of a PCI buffer to (virtual)
12140 kernel space. For example, it can be used to access the frame buffer of a PCI video
12141 device; such buffers are usually mapped at high physical addresses, outside of the
12142 address range for which the kernel builds page tables at boot time. PCI issues are
12143 explained in more detail in Chapter 12.<br>
12144 <br>
12145 It's worth noting that for the sake of portability, you should not directly access
12146 addresses returned by <i>ioremap </i>as if they were pointers to memory. Rather, you
12147 should always use <i>readb </i>and the other I/O functions introduced in Chapter 9. This
12148 requirement applies because some platforms, such as the Alpha, are unable to
12149 directly map PCI memory regions to the processor address space because of differences
12150 between PCI specs and Alpha processors in how data is transferred.<br>
12151 <br>
12152 Both <i>ioremap </i>and <i>vmalloc </i>are page oriented (they work by modifying the page
12153 tables); consequently, the relocated or allocated size is rounded up to the nearest
12154 page boundary. <i>ioremap </i>simulates an unaligned mapping by "rounding down" the
12155 address to be remapped and by returning an offset into the first remapped page.<br>
12156 <br>
12157 One minor drawback of <i>vmalloc </i>is that it can't be used in atomic context because,
12158 internally, it uses <i>kmalloc(GFP_KERNEL) </i>to acquire storage for the page tables, and
12159 therefore could sleep. This shouldn't be a problem--if the use of <i>__get_free_page </i>isn't
12160 good enough for an interrupt handler, the software design needs some cleaning up.<br>
12161 <br>
12162 <A name="227"></a><font color="blue">PAGE 227</font><br>
12163 <br>
12164 <a name="AScullUsingVirtualAddressesScullv"></a><font color="red"><b>A scull Using Virtual Addresses: scullv</b></font><br>
12165 <br>
12166 Sample code using <i>vmalloc </i>is provided in the <i>scullv </i>module. Like <i>scullp</i>, this module
12167 is a stripped-down version of <i>scull </i>that uses a different allocation function to obtain
12168 space for the device to store data.<br>
12169 <br>
12170 The module allocates memory 16 pages at a time. The allocation is done in large
12171 chunks to achieve better performance than <i>scullp </i>and to show something that takes
12172 too long with other allocation techniques to be feasible. Allocating more than one
12173 page with <i>__get_free_pages </i>is failure prone, and even when it succeeds, it can be
12174 slow. As we saw earlier, <i>vmalloc </i>is faster than other functions in allocating several
12175 pages, but somewhat slower when retrieving a single page, because of the overhead
12176 of page-table building. <i>scullv </i>is designed like <i>scullp</i>. order specifies the "order" of
12177 each allocation and defaults to 4. The only difference between <i>scullv </i>and <i>scullp </i>is in
12178 allocation management. These lines use <i>vmalloc</i> to obtain new memory:<br>
12179 <pre>
12180 /* Allocate a quantum using virtual addresses */
12181 if (!dptr->data[s_pos]) {
12182 dptr->data[s_pos] =
12183 (void *)vmalloc(PAGE_SIZE << dptr->order);
12184 if (!dptr->data[s_pos])
12185 goto nomem;
12186 memset(dptr->data[s_pos], 0, PAGE_SIZE << dptr->order);
12187 }
12188 </pre>
12189 and these lines release memory:<br>
12190 <pre>
12191 /* Release the quantum-set */
12192 for (i = 0; i < qset; i++)
12193 if (dptr->data[i])
12194 vfree(dptr->data[i]);
12195 </pre>
12196 If you compile both modules with debugging enabled, you can look at their data
12197 allocation by reading the files they create in <i>/proc</i>. This snapshot was taken on an
12198 x86_64 system:<br>
12199 <pre>
12200 salma% cat /tmp/bigfile > /dev/scullp0; head -5 /proc/scullpmem
12201 Device 0: qset 500, order 0, sz 1535135
12202 item at 000001001847da58, qset at 000001001db4c000
12203 0:1001db56000
12204 1:1003d1c7000
12206 salma% cat /tmp/bigfile > /dev/scullv0; head -5 /proc/scullvmem
12208 Device 0: qset 500, order 4, sz 1535135
12209 item at 000001001847da58, qset at 0000010013dea000
12210 0:ffffff0001177000
12211 1:ffffff0001188000
12212 </pre>
12213 <A name="228"></a><font color="blue">PAGE 228</font><br>
12214 <br>
12215 The following output, instead, came from an x86 system:<br>
12216 <pre>
12217 rudo% cat /tmp/bigfile > /dev/scullp0; head -5 /proc/scullpmem
12219 Device 0: qset 500, order 0, sz 1535135
12220 item at ccf80e00, qset at cf7b9800
12221 0:ccc58000
12222 1:cccdd000
12224 rudo% cat /tmp/bigfile > /dev/scullv0; head -5 /proc/scullvmem
12226 Device 0: qset 500, order 4, sz 1535135
12227 item at cfab4800, qset at cf8e4000
12228 0:d087a000
12229 1:d08d2000
12230 </pre>
12231 The values show two different behaviors. On x86_64, physical addresses and virtual
12232 addresses are mapped to completely different address ranges (0x100 and 0xffffff00),
12233 while on x86 computers, <i>vmalloc </i>returns virtual addresses just above the mapping
12234 used for physical memory.<br>
12235 <br>
12236 <a name="PerCPUVariables"></a><font color="red"><b>Per-CPU Variables</b></font><br>
12237 <br>
12238 Per-CPU variables are an interesting 2.6 kernel feature. When you create a per-CPU
12239 variable, each processor on the system gets its own copy of that variable. This may
12240 seem like a strange thing to want to do, but it has its advantages. Access to per-CPU
12241 variables requires (almost) no locking, because each processor works with its own
12242 copy. Per-CPU variables can also remain in their respective processors'caches, which
12243 leads to significantly better performance for frequently updated quantities.<br>
12244 <br>
12245 A good example of per-CPU variable use can be found in the networking subsystem.
12246 The kernel maintains no end of counters tracking how many of each type of packet
12247 was received; these counters can be updated thousands of times per second. Rather
12248 than deal with the caching and locking issues, the networking developers put the statistics
12249 counters into per-CPU variables. Updates are now lockless and fast. On the
12250 rare occasion that user space requests to see the values of the counters, it is a simple
12251 matter to add up each processor's version and return the total.<br>
12252 <br>
12253 The declarations for per-CPU variables can be found in <i><linux/percpu.h></i>. To create a
12254 per-CPU variable at compile time, use this macro:<br>
12255 <pre>
12256 DEFINE_PER_CPU(type, name);
12257 </pre>
12258 If the variable (to be called <font class="fixd">name</font>) is an array, include the dimension information with
12259 the type. Thus, a per-CPU array of three integers would be created with:<br>
12260 <pre>
12261 DEFINE_PER_CPU(int[3], my_percpu_array);
12262 </pre>
12263 Per-CPU variables can be manipulated without explicit locking--almost. Remember
12264 that the 2.6 kernel is preemptible; it would not do for a processor to be preempted in<br>
12265 <br>
12266 <A name="229"></a><font color="blue">PAGE 229</font><br>
12267 <br>
12268 the middle of a critical section that modifies a per-CPU variable. It also would not be
12269 good if your process were to be moved to another processor in the middle of a perCPU
12270 variable access. For this reason, you must explicitly use the <i>get_cpu_var </i>macro
12271 to access the current processor's copy of a given variable, and call <i>put_cpu_var </i>when
12272 you are done. The call to <i>get_cpu_var </i>returns an lvalue for the current processor's
12273 version of the variable and disables preemption. Since an lvalue is returned, it can be
12274 assigned to or operated on directly. For example, one counter in the networking code
12275 is incremented with these two statements:<br>
12276 <pre>
12277 get_cpu_var(sockets_in_use)++;
12278 put_cpu_var(sockets_in_use);
12279 </pre>
12280 You can access another processor's copy of the variable with:<br>
12281 <pre>
12282 per_cpu(variable, int cpu_id);
12283 </pre>
12284 If you write code that involves processors reaching into each other's per-CPU variables,
12285 you, of course, have to implement a locking scheme that makes that access
12286 safe.<br>
12287 <br>
12288 Dynamically allocated per-CPU variables are also possible. These variables can be
12289 allocated with:<br>
12290 <pre>
12291 void *alloc_percpu(type);
12292 void *__alloc_percpu(size_t size, size_t align);
12293 </pre>
12294 In most cases, <i>alloc_percpu </i>does the job; you can call <i>__alloc_percpu </i>in cases where
12295 a particular alignment is required. In either case, a per-CPU variable can be returned
12296 to the system with <i>free_percpu</i>. Access to a dynamically allocated per-CPU variable is
12297 done via <i>per_cpu_ptr</i>:<br>
12298 <pre>
12299 per_cpu_ptr(void *per_cpu_var, int cpu_id);
12300 </pre>
12301 This macro returns a pointer to the version of <font class="fixd">per_cpu_var</font> corresponding to the given
12302 <font class="fixd">cpu_id</font>. If you are simply reading another CPU's version of the variable, you can dereference
12303 that pointer and be done with it. If, however, you are manipulating the current
12304 processor's version, you probably need to ensure that you cannot be moved out of
12305 that processor first. If the entirety of your access to the per-CPU variable happens
12306 with a spinlock held, all is well. Usually, however, you need to use <i>get_cpu </i>to block
12307 preemption while working with the variable. Thus, code using dynamic per-CPU variables
12308 tends to look like this:<br>
12309 <pre>
12310 int cpu;
12312 cpu = get_cpu( )
12313 ptr = per_cpu_ptr(per_cpu_var, cpu);
12314 /* work with ptr */
12315 put_cpu( );
12316 </pre>
12317 When using compile-time per-CPU variables, the <i>get_cpu_var </i>and <i>put_cpu_var </i>macros
12318 take care of these details. Dynamic per-CPU variables require more explicit protection.<br>
12319 <br>
12320 <A name="230"></a><font color="blue">PAGE 230</font><br>
12321 <br>
12322 Per-CPU variables can be exported to modules, but you must use a special version of
12323 the macros:<br>
12324 <pre>
12325 EXPORT_PER_CPU_SYMBOL(per_cpu_var);
12326 EXPORT_PER_CPU_SYMBOL_GPL(per_cpu_var);
12327 </pre>
12328 To access such a variable within a module, declare it with:<br>
12329 <pre>
12330 DECLARE_PER_CPU(type, name);
12331 </pre>
12332 The use of <i><font class="fixd">DECLARE_PER_CPU</font> </i>(instead of <i><font class="fixd">DEFINE_PER_CPU</font></i>) tells the compiler
12333 that an external reference is being made.<br>
12334 <br>
12335 If you want to use per-CPU variables to create a simple integer counter, take a look
12336 at the canned implementation in <i><linux/percpu_counter.h></i>. Finally, note that some
12337 architectures have a limited amount of address space available for per-CPU variables.
12338 If you create per-CPU variables in your code, you should try to keep them
12339 small.<br>
12340 <br>
12341 <a name="ObtainingLargeBuffers"></a><font color="red"><b>Obtaining Large Buffers</b></font><br>
12342 <br>
12343 As we have noted in previous sections, allocations of large, contiguous memory buffers
12344 are prone to failure. System memory fragments over time, and chances are that a
12345 truly large region of memory will simply not be available. Since there are usually
12346 ways of getting the job done without huge buffers, the kernel developers have not
12347 put a high priority on making large allocations work. Before you try to obtain a large
12348 memory area, you should really consider the alternatives. By far the best way of performing
12349 large I/O operations is through scatter/gather operations, which we discuss
12350 in the section "Scatter-gather mappings" in Chapter 1.<br>
12351 <br>
12352 <a name="AcquiringADedicatedBufferAtBootTime"></a><font color="red"><b>Acquiring a Dedicated Buffer at Boot Time</b></font><br>
12353 <br>
12354 If you really need a huge buffer of physically contiguous memory, the best approach
12355 is often to allocate it by requesting memory at boot time. Allocation at boot time is
12356 the only way to retrieve consecutive memory pages while bypassing the limits
12357 imposed by <i>__get_free_pages </i>on the buffer size, both in terms of maximum allowed
12358 size and limited choice of sizes. Allocating memory at boot time is a "dirty" technique,
12359 because it bypasses all memory management policies by reserving a private
12360 memory pool. This technique is inelegant and inflexible, but it is also the least prone
12361 to failure. Needless to say, a module can't allocate memory at boot time; only drivers
12362 directly linked to the kernel can do that.<br>
12363 <br>
12364 One noticeable problem with boot-time allocation is that it is not a feasible option
12365 for the average user, since this mechanism is available only for code linked in the kernel
12366 image. A device driver using this kind of allocation can be installed or replaced
12367 only by rebuilding the kernel and rebooting the computer.<br>
12368 <br>
12369 <A name="231"></a><font color="blue">PAGE 231</font><br>
12370 <br>
12371 When the kernel is booted, it gains access to all the physical memory available in the
12372 system. It then initializes each of its subsystems by calling that subsystem's initialization
12373 function, allowing initialization code to allocate a memory buffer for private use
12374 by reducing the amount of RAM left for normal system operation.<br>
12375 <br>
12376 Boot-time memory allocation is performed by calling one of these functions:<br>
12377 <pre>
12378 #include <linux/bootmem.h>
12379 void *alloc_bootmem(unsigned long size);
12380 void *alloc_bootmem_low(unsigned long size);
12381 void *alloc_bootmem_pages(unsigned long size);
12382 void *alloc_bootmem_low_pages(unsigned long size);
12383 </pre>
12384 The functions allocate either whole pages (if they end with <font class="fixd">_pages</font>) or non-page aligned
12385 memory areas. The allocated memory may be high memory unless one of the
12386 <font class="fixd">_low</font> versions is used. If you are allocating this buffer for a device driver, you probably
12387 want to use it for DMA operations, and that is not always possible with high
12388 memory; thus, you probably want to use one of the <font class="fixd">_low</font> variants.<br>
12389 <br>
12390 It is rare to free memory allocated at boot time; you will almost certainly be unable
12391 to get it back later if you want it. There is an interface to free this memory, however:<br>
12392 <pre>
12393 void free_bootmem(unsigned long addr, unsigned long size);
12394 </pre>
12395 Note that partial pages freed in this manner are not returned to the system--but, if
12396 you are using this technique, you have probably allocated a fair number of whole
12397 pages to begin with.<br>
12398 <br>
12399 If you must use boot-time allocation, you need to link your driver directly into the
12400 kernel. See the files in the kernel source under <i>Documentation/kbuild </i>for more information
12401 on how this should be done.<br>
12402 <br>
12403 <a name="QuickReference8"></a><font color="red"><b>Quick Reference</b></font><br>
12404 <br>
12405 The functions and symbols related to memory allocation are:<br>
12406 <br>
12407 <font class="fixd">#include <linux/slab.h><br>
12408 void *kmalloc(size_t size, int flags);<br>
12409 void kfree(void *obj);</font><br>
12410 <div class="bq">
12411 The most frequently used interface to memory allocation.</div>
12412 <br>
12413 <font class="fixd">#include <linux/mm.h><br>
12414 GFP_USER<br>
12415 GFP_KERNEL<br>
12416 GFP_NOFS<br>
12417 GFP_NOIO<br>
12418 GFP_ATOMIC</font><br>
12419 <div class="bq">
12420 Flags that control how memory allocations are performed, from the least restrictive
12421 to the most. The <font class="fixd">GFP_USER</font> and <font class="fixd">GFP_KERNEL</font> priorities allow the current process</div>
12422 <br>
12423 <A name="232"></a><font color="blue">PAGE 232</font><br>
12424 <br>
12425 <div class="bq">to be put to sleep to satisfy the request. <font class="fixd">GFP_NOFS</font> and <font class="fixd">GFP_NOIO</font> disable filesystem
12426 operations and all I/O operations, respectively, while <font class="fixd">GFP_ATOMIC</font> allocations cannot
12427 sleep at all.</div>
12428 <br>
12429 <font class="fixd">__GFP_DMA<br>
12430 __GFP_HIGHMEM<br>
12431 __GFP_COLD<br>
12432 __GFP_NOWARN<br>
12433 __GFP_HIGH<br>
12434 __GFP_REPEAT<br>
12435 __GFP_NOFAIL<br>
12436 __GFP_NORETRY</font><br>
12437 <div class="bq">
12438 These flags modify the kernel's behavior when allocating memory.</div>
12439 <br>
12440 <font class="fixd">#include <linux/malloc.h><br>
12441 kmem_cache_t *kmem_cache_create(char *name, size_t size, size_t offset,<br>
12442 unsigned long flags, constructor( ), destructor( ));<br>
12443 int kmem_cache_destroy(kmem_cache_t *cache);</font><br>
12444 <div class="bq">
12445 Create and destroy a slab cache. The cache can be used to allocate several
12446 objects of the same size.</div>
12447 <br>
12448 <font class="fixd">SLAB_NO_REAP<br>
12449 SLAB_HWCACHE_ALIGN<br>
12450 SLAB_CACHE_DMA</font><br>
12451 <div class="bq">
12452 Flags that can be specified while creating a cache.</div>
12453 <br>
12454 <font class="fixd">SLAB_CTOR_ATOMIC<br>
12455 SLAB_CTOR_CONSTRUCTOR</font><br>
12456 <div class="bq">
12457 Flags that the allocator can pass to the constructor and the destructor functions.</div>
12458 <br>
12459 <font class="fixd">void *kmem_cache_alloc(kmem_cache_t *cache, int flags);<br>
12460 void kmem_cache_free(kmem_cache_t *cache, const void *obj);</font><br>
12461 <div class="bq">
12462 Allocate and release a single object from the cache.</div>
12463 <br>
12464 <i>/proc/slabinfo</i><br>
12465 <div class="bq">
12466 A virtual file containing statistics on slab cache usage.</div>
12467 <br>
12468 <font class="fixd">#include <linux/mempool.h><br>
12469 mempool_t *mempool_create(int min_nr, mempool_alloc_t *alloc_fn, mempool_free_t *free_fn, void *data);<br>
12470 void mempool_destroy(mempool_t *pool);</font><br>
12471 <div class="bq">
12472 Functions for the creation of memory pools, which try to avoid memory allocation
12473 failures by keeping an "emergency list" of allocated items.</div>
12474 <br>
12475 <font class="fixd">void *mempool_alloc(mempool_t *pool, int gfp_mask);<br>
12476 void mempool_free(void *element, mempool_t *pool);</font><br>
12477 <div class="bq">
12478 Functions for allocating items from (and returning them to) memory pools.</div>
12479 <br>
12480 <A name="233"></a><font color="blue">PAGE 233</font><br>
12481 <br>
12482 <font class="fixd">unsigned long get_zeroed_page(int flags);<br>
12483 unsigned long __get_free_page(int flags);<br>
12484 unsigned long __get_free_pages(int flags, unsigned long order);</font><br>
12485 <div class="bq">
12486 The page-oriented allocation functions. <i>get_zeroed_page </i>returns a single, zero-filled
12487 page. All the other versions of the call do not initialize the contents of the
12488 returned page(s).</div>
12489 <br>
12490 <font class="fixd">int get_order(unsigned long size);</font><br>
12491 <div class="bq">
12492 Returns the allocation order associated to <i>size </i>in the current platform, according
12493 to <font class="fixd">PAGE_SIZE</font>. The argument must be a power of two, and the return value is at
12494 least 0.</div>
12495 <br>
12496 <font class="fixd">void free_page(unsigned long addr);<br>
12497 void free_pages(unsigned long addr, unsigned long order);</font><br>
12498 <div class="bq">
12499 Functions that release page-oriented allocations.</div>
12500 <br>
12501 <font class="fixd">struct page *alloc_pages_node(int nid, unsigned int flags, unsigned int order);<br>
12502 struct page *alloc_pages(unsigned int flags, unsigned int order);<br>
12503 struct page *alloc_page(unsigned int flags);</font><br>
12504 <div class="bq">
12505 All variants of the lowest-level page allocator in the Linux kernel.</div>
12506 <br>
12507 <font class="fixd">void __free_page(struct page *page);<br>
12508 void __free_pages(struct page *page, unsigned int order);<br>
12509 void free_hot_page(struct page *page);<br>
12510 void free_cold_page(struct page *page);</font><br>
12511 <div class="bq">
12512 Various ways of freeing pages allocated with one of the forms of <i>alloc_page</i>.</div>
12513 <br>
12514 <font class="fixd">#include <linux/vmalloc.h><br>
12515 void * vmalloc(unsigned long size);<br>
12516 void vfree(void * addr);<br>
12517 #include <asm/io.h><br>
12518 void * ioremap(unsigned long offset, unsigned long size);<br>
12519 void iounmap(void *addr);</font><br>
12520 <div class="bq">
12521 Functions that allocate or free a contiguous <i>virtual </i>address space. <i>ioremap
12522 </i>accesses physical memory through virtual addresses, while <i>vmalloc </i>allocates free
12523 pages. Regions mapped with <i>ioremap </i>are freed with <i>iounmap</i>, while pages
12524 obtained from <i>vmalloc</i> are released with <i>vfree</i>.</div>
12525 <br>
12526 <font class="fixd">#include <linux/percpu.h><br>
12527 DEFINE_PER_CPU(type, name);<br>
12528 DECLARE_PER_CPU(type, name);</font><br>
12529 <div class="bq">
12530 Macros that define and declare per-CPU variables.</div>
12531 <br>
12532 <font class="fixd">per_cpu(variable, int cpu_id)<br>
12533 get_cpu_var(variable)<br>
12534 put_cpu_var(variable)</font><br>
12535 <div class="bq">
12536 Macros that provide access to statically declared per-CPU variables.</div>
12537 <br>
12538 <A name="234"></a><font color="blue">PAGE 234</font><br>
12539 <br>
12540 <font class="fixd">void *alloc_percpu(type);<br>
12541 void *__alloc_percpu(size_t size, size_t align);<br>
12542 void free_percpu(void *variable);</font><br>
12543 <div class="bq">
12544 Functions that perform runtime allocation and freeing of per-CPU variables.</div>
12545 <br>
12546 <font class="fixd">int get_cpu( );<br>
12547 void put_cpu( );<br>
12548 per_cpu_ptr(void *variable, int cpu_id)</font><br>
12549 <div class="bq">
12550 <i>get_cpu </i>obtains a reference to the current processor (therefore, preventing preemption
12551 and movement to another processor) and returns the ID number of the
12552 processor; <i>put_cpu </i>returns that reference. To access a dynamically allocated perCPU
12553 variable, use <i>per_cpu_ptr </i>with the ID of the CPU whose version should be
12554 accessed. Manipulations of the current CPU's version of a dynamic, per-CPU
12555 variable should probably be surrounded by calls to <i>get_cpu</i> and <i>put_cpu</i>.</div>
12556 <br>
12557 <font class="fixd">#include <linux/bootmem.h><br>
12558 void *alloc_bootmem(unsigned long size);<br>
12559 void *alloc_bootmem_low(unsigned long size);<br>
12560 void *alloc_bootmem_pages(unsigned long size);<br>
12561 void *alloc_bootmem_low_pages(unsigned long size);<br>
12562 void free_bootmem(unsigned long addr, unsigned long size);</font><br>
12563 <div class="bq">
12564 Functions (which can be used only by drivers directly linked into the kernel) that
12565 perform allocation and freeing of memory at system bootstrap time.</div>
12566 <br>
12567 <A name="235"></a><font color="blue">PAGE 235</font><br>
12568 <br>
12569 <a name="CHAPTER9"></a><font color="red"><b>CHAPTER 9</b></font><br>
12570 <br>
12571 <a name="CommunicatingWithHardware"></a><font color="#7519FF" size="+1"><b>Communicating with Hardware</b></font><br>
12572 <br>
12573 Although playing with <i>scull </i>and similar toys is a good introduction to the software
12574 interface of a Linux device driver, implementing a <i>real </i>device requires hardware. The
12575 driver is the abstraction layer between software concepts and hardware circuitry; as
12576 such, it needs to talk with both of them. Up until now, we have examined the internals
12577 of software concepts; this chapter completes the picture by showing you how
12578 a driver can access I/O ports and I/O memory while being portable across Linux
12579 platforms.<br>
12580 <br>
12581 This chapter continues in the tradition of staying as independent of specific hardware
12582 as possible. However, where specific examples are needed, we use simple digital
12583 I/O ports (such as the standard PC parallel port) to show how the I/O
12584 instructions work and normal frame-buffer video memory to show memory-mapped
12585 I/O.<br>
12586 <br>
12587 We chose simple digital I/O because it is the easiest form of an input/output port.
12588 Also, the parallel port implements raw I/O and is available in most computers: data
12589 bits written to the device appear on the output pins, and voltage levels on the input
12590 pins are directly accessible by the processor. In practice, you have to connect LEDs
12591 or a printer to the port to actually <i>see </i>the results of a digital I/O operation, but the
12592 underlying hardware is extremely easy to use.<br>
12593 <br>
12594 <a name="IOPortsAndIOMemory"></a><font color="red"><b>I/O Ports and I/O Memory</b></font><br>
12595 <br>
12596 Every peripheral device is controlled by writing and reading its registers. Most of the
12597 time a device has several registers, and they are accessed at consecutive addresses,
12598 either in the memory address space or in the I/O address space.<br>
12599 <br>
12600 At the hardware level, there is no conceptual difference between memory regions and
12601 I/O regions: both of them are accessed by asserting electrical signals on the address<br>
12602 <br>
12603 <A name="236"></a><font color="blue">PAGE 236</font><br>
12604 <br>
12605 bus and control bus (i.e., the <i>read </i>and <i>write </i>signals)* and by reading from or writing
12606 to the data bus.<br>
12607 <br>
12608 While some CPU manufacturers implement a single address space in their chips, others
12609 decided that peripheral devices are different from memory and, therefore, deserve
12610 a separate address space. Some processors (most notably the x86 family) have separate
12611 <i>read </i>and <i>write </i>electrical lines for I/O ports and special CPU instructions to
12612 access ports.<br>
12613 <br>
12614 Because peripheral devices are built to fit a peripheral bus, and the most popular I/O
12615 buses are modeled on the personal computer, even processors that do not have a separate
12616 address space for I/O ports must fake reading and writing I/O ports when
12617 accessing some peripheral devices, usually by means of external chipsets or extra circuitry
12618 in the CPU core. The latter solution is common within tiny processors meant
12619 for embedded use.<br>
12620 <br>
12621 For the same reason, Linux implements the concept of I/O ports on all computer
12622 platforms it runs on, even on platforms where the CPU implements a single address
12623 space. The implementation of port access sometimes depends on the specific make
12624 and model of the host computer (because different models use different chipsets to
12625 map bus transactions into memory address space).<br>
12626 <br>
12627 Even if the peripheral bus has a separate address space for I/O ports, not all devices
12628 map their registers to I/O ports. While use of I/O ports is common for ISA peripheral
12629 boards, most PCI devices map registers into a memory address region. This I/O
12630 memory approach is generally preferred, because it doesn't require the use of special purpose
12631 processor instructions; CPU cores access memory much more efficiently,
12632 and the compiler has much more freedom in register allocation and addressing-mode
12633 selection when accessing memory.<br>
12634 <br>
12635 <a name="IORegistersAndConventionalMemory"></a><font color="red"><b>I/O Registers and Conventional Memory</b></font><br>
12636 <br>
12637 Despite the strong similarity between hardware registers and memory, a programmer
12638 accessing I/O registers must be careful to avoid being tricked by CPU (or compiler)
12639 optimizations that can modify the expected I/O behavior.<br>
12640 <br>
12641 The main difference between I/O registers and RAM is that I/O operations have side
12642 effects, while memory operations have none: the only effect of a memory write is
12643 storing a value to a location, and a memory read returns the last value written there.
12644 Because memory access speed is so critical to CPU performance, the no-side-effects
12645 case has been optimized in several ways: values are cached and read/write instructions
12646 are reordered.<br>
12647 <br>
12648 * Not all computer platforms use a <i>read </i>and a <i>write </i>signal; some have different means to address external circuits. The difference is irrelevant at software level, however, and we'll assume all have <i>read </i>and <i>write </i>to simplify
12649 the discussion.<br>
12650 <br>
12651 <A name="237"></a><font color="blue">PAGE 237</font><br>
12652 <br>
12653 The compiler can cache data values into CPU registers without writing them to
12654 memory, and even if it stores them, both write and read operations can operate on
12655 cache memory without ever reaching physical RAM. Reordering can also happen
12656 both at the compiler level and at the hardware level: often a sequence of instructions
12657 can be executed more quickly if it is run in an order different from that which
12658 appears in the program text, for example, to prevent interlocks in the RISC pipeline.
12659 On CISC processors, operations that take a significant amount of time can be executed
12660 concurrently with other, quicker ones.<br>
12661 <br>
12662 These optimizations are transparent and benign when applied to conventional memory
12663 (at least on uniprocessor systems), but they can be fatal to correct I/O operations,
12664 because they interfere with those "side effects" that are the main reason why a
12665 driver accesses I/O registers. The processor cannot anticipate a situation in which
12666 some other process (running on a separate processor, or something happening inside
12667 an I/O controller) depends on the order of memory access. The compiler or the CPU
12668 may just try to outsmart you and reorder the operations you request; the result can
12669 be strange errors that are very difficult to debug. Therefore, a driver must ensure that
12670 no caching is performed and no read or write reordering takes place when accessing
12671 registers.<br>
12672 <br>
12673 The problem with hardware caching is the easiest to face: the underlying hardware is
12674 already configured (either automatically or by Linux initialization code) to disable
12675 any hardware cache when accessing I/O regions (whether they are memory or port
12676 regions).<br>
12677 <br>
12678 The solution to compiler optimization and hardware reordering is to place a <i>memory
12679 barrier </i>between operations that must be visible to the hardware (or to another processor)
12680 in a particular order. Linux provides four macros to cover all possible ordering
12681 needs:<br>
12682 <br>
12683 <font class="fixd">#include <linux/kernel.h><br>
12684 void barrier(void)</font><br>
12685 <div class="bq">
12686 This function tells the compiler to insert a memory barrier but has no effect on
12687 the hardware. Compiled code stores to memory all values that are currently
12688 modified and resident in CPU registers, and rereads them later when they are
12689 needed. A call to <i>barrier </i>prevents compiler optimizations across the barrier but
12690 leaves the hardware free to do its own reordering.</div>
12691 <br>
12692 <font class="fixd">#include <asm/system.h><br>
12693 void rmb(void);<br>
12694 void read_barrier_depends(void);<br>
12695 void wmb(void);<br>
12696 void mb(void);</font><br>
12697 <div class="bq">
12698 These functions insert hardware memory barriers in the compiled instruction
12699 flow; their actual instantiation is platform dependent. An <i>rmb </i>(read memory
12700 barrier) guarantees that any reads appearing before the barrier are completed</div>
12701 <br>
12702 <A name="238"></a><font color="blue">PAGE 238</font><br>
12703 <br>
12704 <div class="bq">
12705 prior to the execution of any subsequent read. <i>wmb </i>guarantees ordering in write
12706 operations, and the <i>mb </i>instruction guarantees both. Each of these functions is a
12707 superset of <i>barrier</i>.<br>
12708 <br>
12709 <i>read_barrier_depends </i>is a special, weaker form of read barrier. Whereas <i>rmb </i>prevents
12710 the reordering of all reads across the barrier, <i>read_barrier_depends </i>blocks
12711 only the reordering of reads that depend on data from other reads. The distinction
12712 is subtle, and it does not exist on all architectures. Unless you understand
12713 exactly what is going on, and you have a reason to believe that a full read barrier
12714 is exacting an excessive performance cost, you should probably stick to using
12715 <i>rmb</i>.</div>
12716 <br>
12717 <font class="fixd">void smp_rmb(void);<br>
12718 void smp_read_barrier_depends(void);<br>
12719 void smp_wmb(void);<br>
12720 void smp_mb(void);</font><br>
12721 <div class="bq">
12722 These versions of the barrier macros insert hardware barriers only when the kernel
12723 is compiled for SMP systems; otherwise, they all expand to a simple <i>barrier
12724 </i>call.</div>
12725 <br>
12726 A typical usage of memory barriers in a device driver may have this sort of form:<br>
12727 <pre>
12728 writel(dev->registers.addr, io_destination_address);
12729 writel(dev->registers.size, io_size);
12730 writel(dev->registers.operation, DEV_READ);
12731 wmb( );
12732 writel(dev->registers.control, DEV_GO);
12733 </pre>
12734 In this case, it is important to be sure that all of the device registers controlling a particular
12735 operation have been properly set prior to telling it to begin. The memory barrier
12736 enforces the completion of the writes in the necessary order.<br>
12737 <br>
12738 Because memory barriers affect performance, they should be used only where they
12739 are really needed. The different types of barriers can also have different performance
12740 characteristics, so it is worthwhile to use the most specific type possible. For example,
12741 on the x86 architecture, <i>wmb( ) </i>currently does nothing, since writes outside the
12742 processor are not reordered. Reads are reordered, however, so <i>mb( ) </i>is slower than
12743 <i>wmb( )</i>.<br>
12744 <br>
12745 It is worth noting that most of the other kernel primitives dealing with synchronization,
12746 such as spinlock and <font class="fixd">atomic_t</font> operations, also function as memory barriers.
12747 Also worthy of note is that some peripheral buses (such as the PCI bus) have caching
12748 issues of their own; we discuss those when we get to them in later chapters.<br>
12749 <br>
12750 Some architectures allow the efficient combination of an assignment and a memory
12751 barrier. The kernel provides a few macros that perform this combination; in the
12752 default case, they are defined as follows:<br>
12753 <pre>
12754 #define set_mb(var, value) do {var = value; mb( );} while 0
12755 #define set_wmb(var, value) do {var = value; wmb( );} while 0
12756 #define set_rmb(var, value) do {var = value; rmb( );} while 0
12757 </pre>
12758 <A name="239"></a><font color="blue">PAGE 239</font><br>
12759 <br>
12760 Where appropriate, <i><asm/system.h> </i>defines these macros to use architecture-specific
12761 instructions that accomplish the task more quickly. Note that <i>set_rmb </i>is defined
12762 only by a small number of architectures. (The use of a <font class="fixd">do...while</font> construct is a standard
12763 C idiom that causes the expanded macro to work as a normal C statement in all
12764 contexts.)<br>
12765 <br>
12766 <a name="UsingIOPorts"></a><font color="red"><b>Using I/O Ports</b></font><br>
12767 <br>
12768 I/O ports are the means by which drivers communicate with many devices, at least
12769 part of the time. This section covers the various functions available for making use of
12770 I/O ports; we also touch on some portability issues.<br>
12771 <br>
12772 <a name="IOPortAllocation"></a><font color="red"><b>I/O Port Allocation</b></font><br>
12773 <br>
12774 As you might expect, you should not go off and start pounding on I/O ports without
12775 first ensuring that you have exclusive access to those ports. The kernel provides a
12776 registration interface that allows your driver to claim the ports it needs. The core
12777 function in that interface is <i>request_region</i>:<br>
12778 <pre>
12779 #include <linux/ioport.h>
12780 struct resource *request_region(unsigned long first, unsigned long n,
12781 const char *name);
12782 </pre>
12783 This function tells the kernel that you would like to make use of <font class="fixd">n</font> ports, starting
12784 with <font class="fixd">first.</font> The <font class="fixd">name</font> parameter should be the name of your device. The return value
12785 is <font class="fixd">non-NULL</font> if the allocation succeeds. If you get <font class="fixd">NULL</font> back from <i>request_region</i>, you
12786 will not be able to use the desired ports.<br>
12787 <br>
12788 All port allocations show up in <i>/proc/ioports</i>. If you are unable to allocate a needed
12789 set of ports, that is the place to look to see who got there first.<br>
12790 <br>
12791 When you are done with a set of I/O ports (at module unload time, perhaps), they
12792 should be returned to the system with:<br>
12793 <pre>
12794 void release_region(unsigned long start, unsigned long n);
12795 </pre>
12796 There is also a function that allows your driver to check to see whether a given set of
12797 I/O ports is available:<br>
12798 <pre>
12799 int check_region(unsigned long first, unsigned long n);
12800 </pre>
12801 Here, the return value is a negative error code if the given ports are not available.
12802 This function is deprecated because its return value provides no guarantee of
12803 whether an allocation would succeed; checking and later allocating are not an atomic
12804 operation. We list it here because several drivers are still using it, but you should
12805 always use <i>request_region</i>, which performs the required locking to ensure that the
12806 allocation is done in a safe, atomic manner.<br>
12807 <br>
12808 <A name="240"></a><font color="blue">PAGE 240</font><br>
12809 <br>
12810 <a name="ManipulatingIOPorts"></a><font color="red"><b>Manipulating I/O ports</b></font><br>
12811 <br>
12812 After a driver has requested the range of I/O ports it needs to use in its activities, it
12813 must read and/or write to those ports. To this end, most hardware differentiates
12814 between 8-bit, 16-bit, and 32-bit ports. Usually you can't mix them like you normally
12815 do with system memory access.*<br>
12816 <br>
12817 A C program, therefore, must call different functions to access different size ports. As
12818 suggested in the previous section, computer architectures that support only memory-mapped
12819 I/O registers fake port I/O by remapping port addresses to memory
12820 addresses, and the kernel hides the details from the driver in order to ease portability.
12821 The Linux kernel headers (specifically, the architecture-dependent header <i><asm/
12822 io.h></i>) define the following inline functions to access I/O ports:<br>
12823 <br>
12824 <font class="fixd">unsigned inb(unsigned port);<br>
12825 void outb(unsigned char byte, unsigned port);</font><br>
12826 <div class="bq">
12827 Read or write byte ports (eight bits wide). The <font class="fixd">port</font> argument is defined as
12828 <font class="fixd">unsigned long</font> for some platforms and <font class="fixd">unsigned short</font> for others. The return
12829 type of <i>inb</i> is also different across architectures.</div>
12830 <br>
12831 <font class="fixd">unsigned inw(unsigned port);<br>
12832 void outw(unsigned short word, unsigned port);</font></div>
12833 <div class="bq">
12834 These functions access 16-bit ports (one word wide); they are not available when
12835 compiling for the S390 platform, which supports only byte I/O.</div>
12836 <br>
12837 <font class="fixd">unsigned inl(unsigned port);<br>
12838 void outl(unsigned longword, unsigned port);</font><br>
12839 <div class="bq">
12840 These functions access 32-bit ports. <font class="fixd">longword</font> is declared as either <font class="fixd">unsigned long</font>
12841 or <font class="fixd">unsigned int</font>, according to the platform. Like word I/O, "long" I/O is not
12842 available on S390.</div>
12843 <br>
12844 <div class="tip">From now on, when we use unsigned without further type specifications,
12845 we are referring to an architecture-dependent definition whose
12846 exact nature is not relevant. The functions are almost always portable,
12847 because the compiler automatically casts the values during assignment--their
12848 being unsigned helps prevent compile-time warnings. No
12849 information is lost with such casts as long as the programmer assigns
12850 sensible values to avoid overflow. We stick to this convention of
12851 "incomplete typing" throughout this chapter.</div>
12852 <br>
12853 Note that no 64-bit port I/O operations are defined. Even on 64-bit architectures, the
12854 port address space uses a 32-bit (maximum) data path.<br>
12855 <br>
12856 * Sometimes I/O ports are arranged like memory, and you can (for example) bind two 8-bit writes into a single
12857 16-bit operation. This applies, for instance, to PC video boards. But generally, you can't count on this feature.<br>
12858 <br>
12859 <A name="241"></a><font color="blue">PAGE 241</font><br>
12860 <br>
12861 <a name="IOPortAccessFromUserSpace"></a><font color="red"><b>I/O Port Access from User Space</b></font><br>
12862 <br>
12863 The functions just described are primarily meant to be used by device drivers, but
12864 they can also be used from user space, at least on PC-class computers. The GNU C
12865 library defines them in <i><sys/io.h></i>. The following conditions should apply in order
12866 for <i>inb</i> and friends to be used in user-space code:<br>
12867 <ul>
12868 <li> The program must be compiled with the <i>-O </i>option to force expansion of inline functions.
12869 <li> The <i>ioperm </i>or <i>iopl </i>system calls must be used to get permission to perform I/O
12870 operations on ports. <i>ioperm </i>gets permission for individual ports, while <i>iopl </i>gets
12871 permission for the entire I/O space. Both of these functions are x86-specific.
12872 <li> The program must run as root to invoke <i>ioperm </i>or <i>iopl</i>.* Alternatively, one of its
12873 ancestors must have gained port access running as root.
12874 </ul>
12875 If the host platform has no <i>ioperm </i>and no <i>iopl </i>system calls, user space can still access
12876 I/O ports by using the <i>/dev/port </i>device file. Note, however, that the meaning of the
12877 file is very platform-specific and not likely useful for anything but the PC.<br>
12878 <br>
12879 The sample sources <i>misc-progs/inp.c </i>and <i>misc-progs/outp.c </i>are a minimal tool for
12880 reading and writing ports from the command line, in user space. They expect to be
12881 installed under multiple names (e.g., <i>inb</i>, <i>inw</i>, and <i>inl </i>and manipulates byte, word, or
12882 long ports depending on which name was invoked by the user). They use <i>ioperm </i>or
12883 <i>iopl</i> under x86, <i>/dev/port</i> on other platforms.<br>
12884 <br>
12885 The programs can be made setuid root, if you want to live dangerously and play with
12886 your hardware without acquiring explicit privileges. Please do not install them setuid
12887 on a production system, however; they are a security hole by design.<br>
12888 <br>
12889 <a name="StringOperations"></a><font color="red"><b>String Operations</b></font><br>
12890 <br>
12891 In addition to the single-shot in and out operations, some processors implement special
12892 instructions to transfer a sequence of bytes, words, or longs to and from a single
12893 I/O port or the same size. These are the so-called <i>string instructions</i>, and they perform
12894 the task more quickly than a C-language loop can do. The following macros
12895 implement the concept of string I/O either by using a single machine instruction or
12896 by executing a tight loop if the target processor has no instruction that performs
12897 string I/O. The macros are not defined at all when compiling for the S390 platform.
12898 This should not be a portability problem, since this platform doesn't usually share
12899 device drivers with other platforms, because its peripheral buses are different.<br>
12900 <br>
12901 * Technically, it must have the <font class="fixd">CAP_SYS_RAWIO</font> capability, but that is the same as running as root on most current systems.<br>
12902 <br>
12903 <A name="242"></a><font color="blue">PAGE 242</font><br>
12904 <br>
12905 The prototypes for string functions are:<br>
12906 <br>
12907 <font class="fixd">void insb(unsigned port, void *addr, unsigned long count);<br>
12908 void outsb(unsigned port, void *addr, unsigned long count);</font><br>
12909 <div class="bq">
12910 Read or write <font class="fixd">count</font> bytes starting at the memory address <font class="fixd">addr.</font> Data is read from
12911 or written to the single port <font class="fixd">port.</font></div>
12912 <br>
12913 <font class="fixd">void insw(unsigned port, void *addr, unsigned long count);<br>
12914 void outsw(unsigned port, void *addr, unsigned long count);</font><br>
12915 <div class="bq">
12916 Read or write 16-bit values to a single 16-bit port.</div>
12917 <br>
12918 <font class="fixd">void insl(unsigned port, void *addr, unsigned long count);<br>
12919 void outsl(unsigned port, void *addr, unsigned long count);</font><br>
12920 <div class="bq">
12921 Read or write 32-bit values to a single 32-bit port.</div>
12922 <br>
12923 There is one thing to keep in mind when using the string functions: they move a
12924 straight byte stream to or from the port. When the port and the host system have different
12925 byte ordering rules, the results can be surprising. Reading a port with <i>inw
12926 </i>swaps the bytes, if need be, to make the value read match the host ordering. The
12927 string functions, instead, do not perform this swapping.<br>
12928 <br>
12929 <a name="PausingIO"></a><font color="red"><b>Pausing I/O</b></font><br>
12930 <br>
12931 Some platforms--most notably the i386--can have problems when the processor
12932 tries to transfer data too quickly to or from the bus. The problems can arise when the
12933 processor is overclocked with respect to the peripheral bus (think ISA here) and can
12934 show up when the device board is too slow. The solution is to insert a small delay
12935 after each I/O instruction if another such instruction follows. On the x86, the pause
12936 is achieved by performing an <font class="fixd">out b</font> instruction to port 0x80 (normally but not always
12937 unused), or by busy waiting. See the <i>io.h </i>file under your platform's <i>asm </i>subdirectory
12938 for details.<br>
12939 <br>
12940 If your device misses some data, or if you fear it might miss some, you can use pausing
12941 functions in place of the normal ones. The pausing functions are exactly like
12942 those listed previously, but their names end in <i>_p</i>; they are called <i>inb_p</i>, <i>outb_p</i>, and
12943 so on. The functions are defined for most supported architectures, although they
12944 often expand to the same code as nonpausing I/O, because there is no need for the
12945 extra pause if the architecture runs with a reasonably modern peripheral bus.<br>
12946 <br>
12947 <a name="PlatformDependencies"></a><font color="red"><b>Platform Dependencies</b></font><br>
12948 <br>
12949 I/O instructions are, by their nature, highly processor dependent. Because they work
12950 with the details of how the processor handles moving data in and out, it is very hard
12951 to hide the differences between systems. As a consequence, much of the source code
12952 related to port I/O is platform-dependent.<br>
12953 <br>
12954 You can see one of the incompatibilities, data typing, by looking back at the list of functions,
12955 where the arguments are typed differently based on the architectural differences<br>
12956 <br>
12957 <A name="243"></a><font color="blue">PAGE 243</font><br>
12958 <br>
12959 between platforms. For example, a port is <font class="fixd">unsigned short</font> on the x86 (where the processor
12960 supports a 64-KB I/O space), but <font class="fixd">unsigned long</font> on other platforms, whose ports are
12961 just special locations in the same address space as memory.<br>
12962 <br>
12963 Other platform dependencies arise from basic structural differences in the processors
12964 and are, therefore, unavoidable. We won't go into detail about the differences,
12965 because we assume that you won't be writing a device driver for a particular system
12966 without understanding the underlying hardware. Instead, here is an overview of the
12967 capabilities of the architectures supported by the kernel:<br>
12968 <br>
12969 <i>IA-32 (x86)<br>
12970 x86_64</i><br>
12971 <div class="bq">
12972 The architecture supports all the functions described in this chapter. Port numbers
12973 are of type <font class="fixd">unsigned short</font>.</div>
12974 <br>
12975 <i>IA-64 (Itanium)</i><br>
12976 <div class="bq">
12977 All functions are supported; ports are <font class="fixd">unsigned long</font> (and memory-mapped).
12978 String functions are implemented in C.</div>
12979 <br>
12980 <i>Alpha</i><br>
12981 <div class="bq">
12982 All the functions are supported, and ports are memory-mapped. The implementation
12983 of port I/O is different in different Alpha platforms, according to the
12984 chipset they use. String functions are implemented in C and defined in <i>arch/
12985 alpha/lib/io.c</i>. Ports are <font class="fixd">unsigned long</font>.</div>
12986 <br>
12987 <i>ARM</i><br>
12988 <div class="bq">
12989 Ports are memory-mapped, and all functions are supported; string functions are
12990 implemented in C. Ports are of type <font class="fixd">unsigned int</font>.</div>
12991 <br>
12992 <i>Cris</i><br>
12993 <div class="bq">
12994 This architecture does not support the I/O port abstraction even in an emulated
12995 mode; the various port operations are defined to do nothing at all.</div>
12996 <br>
12997 <i>M68k<br>
12998 M68k-nommu</i><br>
12999 <div class="bq">
13000 Ports are memory-mapped. String functions are supported, and the port type is
13001 <font class="fixd">unsigned char *.</font></div>
13002 <br>
13003 <i>MIPS<br>
13004 MIPS64</i><br>
13005 <div class="bq">
13006 The MIPS port supports all the functions. String operations are implemented
13007 with tight assembly loops, because the processor lacks machine-level string I/O.
13008 Ports are memory-mapped; they are <font class="fixd">unsigned long</font>.</div>
13009 <br>
13010 <i>PA-RISC</i><br>
13011 <div class="bq">
13012 All of the functions are supported; ports are int on PCI-based systems and
13013 <font class="fixd">unsigned short</font> on EISA systems, except for string operations,
13014 which use <font class="fixd">unsigned long</font> port numbers.</div>
13015 <br>
13016 <A name="244"></a><font color="blue">PAGE 244</font><br>
13017 <br>
13018 <i>PowerPC<br>
13019 PowerPC64</i><br>
13020 <div class="bq">
13021 All the functions are supported; ports have type <font class="fixd">unsigned char *</font> on 32-bit systems
13022 and <font class="fixd">unsigned long</font> on 64-bit systems.</div>
13023 <br>
13024 <i>S390</i><br>
13025 <div class="bq">
13026 Similar to the M68k, the header for this platform supports only byte-wide port I/O
13027 with no string operations. Ports are char pointers and are memory-mapped.</div>
13028 <br>
13029 <i>Super-H</i><br>
13030 <div class="bq">
13031 Ports are <font class="fixd">unsigned int</font> (memory-mapped), and all the functions are supported.</div>
13032 <br>
13033 <i>SPARC<br>
13034 SPARC64</i><br>
13035 <div class="bq">
13036 Once again, I/O space is memory-mapped. Versions of the port functions are
13037 defined to work with <font class="fixd">unsigned long</font> ports.</div>
13038 <br>
13039 The curious reader can extract more information from the <i>io.h </i>files, which sometimes
13040 define a few architecture-specific functions in addition to those we describe in
13041 this chapter. Be warned that some of these files are rather difficult reading, however.<br>
13042 <br>
13043 It's interesting to note that no processor outside the x86 family features a different
13044 address space for ports, even though several of the supported families are shipped
13045 with ISA and/or PCI slots (and both buses implement separate I/O and memory
13046 address spaces).<br>
13047 <br>
13048 Moreover, some processors (most notably the early Alphas) lack instructions that
13049 move one or two bytes at a time.* Therefore, their peripheral chipsets simulate 8-bit
13050 and 16-bit I/O accesses by mapping them to special address ranges in the memory
13051 address space. Thus, an <i>inb </i>and an <i>inw </i>instruction that act on the same port are
13052 implemented by two 32-bit memory reads that operate on different addresses. Fortunately,
13053 all of this is hidden from the device driver writer by the internals of the macros
13054 described in this section, but we feel it's an interesting feature to note. If you
13055 want to probe further, look for examples in <i>include/asm-alpha/core_lca.h</i>.<br>
13056 <br>
13057 How I/O operations are performed on each platform is well described in the programmer's
13058 manual for each platform; those manuals are usually available for download
13059 as PDFs on the Web.<br>
13060 <br>
13061 * Single-byte I/O is not as important as one may imagine, because it is a rare operation. To read/write a single
13062 byte to any address space, you need to implement a data path connecting the low bits of the register-set data
13063 bus to any byte position in the external data bus. These data paths require additional logic gates that get in
13064 the way of every data transfer. Dropping byte-wide loads and stores can benefit overall system performance.<br>
13065 <br>
13066 <A name="245"></a><font color="blue">PAGE 245</font><br>
13067 <br>
13068 <a name="AnIOPortExample"></a><font color="red"><b>An I/O Port Example</b></font><br>
13069 <br>
13070 The sample code we use to show port I/O from within a device driver acts on general-purpose
13071 digital I/O ports; such ports are found in most computer systems.<br>
13072 <br>
13073 A digital I/O port, in its most common incarnation, is a byte-wide I/O location,
13074 either memory-mapped or port-mapped. When you write a value to an output location,
13075 the electrical signal seen on output pins is changed according to the individual
13076 bits being written. When you read a value from the input location, the current logic
13077 level seen on input pins is returned as individual bit values.<br>
13078 <br>
13079 The actual implementation and software interface of such I/O ports varies from system
13080 to system. Most of the time, I/O pins are controlled by two I/O locations: one
13081 that allows selecting what pins are used as input and what pins are used as output
13082 and one in which you can actually read or write logic levels. Sometimes, however,
13083 things are even simpler, and the bits are hardwired as either input or output (but, in
13084 this case, they're no longer called "general-purpose I/O"); the parallel port found on
13085 all personal computers is one such not-so-general-purpose I/O port. Either way, the
13086 I/O pins are usable by the sample code we introduce shortly.<br>
13087 <br>
13088 <a name="AnOverviewOfTheParallelPort"></a><font color="red"><b>An Overview of the Parallel Port</b></font><br>
13089 <br>
13090 Because we expect most readers to be using an x86 platform in the form called "personal
13091 computer," we feel it is worth explaining how the PC parallel port is designed.
13092 The parallel port is the peripheral interface of choice for running digital I/O sample
13093 code on a personal computer. Although most readers probably have parallel port
13094 specifications available, we summarize them here for your convenience.<br>
13095 <br>
13096 The parallel interface, in its minimal configuration (we overlook the ECP and EPP
13097 modes) is made up of three 8-bit ports. The PC standard starts the I/O ports for the
13098 first parallel interface at 0x378 and for the second at 0x278. The first port is a bidirectional
13099 data register; it connects directly to pins 2-9 on the physical connector. The
13100 second port is a read-only status register; when the parallel port is being used for a
13101 printer, this register reports several aspects of printer status, such as being online,
13102 out of paper, or busy. The third port is an output-only control register, which,
13103 among other things, controls whether interrupts are enabled.<br>
13104 <br>
13105 The signal levels used in parallel communications are standard transistor-transistor
13106 logic (TTL) levels: 0 and 5 volts, with the logic threshold at about 1.2 volts. You can
13107 count on the ports at least meeting the standard TTL LS current ratings, although
13108 most modern parallel ports do better in both current and voltage ratings.<br>
13109 <br>
13110 <A name="246"></a><font color="blue">PAGE 246</font><br>
13111 <br>
13112 <div class="warn">The parallel connector is not isolated from the computer's internal circuitry,
13113 which is useful if you want to connect logic gates directly to the
13114 port. But you have to be careful to do the wiring correctly; the parallel
13115 port circuitry is easily damaged when you play with your own custom
13116 circuitry, unless you add optoisolators to your circuit. You can choose
13117 to use plug-in parallel ports if you fear you'll damage your motherboard.</div>
13118 <br>
13119 The bit specifications are outlined in Figure 9-1. You can access 12 output bits and 5
13120 input bits, some of which are logically inverted over the course of their signal path.
13121 The only bit with no associated signal pin is bit 4 (0x10) of port 2, which enables
13122 interrupts from the parallel port. We use this bit as part of our implementation of an
13123 interrupt handler in Chapter 10.<br>
13124 <br><br>
13125 <center>
13126 <img src="fig9-1.gif">
13127 </center>
13128 <br>
13129 <i>Figure 9-1. The pinout of the parallel port</i><br>
13130 <br>
13131 <a name="ASampleDriver"></a><font color="red"><b>A Sample Driver</b></font><br>
13132 <br>
13133 The driver we introduce is called <i>short </i>(Simple Hardware Operations and Raw
13134 Tests). All it does is read and write a few 8-bit ports, starting from the one you select
13135 at load time. By default, it uses the port range assigned to the parallel interface of the
13136 PC. Each device node (with a unique minor number) accesses a different port. The
13137 <i>short </i>driver doesn't do anything useful; it just isolates for external use as a single
13138 instruction acting on a port. If you are not used to port I/O, you can use <i>short </i>to get<br>
13139 <br>
13140 <A name="247"></a><font color="blue">PAGE 247</font><br>
13141 <br>
13142 familiar with it; you can measure the time it takes to transfer data through a port or
13143 play other games.<br>
13144 <br>
13145 For <i>short </i>to work on your system, it must have free access to the underlying hardware
13146 device (by default, the parallel interface); thus, no other driver may have allocated
13147 it. Most modern distributions set up the parallel port drivers as modules that
13148 are loaded only when needed, so contention for the I/O addresses is not usually a
13149 problem. If, however, you get a "can't get I/O address" error from <i>short </i>(on the console
13150 or in the system log file), some other driver has probably already taken the port.
13151 A quicklook at <i>/proc/ioports </i>usually tells you which driver is getting in the way. The
13152 same caveat applies to other I/O devices if you are not using the parallel interface.<br>
13153 <br>
13154 From now on, we just refer to "the parallel interface" to simplify the discussion.
13155 However, you can set the base module parameter at load time to redirect <i>short </i>to
13156 other I/O devices. This feature allows the sample code to run on any Linux platform
13157 where you have access to a digital I/O interface that is accessible via <i>outb </i>and <i>inb
13158 </i>(even though the actual hardware is memory-mapped on all platforms but the x86).
13159 Later, in the section "Using I/O Memory," we show how <i>short </i>can be used with
13160 generic memory-mapped digital I/O as well.<br>
13161 <br>
13162 To watch what happens on the parallel connector and if you have a bit of an inclination
13163 to work with hardware, you can solder a few LEDs to the output pins. Each
13164 LED should be connected in series to a 1-K resistor leading to a ground pin (unless,
13165 of course, your LEDs have the resistor built in). If you connect an output pin to an
13166 input pin, you'll generate your own input to be read from the input ports.<br>
13167 <br>
13168 Note that you cannot just connect a printer to the parallel port and see data sent to
13169 <i>short</i>. This driver implements simple access to the I/O ports and does not perform
13170 the handshake that printers need to operate on the data. In the next chapter, we
13171 show a sample driver (called <i>shortprint</i>), that is capable of driving parallel printers;
13172 that driver uses interrupts, however, so we can't get to it quite yet.<br>
13173 <br>
13174 If you are going to view parallel data by soldering LEDs to a D-type connector, we
13175 suggest that you not use pins 9 and 10, because we connect them together later to
13176 run the sample code shown in Chapter 10.<br>
13177 <br>
13178 As far as <i>short </i>is concerned, <i>/dev/short0 </i>writes to and reads from the 8-bit port
13179 located at the I/O address base (0x378 unless changed at load time). <i>/dev/short1
13180 </i>writes to the 8-bit port located at <font class="fixd">base + 1,</font> and so on up to <font class="fixd">base + 7.</font><br>
13181 <br>
13182 The actual output operation performed by <i>/dev/short0 </i>is based on a tight loop using
13183 <i>outb</i>. A memory barrier instruction is used to ensure that the output operation actually
13184 takes place and is not optimized away:<br>
13185 <pre>
13186 while (count--) {
13187 outb(*(ptr++), port);
13188 wmb( );
13189 }
13190 </pre>
13191 <A name="248"></a><font color="blue">PAGE 248</font><br>
13192 <br>
13193 You can run the following command to light your LEDs:<br>
13194 <pre>
13195 echo -n "any string" > /dev/short0
13196 </pre>
13197 Each LED monitors a single bit of the output port. Remember that only the last character
13198 written remains steady on the output pins long enough to be perceived by your
13199 eyes. For that reason, we suggest that you prevent automatic insertion of a trailing
13200 newline by passing the <i>-n</i> option to <i>echo</i>.<br>
13201 <br>
13202 Reading is performed by a similar function, built around <i>inb </i>instead of <i>outb</i>. In order
13203 to read "meaningful" values from the parallel port, you need to have some hardware
13204 connected to the input pins of the connector to generate signals. If there is no signal,
13205 you read an endless stream of identical bytes. If you choose to read from an output
13206 port, you most likely get back the last value written to the port (this applies to the
13207 parallel interface and to most other digital I/O circuits in common use). Thus, those
13208 uninclined to get out their soldering irons can read the current output value on port
13209 0x378 by running a command such as:<br>
13210 <pre>
13211 dd if=/dev/short0 bs=1 count=1 | od -t x1
13212 </pre>
13213 To demonstrate the use of all the I/O instructions, there are three variations of each
13214 <i>short </i>device: <i>/dev/short0 </i>performs the loop just shown, <i>/dev/short0p </i>uses <i>outb_p </i>and
13215 <i>inb_p </i>in place of the "fast" functions, and <i>/dev/short0s </i>uses the string instructions.
13216 There are eight such devices, from <i>short0 </i>to <i>short7</i>. Although the PC parallel interface
13217 has only three ports, you may need more of them if using a different I/O device
13218 to run your tests.<br>
13219 <br>
13220 The <i>short </i>driver performs an absolute minimum of hardware control but is adequate
13221 to show how the I/O port instructions are used. Interested readers may want to look
13222 at the source for the <i>parport </i>and <i>parport_pc </i>modules to see how complicated this
13223 device can get in real life in order to support a range of devices (printers, tape
13224 backup, network interfaces) on the parallel port.<br>
13225 <br>
13226 <a name="UsingIOMemory"></a><font color="red"><b>Using I/O Memory</b></font><br>
13227 <br>
13228 Despite the popularity of I/O ports in the x86 world, the main mechanism used to
13229 communicate with devices is through memory-mapped registers and device memory.
13230 Both are called <i>I/O memory </i>because the difference between registers and memory
13231 is transparent to software.<br>
13232 <br>
13233 I/O memory is simply a region of RAM-like locations that the device makes available
13234 to the processor over the bus. This memory can be used for a number of purposes,
13235 such as holding video data or Ethernet packets, as well as implementing device registers
13236 that behave just like I/O ports (i.e., they have side effects associated with reading
13237 and writing them).<br>
13238 <br>
13239 The way to access I/O memory depends on the computer architecture, bus, and
13240 device being used, although the principles are the same everywhere. The discussion<br>
13241 <br>
13242 <A name="249"></a><font color="blue">PAGE 249</font><br>
13243 <br>
13244 in this chapter touches mainly on ISA and PCI memory, while trying to convey general
13245 information as well. Although access to PCI memory is introduced here, a thorough
13246 discussion of PCI is deferred to Chapter 12.<br>
13247 <br>
13248 Depending on the computer platform and bus being used, I/O memory may or may
13249 not be accessed through page tables. When access passes though page tables, the
13250 kernel must first arrange for the physical address to be visible from your driver, and
13251 this usually means that you must call <i>ioremap </i>before doing any I/O. If no page tables
13252 are needed, I/O memory locations look pretty much like I/O ports, and you can just
13253 read and write to them using proper wrapper functions.<br>
13254 <br>
13255 Whether or not <i>ioremap </i>is required to access I/O memory, direct use of pointers to I/O
13256 memory is discouraged. Even though (as introduced in the section "I/O Ports and I/O
13257 Memory") I/O memory is addressed like normal RAM at hardware level, the extra
13258 care outlined in the section "I/O Registers and Conventional Memory" suggests
13259 avoiding normal pointers. The wrapper functions used to access I/O memory are safe
13260 on all platforms and are optimized away whenever straight pointer dereferencing can
13261 perform the operation.<br>
13262 <br>
13263 Therefore, even though dereferencing a pointer works (for now) on the x86, failure
13264 to use the proper macros hinders the portability and readability of the driver.<br>
13265 <br>
13266 <a name="IOMemoryAllocationAndMapping"></a><font color="red"><b>I/O Memory Allocation and Mapping</b></font><br>
13267 <br>
13268 I/O memory regions must be allocated prior to use. The interface for allocation of
13269 memory regions (defined in <i><linux/ioport.h></i>) is:<br>
13270 <pre>
13271 struct resource *request_mem_region(unsigned long start, unsigned long len,
13272 char *name);
13273 </pre>
13274 This function allocates a memory region of len bytes, starting at start. If all goes
13275 well, a <font class="fixd">non-NULL</font> pointer is returned; otherwise the return value is <font class="fixd">NULL</font>. All I/O memory
13276 allocations are listed in <i>/proc/iomem</i>.<br>
13277 <br>
13278 Memory regions should be freed when no longer needed:<br>
13279 <pre>
13280 void release_mem_region(unsigned long start, unsigned long len);
13281 </pre>
13282 There is also an old function for checking I/O memory region availability:<br>
13283 <pre>
13284 int check_mem_region(unsigned long start, unsigned long len);
13285 </pre>
13286 But, as with <i>check_region</i>, this function is unsafe and should be avoided.<br>
13287 <br>
13288 Allocation of I/O memory is not the only required step before that memory may be
13289 accessed. You must also ensure that this I/O memory has been made accessible to the
13290 kernel. Getting at I/O memory is not just a matter of dereferencing a pointer; on many
13291 systems, I/O memory is not directly accessible in this way at all. So a mapping must
13292 be set up first. This is the role of the <i>ioremap </i>function, introduced in the section<br>
13293 <br>
13294 <A name="250"></a><font color="blue">PAGE 250</font><br>
13295 <br>
13296 "vmalloc and Friends" in Chapter 1. The function is designed specifically to assign
13297 virtual addresses to I/O memory regions.<br>
13298 <br>
13299 Once equipped with <i>ioremap </i>(and <i>iounmap</i>), a device driver can access any I/O
13300 memory address, whether or not it is directly mapped to virtual address space.
13301 Remember, though, that the addresses returned from <i>ioremap </i>should not be dereferenced
13302 directly; instead, accessor functions provided by the kernel should be used.
13303 Before we get into those functions, we'd better review the <i>ioremap </i>prototypes and
13304 introduce a few details that we passed over in the previous chapter.<br>
13305 <br>
13306 The functions are called according to the following definition:<br>
13307 <pre>
13308 #include <asm/io.h>
13309 void *ioremap(unsigned long phys_addr, unsigned long size);
13310 void *ioremap_nocache(unsigned long phys_addr, unsigned long size);
13311 void iounmap(void * addr);
13312 </pre>
13313 First of all, you notice the new function <i>ioremap_nocache</i>. We didn't cover it in
13314 Chapter 8, because its meaning is definitely hardware related. Quoting from one of
13315 the kernel headers: "It's useful if some control registers are in such an area, and write
13316 combining or read caching is not desirable." Actually, the function's implementation
13317 is identical to <i>ioremap </i>on most computer platforms: in situations where all of I/O
13318 memory is already visible through noncacheable addresses, there's no reason to
13319 implement a separate, noncaching version of <i>ioremap</i>.<br>
13320 <br>
13321 <a name="AccessingIOMemory"></a><font color="red"><b>Accessing I/O Memory</b></font><br>
13322 <br>
13323 On some platforms, you may get away with using the return value from <i>ioremap </i>as a
13324 pointer. Such use is not portable, and, increasingly, the kernel developers have been
13325 working to eliminate any such use. The proper way of getting at I/O memory is via a
13326 set of functions (defined via <i><asm/io.h></i>) provided for that purpose.<br>
13327 <br>
13328 To read from I/O memory, use one of the following:<br>
13329 <pre>
13330 unsigned int ioread8(void *addr);
13331 unsigned int ioread16(void *addr);
13332 unsigned int ioread32(void *addr);
13333 </pre>
13334 Here, <font class="fixd">addr</font> should be an address obtained from <i>ioremap </i>(perhaps with an integer offset);
13335 the return value is what was read from the given I/O memory.<br>
13336 <br>
13337 There is a similar set of functions for writing to I/O memory:<br>
13338 <pre>
13339 void iowrite8(u8 value, void *addr);
13340 void iowrite16(u16 value, void *addr);
13341 void iowrite32(u32 value, void *addr);
13342 </pre>
13343 If you must read or write a series of values to a given I/O memory address, you can
13344 use the repeating versions of the functions:<br>
13345 <pre>
13346 void ioread8_rep(void *addr, void *buf, unsigned long count);
13347 void ioread16_rep(void *addr, void *buf, unsigned long count);
13348 </pre>
13349 <A name="251"></a><font color="blue">PAGE 251</font><br>
13350 <pre>
13351 void ioread32_rep(void *addr, void *buf, unsigned long count);
13352 void iowrite8_rep(void *addr, const void *buf, unsigned long count);
13353 void iowrite16_rep(void *addr, const void *buf, unsigned long count);
13354 void iowrite32_rep(void *addr, const void *buf, unsigned long count);
13355 </pre>
13356 These functions read or write <font class="fixd">count</font> values from the given <font class="fixd">buf</font> to the given <font class="fixd">addr.</font> Note
13357 that <font class="fixd">count</font> is expressed in the size of the data being written; <i>ioread32_rep </i>reads <font class="fixd">count</font>
13358 32-bit values starting at <font class="fixd">buf.</font><br>
13359 <br>
13360 The functions described above perform all I/O to the given <font class="fixd">addr.</font> If, instead, you need
13361 to operate on a block of I/O memory, you can use one of the following:<br>
13362 <pre>
13363 void memset_io(void *addr, u8 value, unsigned int count);
13364 void memcpy_fromio(void *dest, void *source, unsigned int count);
13365 void memcpy_toio(void *dest, void *source, unsigned int count);
13366 </pre>
13367 These functions behave like their C library analogs.<br>
13368 <br>
13369 If you read through the kernel source, you see many calls to an older set of functions
13370 when I/O memory is being used. These functions still work, but their use in new
13371 code is discouraged. Among other things, they are less safe because they do not perform
13372 the same sort of type checking. Nonetheless, we describe them here:<br>
13373 <br>
13374 <font class="fixd">unsigned readb(address);<br>
13375 unsigned readw(address);<br>
13376 unsigned readl(address);</font><br>
13377 <div class="bq">These macros are used to retrieve 8-bit, 16-bit, and 32-bit data values from I/O
13378 memory.</div>
13379 <br>
13380 <font class="fixd">void writeb(unsigned value, address);<br>
13381 void writew(unsigned value, address);<br>
13382 void writel(unsigned value, address);</font><br>
13383 <div class="bq">Like the previous functions, these functions (macros) are used to write 8-bit, 16bit,
13384 and 32-bit data items.</div>
13385 <br>
13386 Some 64-bit platforms also offer <i>readq </i>and <i>writeq</i>, for quad-word (8-byte) memory
13387 operations on the PCI bus. The <i>quad-word </i>nomenclature is a historical leftover from
13388 the times when all real processors had 16-bit words. Actually, the <i>L </i>naming used for
13389 32-bit values has become incorrect too, but renaming everything would confuse
13390 things even more.<br>
13391 <br>
13392 <a name="PortsAsIOMemory"></a><font color="red"><b>Ports as I/O Memory</b></font><br>
13393 <br>
13394 Some hardware has an interesting feature: some versions use I/O ports, while others
13395 use I/O memory. The registers exported to the processor are the same in either case,
13396 but the access method is different. As a way of making life easier for drivers dealing
13397 with this kind of hardware, and as a way of minimizing the apparent differences
13398 between I/O port and memory accesses, the 2.6 kernel provides a function called
13399 <i>ioport_map</i>:<br>
13400 <pre>
13401 void *ioport_map(unsigned long port, unsigned int count);
13402 </pre>
13403 <A name="252"></a><font color="blue">PAGE 252</font><br>
13404 <br>
13405 This function remaps <font class="fixd">count</font> I/O ports and makes them appear to be I/O memory.
13406 From that point thereafter, the driver may use <i>ioread8 </i>and friends on the returned
13407 addresses and forget that it is using I/O ports at all.<br>
13408 <br>
13409 This mapping should be undone when it is no longer needed:<br>
13410 <pre>
13411 void ioport_unmap(void *addr);
13412 </pre>
13413 These functions make I/O ports look like memory. Do note, however, that the I/O
13414 ports must still be allocated with <i>request_region </i>before they can be remapped in this
13415 way.<br>
13416 <br>
13417 <a name="ReusingShortForIOMemory"></a><font color="red"><b>Reusing short for I/O Memory</b></font><br>
13418 <br>
13419 The <i>short </i>sample module, introduced earlier to access I/O ports, can be used to
13420 access I/O memory as well. To this aim, you must tell it to use I/O memory at load
13421 time; also, you need to change the base address to make it point to your I/O region.<br>
13422 <br>
13423 For example, this is how we used <i>short </i>to light the debug LEDs on a MIPS development
13424 board:<br>
13425 <pre>
13426 mips.root# <b>./short_load use_mem=1 base=0xb7ffffc0
13427 </b>mips.root# <b>echo -n 7 > /dev/short0</b>
13428 </pre>
13429 Use of <i>short</i> for I/O memory is the same as it is for I/O ports.<br>
13430 <br>
13431 The following fragment shows the loop used by <i>short</i> in writing to a memory location:<br>
13432 <pre>
13433 while (count--) {
13434 iowrite8(*ptr++, address);
13435 wmb( );
13436 }
13437 </pre>
13438 Note the use of a write memory barrier here. Because <i>iowrite8 </i>likely turns into a
13439 direct assignment on many architectures, the memory barrier is needed to ensure
13440 that the writes happen in the expected order.<br>
13441 <br>
13442 <i>short </i>uses <i>inb </i>and <i>outb </i>to show how that is done. It would be a straightforward exercise
13443 for the reader, however, to change <i>short </i>to remap I/O ports with <i>ioport_map</i>,
13444 and simplify the rest of the code considerably.<br>
13445 <br>
13446 <a name="ISAMemoryBelow1MB"></a><font color="red"><b>ISA Memory Below 1 MB</b></font><br>
13447 <br>
13448 One of the most well-known I/O memory regions is the ISA range found on personal
13449 computers. This is the memory range between 640 KB (0xA0000) and 1 MB
13450 (0x100000). Therefore, it appears right in the middle of regular system RAM. This
13451 positioning may seem a little strange; it is an artifact of a decision made in the early
13452 1980s, when 640 KB of memory seemed like more than anybody would ever be able
13453 to use.<br>
13454 <br>
13455 <A name="253"></a><font color="blue">PAGE 253</font><br>
13456 <br>
13457 This memory range belongs to the non-directly-mapped class of memory.* You can
13458 read/write a few bytes in that memory range using the <i>short </i>module as explained previously,
13459 that is, by setting <font class="fixd">use_mem</font> at load time.<br>
13460 <br>
13461 Although ISA I/O memory exists only in x86-class computers, we thinkit's worth
13462 spending a few words and a sample driver on it.<br>
13463 <br>
13464 We are not going to discuss PCI memory in this chapter, since it is the cleanest kind
13465 of I/O memory: once you know the physical address, you can simply remap and
13466 access it. The "problem" with PCI I/O memory is that it doesn't lend itself to a working
13467 example for this chapter, because we can't know in advance the physical
13468 addresses your PCI memory is mapped to, or whether it's safe to access either of
13469 those ranges. We chose to describe the ISA memory range, because it's both less
13470 clean and more suitable to running sample code.<br>
13471 <br>
13472 To demonstrate access to ISA memory, we use yet another silly little module (part of
13473 the sample sources). In fact, this one is called <i>silly</i>, as an acronym for Simple Tool for
13474 Unloading and Printing ISA Data, or something like that.<br>
13475 <br>
13476 The module supplements the functionality of <i>short </i>by giving access to the whole
13477 384-KB memory space and by showing all the different I/O functions. It features four
13478 device nodes that perform the same task using different data transfer functions. The
13479 <i>silly </i>devices act as a window over I/O memory, in a way similar to <i>/dev/mem</i>. You
13480 can read and write data, and <i>lseek</i> to an arbitrary I/O memory address.<br>
13481 <br>
13482 Because <i>silly </i>provides access to ISA memory, it must start by mapping the physical
13483 ISA addresses into kernel virtual addresses. In the early days of the Linux kernel, one
13484 could simply assign a pointer to an ISA address of interest, then dereference it
13485 directly. In the modern world, though, we must work with the virtual memory system
13486 and remap the memory range first. This mapping is done with <i>ioremap</i>, as
13487 explained earlier for <i>short</i>:<br>
13488 <pre>
13489 #define ISA_BASE 0xA0000
13490 #define ISA_MAX 0x100000 /* for general memory access */
13492 /* this line appears in silly_init */
13493 io_base = ioremap(ISA_BASE, ISA_MAX - ISA_BASE);
13494 </pre>
13495 <i>ioremap </i>returns a pointer value that can be used with <i>ioread8 </i>and the other functions
13496 explained in the section "Accessing I/O Memory."<br>
13497 <br>
13498 Let's look back at our sample module to see how these functions might be used. <i>/dev/
13499 sillyb</i>, featuring minor number 0, accesses I/O memory with <i>ioread8 </i>and <i>iowrite8</i>.
13500 The following code shows the implementation for <i>read</i>, which makes the address<br>
13501 <br>
13502 * Actually, this is not completely true. The memory range is so small and so frequently used that the kernel
13503 builds page tables at boot time to access those addresses. However, the virtual address used to access them
13504 is not the same as the physical address, and thus <i>ioremap</i> is needed anyway.<br>
13505 <br>
13506 <A name="254"></a><font color="blue">PAGE 254</font><br>
13507 <br>
13508 range 0xA0000-0xFFFFF available as a virtual file in the range 0-0x5FFFF. The <i>read
13509 </i>function is structured as a <font class="fixd">switch</font> statement over the different access modes; here is
13510 the <i>sillyb </i>case:<br>
13511 <pre>
13512 case M_8:
13513 while (count) {
13514 *ptr = ioread8(add);
13515 add++;
13516 count--;
13517 ptr++;
13518 }
13519 break;
13520 </pre>
13521 The next two devices are <i>/dev/sillyw </i>(minor number 1) and <i>/dev/sillyl </i>(minor number
13522 2). They act like <i>/dev/sillyb</i>, except that they use 16-bit and 32-bit functions. Here's
13523 the <i>write</i> implementation of <i>sillyl</i>, again part of a switch:<br>
13524 <pre>
13525 case M_32:
13526 while (count >= 4) {
13527 iowrite8(*(u32 *)ptr, add);
13528 add += 4;
13529 count -= 4;
13530 ptr += 4;
13531 }
13532 break;
13533 </pre>
13534 The last device is <i>/dev/sillycp </i>(minor number 3), which uses the <i>memcpy_*io </i>functions
13535 to perform the same task. Here's the core of its <i>read</i> implementation:<br>
13536 <pre>
13537 case M_memcpy:
13538 memcpy_fromio(ptr, add, count);
13539 break;
13540 </pre>
13541 Because <i>ioremap </i>was used to provide access to the ISA memory area, <i>silly </i>must
13542 invoke <i>iounmap</i> when the module is unloaded:<br>
13543 <pre>
13544 iounmap(io_base);
13545 </pre>
13546 <a name="IsareadbAndFriends"></a><font color="red"><b>isa_readb and Friends</b></font><br>
13547 <br>
13548 A look at the kernel source will turn up another set of routines with names such as
13549 <i>isa_readb</i>. In fact, each of the functions just described has an <i>isa_ </i>equivalent. These
13550 functions provide access to ISA memory without the need for a separate <i>ioremap
13551 </i>step. The word from the kernel developers, however, is that these functions are
13552 intended to be temporary driver-porting aids and that they may go away in the
13553 future. Therefore, you should avoid using them.<br>
13554 <br>
13555 <A name="255"></a><font color="blue">PAGE 255</font><br>
13556 <br>
13557 <a name="QuickReference9"></a><font color="red"><b>Quick Reference</b></font><br>
13558 <br>
13559 This chapter introduced the following symbols related to hardware management:<br>
13560 <br>
13561 <font class="fixd">#include <linux/kernel.h><br>
13562 void barrier(void)</font><br>
13563 <div class="bq">
13564 This "software" memory barrier requests the compiler to consider all memory
13565 volatile across this instruction.</div>
13566 <br>
13567 <font class="fixd">#include <asm/system.h><br>
13568 void rmb(void);<br>
13569 void read_barrier_depends(void);<br>
13570 void wmb(void);<br>
13571 void mb(void);</font><br>
13572 <div class="bq">
13573 Hardware memory barriers. They request the CPU (and the compiler) to checkpoint
13574 all memory reads, writes, or both across this instruction.</div>
13575 <br>
13576 <font class="fixd">#include <asm/io.h><br>
13577 unsigned inb(unsigned port);<br>
13578 void outb(unsigned char byte, unsigned port);<br>
13579 unsigned inw(unsigned port);<br>
13580 void outw(unsigned short word, unsigned port);<br>
13581 unsigned inl(unsigned port);<br>
13582 void outl(unsigned doubleword, unsigned port);</font><br>
13583 <div class="bq">
13584 Functions that are used to read and write I/O ports. They can also be called by
13585 user-space programs, provided they have the right privileges to access ports.</div>
13586 <br>
13587 <font class="fixd">unsigned inb_p(unsigned port);<br>
13588 ...</font><br>
13589 <div class="bq">
13590 If a small delay is needed after an I/O operation, you can use the six pausing
13591 counterparts of the functions introduced in the previous entry; these pausing
13592 functions have names ending in <i>_p.</i></div>
13593 <br>
13594 <font class="fixd">void insb(unsigned port, void *addr, unsigned long count);<br>
13595 void outsb(unsigned port, void *addr, unsigned long count);<br>
13596 void insw(unsigned port, void *addr, unsigned long count);<br>
13597 void outsw(unsigned port, void *addr, unsigned long count);<br>
13598 void insl(unsigned port, void *addr, unsigned long count);<br>
13599 void outsl(unsigned port, void *addr, unsigned long count);</font><br>
13600 <div class="bq">
13601 The "string functions" are optimized to transfer data from an input port to a
13602 region of memory, or the other way around. Such transfers are performed by
13603 reading or writing the same port count times.</div>
13604 <br>
13605 <A name="256"></a><font color="blue">PAGE 256</font><br>
13606 <br>
13607 <font class="fixd">#include <linux/ioport.h><br>
13608 struct resource *request_region(unsigned long start, unsigned long len, char *name);<br>
13609 void release_region(unsigned long start, unsigned long len);<br>
13610 int check_region(unsigned long start, unsigned long len);</font><br>
13611 <div class="bq">
13612 Resource allocators for I/O ports. The (deprecated) <i>check </i>function returns 0 for
13613 success and less than 0 in case of error.</div>
13614 <br>
13615 <font class="fixd">struct resource *request_mem_region(unsigned long start, unsigned long len, char *name);<br>
13616 void release_mem_region(unsigned long start, unsigned long len);<br>
13617 int check_mem_region(unsigned long start, unsigned long len);</font><br>
13618 <div class="bq">
13619 Functions that handle resource allocation for memory regions.</div>
13620 <br>
13621 <font class="fixd">#include <asm/io.h><br>
13622 void *ioremap(unsigned long phys_addr, unsigned long size);<br>
13623 void *ioremap_nocache(unsigned long phys_addr, unsigned long size);<br>
13624 void iounmap(void *virt_addr);</font><br>
13625 <div class="bq">
13626 <i>ioremap </i>remaps a physical address range into the processor's virtual address
13627 space, making it available to the kernel. <i>iounmap </i>frees the mapping when it is no
13628 longer needed.</div>
13629 <br>
13630 <font class="fixd">#include <asm/io.h><br>
13631 unsigned int ioread8(void *addr);<br>
13632 unsigned int ioread16(void *addr);<br>
13633 unsigned int ioread32(void *addr);<br>
13634 void iowrite8(u8 value, void *addr);<br>
13635 void iowrite16(u16 value, void *addr);<br>
13636 void iowrite32(u32 value, void *addr);</font><br>
13637 <div class="bq">
13638 Accessor functions that are used to work with I/O memory.</div>
13639 <br>
13640 <font class="fixd">void ioread8_rep(void *addr, void *buf, unsigned long count);<br>
13641 void ioread16_rep(void *addr, void *buf, unsigned long count);<br>
13642 void ioread32_rep(void *addr, void *buf, unsigned long count);<br>
13643 void iowrite8_rep(void *addr, const void *buf, unsigned long count);<br>
13644 void iowrite16_rep(void *addr, const void *buf, unsigned long count);<br>
13645 void iowrite32_rep(void *addr, const void *buf, unsigned long count);</font><br>
13646 <div class="bq">
13647 "Repeating" versions of the I/O memory primitives.</div>
13648 <br>
13649 <A name="257"></a><font color="blue">PAGE 257</font><br>
13650 <br>
13651 <font class="fixd">unsigned readb(address);<br>
13652 unsigned readw(address);<br>
13653 unsigned readl(address);<br>
13654 void writeb(unsigned value, address);<br>
13655 void writew(unsigned value, address);<br>
13656 void writel(unsigned value, address);<br>
13657 memset_io(address, value, count);<br>
13658 memcpy_fromio(dest, source, nbytes);<br>
13659 memcpy_toio(dest, source, nbytes);</font><br>
13660 <div class="bq">
13661 Older, type-unsafe functions for accessing I/O memory.</div>
13662 <br>
13663 <font class="fixd">void *ioport_map(unsigned long port, unsigned int count);<br>
13664 void ioport_unmap(void *addr);</font><br>
13665 <div class="bq">
13666 A driver author that wants to treat I/O ports as if they were I/O memory may pass
13667 those ports to <i>ioport_map</i>. The mapping should be done (with <i>ioport_unmap</i>)
13668 when no longer needed.</div>
13669 <br>
13670 <A name="258"></a><font color="blue">PAGE 258</font><br>
13671 <br>
13672 <a name="CHAPTER10"></a><font color="red"><b>CHAPTER 10</b></font><br>
13673 <br>
13674 <a name="InterruptHandling"></a><font color="#7519FF" size="+1"><b>Interrupt Handling</b></font><br>
13675 <br>
13676 Although some devices can be controlled using nothing but their I/O regions, most
13677 real devices are a bit more complicated than that. Devices have to deal with the
13678 external world, which often includes things such as spinning disks, moving tape,
13679 wires to distant places, and so on. Much has to be done in a time frame that is different
13680 from, and far slower than, that of the processor. Since it is almost always undesirable
13681 to have the processor wait on external events, there must be a way for a device
13682 to let the processor know when something has happened.<br>
13683 <br>
13684 That way, of course, is interrupts. An <i>interrupt </i>is simply a signal that the hardware
13685 can send when it wants the processor's attention. Linux handles interrupts in much
13686 the same way that it handles signals in user space. For the most part, a driver need
13687 only register a handler for its device's interrupts, and handle them properly when
13688 they arrive. Of course, underneath that simple picture there is some complexity; in
13689 particular, interrupt handlers are somewhat limited in the actions they can perform
13690 as a result of how they are run.<br>
13691 <br>
13692 It is difficult to demonstrate the use of interrupts without a real hardware device to
13693 generate them. Thus, the sample code used in this chapter works with the parallel
13694 port. Such ports are starting to become scarce on modern hardware, but, with luck,
13695 most people are still able to get their hands on a system with an available port. We'll
13696 be working with the <i>short </i>module from the previous chapter; with some small additions
13697 it can generate and handle interrupts from the parallel port. The module's
13698 name, <i>short</i>, actually means <i>short int </i>(it is C, isn't it?), to remind us that it handles
13699 <i>int</i>errupts.<br>
13700 <br>
13701 Before we get into the topic, however, it is time for one cautionary note. Interrupt
13702 handlers, by their nature, run concurrently with other code. Thus, they inevitably
13703 raise issues of concurrency and contention for data structures and hardware. If you
13704 succumbed to the temptation to pass over the discussion in Chapter 5, we understand.
13705 But we also recommend that you turn back and have another look now. A
13706 solid understanding of concurrency control techniques is vital when working with
13707 interrupts.<br>
13708 <br>
13709 <A name="259"></a><font color="blue">PAGE 259</font><br>
13710 <br>
13711 <a name="PreparingTheParallelPort"></a><font color="red"><b>Preparing the Parallel Port</b></font><br>
13712 <br>
13713 Although the parallel interface is simple, it can trigger interrupts. This capability is
13714 used by the printer to notify the <i>lp </i>driver that it is ready to accept the next character
13715 in the buffer.<br>
13716 <br>
13717 Like most devices, the parallel port doesn't actually generate interrupts before it's
13718 instructed to do so; the parallel standard states that setting bit 4 of port 2 (0x37a,
13719 0x27a, or whatever) enables interrupt reporting. A simple <i>outb </i>call to set the bit is
13720 performed by <i>short</i> at module initialization.<br>
13721 <br>
13722 Once interrupts are enabled, the parallel interface generates an interrupt whenever
13723 the electrical signal at pin 10 (the so-called ACK bit) changes from low to high. The
13724 simplest way to force the interface to generate interrupts (short of hooking up a
13725 printer to the port) is to connect pins 9 and 10 of the parallel connector. A short
13726 length of wire inserted into the appropriate holes in the parallel port connector on
13727 the back of your system creates this connection. The pinout of the parallel port is
13728 shown in Figure 9-1.<br>
13729 <br>
13730 Pin 9 is the most significant bit of the parallel data byte. If you write binary data to
13731 <i>/dev/short0</i>, you generate several interrupts. Writing ASCII text to the port won't
13732 generate any interrupts, though, because the ASCII character set has no entries with
13733 the top bit set.<br>
13734 <br>
13735 If you'd rather avoid wiring pins together, but you do have a printer at hand, you can
13736 run the sample interrupt handler using a real printer, as shown later. However, note
13737 that the probing functions we introduce depend on the jumper between pin 9 and 10
13738 being in place, and you need it to experiment with probing using our code.<br>
13739 <br>
13740 <a name="InstallingAnInterruptHandler"></a><font color="red"><b>Installing an Interrupt Handler</b></font><br>
13741 <br>
13742 If you want to actually "see" interrupts being generated, writing to the hardware
13743 device isn't enough; a software handler must be configured in the system. If the
13744 Linux kernel hasn't been told to expect your interrupt, it simply acknowledges and
13745 ignores it.<br>
13746 <br>
13747 Interrupt lines are a precious and often limited resource, particularly when there are
13748 only 15 or 16 of them. The kernel keeps a registry of interrupt lines, similar to the
13749 registry of I/O ports. A module is expected to request an interrupt channel (or IRQ,
13750 for interrupt request) before using it and to release it when finished. In many situations,
13751 modules are also expected to be able to share interrupt lines with other drivers,
13752 as we will see. The following functions, declared in <i><linux/interrupt.h></i>,
13753 implement the interrupt registration interface:<br>
13754 <pre>
13755 int request_irq(unsigned int irq,
13756 irqreturn_t (*handler)(int, void *, struct pt_regs *),
13757 unsigned long flags,
13758 </pre>
13759 <A name="260"></a><font color="blue">PAGE 260</font><br>
13760 <pre>
13761 const char *dev_name,
13762 void *dev_id);
13764 void free_irq(unsigned int irq, void *dev_id);
13765 </pre>
13766 The value returned from <i>request_irq </i>to the requesting function is either 0 to indicate
13767 success or a negative error code, as usual. It's not uncommon for the function to
13768 return <font class="fixd">-EBUSY</font> to signal that another driver is already using the requested interrupt
13769 line. The arguments to the functions are as follows:<br>
13770 <br>
13771 <font class="fixd">unsigned int irq</font><br>
13772 <div class="bq">
13773 The interrupt number being requested.</div>
13774 <br>
13775 <font class="fixd">irqreturn_t (*handler)(int, void *, struct pt_regs *)</font><br>
13776 <div class="bq">
13777 The pointer to the handling function being installed. We discuss the arguments
13778 to this function and its return value later in this chapter.</div>
13779 <br>
13780 <font class="fixd">unsigned long flags</font><br>
13781 <div class="bq">
13782 As you might expect, a bit maskof options (described later) related to interrupt
13783 management.</div>
13784 <br>
13785 <font class="fixd">const char *dev_name</font><br>
13786 <div class="bq">
13787 The string passed to <i>request_irq </i>is used in <i>/proc/interrupts </i>to show the owner of
13788 the interrupt (see the next section).</div>
13789 <br>
13790 <font class="fixd">void *dev_id</font><br>
13791 <div class="bq">
13792 Pointer used for shared interrupt lines. It is a unique identifier that is used when
13793 the interrupt line is freed and that may also be used by the driver to point to its
13794 own private data area (to identify which device is interrupting). If the interrupt is
13795 not shared, <font class="fixd">dev_id</font> can be set to <font class="fixd">NULL</font>, but it a good idea anyway to use this item
13796 to point to the device structure. We'll see a practical use for <font class="fixd">dev_id</font> in the section
13797 "Implementing a Handler."</div>
13798 <br>
13799 The bits that can be set in flags are as follows:<br>
13800 <br>
13801 <font class="fixd">SA_INTERRUPT</font><br>
13802 <div class="bq">
13803 When set, this indicates a "fast" interrupt handler. Fast handlers are executed
13804 with interrupts disabled on the current processor (the topic is covered in the section
13805 "Fast and Slow Handlers").</div>
13806 <br>
13807 <font class="fixd">SA_SHIRQ</font><br>
13808 <div class="bq">
13809 This bit signals that the interrupt can be shared between devices. The concept of
13810 sharing is outlined in the section "Interrupt Sharing."</div>
13811 <br>
13812 <font class="fixd">SA_SAMPLE_RANDOM</font><br>
13813 <div class="bq">
13814 This bit indicates that the generated interrupts can contribute to the entropy pool
13815 used by <i>/dev/random </i>and <i>/dev/urandom</i>. These devices return truly random numbers
13816 when read and are designed to help application software choose secure keys
13817 for encryption. Such random numbers are extracted from an entropy pool that is
13818 contributed by various random events. If your device generates interrupts at truly
13819 random times, you should set this flag. If, on the other hand, your interrupts are</div>
13820 <br>
13821 <A name="261"></a><font color="blue">PAGE 261</font><br>
13822 <br>
13823 <div class="bq">predictable (for example, vertical blanking of a frame grabber), the flag is not
13824 worth setting--it wouldn't contribute to system entropy anyway. Devices that
13825 could be influenced by attackers should not set this flag; for example, network
13826 drivers can be subjected to predictable packet timing from outside and should not
13827 contribute to the entropy pool. See the comments in <i>drivers/char/random.c </i>for
13828 more information.</div>
13829 <br>
13830 The interrupt handler can be installed either at driver initialization or when the
13831 device is first opened. Although installing the interrupt handler from within the module's
13832 initialization function might sound like a good idea, it often isn't, especially if
13833 your device does not share interrupts. Because the number of interrupt lines is limited,
13834 you don't want to waste them. You can easily end up with more devices in your
13835 computer than there are interrupts. If a module requests an IRQ at initialization, it
13836 prevents any other driver from using the interrupt, even if the device holding it is
13837 never used. Requesting the interrupt at device open, on the other hand, allows some
13838 sharing of resources.<br>
13839 <br>
13840 It is possible, for example, to run a frame grabber on the same interrupt as a modem,
13841 as long as you don't use the two devices at the same time. It is quite common for
13842 users to load the module for a special device at system boot, even if the device is
13843 rarely used. A data acquisition gadget might use the same interrupt as the second
13844 serial port. While it's not too hard to avoid connecting to your Internet service provider
13845 (ISP) during data acquisition, being forced to unload a module in order to use
13846 the modem is really unpleasant.<br>
13847 <br>
13848 The correct place to call <i>request_irq </i>is when the device is first opened, <i>before </i>the
13849 hardware is instructed to generate interrupts. The place to call <i>free_irq </i>is the last
13850 time the device is closed, <i>after </i>the hardware is told not to interrupt the processor any
13851 more. The disadvantage of this technique is that you need to keep a per-device open
13852 count so that you know when interrupts can be disabled.<br>
13853 <br>
13854 This discussion notwithstanding, <i>short </i>requests its interrupt line at load time. This
13855 was done so that you can run the test programs without having to run an extra process
13856 to keep the device open. <i>short</i>, therefore, requests the interrupt from within its
13857 initialization function (<i>short_init</i>) instead of doing it in <i>short_open</i>, as a real device
13858 driver would.<br>
13859 <br>
13860 The interrupt requested by the following code is <font class="fixd">short_irq</font>. The actual assignment of
13861 the variable (i.e., determining which IRQ to use) is shown later, since it is not relevant
13862 to the current discussion. <font class="fixd">short_base</font> is the base I/O address of the parallel interface
13863 being used; register 2 of the interface is written to enable interrupt reporting.<br>
13864 <pre>
13865 if (short_irq >= 0) {
13866 result = request_irq(short_irq, short_interrupt,
13867 SA_INTERRUPT, "short", NULL);
13868 if (result) {
13869 printk(KERN_INFO "short: can't get assigned irq %i\n",
13870 short_irq);
13871 </pre>
13872 <A name="262"></a><font color="blue">PAGE 262</font><br>
13873 <pre>
13874 short_irq = -1;
13875 }
13876 else { /* actually enable it -- assume this *is* a parallel port */
13877 outb(0x10,short_base+2);
13878 }
13879 }
13880 </pre>
13881 The code shows that the handler being installed is a fast handler (<font class="fixd">SA_INTERRUPT</font>),
13882 doesn't support interrupt sharing (<font class="fixd">SA_SHIRQ</font> is missing), and doesn't contribute to
13883 system entropy (<font class="fixd">SA_SAMPLE_RANDOM</font> is missing, too). The <i>outb </i>call then enables interrupt
13884 reporting for the parallel port.<br>
13885 <br>
13886 For what it's worth, the i386 and x86_64 architectures define a function for querying
13887 the availability of an interrupt line:<br>
13888 <pre>
13889 int can_request_irq(unsigned int irq, unsigned long flags);
13890 </pre>
13891 This function returns a nonzero value if an attempt to allocate the given interrupt succeeds.
13892 Note, however, that things can always change between calls to <i>can_request_irq
13893 </i>and <i>request_irq</i>.<br>
13894 <br>
13895 <a name="TheProcInterface"></a><font color="red"><b>The /proc Interface</b></font><br>
13896 <br>
13897 Whenever a hardware interrupt reaches the processor, an internal counter is incremented,
13898 providing a way to check whether the device is working as expected.<br>
13899 <br>
13900 Reported interrupts are shown in <i>/proc/interrupts</i>. The following snapshot was taken
13901 on a two-processor Pentium system:<br>
13902 <pre>
13903 root@montalcino:/bike/corbet/write/ldd3/src/short# <b>m /proc/interrupts
13904 </b> CPU0 CPU1
13905 0: 4848108 34 IO-APIC-edge timer
13906 2: 0 0 XT-PIC cascade
13907 8: 3 1 IO-APIC-edge rtc
13908 10: 4335 1 IO-APIC-level aic7xxx
13909 11: 8903 0 IO-APIC-level uhci_hcd
13910 12: 49 1 IO-APIC-edge i8042
13911 NMI: 0 0
13912 LOC: 4848187 4848186
13913 ERR: 0
13914 MIS: 0
13915 </pre>
13916 The first column is the IRQ number. You can see from the IRQs that are missing that
13917 the file shows only interrupts corresponding to installed handlers. For example, the
13918 first serial port (which uses interrupt number 4) is not shown, indicating that the
13919 modem isn't being used. In fact, even if the modem had been used earlier but wasn't
13920 in use at the time of the snapshot, it would not show up in the file; the serial ports
13921 are well behaved and release their interrupt handlers when the device is closed.<br>
13922 <br>
13923 The <i>/proc/interrupts </i>display shows how many interrupts have been delivered to each
13924 CPU on the system. As you can see from the output, the Linux kernel generally handles<br>
13925 <br>
13926 <A name="263"></a><font color="blue">PAGE 263</font><br>
13927 <br>
13928 interrupts on the first CPU as a way of maximizing cache locality.* The last two columns
13929 give information on the programmable interrupt controller that handles the interrupt
13930 (and that a driver writer does not need to worry about), and the name(s) of the
13931 device(s) that have registered handlers for the interrupt (as specified in the <font class="fixd">dev_name</font>
13932 argument to <i>request_irq</i>).<br>
13933 <br>
13934 The <i>/proc </i>tree contains another interrupt-related file, <i>/proc/stat</i>; sometimes you'll
13935 find one file more useful and sometimes you'll prefer the other. <i>/proc/stat </i>records
13936 several low-level statistics about system activity, including (but not limited to) the
13937 number of interrupts received since system boot. Each line of <i>stat </i>begins with a text
13938 string that is the key to the line; the <font class="fixd">intr</font> markis what we are looking for. The following
13939 (truncated) snapshot was taken shortly after the previous one:<br>
13940 <pre>
13941 intr 5167833 5154006 2 0 2 4907 0 2 68 4 0 4406 9291 50 0 0
13942 </pre>
13943 The first number is the total of all interrupts, while each of the others represents a
13944 single IRQ line, starting with interrupt 0. All of the counts are summed across all
13945 processors in the system. This snapshot shows that interrupt number 4 has been
13946 used 4907 times, even though no handler is <i>currently </i>installed. If the driver you're
13947 testing acquires and releases the interrupt at each open and close cycle, you may find
13948 <i>/proc/stat</i> more useful than <i>/proc/interrupts</i>.<br>
13949 <br>
13950 Another difference between the two files is that <i>interrupts </i>is not architecture dependent
13951 (except, perhaps, for a couple of lines at the end), whereas <i>stat </i>is; the number of
13952 fields depends on the hardware underlying the kernel. The number of available interrupts
13953 varies from as few as 15 on the SPARC to as many as 256 on the IA-64 and a
13954 few other systems. It's interesting to note that the number of interrupts defined on
13955 the x86 is currently 224, not 16 as you may expect; this, as explained in <i>include/
13956 asm-i386/irq.h</i>, depends on Linux using the architectural limit instead of an implementation-specific
13957 limit (such as the 16 interrupt sources of the old-fashioned PC
13958 interrupt controller).<br>
13959 <br>
13960 The following is a snapshot of <i>/proc/interrupts </i>taken on an IA-64 system. As you can
13961 see, besides different hardware routing of common interrupt sources, the output is
13962 very similar to that from the 32-bit system shown earlier.<br>
13963 <pre>
13964 CPU0 CPU1
13965 27: 1705 34141 IO-SAPIC-level qla1280
13966 40: 0 0 SAPIC perfmon
13967 43: 913 6960 IO-SAPIC-level eth0
13968 47: 26722 146 IO-SAPIC-level usb-uhci
13969 64: 3 6 IO-SAPIC-edge ide0
13970 80: 4 2 IO-SAPIC-edge keyboard
13971 89: 0 0 IO-SAPIC-edge PS/2 Mouse
13972 239: 5606341 5606052 SAPIC timer
13973 </pre>
13974 * Although, some larger systems explicitly use interrupt balancing schemes to spread the
13975 interrupt load across the system.<br>
13976 <br>
13977 <A name="264"></a><font color="blue">PAGE 264</font><br>
13978 <pre>
13979 254: 67575 52815 SAPIC IPI
13980 NMI: 0 0
13981 ERR: 0
13982 </pre>
13983 <a name="AutodetectingTheIRQNumber"></a><font color="red"><b>Auto-Detecting the IRQ Number</b></font><br>
13984 <br>
13985 One of the most challenging problems for a driver at initialization time can be how
13986 to determine which IRQ line is going to be used by the device. The driver needs the
13987 information in order to correctly install the handler. Even though a programmer
13988 could require the user to specify the interrupt number at load time, this is a bad practice,
13989 because most of the time the user doesn't know the number, either because he
13990 didn't configure the jumpers or because the device is jumperless. Most users want
13991 their hardware to "just work" and are not interested in issues like interrupt numbers.
13992 So auto-detection of the interrupt number is a basic requirement for driver
13993 usability.<br>
13994 <br>
13995 Sometimes auto-detection depends on the knowledge that some devices feature a
13996 default behavior that rarely, if ever, changes. In this case, the driver might assume
13997 that the default values apply. This is exactly how <i>short </i>behaves by default with the
13998 parallel port. The implementation is straightforward, as shown by <i>short</i> itself:<br>
13999 <pre>
14000 if (short_irq < 0) /* not yet specified: force the default on */
14001 switch(short_base) {
14002 case 0x378: short_irq = 7; break;
14003 case 0x278: short_irq = 2; break;
14004 case 0x3bc: short_irq = 5; break;
14005 }
14006 </pre>
14007 The code assigns the interrupt number according to the chosen base I/O address,
14008 while allowing the user to override the default at load time with something like:<br>
14009 <pre>
14010 insmod ./short.ko irq=<i>x</i>
14011 </pre>
14012 <font class="fixd">short_base</font> defaults to <font class="fixd">0x378,</font> so <font class="fixd">short_irq</font> defaults to <font class="fixd">7.</font><br>
14013 <br>
14014 Some devices are more advanced in design and simply "announce" which interrupt
14015 they're going to use. In this case, the driver retrieves the interrupt number by reading
14016 a status byte from one of the device's I/O ports or PCI configuration space.
14017 When the target device is one that has the ability to tell the driver which interrupt it
14018 is going to use, auto-detecting the IRQ number just means probing the device, with
14019 no additional work required to probe the interrupt. Most modern hardware works
14020 this way, fortunately; for example, the PCI standard solves the problem by requiring
14021 peripheral devices to declare what interrupt line(s) they are going to use. The PCI
14022 standard is discussed in Chapter 12.<br>
14023 <br>
14024 Unfortunately, not every device is programmer friendly, and auto-detection might
14025 require some probing. The technique is quite simple: the driver tells the device to
14026 generate interrupts and watches what happens. If everything goes well, only one
14027 interrupt line is activated.<br>
14028 <br>
14029 <A name="265"></a><font color="blue">PAGE 265</font><br>
14030 <br>
14031 Although probing is simple in theory, the actual implementation might be unclear.
14032 We look at two ways to perform the task: calling kernel-defined helper functions and
14033 implementing our own version.<br>
14034 <br>
14035 <a name="KernelassistedProbing"></a><font color="red"><b>Kernel-assisted probing</b></font><br>
14036 <br>
14037 The Linux kernel offers a low-level facility for probing the interrupt number. It works
14038 for only nonshared interrupts, but most hardware that is capable of working in a
14039 shared interrupt mode provides better ways of finding the configured interrupt number
14040 anyway. The facility consists of two functions, declared in <i><linux/interrupt.h>
14041 </i>(which also describes the probing machinery):<br>
14042 <br>
14043 <font class="fixd">unsigned long probe_irq_on(void);</font><br>
14044 <div class="bq">
14045 This function returns a bit maskof unassigned interrupts. The driver must preserve
14046 the returned bit mask, and pass it to <i>probe_irq_off </i>later. After this call, the
14047 driver should arrange for its device to generate at least one interrupt.</div>
14048 <br>
14049 <font class="fixd">int probe_irq_off(unsigned long);</font><br>
14050 <div class="bq">
14051 After the device has requested an interrupt, the driver calls this function, passing
14052 as its argument the bit maskpreviously returned by <i>probe_irq_on</i>. <i>probe_irq_off
14053 </i>returns the number of the interrupt that was issued after "probe_on." If no interrupts
14054 occurred, 0 is returned (therefore, IRQ 0 can't be probed for, but no custom
14055 device can use it on any of the supported architectures anyway). If more than
14056 one interrupt occurred (ambiguous detection), <i>probe_irq_off </i>returns a negative
14057 value.</div>
14058 <br>
14059 The programmer should be careful to enable interrupts on the device <i>after </i>the call to
14060 <i>probe_irq_on </i>and to disable them <i>before </i>calling <i>probe_irq_off</i>. Additionally, you
14061 must remember to service the pending interrupt in your device after <i>probe_irq_off</i>.<br>
14062 <br>
14063 The <i>short </i>module demonstrates how to use such probing. If you load the module
14064 with <font class="fixd">probe=1,</font> the following code is executed to detect your interrupt line, provided
14065 pins 9 and 10 of the parallel connector are bound together:<br>
14066 <pre>
14067 int count = 0;
14068 do {
14069 unsigned long mask;
14071 mask = probe_irq_on( );
14072 outb_p(0x10,short_base+2); /* enable reporting */
14073 outb_p(0x00,short_base); /* clear the bit */
14074 outb_p(0xFF,short_base); /* set the bit: interrupt! */
14075 outb_p(0x00,short_base+2); /* disable reporting */
14076 udelay(5); /* give it some time */
14077 short_irq = probe_irq_off(mask);
14079 if (short_irq = = 0) { /* none of them? */
14080 printk(KERN_INFO "short: no irq reported by probe\n");
14081 short_irq = -1;
14082 }
14083 </pre>
14084 <A name="266"></a><font color="blue">PAGE 266</font><br>
14085 <pre>
14086 /*
14087 * if more than one line has been activated, the result is
14088 * negative. We should service the interrupt (no need for lpt port)
14089 * and loop over again. Loop at most five times, then give up
14090 */
14091 } while (short_irq < 0 && count++ < 5);
14092 if (short_irq < 0)
14093 printk("short: probe failed %i times, giving up\n", count);
14094 </pre>
14095 Note the use of <i>udelay </i>before calling <i>probe_irq_off</i>. Depending on the speed of your
14096 processor, you may have to wait for a brief period to give the interrupt time to actually
14097 be delivered.<br>
14098 <br>
14099 Probing might be a lengthy task. While this is not true for <i>short</i>, probing a frame
14100 grabber, for example, requires a delay of at least 20 ms (which is ages for the processor),
14101 and other devices might take even longer. Therefore, it's best to probe for the
14102 interrupt line only once, at module initialization, independently of whether you
14103 install the handler at device open (as you should) or within the initialization function
14104 (which is not recommended).<br>
14105 <br>
14106 It's interesting to note that on some platforms (PowerPC, M68k, most MIPS implementations,
14107 and both SPARC versions) probing is unnecessary, and, therefore, the
14108 previous functions are just empty placeholders, sometimes called "useless ISA nonsense."
14109 On other platforms, probing is implemented only for ISA devices. Anyway,
14110 most architectures define the functions (even if they are empty) to ease porting existing
14111 device drivers.<br>
14112 <br>
14113 <a name="DoityourselfProbing"></a><font color="red"><b>Do-it-yourself probing</b></font><br>
14114 <br>
14115 Probing can also be implemented in the driver itself without too much trouble. It is a
14116 rare driver that must implement its own probing, but seeing how it works gives some
14117 insight into the process. To that end, the <i>short </i>module performs do-it-yourself detection
14118 of the IRQ line if it is loaded with <font class="fixd">probe=2.</font><br>
14119 <br>
14120 The mechanism is the same as the one described earlier: enable all unused interrupts,
14121 then wait and see what happens. We can, however, exploit our knowledge of
14122 the device. Often a device can be configured to use one IRQ number from a set of
14123 three or four; probing just those IRQs enables us to detect the right one, without
14124 having to test for all possible IRQs.<br>
14125 <br>
14126 The <i>short </i>implementation assumes that 3, 5, 7, and 9 are the only possible IRQ values.
14127 These numbers are actually the values that some parallel devices allow you to
14128 select.<br>
14129 <br>
14130 The following code probes by testing all "possible" interrupts and looking at what
14131 happens. The trials array lists the IRQs to try and has 0 as the end marker; the
14132 tried array is used to keep track of which handlers have actually been registered by
14133 this driver.<br>
14134 <br>
14135 <A name="267"></a><font color="blue">PAGE 267</font><br>
14136 <pre>
14137 int trials[ ] = {3, 5, 7, 9, 0};
14138 int tried[ ] = {0, 0, 0, 0, 0};
14139 int i, count = 0;
14141 /*
14142 * install the probing handler for all possible lines. Remember
14143 * the result (0 for success, or -EBUSY) in order to only free
14144 * what has been acquired
14145 */
14146 for (i = 0; trials[i]; i++)
14147 tried[i] = request_irq(trials[i], short_probing,
14148 SA_INTERRUPT, "short probe", NULL);
14150 do {
14151 short_irq = 0; /* none got, yet */
14152 outb_p(0x10,short_base+2); /* enable */
14153 outb_p(0x00,short_base);
14154 outb_p(0xFF,short_base); /* toggle the bit */
14155 outb_p(0x00,short_base+2); /* disable */
14156 udelay(5); /* give it some time */
14158 /* the value has been set by the handler */
14159 if (short_irq = = 0) { /* none of them? */
14160 printk(KERN_INFO "short: no irq reported by probe\n");
14161 }
14162 /*
14163 * If more than one line has been activated, the result is
14164 * negative. We should service the interrupt (but the lpt port
14165 * doesn't need it) and loop over again. Do it at most 5 times
14166 */
14167 } while (short_irq <=0 && count++ < 5);
14169 /* end of loop, uninstall the handler */
14170 for (i = 0; trials[i]; i++)
14171 if (tried[i] = = 0)
14172 free_irq(trials[i], NULL);
14174 if (short_irq < 0)
14175 printk("short: probe failed %i times, giving up\n", count);
14176 </pre>
14177 You might not know in advance what the "possible" IRQ values are. In that case,
14178 you need to probe all the free interrupts, instead of limiting yourself to a few <font class="fixd">trials[ ].</font>
14179 To probe for all interrupts, you have to probe from IRQ 0 to IRQ <font class="fixd">NR_IRQS-1,</font> where
14180 <font class="fixd">NR_IRQS</font> is defined in <i><asm/irq.h></i> and is platform dependent.<br>
14181 <br>
14182 Now we are missing only the probing handler itself. The handler's role is to update
14183 <font class="fixd">short_irq</font> according to which interrupts are actually received. A 0 value in <font class="fixd">short_irq</font>
14184 means "nothing yet," while a negative value means "ambiguous." These values were
14185 chosen to be consistent with <i>probe_irq_off </i>and to allow the same code to call either
14186 kind of probing within <i>short.c</i>.<br>
14187 <pre>
14188 irqreturn_t short_probing(int irq, void *dev_id, struct pt_regs *regs)
14189 {
14190 </pre>
14191 <A name="268"></a><font color="blue">PAGE 268</font><br>
14192 <pre>
14193 if (short_irq = = 0) short_irq = irq; /* found */
14194 if (short_irq != irq) short_irq = -irq; /* ambiguous */
14195 return IRQ_HANDLED;
14196 }
14197 </pre>
14198 The arguments to the handler are described later. Knowing that <font class="fixd">irq</font> is the interrupt
14199 being handled should be sufficient to understand the function just shown.<br>
14200 <br>
14201 <a name="FastAndSlowHandlers"></a><font color="red"><b>Fast and Slow Handlers</b></font><br>
14202 <br>
14203 Older versions of the Linux kernel took great pains to distinguish between "fast" and
14204 "slow" interrupts. Fast interrupts were those that could be handled very quickly,
14205 whereas handling slow interrupts took significantly longer. Slow interrupts could be
14206 sufficiently demanding of the processor, and it was worthwhile to reenable interrupts
14207 while they were being handled. Otherwise, tasks requiring quick attention
14208 could be delayed for too long.<br>
14209 <br>
14210 In modern kernels, most of the differences between fast and slow interrupts have disappeared.
14211 There remains only one: fast interrupts (those that were requested with
14212 the <font class="fixd">SA_INTERRUPT</font> flag) are executed with all other interrupts disabled on the current
14213 processor. Note that other processors can still handle interrupts, although you will
14214 never see two processors handling the same IRQ at the same time.<br>
14215 <br>
14216 So, which type of interrupt should your driver use? On modern systems, <font class="fixd">SA_INTERRUPT</font> is
14217 intended only for use in a few, specific situations such as timer interrupts. Unless you
14218 have a strong reason to run your interrupt handler with other interrupts disabled, you
14219 should not use <font class="fixd">SA_INTERRUPT</font>.<br>
14220 <br>
14221 This description should satisfy most readers, although someone with a taste for hardware
14222 and some experience with her computer might be interested in going deeper. If
14223 you don't care about the internal details, you can skip to the next section.<br>
14224 <br>
14225 <a name="TheInternalsOfInterruptHandlingOnTheX86"></a><font color="red"><b>The internals of interrupt handling on the x86</b></font><br>
14226 <br>
14227 This description has been extrapolated from <i>arch/i386/kernel/irq.c</i>, <i>arch/i386/kernel/
14228 apic.c</i>, <i>arch/i386/kernel/entry.S</i>, <i>arch/i386/kernel/i8259.c</i>, and <i>include/asm-i386/hw_irq.h
14229 </i>as they appear in the 2.6 kernels; although the general concepts remain the same, the
14230 hardware details differ on other platforms.<br>
14231 <br>
14232 The lowest level of interrupt handling can be found in <i>entry.S</i>, an assembly-language
14233 file that handles much of the machine-level work. By way of a bit of assembler trickery
14234 and some macros, a bit of code is assigned to every possible interrupt. In each
14235 case, the code pushes the interrupt number on the stack and jumps to a common
14236 segment, which calls <i>do_IRQ</i>, defined in <i>irq.c</i>.<br>
14237 <br>
14238 The first thing <i>do_IRQ </i>does is to acknowledge the interrupt so that the interrupt controller
14239 can go on to other things. It then obtains a spinlock for the given IRQ number,
14240 thus preventing any other CPU from handling this IRQ. It clears a couple of status<br>
14241 <br>
14242 <A name="269"></a><font color="blue">PAGE 269</font><br>
14243 <br>
14244 bits (including one called <font class="fixd">IRQ_WAITING</font> that we'll look at shortly) and then looks up the
14245 handler(s) for this particular IRQ. If there is no handler, there's nothing to do; the
14246 spinlock is released, any pending software interrupts are handled, and <i>do_IRQ
14247 </i>returns.<br>
14248 <br>
14249 Usually, however, if a device is interrupting, there is at least one handler registered
14250 for its IRQ as well. The function <i>handle_IRQ_event </i>is called to actually invoke the
14251 handlers. If the handler is of the slow variety (SA_INTERRUPT is not set), interrupts are
14252 reenabled in the hardware, and the handler is invoked. Then it's just a matter of
14253 cleaning up, running software interrupts, and getting back to regular work. The "regular
14254 work" may well have changed as a result of an interrupt (the handler could
14255 <i>wake_up </i>a process, for example), so the last thing that happens on return from an
14256 interrupt is a possible rescheduling of the processor.<br>
14257 <br>
14258 Probing for IRQs is done by setting the <font class="fixd">IRQ_WAITING</font> status bit for each IRQ that currently
14259 lacks a handler. When the interrupt happens, <i>do_IRQ </i>clears that bit and then
14260 returns, because no handler is registered. <i>probe_irq_off</i>, when called by a driver,
14261 needs to search for only the IRQ that no longer has <font class="fixd">IRQ_WAITING</font> set.<br>
14262 <br>
14263 <a name="ImplementingAHandler"></a><font color="red"><b>Implementing a Handler</b></font><br>
14264 <br>
14265 So far, we've learned to register an interrupt handler but not to write one. Actually,
14266 there's nothing unusual about a handler--it's ordinary C code.<br>
14267 <br>
14268 The only peculiarity is that a handler runs at interrupt time and, therefore, suffers
14269 some restrictions on what it can do. These restrictions are the same as those we saw
14270 with kernel timers. A handler can't transfer data to or from user space, because it
14271 doesn't execute in the context of a process. Handlers also cannot do anything that
14272 would sleep, such as calling <i>wait_event</i>, allocating memory with anything other than
14273 <font class="fixd">GFP_ATOMIC</font>, or locking a semaphore. Finally, handlers cannot call <i>schedule</i>.<br>
14274 <br>
14275 The role of an interrupt handler is to give feedback to its device about interrupt
14276 reception and to read or write data according to the meaning of the interrupt being
14277 serviced. The first step usually consists of clearing a bit on the interface board; most
14278 hardware devices won't generate other interrupts until their "interrupt-pending" bit
14279 has been cleared. Depending on how your hardware works, this step may need to be
14280 performed last instead of first; there is no catch-all rule here. Some devices don't
14281 require this step, because they don't have an "interrupt-pending" bit; such devices
14282 are a minority, although the parallel port is one of them. For that reason, <i>short </i>does
14283 not have to clear such a bit.<br>
14284 <br>
14285 A typical task for an interrupt handler is awakening processes sleeping on the device
14286 if the interrupt signals the event they're waiting for, such as the arrival of new data.<br>
14287 <br>
14288 To stick with the frame grabber example, a process could acquire a sequence of
14289 images by continuously reading the device; the <i>read </i>call blocks before reading each<br>
14290 <br>
14291 <A name="270"></a><font color="blue">PAGE 270</font><br>
14292 <br>
14293 frame, while the interrupt handler awakens the process as soon as each new frame
14294 arrives. This assumes that the grabber interrupts the processor to signal successful
14295 arrival of each new frame.<br>
14296 <br>
14297 The programmer should be careful to write a routine that executes in a minimum
14298 amount of time, independent of its being a fast or slow handler. If a long computation
14299 needs to be performed, the best approach is to use a tasklet or workqueue to
14300 schedule computation at a safer time (we'll look at how work can be deferred in this
14301 manner in the section "Top and Bottom Halves.")<br>
14302 <br>
14303 Our sample code in <i>short </i>responds to the interrupt by calling <i>do_gettimeofday </i>and
14304 printing the current time into a page-sized circular buffer. It then awakens any reading
14305 process, because there is now data available to be read.<br>
14306 <pre>
14307 irqreturn_t short_interrupt(int irq, void *dev_id, struct pt_regs *regs)
14308 {
14309 struct timeval tv;
14310 int written;
14312 do_gettimeofday(&tv);
14314 /* Write a 16 byte record. Assume PAGE_SIZE is a multiple of 16 */
14315 written = sprintf((char *)short_head,"%08u.%06u\n",
14316 (int)(tv.tv_sec % 100000000), (int)(tv.tv_usec));
14317 BUG_ON(written != 16);
14318 short_incr_bp(&short_head, written);
14319 wake_up_interruptible(&short_queue); /* awake any reading process */
14320 return IRQ_HANDLED;
14321 }
14322 </pre>
14323 This code, though simple, represents the typical job of an interrupt handler. It, in
14324 turn, calls <i>short_incr_bp</i>, which is defined as follows:<br>
14325 <pre>
14326 static inline void short_incr_bp(volatile unsigned long *index, int delta)
14327 {
14328 unsigned long new = *index + delta;
14329 barrier( ); /* Don't optimize these two together */
14330 *index = (new >= (short_buffer + PAGE_SIZE)) ? short_buffer : new;
14331 }
14332 </pre>
14333 This function has been carefully written to wrap a pointer into the circular buffer
14334 without ever exposing an incorrect value. The <i>barrier </i>call is there to block compiler
14335 optimizations across the other two lines of the function. Without the barrier, the
14336 compiler might decide to optimize out the new variable and assign directly to <font class="fixd">*index.</font>
14337 That optimization could expose an incorrect value of the index for a brief period in
14338 the case where it wraps. By taking care to prevent in inconsistent value from ever
14339 being visible to other threads, we can manipulate the circular buffer pointers safely
14340 without locks.<br>
14341 <br>
14342 The device file used to read the buffer being filled at interrupt time is <i>/dev/shortint</i>.
14343 This device special file, together with <i>/dev/shortprint</i>, wasn't introduced in<br>
14344 <br>
14345 <A name="271"></a><font color="blue">PAGE 271</font><br>
14346 <br>
14347 Chapter 9, because its use is specific to interrupt handling. The internals of <i>/dev/
14348 shortint </i>are specifically tailored for interrupt generation and reporting. Writing to the
14349 device generates one interrupt every other byte; reading the device gives the time
14350 when each interrupt was reported.<br>
14351 <br>
14352 If you connect together pins 9 and 10 of the parallel connector, you can generate
14353 interrupts by raising the high bit of the parallel data byte. This can be accomplished
14354 by writing binary data to <i>/dev/short0</i> or by writing anything to <i>/dev/shortint</i>.*<br>
14355 <br>
14356 The following code implements <i>read</i> and <i>write</i> for <i>/dev/shortint</i>:<br>
14357 <pre>
14358 ssize_t short_i_read (struct file *filp, char __user *buf, size_t count,
14359 loff_t *f_pos)
14360 {
14361 int count0;
14362 DEFINE_WAIT(wait);
14364 while (short_head = = short_tail) {
14365 prepare_to_wait(&short_queue, &wait, TASK_INTERRUPTIBLE);
14366 if (short_head = = short_tail)
14367 schedule( );
14368 finish_wait(&short_queue, &wait);
14369 if (signal_pending (current)) /* a signal arrived */
14370 return -ERESTARTSYS; /* tell the fs layer to handle it */
14371 }
14372 /* count0 is the number of readable data bytes */
14373 count0 = short_head - short_tail;
14374 if (count0 < 0) /* wrapped */
14375 count0 = short_buffer + PAGE_SIZE - short_tail;
14376 if (count0 < count) count = count0;
14378 if (copy_to_user(buf, (char *)short_tail, count))
14379 return -EFAULT;
14380 short_incr_bp (&short_tail, count);
14381 return count;
14382 }
14384 ssize_t short_i_write (struct file *filp, const char __user *buf, size_t count,
14385 loff_t *f_pos)
14386 {
14387 int written = 0, odd = *f_pos & 1;
14388 unsigned long port = short_base; /* output to the parallel data latch */
14389 void *address = (void *) short_base;
14391 if (use_mem) {
14392 while (written < count)
14393 iowrite8(0xff * ((++written + odd) & 1), address);
14394 } else {
14395 </pre>
14396 * The <i>shortint</i> device accomplishes its task by alternately writing 0x00 and 0xff to the parallel port.<br>
14397 <br>
14398 <A name="272"></a><font color="blue">PAGE 272</font><br>
14399 <pre>
14400 while (written < count)
14401 outb(0xff * ((++written + odd) & 1), port);
14402 }
14404 *f_pos += count;
14405 return written;
14406 }
14407 </pre>
14408 The other device special file, <i>/dev/shortprint</i>, uses the parallel port to drive a printer;
14409 you can use it if you want to avoid connecting pins 9 and 10 of a D-25 connector.
14410 The <i>write </i>implementation of <i>shortprint </i>uses a circular buffer to store data to be
14411 printed, while the <i>read </i>implementation is the one just shown (so you can read the
14412 time your printer takes to eat each character).<br>
14413 <br>
14414 In order to support printer operation, the interrupt handler has been slightly modified
14415 from the one just shown, adding the ability to send the next data byte to the
14416 printer if there is more data to transfer.<br>
14417 <br>
14418 <a name="HandlerArgumentsAndReturnValue"></a><font color="red"><b>Handler Arguments and Return Value</b></font><br>
14419 <br>
14420 Though <i>short </i>ignores them, three arguments are passed to an interrupt handler: <font class="fixd">irq,
14421 dev_id,</font> and <font class="fixd">regs.</font> Let's look at the role of each.<br>
14422 <br>
14423 The interrupt number (<font class="fixd">int irq</font>) is useful as information you may print in your log
14424 messages, if any. The second argument, <font class="fixd">void *dev_id,</font> is a sort of client data; a <font class="fixd">void *</font>
14425 argument is passed to <i>request_irq</i>, and this same pointer is then passed back as an
14426 argument to the handler when the interrupt happens. You usually pass a pointer to
14427 your device data structure in <font class="fixd">dev_id,</font> so a driver that manages several instances of the
14428 same device doesn't need any extra code in the interrupt handler to find out which
14429 device is in charge of the current interrupt event.<br>
14430 <br>
14431 Typical use of the argument in an interrupt handler is as follows:<br>
14432 <pre>
14433 static irqreturn_t sample_interrupt(int irq, void *dev_id, struct pt_regs
14434 *regs)
14435 {
14436 struct sample_dev *dev = dev_id;
14438 /* now `dev' points to the right hardware item */
14439 /* .... */
14440 }
14441 </pre>
14442 The typical <i>open</i> code associated with this handler looks like this:<br>
14443 <pre>
14444 static void sample_open(struct inode *inode, struct file *filp)
14445 {
14446 struct sample_dev *dev = hwinfo + MINOR(inode->i_rdev);
14447 request_irq(dev->irq, sample_interrupt,
14448 0 /* flags */, "sample", dev /* dev_id */);
14449 /*....*/
14450 return 0;
14451 }
14452 </pre>
14453 <A name="273"></a><font color="blue">PAGE 273</font><br>
14454 <br>
14455 The last argument, <font class="fixd">struct pt_regs *regs,</font> is rarely used. It holds a snapshot of the
14456 processor's context before the processor entered interrupt code. The registers can be
14457 used for monitoring and debugging; they are not normally needed for regular device
14458 driver tasks.<br>
14459 <br>
14460 Interrupt handlers should return a value indicating whether there was actually an
14461 interrupt to handle. If the handler found that its device did, indeed, need attention, it
14462 should return <font class="fixd">IRQ_HANDLED;</font> otherwise the return value should be <font class="fixd">IRQ_NONE</font>. You can
14463 also generate the return value with this macro:<br>
14464 <pre>
14465 IRQ_RETVAL(handled)
14466 </pre>
14467 where handled is nonzero if you were able to handle the interrupt. The return value is
14468 used by the kernel to detect and suppress spurious interrupts. If your device gives
14469 you no way to tell whether it really interrupted, you should return <font class="fixd">IRQ_HANDLED</font>.<br>
14470 <br>
14471 <a name="EnablingAndDisablingInterrupts"></a><font color="red"><b>Enabling and Disabling Interrupts</b></font><br>
14472 <br>
14473 There are times when a device driver must block the delivery of interrupts for a
14474 (hopefully short) period of time (we saw one such situation in the section "Spinlocks"
14475 in Chapter 5). Often, interrupts must be blocked while holding a spinlock to
14476 avoid deadlocking the system. There are ways of disabling interrupts that do not
14477 involve spinlocks. But before we discuss them, note that disabling interrupts should
14478 be a relatively rare activity, even in device drivers, and this technique should never be
14479 used as a mutual exclusion mechanism within a driver.<br>
14480 <br>
14481 <a name="DisablingASingleInterrupt"></a><font color="red"><b>Disabling a single interrupt</b></font><br>
14482 <br>
14483 Sometimes (but rarely!) a driver needs to disable interrupt delivery for a specific
14484 interrupt line. The kernel offers three functions for this purpose, all declared in
14485 <i><asm/irq.h></i>. These functions are part of the kernel API, so we describe them, but
14486 their use is discouraged in most drivers. Among other things, you cannot disable
14487 shared interrupt lines, and, on modern systems, shared interrupts are the norm. That
14488 said, here they are:<br>
14489 <pre>
14490 void disable_irq(int irq);
14491 void disable_irq_nosync(int irq);
14492 void enable_irq(int irq);
14493 </pre>
14494 Calling any of these functions may update the maskfor the specified irq in the programmable
14495 interrupt controller (PIC), thus disabling or enabling the specified IRQ
14496 across all processors. Calls to these functions can be nested--if <i>disable_irq </i>is called
14497 twice in succession, two <i>enable_irq </i>calls are required before the IRQ is truly reenabled.
14498 It is possible to call these functions from an interrupt handler, but enabling
14499 your own IRQ while handling it is not usually good practice.<br>
14500 <br>
14501 <i>disable_irq </i>not only disables the given interrupt but also waits for a currently executing
14502 interrupt handler, if any, to complete. Be aware that if the thread calling <i>disable_irq</i><br>
14503 <br>
14504 <A name="274"></a><font color="blue">PAGE 274</font><br>
14505 <br>
14506 holds any resources (such as spinlocks) that the interrupt handler needs, the system
14507 can deadlock. <i>disable_irq_nosync </i>differs from <i>disable_irq </i>in that it returns immediately.
14508 Thus, using <i>disable_irq_nosync </i>is a little faster but may leave your driver open to
14509 race conditions.<br>
14510 <br>
14511 But why disable an interrupt? Sticking to the parallel port, let's look at the <i>plip </i>network interface.
14512 A <i>plip </i>device uses the bare-bones parallel port to transfer data. Since
14513 only five bits can be read from the parallel connector, they are interpreted as four
14514 data bits and a clock/handshake signal. When the first four bits of a packet are transmitted
14515 by the initiator (the interface sending the packet), the clock line is raised,
14516 causing the receiving interface to interrupt the processor. The <i>plip </i>handler is then
14517 invoked to deal with newly arrived data.<br>
14518 <br>
14519 After the device has been alerted, the data transfer proceeds, using the handshake
14520 line to clocknew data to the receiving interface (this might not be the best implementation,
14521 but it is necessary for compatibility with other packet drivers using the
14522 parallel port). Performance would be unbearable if the receiving interface had to handle
14523 two interrupts for every byte received. Therefore, the driver disables the interrupt
14524 during the reception of the packet; instead, a poll-and-delay loop is used to
14525 bring in the data.<br>
14526 <br>
14527 Similarly, because the handshake line from the receiver to the transmitter is used to
14528 acknowledge data reception, the transmitting interface disables its IRQ line during
14529 packet transmission.<br>
14530 <br>
14531 <a name="DisablingAllInterrupts"></a><font color="red"><b>Disabling all interrupts</b></font><br>
14532 <br>
14533 What if you need to disable <i>all </i>interrupts? In the 2.6 kernel, it is possible to turn off
14534 all interrupt handling on the current processor with either of the following two functions
14535 (which are defined in <i><asm/system.h></i>):<br>
14536 <pre>
14537 void local_irq_save(unsigned long flags);
14538 void local_irq_disable(void);
14539 </pre>
14540 A call to <i>local_irq_save </i>disables interrupt delivery on the current processor after saving
14541 the current interrupt state into <font class="fixd">flags</font>. Note that <font class="fixd">flags</font> is passed directly, not by
14542 pointer. <i>local_irq_disable </i>shuts off local interrupt delivery without saving the state;
14543 you should use this version only if you know that interrupts have not already been
14544 disabled elsewhere.<br>
14545 <br>
14546 Turning interrupts back on is accomplished with:<br>
14547 <pre>
14548 void local_irq_restore(unsigned long flags);
14549 void local_irq_enable(void);
14550 </pre>
14551 The first version restores that state which was stored into <font class="fixd">flags</font> by <i>local_irq_save</i>,
14552 while <i>local_irq_enable </i>enables interrupts unconditionally. Unlike <i>disable_irq</i>,
14553 <i>local_irq_disable </i>does not keep track of multiple calls. If more than one function in
14554 the call chain might need to disable interrupts, <i>local_irq_save</i> should be used.<br>
14555 <br>
14556 <A name="275"></a><font color="blue">PAGE 275</font><br>
14557 <br>
14558 In the 2.6 kernel, there is no way to disable all interrupts globally across the entire
14559 system. The kernel developers have decided that the cost of shutting off all interrupts
14560 is too high and that there is no need for that capability in any case. If you are
14561 working with an older driver that makes calls to functions such as <i>cli </i>and <i>sti</i>, you
14562 need to update it to use proper locking before it will work under 2.6.<br>
14563 <br>
14564 <a name="TopAndBottomHalves"></a><font color="red"><b>Top and Bottom Halves</b></font><br>
14565 <br>
14566 One of the main problems with interrupt handling is how to perform lengthy tasks
14567 within a handler. Often a substantial amount of work must be done in response to a
14568 device interrupt, but interrupt handlers need to finish up quickly and not keep interrupts
14569 blocked for long. These two needs (work and speed) conflict with each other,
14570 leaving the driver writer in a bit of a bind.<br>
14571 <br>
14572 Linux (along with many other systems) resolves this problem by splitting the interrupt
14573 handler into two halves. The so-called <i>top half </i>is the routine that actually
14574 responds to the interrupt--the one you register with <i>request_irq</i>. The <i>bottom half </i>is a
14575 routine that is scheduled by the top half to be executed later, at a safer time. The big
14576 difference between the top-half handler and the bottom half is that all interrupts are
14577 enabled during execution of the bottom half--that's why it runs at a safer time. In
14578 the typical scenario, the top half saves device data to a device-specific buffer, schedules
14579 its bottom half, and exits: this operation is very fast. The bottom half then performs
14580 whatever other work is required, such as awakening processes, starting up
14581 another I/O operation, and so on. This setup permits the top half to service a new
14582 interrupt while the bottom half is still working.<br>
14583 <br>
14584 Almost every serious interrupt handler is split this way. For instance, when a network interface
14585 reports the arrival of a new packet, the handler just retrieves the data
14586 and pushes it up to the protocol layer; actual processing of the packet is performed
14587 in a bottom half.<br>
14588 <br>
14589 The Linux kernel has two different mechanisms that may be used to implement bottom-half
14590 processing, both of which were introduced in Chapter 7. Tasklets are often
14591 the preferred mechanism for bottom-half processing; they are very fast, but all tasklet
14592 code must be atomic. The alternative to tasklets is workqueues, which may have a
14593 higher latency but that are allowed to sleep.<br>
14594 <br>
14595 The following discussion works, once again, with the <i>short </i>driver. When loaded with
14596 a module option, <i>short </i>can be told to do interrupt processing in a top/bottom-half
14597 mode with either a tasklet or workqueue handler. In this case, the top half executes
14598 quickly; it simply remembers the current time and schedules the bottom half processing.
14599 The bottom half is then charged with encoding this time and awakening any
14600 user processes that may be waiting for data.<br>
14601 <br>
14602 <A name="276"></a><font color="blue">PAGE 276</font><br>
14603 <br>
14604 <a name="Tasklets3"></a><font color="red"><b>Tasklets</b></font><br>
14605 <br>
14606 Remember that tasklets are a special function that may be scheduled to run, in software
14607 interrupt context, at a system-determined safe time. They may be scheduled to
14608 run multiple times, but tasklet scheduling is not cumulative; the tasklet runs only
14609 once, even if it is requested repeatedly before it is launched. No tasklet ever runs in
14610 parallel with itself, since they run only once, but tasklets can run in parallel with
14611 other tasklets on SMP systems. Thus, if your driver has multiple tasklets, they must
14612 employ some sort of locking to avoid conflicting with each other.<br>
14613 <br>
14614 Tasklets are also guaranteed to run on the same CPU as the function that first schedules
14615 them. Therefore, an interrupt handler can be secure that a tasklet does not begin
14616 executing before the handler has completed. However, another interrupt can certainly
14617 be delivered while the tasklet is running, so locking between the tasklet and
14618 the interrupt handler may still be required.<br>
14619 <br>
14620 Tasklets must be declared with the <font class="fixd">DECLARE_TASKLET</font> macro:<br>
14621 <pre>
14622 DECLARE_TASKLET(name, function, data);
14623 </pre>
14624 <font class="fixd">name</font> is the name to be given to the tasklet, <i>function </i>is the function that is called to
14625 execute the tasklet (it takes one <font class="fixd">unsigned long</font> argument and returns <font class="fixd">void</font>), and <font class="fixd">data</font>
14626 is an <font class="fixd">unsigned long</font> value to be passed to the <i>tasklet</i> function.<br>
14627 <br>
14628 The <i>short</i> driver declares its tasklet as follows:<br>
14629 <pre>
14630 void short_do_tasklet(unsigned long);
14631 DECLARE_TASKLET(short_tasklet, short_do_tasklet, 0);
14632 </pre>
14633 The function <i>tasklet_schedule </i>is used to schedule a tasklet for running. If <i>short </i>is
14634 loaded with <font class="fixd">tasklet=1,</font> it installs a different interrupt handler that saves data and
14635 schedules the tasklet as follows:<br>
14636 <pre>
14637 irqreturn_t short_tl_interrupt(int irq, void *dev_id, struct pt_regs *regs)
14638 {
14639 do_gettimeofday((struct timeval *) tv_head); /* cast to stop 'volatile' warning
14640 */
14641 short_incr_tv(&tv_head);
14642 tasklet_schedule(&short_tasklet);
14643 short_wq_count++; /* record that an interrupt arrived */
14644 return IRQ_HANDLED;
14645 }
14646 </pre>
14647 The actual tasklet routine, <i>short_do_tasklet</i>, will be executed shortly (so to speak) at
14648 the system's convenience. As mentioned earlier, this routine performs the bulk of the
14649 work of handling the interrupt; it looks like this:<br>
14650 <pre>
14651 void short_do_tasklet (unsigned long unused)
14652 {
14653 int savecount = short_wq_count, written;
14654 short_wq_count = 0; /* we have already been removed from the queue */
14655 /*
14656 * The bottom half reads the tv array, filled by the top half,
14657 </pre>
14658 <A name="277"></a><font color="blue">PAGE 277</font><br>
14659 <pre>
14660 * and prints it to the circular text buffer, which is then consumed
14661 * by reading processes
14662 */
14664 /* First write the number of interrupts that occurred before this bh */
14665 written = sprintf((char *)short_head,"bh after %6i\n",savecount);
14666 short_incr_bp(&short_head, written);
14668 /*
14669 * Then, write the time values. Write exactly 16 bytes at a time,
14670 * so it aligns with PAGE_SIZE
14671 */
14673 do {
14674 written = sprintf((char *)short_head,"%08u.%06u\n",
14675 (int)(tv_tail->tv_sec % 100000000),
14676 (int)(tv_tail->tv_usec));
14677 short_incr_bp(&short_head, written);
14678 short_incr_tv(&tv_tail);
14679 } while (tv_tail != tv_head);
14681 wake_up_interruptible(&short_queue); /* awake any reading process */
14682 }
14683 </pre>
14684 Among other things, this tasklet makes a note of how many interrupts have arrived
14685 since it was last called. A device such as <i>short </i>can generate a great many interrupts in
14686 a brief period, so it is not uncommon for several to arrive before the bottom half is
14687 executed. Drivers must always be prepared for this possibility and must be able to
14688 determine how much work there is to perform from the information left by the top
14689 half.<br>
14690 <br>
14691 <a name="Workqueues3"></a><font color="red"><b>Workqueues</b></font><br>
14692 <br>
14693 Recall that workqueues invoke a function at some future time in the context of a special
14694 worker process. Since the <i>workqueue </i>function runs in process context, it can
14695 sleep if need be. You cannot, however, copy data into user space from a workqueue,
14696 unless you use the advanced techniques we demonstrate in Chapter 15; the worker
14697 process does not have access to any other process's address space.<br>
14698 <br>
14699 The <i>short </i>driver, if loaded with the <font class="fixd">wq</font> option set to a nonzero value, uses a workqueue
14700 for its bottom-half processing. It uses the system default workqueue, so there
14701 is no special setup code required; if your driver has special latency requirements (or
14702 might sleep for a long time in the <i>workqueue </i>function), you may want to create your
14703 own, dedicated workqueue. We do need a <font class="fixd">work_struct</font> structure, which is declared
14704 and initialized with the following:<br>
14705 <pre>
14706 static struct <font class="fixd">work_struct</font> short_wq;
14708 /* this line is in short_init( ) */
14709 INIT_WORK(&short_wq, (void (*)(void *)) short_do_tasklet, NULL);
14710 </pre>
14711 <A name="278"></a><font color="blue">PAGE 278</font><br>
14712 <br>
14713 Our worker function is <i>short_do_tasklet</i>, which we have already seen in the previous
14714 section.<br>
14715 <br>
14716 When working with a workqueue, <i>short </i>establishes yet another interrupt handler
14717 that looks like this:<br>
14718 <pre>
14719 irqreturn_t short_wq_interrupt(int irq, void *dev_id, struct pt_regs *regs)
14720 {
14721 /* Grab the current time information. */
14722 do_gettimeofday((struct timeval *) tv_head);
14723 short_incr_tv(&tv_head);
14725 /* Queue the bh. Don't worry about multiple enqueueing */
14726 schedule_work(&short_wq);
14728 short_wq_count++; /* record that an interrupt arrived */
14729 return IRQ_HANDLED;
14730 }
14731 </pre>
14732 As you can see, the interrupt handler looks very much like the tasklet version, with
14733 the exception that it calls <i>schedule_work</i> to arrange the bottom-half processing.<br>
14734 <br>
14735 <a name="InterruptSharing"></a><font color="red"><b>Interrupt Sharing</b></font><br>
14736 <br>
14737 The notion of an IRQ conflict is almost synonymous with the PC architecture. In the
14738 past, IRQ lines on the PC have not been able to serve more than one device, and
14739 there have never been enough of them. As a result, frustrated users have often spent
14740 much time with their computer case open, trying to find a way to make all of their
14741 peripherals play well together.<br>
14742 <br>
14743 Modern hardware, of course, has been designed to allow the sharing of interrupts;
14744 the PCI bus requires it. Therefore, the Linux kernel supports interrupt sharing on all
14745 buses, even those (such as the ISA bus) where sharing has traditionally not been supported.
14746 Device drivers for the 2.6 kernel should be written to work with shared interrupts
14747 if the target hardware can support that mode of operation. Fortunately,
14748 working with shared interrupts is easy, most of the time.<br>
14749 <br>
14750 <a name="InstallingASharedHandler"></a><font color="red"><b>Installing a Shared Handler</b></font><br>
14751 <br>
14752 Shared interrupts are installed through <i>request_irq </i>just like nonshared ones, but
14753 there are two differences:<br>
14754 <ul>
14755 <li> The <font class="fixd">SA_SHIRQ</font> bit must be specified in the <font class="fixd">flags</font>
14756 argument when requesting the interrupt.
14757 <li> The <font class="fixd">dev_id</font> argument <i>must </i>be unique. Any pointer into the module's address
14758 space will do, but <font class="fixd">dev_id</font> definitely cannot be set to <font class="fixd">NULL</font>.
14759 </ul>
14760 <A name="279"></a><font color="blue">PAGE 279</font><br>
14761 <br>
14762 The kernel keeps a list of shared handlers associated with the interrupt, and <font class="fixd">dev_id</font>
14763 can be thought of as the signature that differentiates between them. If two drivers
14764 were to register <font class="fixd">NULL</font> as their signature on the same interrupt, things might get mixed
14765 up at unload time, causing the kernel to oops when an interrupt arrived. For this reason,
14766 modern kernels complain loudly if passed a <font class="fixd">NULL</font> <font class="fixd">dev_id</font> when registering shared
14767 interrupts. When a shared interrupt is requested, <i>request_irq </i>succeeds if one of the
14768 following is true:<br>
14769 <ul>
14770 <li> The interrupt line is free.
14771 <li> All handlers already registered for that line have also specified that the IRQ is to be shared.
14772 </ul>
14773 Whenever two or more drivers are sharing an interrupt line and the hardware interrupts
14774 the processor on that line, the kernel invokes every handler registered for that
14775 interrupt, passing each its own <font class="fixd">dev_id</font>. Therefore, a shared handler must be able to
14776 recognize its own interrupts and should quickly exit when its own device has not
14777 interrupted. Be sure to return <font class="fixd">IRQ_NONE</font> whenever your handler is called and finds
14778 that the device is not interrupting.<br>
14779 <br>
14780 If you need to probe for your device before requesting the IRQ line, the kernel can't
14781 help you. No probing function is available for shared handlers. The standard probing
14782 mechanism works if the line being used is free, but if the line is already held by
14783 another driver with sharing capabilities, the probe fails, even if your driver would
14784 have worked perfectly. Fortunately, most hardware designed for interrupt sharing is
14785 also able to tell the processor which interrupt it is using, thus eliminating the need
14786 for explicit probing.<br>
14787 <br>
14788 Releasing the handler is performed in the normal way, using <i>free_irq</i>. Here the <font class="fixd">dev_id</font>
14789 argument is used to select the correct handler to release from the list of shared handlers
14790 for the interrupt. That's why the <font class="fixd">dev_id</font> pointer must be unique.<br>
14791 <br>
14792 A driver using a shared handler needs to be careful about one more thing: it can't
14793 play with <i>enable_irq </i>or <i>disable_irq</i>. If it does, things might go haywire for other
14794 devices sharing the line; disabling another device's interrupts for even a short time
14795 may create latencies that are problematic for that device and it's user. Generally, the
14796 programmer must remember that his driver doesn't own the IRQ, and its behavior
14797 should be more "social" than is necessary if one owns the interrupt line.<br>
14798 <br>
14799 <a name="RunningTheHandler"></a><font color="red"><b>Running the Handler</b></font><br>
14800 <br>
14801 As suggested earlier, when the kernel receives an interrupt, all the registered handlers
14802 are invoked. A shared handler must be able to distinguish between interrupts
14803 that it needs to handle and interrupts generated by other devices.<br>
14804 <br>
14805 <A name="280"></a><font color="blue">PAGE 280</font><br>
14806 <br>
14807 Loading <i>short </i>with the option <i>shared=1 </i>installs the following handler instead of the
14808 default:<br>
14809 <pre>
14810 irqreturn_t short_sh_interrupt(int irq, void *dev_id, struct pt_regs *regs)
14811 {
14812 int value, written;
14813 struct timeval tv;
14815 /* If it wasn't short, return immediately */
14816 value = inb(short_base);
14817 if (!(value & 0x80))
14818 return IRQ_NONE;
14820 /* clear the interrupting bit */
14821 outb(value & 0x7F, short_base);
14823 /* the rest is unchanged */
14825 do_gettimeofday(&tv);
14826 written = sprintf((char *)short_head,"%08u.%06u\n",
14827 (int)(tv.tv_sec % 100000000), (int)(tv.tv_usec));
14828 short_incr_bp(&short_head, written);
14829 wake_up_interruptible(&short_queue); /* awake any reading process */
14830 return IRQ_HANDLED;
14831 }
14832 </pre>
14833 An explanation is due here. Since the parallel port has no "interrupt-pending" bit to
14834 check, the handler uses the ACK bit for this purpose. If the bit is high, the interrupt
14835 being reported is for <i>short</i>, and the handler clears the bit.<br>
14836 <br>
14837 The handler resets the bit by zeroing the high bit of the parallel interface's data
14838 port--<i>short </i>assumes that pins 9 and 10 are connected together. If one of the other
14839 devices sharing the IRQ with <i>short </i>generates an interrupt, <i>short </i>sees that its own line
14840 is still inactive and does nothing.<br>
14841 <br>
14842 A full-featured driver probably splits the work into top and bottom halves, of course,
14843 but that's easy to add and does not have any impact on the code that implements
14844 sharing. A real driver would also likely use the <font class="fixd">dev_id</font> argument to determine which,
14845 of possibly many, devices might be interrupting.<br>
14846 <br>
14847 Note that if you are using a printer (instead of the jumper wire) to test interrupt management
14848 with <i>short</i>, this shared handler won't work as advertised, because the
14849 printer protocol doesn't allow for sharing, and the driver can't know whether the
14850 interrupt was from the printer.<br>
14851 <br>
14852 <a name="TheProcInterfaceAndSharedInterrupts"></a><font color="red"><b>The /proc Interface and Shared Interrupts</b></font><br>
14853 <br>
14854 Installing shared handlers in the system doesn't affect <i>/proc/stat</i>, which doesn't even
14855 know about handlers. However, <i>/proc/interrupts</i> changes slightly.<br>
14856 <br>
14857 <A name="281"></a><font color="blue">PAGE 281</font><br>
14858 <br>
14859 All the handlers installed for the same interrupt number appear on the same line of
14860 <i>/proc/interrupts</i>. The following output (from an x86_64 system) shows how shared
14861 interrupt handlers are displayed:<br>
14862 <pre>
14863 CPU0
14864 0: 892335412 XT-PIC timer
14865 1: 453971 XT-PIC i8042
14866 2: 0 XT-PIC cascade
14867 5: 0 XT-PIC libata, ehci_hcd
14868 8: 0 XT-PIC rtc
14869 9: 0 XT-PIC acpi
14870 10: 11365067 XT-PIC ide2, uhci_hcd, uhci_hcd, SysKonnect SK-98xx, EMU10K1
14871 11: 4391962 XT-PIC uhci_hcd, uhci_hcd
14872 12: 224 XT-PIC i8042
14873 14: 2787721 XT-PIC ide0
14874 15: 203048 XT-PIC ide1
14875 NMI: 41234
14876 LOC: 892193503
14877 ERR: 102
14878 MIS: 0
14879 </pre>
14880 This system has several shared interrupt lines. IRQ 5 is used for the serial ATA and
14881 IEEE 1394 controllers; IRQ 10 has several devices, including an IDE controller, two
14882 USB controllers, an Ethernet interface, and a sound card; and IRQ 11 also is used by
14883 two USB controllers.<br>
14884 <br>
14885 <a name="InterruptDrivenIO"></a><font color="red"><b>Interrupt-Driven I/O</b></font><br>
14886 <br>
14887 Whenever a data transfer to or from the managed hardware might be delayed for any
14888 reason, the driver writer should implement buffering. Data buffers help to detach
14889 data transmission and reception from the <i>write </i>and <i>read </i>system calls, and overall system
14890 performance benefits.<br>
14891 <br>
14892 A good buffering mechanism leads to <i>interrupt-driven I/O</i>, in which an input buffer is
14893 filled at interrupt time and is emptied by processes that read the device; an output
14894 buffer is filled by processes that write to the device and is emptied at interrupt time.
14895 An example of interrupt-driven output is the implementation of <i>/dev/shortprint</i>.<br>
14896 <br>
14897 For interrupt-driven data transfer to happen successfully, the hardware should be
14898 able to generate interrupts with the following semantics:<br>
14899 <ul>
14900 <li> For input, the device interrupts the processor when new data has arrived and is
14901 ready to be retrieved by the system processor. The actual actions to perform
14902 depend on whether the device uses I/O ports, memory mapping, or DMA.
14903 <li> For output, the device delivers an interrupt either when it is ready to accept new
14904 data or to acknowledge a successful data transfer. Memory-mapped and DMA capable
14905 devices usually generate interrupts to tell the system they are done with
14906 the buffer.
14907 </ul>
14908 <A name="282"></a><font color="blue">PAGE 282</font><br>
14909 <br>
14910 The timing relationships between a <i>read </i>or <i>write </i>and the actual arrival of data were
14911 introduced in the section "Blocking and Nonblocking Operations" in Chapter 6.<br>
14912 <br>
14913 <a name="AWriteBufferingExample"></a><font color="red"><b>A Write-Buffering Example</b></font><br>
14914 <br>
14915 We have mentioned the <i>shortprint </i>driver a couple of times; now it is time to actually
14916 take a look. This module implements a very simple, output-oriented driver for the
14917 parallel port; it is sufficient, however, to enable the printing of files. If you chose to
14918 test this driver out, however, remember that you must pass the printer a file in a format
14919 it understands; not all printers respond well when given a stream of arbitrary
14920 data.<br>
14921 <br>
14922 The <i>shortprint </i>driver maintains a one-page circular output buffer. When a user-space
14923 process writes data to the device, that data is fed into the buffer, but the <i>write
14924 </i>method does not actually perform any I/O. Instead, the core of <i>shortp_write </i>looks
14925 like this:<br>
14926 <pre>
14927 while (written < count) {
14928 /* Hang out until some buffer space is available. */
14929 space = shortp_out_space( );
14930 if (space <= 0) {
14931 if (wait_event_interruptible(shortp_out_queue,
14932 (space = shortp_out_space( )) > 0))
14933 goto out;
14934 }
14936 /* Move data into the buffer. */
14937 if ((space + written) > count)
14938 space = count - written;
14939 if (copy_from_user((char *) shortp_out_head, buf, space)) {
14940 up(&shortp_out_sem);
14941 return -EFAULT;
14942 }
14943 shortp_incr_out_bp(&shortp_out_head, space);
14944 buf += space;
14945 written += space;
14947 /* If no output is active, make it active. */
14948 spin_lock_irqsave(&shortp_out_lock, flags);
14949 if (! shortp_output_active)
14950 shortp_start_output( );
14951 spin_unlock_irqrestore(&shortp_out_lock, flags);
14952 }
14954 out:
14955 *f_pos += written;
14956 </pre>
14957 A semaphore (<font class="fixd">shortp_out_sem</font>) controls access to the circular buffer; <i>shortp_write
14958 </i>obtains that semaphore just prior to the code fragment above. While holding the semaphore,
14959 it attempts to feed data into the circular buffer. The function <i>shortp_out_space
14960 </i>returns the amount of contiguous space available (so there is no need to worry about<br>
14961 <br>
14962 <A name="283"></a><font color="blue">PAGE 283</font><br>
14963 <br>
14964 buffer wraps); if that amount is 0, the driver waits until some space is freed. It then
14965 copies as much data as it can into the buffer.<br>
14966 <br>
14967 Once there is data to output, <i>shortp_write </i>must ensure that the data is written to the
14968 device. The actual writing is done by way of a <i>workqueue </i>function; <i>shortp_write
14969 </i>must kick that function off if it is not already running. After obtaining a separate
14970 spinlock that controls access to variables used on the consumer side of the output
14971 buffer (including <font class="fixd">shortp_output_active</font>), it calls <i>shortp_start_output </i>if need be. Then
14972 it's just a matter of noting how much data was "written" to the buffer and returning.<br>
14973 <br>
14974 The function that starts the output process looks like the following:<br>
14975 <pre>
14976 static void shortp_start_output(void)
14977 {
14978 if (shortp_output_active) /* Should never happen */
14979 return;
14981 /* Set up our 'missed interrupt' timer */
14982 shortp_output_active = 1;
14983 shortp_timer.expires = jiffies + TIMEOUT;
14984 add_timer(&shortp_timer);
14986 /* And get the process going. */
14987 queue_work(shortp_workqueue, &shortp_work);
14988 }
14989 </pre>
14990 The reality of dealing with hardware is that you can, occasionally, lose an interrupt
14991 from the device. When this happens, you really do not want your driver to stop forevermore
14992 until the system is rebooted; that is not a user-friendly way of doing things.
14993 It is far better to realize that an interrupt has been missed, pickup the pieces, and go
14994 on. To that end, <i>shortprint </i>sets a kernel timer whenever it outputs data to the device.
14995 If the timer expires, we may have missed an interrupt. We look at the timer function
14996 shortly, but, for the moment, let's stick with the main output functionality. That is
14997 implemented in our <i>workqueue </i>function, which, as you can see above, is scheduled
14998 here. The core of that function looks like the following:<br>
14999 <pre>
15000 spin_lock_irqsave(&shortp_out_lock, flags);
15002 /* Have we written everything? */
15003 if (shortp_out_head = = shortp_out_tail) { /* empty */
15004 shortp_output_active = 0;
15005 wake_up_interruptible(&shortp_empty_queue);
15006 del_timer(&shortp_timer);
15007 }
15008 /* Nope, write another byte */
15009 else
15010 shortp_do_write( );
15012 /* If somebody's waiting, maybe wake them up. */
15014 if (((PAGE_SIZE + <font class="fixd">shortp_out_tail</font> -shortp_out_head) % PAGE_SIZE) > SP_MIN_SPACE)
15016 {
15017 </pre>
15018 <A name="284"></a><font color="blue">PAGE 284</font><br>
15019 <pre>
15020 wake_up_interruptible(&shortp_out_queue);
15021 }
15022 spin_unlock_irqrestore(&shortp_out_lock, flags);
15023 </pre>
15024 Since we are dealing with the output side's shared variables, we must obtain the
15025 spinlock. Then we look to see whether there is any more data to send out; if not, we
15026 note that output is no longer active, delete the timer, and wake up anybody who
15027 might have been waiting for the queue to become completely empty (this sort of wait
15028 is done when the device is closed). If, instead, there remains data to write, we call
15029 <i>shortp_do_write</i> to actually send a byte to the hardware.<br>
15030 <br>
15031 Then, since we may have freed space in the output buffer, we consider waking up
15032 any processes waiting to add more data to that buffer. We do not perform that
15033 wakeup unconditionally, however; instead, we wait until a minimum amount of
15034 space is available. There is no point in awakening a writer every time we take one
15035 byte out of the buffer; the cost of awakening the process, scheduling it to run, and
15036 putting it back to sleep is too high for that. Instead, we should wait until that process
15037 is able to move a substantial amount of data into the buffer at once. This technique
15038 is common in buffering, interrupt-driven drivers.<br>
15039 <br>
15040 For completeness, here is the code that actually writes the data to the port:<br>
15041 <pre>
15042 static void shortp_do_write(void)
15043 {
15044 unsigned char cr = inb(shortp_base + SP_CONTROL);
15046 /* Something happened; reset the timer */
15047 mod_timer(&shortp_timer, jiffies + TIMEOUT);
15049 /* Strobe a byte out to the device */
15050 outb_p(*shortp_out_tail, shortp_base+SP_DATA);
15051 shortp_incr_out_bp(&shortp_out_tail, 1);
15052 if (shortp_delay)
15053 udelay(shortp_delay);
15054 outb_p(cr | SP_CR_STROBE, shortp_base+SP_CONTROL);
15055 if (shortp_delay)
15056 udelay(shortp_delay);
15057 outb_p(cr & ~SP_CR_STROBE, shortp_base+SP_CONTROL);
15058 }
15059 </pre>
15060 Here, we reset the timer to reflect the fact that we have made some progress, strobe
15061 the byte out to the device, and update the circular buffer pointer.<br>
15062 <br>
15063 The <i>workqueue </i>function does not resubmit itself directly, so only a single byte will be
15064 written to the device. At some point, the printer will, in its slow way, consume the
15065 byte and become ready for the next one; it will then interrupt the processor. The
15066 interrupt handler used in <i>shortprint</i> is short and simple:<br>
15067 <pre>
15068 static irqreturn_t shortp_interrupt(int irq, void *dev_id, struct pt_regs *regs)
15069 {
15070 if (! shortp_output_active)
15071 return IRQ_NONE;
15072 </pre>
15073 <A name="285"></a><font color="blue">PAGE 285</font><br>
15074 <pre>
15075 /* Remember the time, and farm off the rest to the workqueue function */
15076 do_gettimeofday(&shortp_tv);
15077 queue_work(shortp_workqueue, &shortp_work);
15078 return IRQ_HANDLED;
15079 }
15080 </pre>
15081 Since the parallel port does not require an explicit interrupt acknowledgment, all the
15082 interrupt handler really needs to do is to tell the kernel to run the <i>workqueue </i>function
15083 again.<br>
15084 <br>
15085 What if the interrupt never comes? The driver code that we have seen thus far would
15086 simply come to a halt. To keep that from happening, we set a timer back a few pages
15087 ago. The function that is executed when that timer expires is:<br>
15088 <pre>
15089 static void shortp_timeout(unsigned long unused)
15090 {
15091 unsigned long flags;
15092 unsigned char status;
15094 if (! shortp_output_active)
15095 return;
15096 spin_lock_irqsave(&shortp_out_lock, flags);
15097 status = inb(shortp_base + SP_STATUS);
15099 /* If the printer is still busy we just reset the timer */
15100 if ((status & SP_SR_BUSY) = = 0 || (status & SP_SR_ACK)) {
15101 shortp_timer.expires = jiffies + TIMEOUT;
15102 add_timer(&shortp_timer);
15103 spin_unlock_irqrestore(&shortp_out_lock, flags);
15104 return;
15105 }
15107 /* Otherwise we must have dropped an interrupt. */
15108 spin_unlock_irqrestore(&shortp_out_lock, flags);
15109 shortp_interrupt(shortp_irq, NULL, NULL);
15110 }
15111 </pre>
15112 If no output is supposed to be active, the timer function simply returns; this keeps
15113 the timer from resubmitting itself when things are being shut down. Then, after taking
15114 the lock, we query the status of the port; if it claims to be busy, it simply hasn't
15115 gotten around to interrupting us yet, so we reset the timer and return. Printers can, at
15116 times, take a very long time to make themselves ready; consider the printer that runs
15117 out of paper while everybody is gone over a long weekend. In such situations, there
15118 is nothing to do other than to wait patiently until something changes.<br>
15119 <br>
15120 If, however, the printer claims to be ready, we must have missed its interrupt. In that
15121 case, we simply invoke our interrupt handler manually to get the output process
15122 moving again.<br>
15123 <br>
15124 The <i>shortprint </i>driver does not support reading from the port; instead, it behaves like
15125 <i>shortint </i>and returns interrupt timing information. The implementation of an interrupt-driven
15126 <i>read </i>method would be very similar to what we have seen, however. Data<br>
15127 <br>
15128 <A name="286"></a><font color="blue">PAGE 286</font><br>
15129 <br>
15130 from the device would be read into a driver buffer; it would be copied out to user
15131 space only when a significant amount of data has accumulated in the buffer, the full
15132 <i>read</i> request has been satisfied, or some sort of timeout occurs.<br>
15133 <br>
15134 <a name="QuickReference10"></a><font color="red"><b>Quick Reference</b></font><br>
15135 <br>
15136 These symbols related to interrupt management were introduced in this chapter:<br>
15137 <br>
15138 <font class="fixd">#include <linux/interrupt.h><br>
15139 int request_irq(unsigned int irq, irqreturn_t (*handler)( ), unsigned long flags, const char *dev_name, void *dev_id);<br>
15140 void free_irq(unsigned int irq, void *dev_id);</font><br>
15141 <br>
15142 Calls that register and unregister an interrupt handler.<br>
15143 <br>
15144 <font class="fixd">#include <linux/irq.h.h><br>
15145 int can_request_irq(unsigned int irq, unsigned long flags);</font><br>
15146 <br>
15147 This function, available on the i386 and x86_64 architectures, returns a nonzero
15148 value if an attempt to allocate the given interrupt line succeeds.<br>
15149 <br>
15150 <font class="fixd">#include <asm/signal.h><br>
15151 SA_INTERRUPT<br>
15152 SA_SHIRQ<br>
15153 SA_SAMPLE_RANDOM</font><br>
15154 <br>
15155 Flags for <i>request_irq</i>. <font class="fixd">SA_INTERRUPT</font> requests installation of a fast handler (as
15156 opposed to a slow one). <font class="fixd">SA_SHIRQ</font> installs a shared handler, and the third flag
15157 asserts that interrupt timestamps can be used to generate system entropy.<br>
15158 <br>
15159 <font class="fixd">/proc/interrupts<br>
15160 /proc/stat</font><br>
15161 <br>
15162 Filesystem nodes that report information about hardware interrupts and
15163 installed handlers.<br>
15164 <br>
15165 <font class="fixd">unsigned long probe_irq_on(void);<br>
15166 int probe_irq_off(unsigned long);</font><br>
15167 <br>
15168 Functions used by the driver when it has to probe to determine which interrupt
15169 line is being used by a device. The result of <i>probe_irq_on </i>must be passed back to
15170 <i>probe_irq_off </i>after the interrupt has been generated. The return value of <i>probe_
15171 irq_off</i> is the detected interrupt number.<br>
15172 <br>
15173 <font class="fixd">IRQ_NONE<br>
15174 IRQ_HANDLED<br>
15175 IRQ_RETVAL(int x)</font><br>
15176 <br>
15177 The possible return values from an interrupt handler, indicating whether an
15178 actual interrupt from the device was present.<br>
15179 <br>
15180 <A name="287"></a><font color="blue">PAGE 287</font><br>
15181 <br>
15182 <font class="fixd">void disable_irq(int irq);<br>
15183 void disable_irq_nosync(int irq);<br>
15184 void enable_irq(int irq);</font><br>
15185 <br>
15186 A driver can enable and disable interrupt reporting. If the hardware tries to generate
15187 an interrupt while interrupts are disabled, the interrupt is lost forever. A
15188 driver using a shared handler must not use these functions.<br>
15189 <br>
15190 <font class="fixd">void local_irq_save(unsigned long flags);<br>
15191 void local_irq_restore(unsigned long flags);</font><br>
15192 <br>
15193 Use <i>local_irq_save </i>to disable interrupts on the local processor and remember
15194 their previous state. The <font class="fixd">flags</font> can be passed to <i>local_irq_restore </i>to restore the
15195 previous interrupt state.<br>
15196 <br>
15197 <font class="fixd">void local_irq_disable(void);<br>
15198 void local_irq_enable(void);</font><br>
15199 <br>
15200 Functions that unconditionally disable and enable interrupts on the current
15201 processor.<br>
15202 <br>
15203 <A name="288"></a><font color="blue">PAGE 288</font><br>
15204 <br>
15205 <a name="CHAPTER11"></a><font color="red"><b>CHAPTER 11</b></font><br>
15206 <br>
15207 <a name="DataTypesInThebrKernel"></a><font color="#7519FF" size="+1"><b>Data Types in the Kernel</b></font><br>
15208 <br>
15209 Before we go on to more advanced topics, we need to stop for a quick note on portability
15210 issues. Modern versions of the Linux kernel are highly portable, running on
15211 numerous different architectures. Given the multiplatform nature of Linux, drivers
15212 intended for serious use should be portable as well.<br>
15213 <br>
15214 But a core issue with kernel code is being able both to access data items of known
15215 length (for example, filesystem data structures or registers on device boards) and to
15216 exploit the capabilities of different processors (32-bit and 64-bit architectures, and
15217 possibly 16 bit as well).<br>
15218 <br>
15219 Several of the problems encountered by kernel developers while porting x86 code to
15220 new architectures have been related to incorrect data typing. Adherence to strict data
15221 typing and compiling with the <i>-Wall -Wstrict-prototypes</i> flags can prevent most bugs.<br>
15222 <br>
15223 Data types used by kernel data are divided into three main classes: standard C types
15224 such as int, explicitly sized types such as <font class="fixd">u32,</font> and types used for specific kernel
15225 objects, such as <font class="fixd">pid_t</font>. We are going to see when and how each of the three typing
15226 classes should be used. The final sections of the chapter talk about some other typical
15227 problems you might run into when porting driver code from the x86 to other
15228 platforms, and introduce the generalized support for linked lists exported by recent
15229 kernel headers.<br>
15230 <br>
15231 If you follow the guidelines we provide, your driver should compile and run even on
15232 platforms on which you are unable to test it.<br>
15233 <br>
15234 <a name="UseOfStandardCTypes"></a><font color="red"><b>Use of Standard C Types</b></font><br>
15235 <br>
15236 Although most programmers are accustomed to freely using standard types like <font class="fixd">int</font>
15237 and <font class="fixd">long,</font> writing device drivers requires some care to avoid typing conflicts and
15238 obscure bugs.<br>
15239 <br>
15240 The problem is that you can't use the standard types when you need "a 2-byte filler"
15241 or "something representing a 4-byte string," because the normal C data types are not<br>
15242 <br>
15243 <A name="289"></a><font color="blue">PAGE 289</font><br>
15244 <br>
15245 the same size on all architectures. To show the data size of the various C types, the
15246 <i>datasize </i>program has been included in the sample files provided on O'Reilly's FTP
15247 site in the directory <i>misc-progs</i>. This is a sample run of the program on an i386 system
15248 (the last four types shown are introduced in the next section):<br>
15249 <pre>
15250 morgana% misc-progs/datasize
15251 arch Size: char short int long ptr long-long u8 u16 u32 u64
15252 i686 1 2 4 4 4 8 1 2 4 8
15253 </pre>
15254 The program can be used to show that <font class="fixd">long</font> integers and pointers feature a different
15255 size on 64-bit platforms, as demonstrated by running the program on different Linux
15256 computers:<br>
15257 <pre>
15258 arch Size: char short int long ptr long-long u8 u16 u32 u64
15259 i386 1 2 4 4 4 8 1 2 4 8
15260 alpha 1 2 4 8 8 8 1 2 4 8
15261 armv4l 1 2 4 4 4 8 1 2 4 8
15262 ia64 1 2 4 8 8 8 1 2 4 8
15263 m68k 1 2 4 4 4 8 1 2 4 8
15264 mips 1 2 4 4 4 8 1 2 4 8
15265 ppc 1 2 4 4 4 8 1 2 4 8
15266 sparc 1 2 4 4 4 8 1 2 4 8
15267 sparc64 1 2 4 4 4 8 1 2 4 8
15268 x86_64 1 2 4 8 8 8 1 2 4 8
15269 </pre>
15270 It's interesting to note that the SPARC 64 architecture runs with a 32-bit user space,
15271 so pointers are 32 bits wide there, even though they are 64 bits wide in kernel space.
15272 This can be verified by loading the <i>kdatasize </i>module (available in the directory <i>miscmodules
15273 </i>within the sample files). The module reports size information at load time
15274 using <i>printk</i> and returns an error (so there's no need to unload it):<br>
15275 <pre>
15276 kernel: arch Size: char short int long ptr long-long u8 u16 u32 u64
15277 kernel: sparc64 1 2 4 8 8 8 1 2 4 8
15278 </pre>
15279 Although you must be careful when mixing different data types, sometimes there are
15280 good reasons to do so. One such situation is for memory addresses, which are special
15281 as far as the kernel is concerned. Although, conceptually, addresses are pointers,
15282 memory administration is often better accomplished by using an unsigned integer
15283 type; the kernel treats physical memory like a huge array, and a memory address is
15284 just an index into the array. Furthermore, a pointer is easily dereferenced; when dealing
15285 directly with memory addresses, you almost never want to dereference them in
15286 this manner. Using an integer type prevents this dereferencing, thus avoiding bugs.
15287 Therefore, generic memory addresses in the kernel are usually <font class="fixd">unsigned long</font>, exploiting
15288 the fact that pointers and long integers are always the same size, at least on all the
15289 platforms currently supported by Linux.<br>
15290 <br>
15291 For what it's worth, the C99 standard defines the <font class="fixd">intptr_t</font> and <font class="fixd">uintptr_t</font> types for
15292 an integer variable that can hold a pointer value. These types are almost unused in
15293 the 2.6 kernel, however.<br>
15294 <br>
15295 <A name="290"></a><font color="blue">PAGE 290</font><br>
15296 <br>
15297 <a name="AssigningAnExplicitSizeToDataItems"></a><font color="red"><b>Assigning an Explicit Size to Data Items</b></font><br>
15298 <br>
15299 Sometimes kernel code requires data items of a specific size, perhaps to match predefined
15300 binary structures,* to communicate with user space, or to align data within
15301 structures by inserting "padding" fields (but refer to the section "Data Alignment"
15302 for information about alignment issues).<br>
15303 <br>
15304 The kernel offers the following data types to use whenever you need to know the size
15305 of your data. All the types are declared in <i><asm/types.h></i>, which, in turn, is included
15306 by <i><linux/types.h></i>:<br>
15307 <pre>
15308 u8; /* unsigned byte (8 bits) */
15309 u16; /* unsigned word (16 bits) */
15310 u32; /* unsigned 32-bit value */
15311 u64; /* unsigned 64-bit value */
15312 </pre>
15313 The corresponding signed types exist, but are rarely needed; just replace <font class="fixd">u</font> with <font class="fixd">s</font> in
15314 the name if you need them.<br>
15315 <br>
15316 If a user-space program needs to use these types, it can prefix the names with a double
15317 underscore: <font class="fixd">__u8</font> and the other types are defined independent of <font class="fixd">__KERNEL__</font>. If,
15318 for example, a driver needs to exchange binary structures with a program running in
15319 user space by means of <i>ioctl</i>, the header files should declare 32-bit fields in the structures
15320 as <font class="fixd">__u32.</font><br>
15321 <br>
15322 It's important to remember that these types are Linux specific, and using them hinders
15323 porting software to other Unix flavors. Systems with recent compilers support
15324 the C99-standard types, such as <font class="fixd">uint8_t</font> and <font class="fixd">uint32_t;</font> if portability is a concern,
15325 those types can be used in favor of the Linux-specific variety.<br>
15326 <br>
15327 You might also note that sometimes the kernel uses conventional types, such as
15328 <font class="fixd">unsigned int</font>, for items whose dimension is architecture independent. This is usually
15329 done for backward compatibility. When <font class="fixd">u32</font> and friends were introduced in Version
15330 1.1.67, the developers couldn't change existing data structures to the new types
15331 because the compiler issues a warning when there is a type mismatch between the
15332 structure field and the value being assigned to it.† Linus didn't expect the operating
15333 system (OS) he wrote for his own use to become multiplatform; as a result, old structures
15334 are sometimes loosely typed.<br>
15335 <br>
15336 * This happens when reading partition tables, when executing a binary file, or when decoding a network packet.<br>
15337 <br>
15338 † As a matter of fact, the compiler signals type inconsistencies even if the two types are just different
15339 names for the same object, such as <font class="fixd">unsigned long</font> and <font class="fixd">u32</font> on the PC.<br>
15340 <br>
15341 <A name="291"></a><font color="blue">PAGE 291</font><br>
15342 <br>
15343 <a name="InterfaceSpecificTypes"></a><font color="red"><b>Interface-Specific Types</b></font><br>
15344 <br>
15345 Some of the commonly used data types in the kernel have their own <font class="fixd">typedef</font> statements,
15346 thus preventing any portability problems. For example, a process identifier
15347 (pid) is usually <font class="fixd">pid_t</font> instead of <font class="fixd">int.</font> Using <font class="fixd">pid_t</font> masks any possible difference in the
15348 actual data typing. We use the expression <i>interface-specific </i>to refer to a type defined
15349 by a library in order to provide an interface to a specific data structure.<br>
15350 <br>
15351 Note that, in recent times, relatively few new interface-specific types have been
15352 defined. Use of the <font class="fixd">typedef</font> statement has gone out of favor among many kernel
15353 developers, who would rather see the real type information used directly in the code,
15354 rather than hidden behind a user-defined type. Many older interface-specific types
15355 remain in the kernel, however, and they will not be going away anytime soon.<br>
15356 <br>
15357 Even when no interface-specific type is defined, it's always important to use the
15358 proper data type in a way consistent with the rest of the kernel. A jiffy count, for
15359 instance, is always <font class="fixd">unsigned long</font>, independent of its actual size, so the <font class="fixd">unsigned long</font>
15360 type should always be used when working with jiffies. In this section we concentrate
15361 on use of <font class="fixd">_t</font> types.<br>
15362 <br>
15363 Many <font class="fixd">_t</font> types are defined in <i><linux/types.h></i>, but the list is rarely useful. When you
15364 need a specific type, you'll find it in the prototype of the functions you need to call or
15365 in the data structures you use.<br>
15366 <br>
15367 Whenever your driver uses functions that require such "custom" types and you don't
15368 follow the convention, the compiler issues a warning; if you use the <i>-Wall </i>compiler
15369 flag and are careful to remove all the warnings, you can feel confident that your code
15370 is portable.<br>
15371 <br>
15372 The main problem with <font class="fixd">_t</font> data items is that when you need to print them, it's not
15373 always easy to choose the right <i>printk </i>or <i>printf </i>format, and warnings you resolve on
15374 one architecture reappear on another. For example, how would you print a <font class="fixd">size_t,</font>
15375 that is <font class="fixd">unsigned long</font> on some platforms and <font class="fixd">unsigned int</font> on some others?<br>
15376 <br>
15377 Whenever you need to print some interface-specific data, the best way to do it is by
15378 casting the value to the biggest possible type (usually <font class="fixd">long</font> or <font class="fixd">unsigned long</font>) and then
15379 printing it through the corresponding format. This kind of tweaking won't generate
15380 errors or warnings because the format matches the type, and you won't lose data bits
15381 because the cast is either a null operation or an extension of the item to a bigger data
15382 type.<br>
15383 <br>
15384 In practice, the data items we're talking about aren't usually meant to be printed, so
15385 the issue applies only to debugging messages. Most often, the code needs only to
15386 store and compare the interface-specific types, in addition to passing them as arguments
15387 to library or kernel functions.<br>
15388 <br>
15389 Although <font class="fixd">_t</font> types are the correct solution for most situations, sometimes the right type
15390 doesn't exist. This happens for some old interfaces that haven't yet been cleaned up.<br>
15391 <br>
15392 <A name="292"></a><font color="blue">PAGE 292</font><br>
15393 <br>
15394 The one ambiguous point we've found in the kernel headers is data typing for I/O
15395 functions, which is loosely defined (see the section "Platform Dependencies" in
15396 Chapter 9). The loose typing is mainly there for historical reasons, but it can create
15397 problems when writing code. For example, one can get into trouble by swapping the
15398 arguments to functions like <i>outb</i>; if there were a <font class="fixd">port_t</font> type, the compiler would find
15399 this type of error.<br>
15400 <br>
15401 <a name="OtherPortabilityIssues"></a><font color="red"><b>Other Portability Issues</b></font><br>
15402 <br>
15403 In addition to data typing, there are a few other software issues to keep in mind
15404 when writing a driver if you want it to be portable across Linux platforms.<br>
15405 <br>
15406 A general rule is to be suspicious of explicit constant values. Usually the code has
15407 been parameterized using preprocessor macros. This section lists the most important
15408 portability problems. Whenever you encounter other values that have been
15409 parameterized, you can find hints in the header files and in the device drivers distributed
15410 with the official kernel.<br>
15411 <br>
15412 <a name="TimeIntervals"></a><font color="red"><b>Time Intervals</b></font><br>
15413 <br>
15414 When dealing with time intervals, don't assume that there are 1000 jiffies per second.
15415 Although this is currently true for the i386 architecture, not every Linux platform
15416 runs at this speed. The assumption can be false even for the x86 if you play
15417 with the <font class="fixd">HZ</font> value (as some people do), and nobody knows what will happen in future
15418 kernels. Whenever you calculate time intervals using jiffies</font>, scale your times using <font class="fixd">HZ</font>
15419 (the number of timer interrupts per second). For example, to check against a timeout
15420 of half a second, compare the elapsed time against <font class="fixd">HZ/2.</font> More generally, the
15421 number of <font class="fixd">jiffies</font> corresponding to <font class="fixd">msec</font> milliseconds is always <font class="fixd">msec*HZ/1000.</font><br>
15422 <br>
15423 <a name="PageSize"></a><font color="red"><b>Page Size</b></font><br>
15424 <br>
15425 When playing games with memory, remember that a memory page is <font class="fixd">PAGE_SIZE</font>
15426 bytes, not 4 KB. Assuming that the page size is 4 KB and hard-coding the value is a
15427 common error among PC programmers, instead, supported platforms show page
15428 sizes from 4 KB to 64 KB, and sometimes they differ between different implementations
15429 of the same platform. The relevant macros are <font class="fixd">PAGE_SIZE</font> and <font class="fixd">PAGE_SHIFT</font>. The
15430 latter contains the number of bits to shift an address to get its page number. The
15431 number currently is 12 or greater for pages that are 4 KB and larger. The macros are
15432 defined in <i><asm/page.h></i>; user-space programs can use the <i>getpagesize </i>library function
15433 if they ever need the information.<br>
15434 <br>
15435 <A name="293"></a><font color="blue">PAGE 293</font><br>
15436 <br>
15437 Let's look at a nontrivial situation. If a driver needs 16 KB for temporary data, it
15438 shouldn't specify an order of 2 to <i>get_free_pages</i>. You need a portable solution. Such a
15439 solution, fortunately, has been written by the kernel developers and is called <i>get_order</i>:<br>
15440 <pre>
15441 #include <asm/page.h>
15442 int order = get_order(16*1024);
15443 buf = get_free_pages(GFP_KERNEL, order);
15444 </pre>
15445 Remember that the argument to <i>get_order</i> must be a power of two.<br>
15446 <br>
15447 <a name="ByteOrder"></a><font color="red"><b>Byte Order</b></font><br>
15448 <br>
15449 Be careful not to make assumptions about byte ordering. Whereas the PC stores
15450 multibyte values low-byte first (little end first, thus little-endian), some high-level
15451 platforms work the other way (big-endian). Whenever possible, your code should be
15452 written such that it does not care about byte ordering in the data it manipulates.
15453 However, sometimes a driver needs to build an integer number out of single bytes or
15454 do the opposite, or it must communicate with a device that expects a specific order.<br>
15455 <br>
15456 The include file <i><asm/byteorder.h> </i>defines either <font class="fixd">__BIG_ENDIAN</font> or <font class="fixd">__LITTLE_ENDIAN,</font>
15457 depending on the processor's byte ordering. When dealing with byte ordering issues,
15458 you could code a bunch of <font class="fixd">#ifdef __LITTLE_ENDIAN</font> conditionals, but there is a better
15459 way. The Linux kernel defines a set of macros that handle conversions between
15460 the processor's byte ordering and that of the data you need to store or load in a specific
15461 byte order. For example:<br>
15462 <pre>
15463 u32 cpu_to_le32 (u32);
15464 u32 le32_to_cpu (u32);
15465 </pre>
15466 These two macros convert a value from whatever the CPU uses to an unsigned, littleendian,
15467 32-bit quantity and back. They work whether your CPU is big-endian or little-endian
15468 and, for that matter, whether it is a 32-bit processor or not. They return
15469 their argument unchanged in cases where there is no work to be done. Use of these
15470 macros makes it easy to write portable code without having to use a lot of conditional
15471 compilation constructs.<br>
15472 <br>
15473 There are dozens of similar routines; you can see the full list in <i><linux/byteorder/
15474 <font class="fixd">big_endian</font>.h> </i>and <i><linux/byteorder/little_endian.h></i>. After a while, the pattern is
15475 not hard to follow. <i>be64_to_cpu </i>converts an unsigned, big-endian, 64-bit value to
15476 the internal CPU representation. <i>le16_to_cpus</i>, instead, handles signed, littleendian,
15477 16-bit quantities. When dealing with pointers, you can also use functions
15478 like <i>cpu_to_le32p</i>, which take a pointer to the value to be converted rather than the
15479 value itself. See the include file for the rest.<br>
15480 <br>
15481 <a name="DataAlignment"></a><font color="red"><b>Data Alignment</b></font><br>
15482 <br>
15483 The last problem worth considering when writing portable code is how to access
15484 unaligned data--for example, how to read a 4-byte value stored at an address that<br>
15485 <br>
15486 <A name="294"></a><font color="blue">PAGE 294</font><br>
15487 <br>
15488 isn't a multiple of 4 bytes. i386 users often access unaligned data items, but not all
15489 architectures permit it. Many modern architectures generate an exception every time
15490 the program tries unaligned data transfers; data transfer is handled by the exception
15491 handler, with a great performance penalty. If you need to access unaligned data, you
15492 should use the following macros:<br>
15493 <pre>
15494 #include <asm/unaligned.h>
15495 get_unaligned(ptr);
15496 put_unaligned(val, ptr);
15497 </pre>
15498 These macros are typeless and work for every data item, whether it's one, two, four,
15499 or eight bytes long. They are defined with any kernel version.<br>
15500 <br>
15501 Another issue related to alignment is portability of data structures across platforms.
15502 The same data structure (as defined in the C-language source file) can be compiled
15503 differently on different platforms. The compiler arranges structure fields to be
15504 aligned according to conventions that differ from platform to platform.<br>
15505 <br>
15506 In order to write data structures for data items that can be moved across architectures,
15507 you should always enforce natural alignment of the data items in addition to
15508 standardizing on a specific endianness. <i>Natural alignment </i>means storing data items
15509 at an address that is a multiple of their size (for instance, 8-byte items go in an
15510 address multiple of 8). To enforce natural alignment while preventing the compiler
15511 to arrange the fields in unpredictable ways, you should use filler fields that avoid
15512 leaving holes in the data structure.<br>
15513 <br>
15514 To show how alignment is enforced by the compiler, the <i>dataalign </i>program is distributed
15515 in the <i>misc-progs </i>directory of the sample code, and an equivalent <i>kdataalign
15516 </i>module is part of <i>misc-modules</i>. This is the output of the program on several platforms
15517 and the output of the module on the SPARC64:<br>
15518 <pre>
15519 arch Align: char short int long ptr long-long u8 u16 u32 u64
15520 i386 1 2 4 4 4 4 1 2 4 4
15521 i686 1 2 4 4 4 4 1 2 4 4
15522 alpha 1 2 4 8 8 8 1 2 4 8
15523 armv4l 1 2 4 4 4 4 1 2 4 4
15524 ia64 1 2 4 8 8 8 1 2 4 8
15525 mips 1 2 4 4 4 8 1 2 4 8
15526 ppc 1 2 4 4 4 8 1 2 4 8
15527 sparc 1 2 4 4 4 8 1 2 4 8
15528 sparc64 1 2 4 4 4 8 1 2 4 8
15529 x86_64 1 2 4 8 8 8 1 2 4 8
15531 kernel: arch Align: char short int long ptr long-long u8 u16 u32 u64
15532 kernel: sparc64 1 2 4 8 8 8 1 2 4 8
15533 </pre>
15534 It's interesting to note that not all platforms align 64-bit values on 64-bit boundaries,
15535 so you need filler fields to enforce alignment and ensure portability.<br>
15536 <br>
15537 Finally, be aware that the compiler may quietly insert padding into structures itself to
15538 ensure that every field is aligned for good performance on the target processor. If you<br>
15539 <br>
15540 <A name="295"></a><font color="blue">PAGE 295</font><br>
15541 <br>
15542 are defining a structure that is intended to match a structure expected by a device,
15543 this automatic padding may thwart your attempt. The way around this problem is to
15544 tell the compiler that the structure must be "packed," with no fillers added. For
15545 example, the kernel header file <i><linux/edd.h> </i>defines several data structures used in
15546 interfacing with the x86 BIOS, and it includes the following definition:<br>
15547 <pre>
15548 struct {
15549 u16 id;
15550 u64 lun;
15551 u16 reserved1;
15552 u32 reserved2;
15553 } __attribute__ ((packed)) scsi;
15554 </pre>
15555 Without the <font class="fixd">__attribute__ ((packed)),</font> the <font class="fixd">lun</font> field would be preceded by two filler
15556 bytes or six if we compile the structure on a 64-bit platform.<br>
15557 <br>
15558 <a name="PointersAndErrorValues"></a><font color="red"><b>Pointers and Error Values</b></font><br>
15559 <br>
15560 Many internal kernel functions return a pointer value to the caller. Many of those
15561 functions can also fail. In most cases, failure is indicated by returning a <font class="fixd">NULL</font> pointer
15562 value. This technique works, but it is unable to communicate the exact nature of the
15563 problem. Some interfaces really need to return an actual error code so that the caller
15564 can make the right decision based on what actually went wrong.<br>
15565 <br>
15566 A number of kernel interfaces return this information by encoding the error code in a
15567 pointer value. Such functions must be used with care, since their return value cannot
15568 simply be compared against <font class="fixd">NULL</font>. To help in the creation and use of this sort of interface,
15569 a small set of functions has been made available (in <i><linux/err.h></i>).<br>
15570 <br>
15571 A function returning a pointer type can return an error value with:<br>
15572 <pre>
15573 void *ERR_PTR(long error);
15574 </pre>
15575 where <font class="fixd">error</font> is the usual negative error code. The caller can use <i><font class="fixd">IS_ERR</font> </i>to test
15576 whether a returned pointer is an error code or not:<br>
15577 <pre>
15578 long IS_ERR(const void *ptr);
15579 </pre>
15580 If you need the actual error code, it can be extracted with:<br>
15581 <pre>
15582 long PTR_ERR(const void *ptr);
15583 </pre>
15584 You should use <i><font class="fixd">PTR_ERR</font> </i>only on a value for which <i><font class="fixd">IS_ERR</font> </i>returns a true value;
15585 any other value is a valid pointer.<br>
15586 <br>
15587 <a name="LinkedLists"></a><font color="red"><b>Linked Lists</b></font><br>
15588 <br>
15589 Operating system kernels, like many other programs, often need to maintain lists of
15590 data structures. The Linux kernel has, at times, been host to several linked list implementations
15591 at the same time. To reduce the amount of duplicated code, the kernel<br>
15592 <br>
15593 <A name="296"></a><font color="blue">PAGE 296</font><br>
15594 <br>
15595 developers have created a standard implementation of circular, doubly linked lists;
15596 others needing to manipulate lists are encouraged to use this facility.<br>
15597 <br>
15598 When working with the linked list interface, you should always bear in mind that the
15599 list functions perform no locking. If there is a possibility that your driver could
15600 attempt to perform concurrent operations on the same list, it is your responsibility to
15601 implement a locking scheme. The alternatives (corrupted list structures, data loss,
15602 kernel panics) tend to be difficult to diagnose.<br>
15603 <br>
15604 To use the list mechanism, your driver must include the file <i><linux/list.h></i>. This file
15605 defines a simple structure of type list_head:<br>
15606 <pre>
15607 struct list_head {
15608 struct list_head *next, *prev;
15609 };
15610 </pre>
15611 Linked lists used in real code are almost invariably made up of some type of structure,
15612 each one describing one entry in the list. To use the Linux list facility in your
15613 code, you need only embed a <font class="fixd">list_head</font> inside the structures that make up the list. If
15614 your driver maintains a list of things to do, say, its declaration would look something
15615 like this:<br>
15616 <pre>
15617 struct todo_struct {
15618 struct list_head list;
15619 int priority; /* driver specific */
15620 /* ... add other driver-specific fields */
15621 };
15622 </pre>
15623 The head of the list is usually a stand alone <font class="fixd">list_head</font> structure. Figure 11-1 shows
15624 how the simple struct <font class="fixd">list_head</font> is used to maintain a list of data structures.<br>
15625 <br><br>
15626 <center>
15627 <img src="fig11-1.gif">
15628 </center>
15629 <br>
15630 <i>Figure 11-1. The <font class="fixd">list_head</font> data structure</i><br>
15631 <br>
15632 <A name="297"></a><font color="blue">PAGE 297</font><br>
15633 <br>
15634 List heads must be initialized prior to use with the <font class="fixd">INIT_LIST_HEAD</font> macro. A "things
15635 to do" list head could be declared and initialized with:<br>
15636 <pre>
15637 struct <font class="fixd">list_head</font> todo_list;
15639 INIT_LIST_HEAD(&todo_list);
15640 </pre>
15641 Alternatively, lists can be initialized at compile time:<br>
15642 <pre>
15643 LIST_HEAD(todo_list);
15644 </pre>
15645 Several functions are defined in <i><linux/list.h></i> that work with lists:<br>
15646 <br>
15647 <font class="fixd">list_add(struct list_head *new, struct list_head *head);</font><br>
15648 <div class="bq">
15649 Adds the <font class="fixd">new</font> entry immediately after the list head--normally at the beginning of
15650 the list. Therefore, it can be used to build stacks. Note, however, that the head
15651 need not be the nominal head of the list; if you pass a <font class="fixd">list_head</font> structure that
15652 happens to be in the middle of the list somewhere, the new entry goes immediately
15653 after it. Since Linux lists are circular, the head of the list is not generally different
15654 from any other entry.</div>
15655 <br>
15656 <font class="fixd">list_add_tail(struct list_head *new, struct list_head *head);</font><br>
15657 <div class="bq">
15658 Adds a new entry just before the given list head--at the end of the list, in other
15659 words. <i>list_add_tail</i> can, thus, be used to build first-in first-out queues.</div>
15660 <br>
15661 <font class="fixd">list_del(struct list_head *entry);<br>
15662 list_del_init(struct list_head *entry);</font><br>
15663 <div class="bq">
15664 The given entry is removed from the list. If the entry might ever be reinserted
15665 into another list, you should use <i>list_del_init</i>, which reinitializes the linked list
15666 pointers.</div>
15667 <br>
15668 <font class="fixd">list_move(struct list_head *entry, struct list_head *head);<br>
15669 list_move_tail(struct list_head *entry, struct list_head *head);</font><br>
15670 <div class="bq">
15671 The given entry is removed from its current list and added to the beginning of
15672 <font class="fixd">head.</font> To put the entry at the end of the new list, use <i>list_move_tail</i> instead.</div>
15673 <br>
15674 <font class="fixd">list_empty(struct list_head *head);</font><br>
15675 <div class="bq">
15676 Returns a nonzero value if the given list is empty.</div>
15677 <br>
15678 <font class="fixd">list_splice(struct list_head *list, struct list_head *head);</font><br>
15679 <div class="bq">
15680 Joins two lists by inserting list immediately after <font class="fixd">head.</font></div>
15681 <br>
15682 The <font class="fixd">list_head</font> structures are good for implementing a list of like structures, but the
15683 invoking program is usually more interested in the larger structures that make up the
15684 list as a whole. A macro, <i>list_entry</i>, is provided that maps a <font class="fixd">list_head</font> structure
15685 pointer back into a pointer to the structure that contains it. It is invoked as follows:<br>
15686 <pre>
15687 list_entry(struct list_head *ptr, type_of_struct, field_name);
15688 </pre>
15689 where <font class="fixd">ptr</font> is a pointer to the struct <font class="fixd">list_head</font> being used, <font class="fixd">type_of_struct</font> is the type
15690 of the structure containing the <font class="fixd">ptr</font>, and <font class="fixd">field_name</font> is the name of the list field within<br>
15691 <br>
15692 <A name="298"></a><font color="blue">PAGE 298</font><br>
15693 <br>
15694 the structure. In our <font class="fixd">todo_struct</font> structure from before, the list field is called simply
15695 <font class="fixd">list.</font> Thus, we would turn a list entry into its containing structure with a line such as:<br>
15696 <pre>
15697 struct todo_struct *todo_ptr =
15698 list_entry(listptr, struct todo_struct, list);
15699 </pre>
15700 The <i>list_entry</i> macro takes a little getting used to but is not that hard to use.<br>
15701 <br>
15702 The traversal of linked lists is easy: one need only follow the <font class="fixd">prev</font> and <font class="fixd">next</font> pointers.
15703 As an example, suppose we want to keep the list of <font class="fixd">todo_struct</font> items sorted in
15704 descending priority order. A function to add a new entry would look something like
15705 this:<br>
15706 <pre>
15707 void todo_add_entry(struct todo_struct *new)
15708 {
15709 struct list_head *ptr;
15710 struct todo_struct *entry;
15712 for (ptr = todo_list.next; ptr != &todo_list; ptr = ptr->next) {
15713 entry = list_entry(ptr, struct todo_struct, list);
15714 if (entry->priority < new->priority) {
15715 list_add_tail(&new->list, ptr);
15716 return;
15717 }
15718 }
15719 list_add_tail(&new->list, &todo_struct)
15720 }
15721 </pre>
15722 However, as a general rule, it is better to use one of a set of predefined macros for
15723 creating loops that iterate through lists. The previous loop, for example, could be
15724 coded as:<br>
15725 <pre>
15726 void todo_add_entry(struct todo_struct *new)
15727 {
15728 struct list_head *ptr;
15729 struct todo_struct *entry;
15731 list_for_each(ptr, &todo_list) {
15732 entry = list_entry(ptr, struct todo_struct, list);
15733 if (entry->priority < new->priority) {
15734 list_add_tail(&new->list, ptr);
15735 return;
15736 }
15737 }
15738 list_add_tail(&new->list, &todo_struct)
15739 }
15740 </pre>
15741 <A name="299"></a><font color="blue">PAGE 299</font><br>
15742 <br>
15743 Using the provided macros helps avoid simple programming errors; the developers of
15744 these macros have also put some effort into ensuring that they perform well. A few
15745 variants exist:<br>
15746 <br>
15747 <font class="fixd">list_for_each(struct list_head *cursor, struct list_head *list)</font><br>
15748 <div class="bq">
15749 This macro creates a for loop that executes once with <font class="fixd">cursor</font> pointing at each
15750 successive entry in the list. Be careful about changing the list while iterating
15751 through it.</div>
15752 <br>
15753 <font class="fixd">list_for_each_prev(struct list_head *cursor, struct list_head *list)</font><br>
15754 <div class="bq">
15755 This version iterates backward through the list.</div>
15756 <br>
15757 <font class="fixd">list_for_each_safe(struct list_head *cursor, struct list_head *next, struct list_head *list)</font><br>
15758 <div class="bq">
15759 If your loop may delete entries in the list, use this version. It simply stores the
15760 next entry in the list in <font class="fixd">next</font> at the beginning of the loop, so it does not get confused
15761 if the entry pointed to by <font class="fixd">cursor</font> is deleted.</div>
15762 <br>
15763 <font class="fixd">list_for_each_entry(type *cursor, struct list_head *list, member)<br>
15764 list_for_each_entry_safe(type *cursor, type *next, struct list_head *list, member)</font><br>
15765 <div class="bq">
15766 These macros ease the process of dealing with a list containing a given <font class="fixd">type</font> of
15767 structure. Here, <font class="fixd">cursor</font> is a pointer to the containing structure type, and <font class="fixd">member</font>
15768 is the name of the <font class="fixd">list_head</font> structure within the containing structure. With
15769 these macros, there is no need to put <font class="fixd">list_entry</font> calls inside the loop.</div>
15770 <br>
15771 If you look inside <i><linux/list.h></i>, you see some additional declarations. The <font class="fixd">hlist</font>
15772 type is a doubly linked list with a separate, single-pointer list head type; it is often
15773 used for creation of hash tables and similar structures. There are also macros for iterating
15774 through both types of lists that are intended to work with the read-copy-update
15775 mechanism (described in the section "Read-Copy-Update" in Chapter 5). These
15776 primitives are unlikely to be useful in device drivers; see the header file if you would
15777 like more information on how they work.<br>
15778 <br>
15779 <a name="QuickReference11"></a><font color="red"><b>Quick Reference</b></font><br>
15780 <br>
15781 The following symbols were introduced in this chapter:<br>
15782 <br>
15783 <font class="fixd">#include <linux/types.h><br>
15784 typedef u8;<br>
15785 typedef u16;<br>
15786 typedef u32;<br>
15787 typedef u64;</font><br>
15788 <div class="bq">
15789 Types guaranteed to be 8-, 16-, 32-, and 64-bit unsigned integer values. The
15790 equivalent signed types exist as well. In user space, you can refer to the types
15791 as <font class="fixd">__u8, __u16,</font> and so forth.</div>
15792 <br>
15793 <A name="300"></a><font color="blue">PAGE 300</font><br>
15794 <br>
15795 <font class="fixd">#include <asm/page.h><br>
15796 PAGE_SIZE<br>
15797 PAGE_SHIFT</font><br>
15798 <div class="bq">
15799 Symbols that define the number of bytes per page for the current architecture
15800 and the number of bits in the page offset (12 for 4-KB pages and 13 for 8-KB
15801 pages).</div>
15802 <br>
15803 <font class="fixd">#include <asm/byteorder.h><br>
15804 __LITTLE_ENDIAN<br>
15805 __BIG_ENDIAN</font><br>
15806 <div class="bq">
15807 Only one of the two symbols is defined, depending on the architecture.</div>
15808 <br>
15809 <font class="fixd">#include <asm/byteorder.h><br>
15810 u32 __cpu_to_le32 (u32);<br>
15811 u32 __le32_to_cpu (u32);</font><br>
15812 <div class="bq">
15813 Functions that convert between known byte orders and that of the processor.
15814 There are more than 60 such functions; see the various files in <i>include/linux/
15815 byteorder/</i> for a full list and the ways in which they are defined.</div>
15816 <br>
15817 <font class="fixd">#include <asm/unaligned.h><br>
15818 get_unaligned(ptr);<br>
15819 put_unaligned(val, ptr);</font><br>
15820 <div class="bq">
15821 Some architectures need to protect unaligned data access using these macros.
15822 The macros expand to normal pointer dereferencing for architectures that permit
15823 you to access unaligned data.</div>
15824 <br>
15825 <font class="fixd">#include <linux/err.h><br>
15826 void *ERR_PTR(long error);<br>
15827 long PTR_ERR(const void *ptr);<br>
15828 long IS_ERR(const void *ptr);</font><br>
15829 <div class="bq">
15830 Functions allow error codes to be returned by functions that return a pointer
15831 value.</div>
15832 <br>
15833 <font class="fixd">#include <linux/list.h><br>
15834 list_add(struct list_head *new, struct list_head *head);<br>
15835 list_add_tail(struct list_head *new, struct list_head *head);<br>
15836 list_del(struct list_head *entry);<br>
15837 list_del_init(struct list_head *entry);<br>
15838 list_empty(struct list_head *head);<br>
15839 list_entry(entry, type, member);<br>
15840 list_move(struct list_head *entry, struct list_head *head);<br>
15841 list_move_tail(struct list_head *entry, struct list_head *head);<br>
15842 list_splice(struct list_head *list, struct list_head *head);</font><br>
15843 <div class="bq">
15844 Functions that manipulate circular, doubly linked lists.</div>
15845 <br>
15846 <A name="301"></a><font color="blue">PAGE 301</font><br>
15847 <br>
15848 <font class="fixd">list_for_each(struct list_head *cursor, struct list_head *list)<br>
15849 list_for_each_prev(struct list_head *cursor, struct list_head *list)<br>
15850 list_for_each_safe(struct list_head *cursor, struct list_head *next, struct list_head *list)<br>
15851 list_for_each_entry(type *cursor, struct list_head *list, member)<br>
15852 list_for_each_entry_safe(type *cursor, type *next struct list_head *list, member)</font><br>
15853 <div class="bq">
15854 Convenience macros for iterating through linked lists.</div>
15855 <br>
15856 <A name="302"></a><font color="blue">PAGE 302</font><br>
15857 <br>
15858 <a name="CHAPTER12"></a><font color="red"><b>CHAPTER 12</b></font><br>
15859 <br>
15860 <a name="PCIDrivers"></a><font color="#7519FF" size="+1"><b>PCI Drivers</b></font><br>
15861 <br>
15862 While Chapter 9 introduced the lowest levels of hardware control, this chapter provides
15863 an overview of the higher-level bus architectures. A bus is made up of both an
15864 electrical interface and a programming interface. In this chapter, we deal with the
15865 programming interface.<br>
15866 <br>
15867 This chapter covers a number of bus architectures. However, the primary focus is on
15868 the kernel functions that access Peripheral Component Interconnect (PCI) peripherals,
15869 because these days the PCI bus is the most commonly used peripheral bus on
15870 desktops and bigger computers. The bus is the one that is best supported by the kernel.
15871 ISA is still common for electronic hobbyists and is described later, although it is
15872 pretty much a bare-metal kind of bus, and there isn't much to say in addition to
15873 what is covered in Chapters 9 and 10.<br>
15874 <br>
15875 <a name="ThePCIInterface"></a><font color="red"><b>The PCI Interface</b></font><br>
15876 <br>
15877 Although many computer users think of PCI as a way of laying out electrical wires, it
15878 is actually a complete set of specifications defining how different parts of a computer
15879 should interact.<br>
15880 <br>
15881 The PCI specification covers most issues related to computer interfaces. We are not
15882 going to cover it all here; in this section, we are mainly concerned with how a PCI
15883 driver can find its hardware and gain access to it. The probing techniques discussed
15884 in the sections "Module Parameters" in Chapter 2 and "Auto-Detecting the IRQ
15885 Number" in Chapter 10 can be used with PCI devices, but the specification offers an
15886 alternative that is preferable to probing.<br>
15887 <br>
15888 The PCI architecture was designed as a replacement for the ISA standard, with three
15889 main goals: to get better performance when transferring data between the computer
15890 and its peripherals, to be as platform independent as possible, and to simplify adding
15891 and removing peripherals to the system.<br>
15892 <br>
15893 <A name="303"></a><font color="blue">PAGE 303</font><br>
15894 <br>
15895 The PCI bus achieves better performance by using a higher clock rate than ISA; its
15896 clock runs at 25 or 33 MHz (its actual rate being a factor of the system clock), and
15897 66-MHz and even 133-MHz implementations have recently been deployed as well.
15898 Moreover, it is equipped with a 32-bit data bus, and a 64-bit extension has been
15899 included in the specification. Platform independence is often a goal in the design of a
15900 computer bus, and it's an especially important feature of PCI, because the PC world
15901 has always been dominated by processor-specific interface standards. PCI is currently
15902 used extensively on IA-32, Alpha, PowerPC, SPARC64, and IA-64 systems,
15903 and some other platforms as well.<br>
15904 <br>
15905 What is most relevant to the driver writer, however, is PCI's support for auto-detection
15906 of interface boards. PCI devices are jumperless (unlike most older peripherals)
15907 and are automatically configured at boot time. Then, the device driver must be able
15908 to access configuration information in the device in order to complete initialization.
15909 This happens without the need to perform any probing.<br>
15910 <br>
15911 <a name="PCIAddressing"></a><font color="red"><b>PCI Addressing</b></font><br>
15912 <br>
15913 Each PCI peripheral is identified by a <i>bus </i>number, a <i>device </i>number, and a <i>function
15914 </i>number. The PCI specification permits a single system to host up to 256 buses, but
15915 because 256 buses are not sufficient for many large systems, Linux now supports PCI
15916 <i>domains</i>. Each PCI domain can host up to 256 buses. Each bus hosts up to 32
15917 devices, and each device can be a multifunction board (such as an audio device with
15918 an accompanying CD-ROM drive) with a maximum of eight functions. Therefore,
15919 each function can be identified at hardware level by a 16-bit address, or key. Device
15920 drivers written for Linux, though, don't need to deal with those binary addresses,
15921 because they use a specific data structure, called <font class="fixd">pci_dev,</font> to act on the devices.<br>
15922 <br>
15923 Most recent workstations feature at least two PCI buses. Plugging more than one bus
15924 in a single system is accomplished by means of <i>bridges</i>, special-purpose PCI peripherals
15925 whose task is joining two buses. The overall layout of a PCI system is a tree where
15926 each bus is connected to an upper-layer bus, up to bus 0 at the root of the tree. The
15927 CardBus PC-card system is also connected to the PCI system via bridges. A typical
15928 PCI system is represented in Figure 12-1, where the various bridges are highlighted.<br>
15929 <br>
15930 The 16-bit hardware addresses associated with PCI peripherals, although mostly hidden
15931 in the <font class="fixd">struct pci_dev</font> object, are still visible occasionally, especially when lists of
15932 devices are being used. One such situation is the output of <i>lspci </i>(part of the <i>pciutils
15933 </i>package, available with most distributions) and the layout of information in <i>/proc/pci
15934 </i>and <i>/proc/bus/pci</i>. The sysfs representation of PCI devices also shows this addressing
15935 scheme, with the addition of the PCI domain information.* When the hardware
15936 address is displayed, it can be shown as two values (an 8-bit bus number and an 8-bit<br>
15937 <br>
15938 * Some architectures also display the PCI domain information in the <i>/proc/pci</i> and <i>/proc/bus/pci</i> files.<br>
15939 <br>
15940 <A name="304"></a><font color="blue">PAGE 304</font><br>
15941 <br>
15942 <center>
15943 <img src="fig12-1.gif">
15944 </center>
15945 <br>
15946 <i>Figure 12-1. Layout of a typical PCI system</i><br>
15947 <br>
15948 device and function number), as three values (bus, device, and function), or as four
15949 values (domain, bus, device, and function); all the values are usually displayed in
15950 hexadecimal.<br>
15951 <br>
15952 For example, <i>/proc/bus/pci/devices </i>uses a single 16-bit field (to ease parsing and sorting),
15953 while <i>/proc/bus/busnumber </i>splits the address into three fields. The following
15954 shows how those addresses appear, showing only the beginning of the output lines:<br>
15955 <pre>
15956 $ <b>lspci | cut -d: -f1-3
15957 </b>0000:00:00.0 Host bridge
15958 0000:00:00.1 RAM memory
15959 0000:00:00.2 RAM memory
15960 0000:00:02.0 USB Controller
15961 0000:00:04.0 Multimedia audio controller
15962 0000:00:06.0 Bridge
15963 0000:00:07.0 ISA bridge
15964 0000:00:09.0 USB Controller
15965 0000:00:09.1 USB Controller
15966 0000:00:09.2 USB Controller
15967 0000:00:0c.0 CardBus bridge
15968 0000:00:0f.0 IDE interface
15969 0000:00:10.0 Ethernet controller
15970 0000:00:12.0 Network controller
15971 0000:00:13.0 FireWire (IEEE 1394)
15972 0000:00:14.0 VGA compatible controller
15973 $ <b>cat /proc/bus/pci/devices | cut -f1
15974 </b>0000
15975 0001
15976 0002
15977 0010
15978 0020
15979 0030
15980 </pre>
15981 <A name="305"></a><font color="blue">PAGE 305</font><br>
15982 <pre>
15983 0038
15984 0048
15985 0049
15986 004a
15987 0060
15988 0078
15989 0080
15990 0090
15991 0098
15992 00a0
15993 $ <b>tree /sys/bus/pci/devices/
15994 </b>/sys/bus/pci/devices/
15995 |-- 0000:00:00.0 -> ../../../devices/pci0000:00/0000:00:00.0
15996 |-- 0000:00:00.1 -> ../../../devices/pci0000:00/0000:00:00.1
15997 |-- 0000:00:00.2 -> ../../../devices/pci0000:00/0000:00:00.2
15998 |-- 0000:00:02.0 -> ../../../devices/pci0000:00/0000:00:02.0
15999 |-- 0000:00:04.0 -> ../../../devices/pci0000:00/0000:00:04.0
16000 |-- 0000:00:06.0 -> ../../../devices/pci0000:00/0000:00:06.0
16001 |-- 0000:00:07.0 -> ../../../devices/pci0000:00/0000:00:07.0
16002 |-- 0000:00:09.0 -> ../../../devices/pci0000:00/0000:00:09.0
16003 |-- 0000:00:09.1 -> ../../../devices/pci0000:00/0000:00:09.1
16004 |-- 0000:00:09.2 -> ../../../devices/pci0000:00/0000:00:09.2
16005 |-- 0000:00:0c.0 -> ../../../devices/pci0000:00/0000:00:0c.0
16006 |-- 0000:00:0f.0 -> ../../../devices/pci0000:00/0000:00:0f.0
16007 |-- 0000:00:10.0 -> ../../../devices/pci0000:00/0000:00:10.0
16008 |-- 0000:00:12.0 -> ../../../devices/pci0000:00/0000:00:12.0
16009 |-- 0000:00:13.0 -> ../../../devices/pci0000:00/0000:00:13.0
16010 `-- 0000:00:14.0 -> ../../../devices/pci0000:00/0000:00:14.0
16011 </pre>
16012 All three lists of devices are sorted in the same order, since <i>lspci </i>uses the <i>/proc </i>files as
16013 its source of information. Taking the VGA video controller as an example, <font class="fixd">0x00a0</font>
16014 means <font class="fixd">0000:00:14.0</font> when split into domain (16 bits), bus (8 bits), device (5 bits) and
16015 function (3 bits).<br>
16016 <br>
16017 The hardware circuitry of each peripheral board answers queries pertaining to three
16018 address spaces: memory locations, I/O ports, and configuration registers. The first
16019 two address spaces are shared by all the devices on the same PCI bus (i.e., when you
16020 access a memory location, all the devices on that PCI bus see the bus cycle at the
16021 same time). The configuration space, on the other hand, exploits <i>geographical
16022 addressing</i>. Configuration queries address only one slot at a time, so they never collide.<br>
16023 <br>
16024 As far as the driver is concerned, memory and I/O regions are accessed in the usual
16025 ways via <i>inb</i>, <i>readb</i>, and so forth. Configuration transactions, on the other hand, are
16026 performed by calling specific kernel functions to access configuration registers. With
16027 regard to interrupts, every PCI slot has four interrupt pins, and each device function
16028 can use one of them without being concerned about how those pins are routed to the
16029 CPU. Such routing is the responsibility of the computer platform and is implemented
16030 outside of the PCI bus. Since the PCI specification requires interrupt lines to
16031 be shareable, even a processor with a limited number of IRQ lines, such as the x86,
16032 can host many PCI interface boards (each with four interrupt pins).<br>
16033 <br>
16034 <A name="306"></a><font color="blue">PAGE 306</font><br>
16035 <br>
16036 The I/O space in a PCI bus uses a 32-bit address bus (leading to 4 GB of I/O ports),
16037 while the memory space can be accessed with either 32-bit or 64-bit addresses. 64-bit
16038 addresses are available on more recent platforms. Addresses are supposed to be
16039 unique to one device, but software may erroneously configure two devices to the
16040 same address, making it impossible to access either one. But this problem never
16041 occurs unless a driver is willingly playing with registers it shouldn't touch. The good
16042 news is that every memory and I/O address region offered by the interface board can
16043 be remapped by means of configuration transactions. That is, the firmware initializes
16044 PCI hardware at system boot, mapping each region to a different address to
16045 avoid collisions.* The addresses to which these regions are currently mapped can be
16046 read from the configuration space, so the Linux driver can access its devices without
16047 probing. After reading the configuration registers, the driver can safely access its
16048 hardware.<br>
16049 <br>
16050 The PCI configuration space consists of 256 bytes for each device function (except
16051 for PCI Express devices, which have 4 KB of configuration space for each function),
16052 and the layout of the configuration registers is standardized. Four bytes of the configuration
16053 space hold a unique function ID, so the driver can identify its device by looking
16054 for the specific ID for that peripheral.† In summary, each device board is
16055 geographically addressed to retrieve its configuration registers; the information in
16056 those registers can then be used to perform normal I/O access, without the need for
16057 further geographic addressing.<br>
16058 <br>
16059 It should be clear from this description that the main innovation of the PCI interface
16060 standard over ISA is the configuration address space. Therefore, in addition to the
16061 usual driver code, a PCI driver needs the ability to access the configuration space, in
16062 order to save itself from risky probing tasks.<br>
16063 <br>
16064 For the remainder of this chapter, we use the word <i>device </i>to refer to a device function,
16065 because each function in a multifunction board acts as an independent entity.
16066 When we refer to a device, we mean the tuple "domain number, bus number, device
16067 number, and function number."<br>
16068 <br>
16069 <a name="BootTime"></a><font color="red"><b>Boot Time</b></font><br>
16070 <br>
16071 To see how PCI works, we start from system boot, since that's when the devices are
16072 configured.<br>
16073 <br>
16074 * Actually, that configuration is not restricted to the time the system boots; hotpluggable devices, for example,
16075 cannot be available at boot time and appear later instead. The main point here is that the device driver must
16076 not change the address of I/O or memory regions.<br>
16077 <br>
16078 † You'll find the ID of any device in its own hardware manual. A list is included in the file <i>pci.ids</i>, part
16079 of the<i>pciutils </i>package and the kernel sources; it doesn't pretend to be complete but just lists the most renowned
16080 vendors and devices. The kernel version of this file will not be included in future kernel series.<br>
16081 <br>
16082 <A name="307"></a><font color="blue">PAGE 307</font><br>
16083 <br>
16084 When power is applied to a PCI device, the hardware remains inactive. In other
16085 words, the device responds only to configuration transactions. At power on, the
16086 device has no memory and no I/O ports mapped in the computer's address space;
16087 every other device-specific feature, such as interrupt reporting, is disabled as well.<br>
16088 <br>
16089 Fortunately, every PCI motherboard is equipped with PCI-aware firmware, called the
16090 BIOS, NVRAM, or PROM, depending on the platform. The firmware offers access to
16091 the device configuration address space by reading and writing registers in the PCI
16092 controller.<br>
16093 <br>
16094 At system boot, the firmware (or the Linux kernel, if so configured) performs configuration
16095 transactions with every PCI peripheral in order to allocate a safe place for
16096 each address region it offers. By the time a device driver accesses the device, its memory
16097 and I/O regions have already been mapped into the processor's address space.
16098 The driver can change this default assignment, but it never needs to do that.<br>
16099 <br>
16100 As suggested, the user can look at the PCI device list and the devices' configuration
16101 registers by reading <i>/proc/bus/pci/devices </i>and <i>/proc/bus/pci/*/*</i>. The former is a text file
16102 with (hexadecimal) device information, and the latter are binary files that report a
16103 snapshot of the configuration registers of each device, one file per device. The individual
16104 PCI device directories in the sysfs tree can be found in <i>/sys/bus/pci/devices</i>. A
16105 PCI device directory contains a number of different files:<br>
16106 <pre>
16107 $ <b>tree /sys/bus/pci/devices/0000:00:10.0
16108 </b>/sys/bus/pci/devices/0000:00:10.0
16109 |-- class
16110 |-- config
16111 |-- detach_state
16112 |-- device
16113 |-- irq
16114 |-- power
16115 | `-- state
16116 |-- resource
16117 |-- subsystem_device
16118 |-- subsystem_vendor
16119 `-- vendor
16120 </pre>
16121 The file <i>config </i>is a binary file that allows the raw PCI config information to be read
16122 from the device (just like the <i>/proc/bus/pci/*/* </i>provides.) The files <i>vendor</i>, <i>device</i>,
16123 <i>subsystem_device</i>, <i>subsystem_vendor</i>, and <i>class </i>all refer to the specific values of this
16124 PCI device (all PCI devices provide this information.) The file <i>irq </i>shows the current
16125 IRQ assigned to this PCI device, and the file <i>resource </i>shows the current memory
16126 resources allocated by this device.<br>
16127 <br>
16128 <A name="308"></a><font color="blue">PAGE 308</font><br>
16129 <br>
16130 <a name="ConfigurationRegistersAndInitialization"></a><font color="red"><b>Configuration Registers and Initialization</b></font><br>
16131 <br>
16132 In this section, we look at the configuration registers that PCI devices contain. All
16133 PCI devices feature at least a 256-byte address space. The first 64 bytes are standardized,
16134 while the rest are device dependent. Figure 12-2 shows the layout of the device-independent
16135 configuration space.<br>
16136 <br><br>
16137 <center>
16138 <img src="fig12-2.gif">
16139 </center>
16140 <br>
16141 <i>Figure 12-2. The standardized PCI configuration registers</i><br>
16142 <br>
16143 As the figure shows, some of the PCI configuration registers are required and some
16144 are optional. Every PCI device must contain meaningful values in the required registers,
16145 whereas the contents of the optional registers depend on the actual capabilities
16146 of the peripheral. The optional fields are not used unless the contents of the required
16147 fields indicate that they are valid. Thus, the required fields assert the board's capabilities,
16148 including whether the other fields are usable.<br>
16149 <br>
16150 It's interesting to note that the PCI registers are always little-endian. Although the
16151 standard is designed to be architecture independent, the PCI designers sometimes
16152 show a slight bias toward the PC environment. The driver writer should be careful
16153 about byte ordering when accessing multibyte configuration registers; code that
16154 works on the PC might not work on other platforms. The Linux developers have
16155 taken care of the byte-ordering problem (see the next section, "Accessing the Configuration
16156 Space"), but the issue must be kept in mind. If you ever need to convert data
16157 from host order to PCI order or vice versa, you can resort to the functions defined in
16158 <i><asm/byteorder.h></i>, introduced in Chapter 11, knowing that PCI byte order is little-endian.<br>
16159 <br>
16160 <A name="309"></a><font color="blue">PAGE 309</font><br>
16161 <br>
16162 Describing all the configuration items is beyond the scope of this book. Usually, the
16163 technical documentation released with each device describes the supported registers.
16164 What we're interested in is how a driver can look for its device and how it can access
16165 the device's configuration space.<br>
16166 <br>
16167 Three or five PCI registers identify a device: <font class="fixd">vendorID, deviceID,</font> and <font class="fixd">class</font> are the
16168 three that are always used. Every PCI manufacturer assigns proper values to these
16169 read-only registers, and the driver can use them to look for the device. Additionally,
16170 the fields <font class="fixd">subsystem vendorID</font> and <font class="fixd">subsystem deviceID</font> are sometimes set by the vendor
16171 to further differentiate similar devices.<br>
16172 <br>
16173 Let's look at these registers in more detail:<br>
16174 <br>
16175 <font class="fixd">vendorID</font><br>
16176 <div class="bq">
16177 This 16-bit register identifies a hardware manufacturer. For instance, every Intel
16178 device is marked with the same vendor number, <font class="fixd">0x8086.</font> There is a global registry
16179 of such numbers, maintained by the PCI Special Interest Group, and manufacturers
16180 must apply to have a unique number assigned to them.</div>
16181 <br>
16182 <font class="fixd">deviceID</font><br>
16183 <div class="bq">
16184 This is another 16-bit register, selected by the manufacturer; no official registration
16185 is required for the device ID. This ID is usually paired with the vendor ID to
16186 make a unique 32-bit identifier for a hardware device. We use the word <i>signature
16187 </i>to refer to the vendor and device ID pair. A device driver usually relies on
16188 the signature to identify its device; you can find what value to look for in the
16189 hardware manual for the target device.</div>
16190 <br>
16191 <font class="fixd">class</font><br>
16192 <div class="bq">
16193 Every peripheral device belongs to a <i>class</i>. The <font class="fixd">class</font> register is a 16-bit value
16194 whose top 8 bits identify the "base class" (or <i>group</i>). For example, "ethernet"
16195 and "token ring" are two classes belonging to the "network" group, while the
16196 "serial" and "parallel" classes belong to the "communication" group. Some drivers
16197 can support several similar devices, each of them featuring a different signature
16198 but all belonging to the same class; these drivers can rely on the <font class="fixd">class</font>
16199 register to identify their peripherals, as shown later.</div>
16200 <br>
16201 <font class="fixd">subsystem vendorID<br>
16202 subsystem deviceID</font><br>
16203 <div class="bq">
16204 These fields can be used for further identification of a device. If the chip is a
16205 generic interface chip to a local (onboard) bus, it is often used in several completely
16206 different roles, and the driver must identify the actual device it is talking
16207 with. The subsystem identifiers are used to this end.</div>
16208 <br>
16209 Using these different identifiers, a PCI driver can tell the kernel what kind of devices it
16210 supports. The struct <font class="fixd">pci_device_id</font> structure is used to define a list of the different<br>
16211 <br>
16212 <A name="310"></a><font color="blue">PAGE 310</font><br>
16213 <br>
16214 types of PCI devices that a driver supports. This structure contains the following
16215 fields:<br>
16216 <br>
16217 <font class="fixd">__u32 vendor;<br>
16218 __u32 device;</font><br>
16219 <div class="bq">
16220 These specify the PCI vendor and device IDs of a device. If a driver can handle
16221 any vendor or device ID, the value <font class="fixd">PCI_ANY_ID</font> should be used for these fields.</div>
16222 <br>
16223 <font class="fixd">__u32 subvendor;<br>
16224 __u32 subdevice;</font><br>
16225 <div class="bq">
16226 These specify the PCI subsystem vendor and subsystem device IDs of a device. If
16227 a driver can handle any type of subsystem ID, the value <font class="fixd">PCI_ANY_ID</font> should be
16228 used for these fields.</div>
16229 <br>
16230 <font class="fixd">__u32 class;<br>
16231 __u32 class_mask;</font><br>
16232 <div class="bq">
16233 These two values allow the driver to specify that it supports a type of PCI class
16234 device. The different classes of PCI devices (a VGA controller is one example)
16235 are described in the PCI specification. If a driver can handle any type of subsystem
16236 ID, the value <font class="fixd">PCI_ANY_ID</font> should be used for these fields.</div>
16237 <br>
16238 <font class="fixd">kernel_ulong_t driver_data;</font><br>
16239 <div class="bq">
16240 This value is not used to match a device but is used to hold information that the
16241 PCI driver can use to differentiate between different devices if it wants to.</div>
16242 <br>
16243 There are two helper macros that should be used to initialize a <font class="fixd">struct pci_device_id</font>
16244 structure:<br>
16245 <br>
16246 <font class="fixd">PCI_DEVICE(vendor, device)</font><br>
16247 <div class="bq">
16248 This creates a <font class="fixd">struct pci_device_id</font> that matches only the specific vendor and
16249 device ID. The macro sets the subvendor and subdevice fields of the structure to
16250 <font class="fixd">PCI_ANY_ID</font>.</div>
16251 <br>
16252 <font class="fixd">PCI_DEVICE_CLASS(device_class, device_class_mask)</font><br>
16253 <div class="bq">
16254 This creates a <font class="fixd">struct pci_device_id</font> that matches a specific PCI class.</div>
16255 <br>
16256 An example of using these macros to define the type of devices a driver supports can
16257 be found in the following kernel files:<br>
16258 <pre>
16259 drivers/usb/host/ehci-hcd.c:
16261 static const struct pci_device_id pci_ids[ ] = { {
16262 /* handle any USB 2.0 EHCI controller */
16263 PCI_DEVICE_CLASS(((PCI_CLASS_SERIAL_USB << 8) | 0x20), ~0),
16264 .driver_data = (unsigned long) &ehci_driver,
16265 },
16266 { /* end: all zeroes */ }
16267 };
16269 drivers/i2c/busses/i2c-i810.c:
16270 </pre>
16271 <A name="311"></a><font color="blue">PAGE 311</font><br>
16272 <pre>
16273 static struct pci_device_id i810_ids[ ] = {
16274 { PCI_DEVICE(PCI_VENDOR_ID_INTEL, PCI_DEVICE_ID_INTEL_82810_IG1) },
16275 { PCI_DEVICE(PCI_VENDOR_ID_INTEL, PCI_DEVICE_ID_INTEL_82810_IG3) },
16276 { PCI_DEVICE(PCI_VENDOR_ID_INTEL, PCI_DEVICE_ID_INTEL_82810E_IG) },
16277 { PCI_DEVICE(PCI_VENDOR_ID_INTEL, PCI_DEVICE_ID_INTEL_82815_CGC) },
16278 { PCI_DEVICE(PCI_VENDOR_ID_INTEL, PCI_DEVICE_ID_INTEL_82845G_IG) },
16279 { 0, },
16280 };
16281 </pre>
16282 These examples create a list of <font class="fixd">struct pci_device_id</font> structures, with an empty structure
16283 set to all zeros as the last value in the list. This array of IDs is used in the <font class="fixd">struct pci_driver</font>
16284 (described below), and it is also used to tell user space which devices this specific driver supports.<br>
16285 <br>
16286 <a name="MODULEDEVICETABLE"></a><font color="red"><b><font class="fixd">MODULE_DEVICE_TABLE</font></b></font><br>
16287 <br>
16288 This <font class="fixd">pci_device_id</font> structure needs to be exported to user space to allow the hotplug
16289 and module loading systems know what module works with what hardware devices.
16290 The macro <font class="fixd">MODULE_DEVICE_TABLE</font> accomplishes this. An example is:<br>
16291 <pre>
16292 MODULE_DEVICE_TABLE(pci, i810_ids);
16293 </pre>
16294 This statement creates a local variable called <font class="fixd">__mod_pci_device_table</font> that points to
16295 the list of <font class="fixd">struct pci_device_id</font>. Later in the kernel build process, the <font class="fixd">depmod</font> program
16296 searches all modules for the symbol <font class="fixd">__mod_pci_device_table</font>. If that symbol is
16297 found, it pulls the data out of the module and adds it to the file <i>/lib/modules/
16298 KERNEL_VERSION/modules.pcimap</i>. After <font class="fixd">depmod</font> completes, all PCI devices that
16299 are supported by modules in the kernel are listed, along with their module names, in
16300 that file. When the kernel tells the hotplug system that a new PCI device has been
16301 found, the hotplug system uses the <i>modules.pcimap </i>file to find the proper driver to
16302 load.<br>
16303 <br>
16304 <a name="RegisteringAPCIDriver"></a><font color="red"><b>Registering a PCI Driver</b></font><br>
16305 <br>
16306 The main structure that all PCI drivers must create in order to be registered with the
16307 kernel properly is the <font class="fixd">struct pci_driver</font> structure. This structure consists of a number
16308 of function callbacks and variables that describe the PCI driver to the PCI core.
16309 Here are the fields in this structure that a PCI driver needs to be aware of:<br>
16310 <br>
16311 <font class="fixd">const char *name;</font><br>
16312 <div class="bq">
16313 The name of the driver. It must be unique among all PCI drivers in the kernel
16314 and is normally set to the same name as the module name of the driver. It shows
16315 up in sysfs under <i>/sys/bus/pci/drivers/</i> when the driver is in the kernel.</div>
16316 <br>
16317 <font class="fixd">const struct pci_device_id *id_table;</font><br>
16318 <div class="bq">
16319 Pointer to the <font class="fixd">struct pci_device_id</font> table described earlier in this chapter.</div>
16320 <br>
16321 <A name="312"></a><font color="blue">PAGE 312</font><br>
16322 <br>
16323 <font class="fixd">int (*probe) (struct pci_dev *dev, const struct pci_device_id *id);</font><br>
16324 <div class="bq">
16325 Pointer to the probe function in the PCI driver. This function is called by the PCI
16326 core when it has a <font class="fixd">struct pci_dev</font> that it thinks this driver wants to control. A
16327 pointer to the <font class="fixd">struct pci_device_id</font> that the PCI core used to make this decision
16328 is also passed to this function. If the PCI driver claims the <font class="fixd">struct pci_dev</font> that is
16329 passed to it, it should initialize the device properly and return 0. If the driver
16330 does not want to claim the device, or an error occurs, it should return a negative
16331 error value. More details about this function follow later in this chapter.</div>
16332 <br>
16333 <font class="fixd">void (*remove) (struct pci_dev *dev);</font><br>
16334 <div class="bq">
16335 Pointer to the function that the PCI core calls when the <font class="fixd">struct pci_dev</font> is being
16336 removed from the system, or when the PCI driver is being unloaded from the
16337 kernel. More details about this function follow later in this chapter.</div>
16338 <br>
16339 <font class="fixd">int (*suspend) (struct pci_dev *dev, u32 state);</font><br>
16340 <div class="bq">
16341 Pointer to the function that the PCI core calls when the <font class="fixd">struct pci_dev</font> is being
16342 suspended. The suspend state is passed in the state variable. This function is
16343 optional; a driver does not have to provide it.</div>
16344 <br>
16345 <font class="fixd">int (*resume) (struct pci_dev *dev);</font><br>
16346 <div class="bq">
16347 Pointer to the function that the PCI core calls when the <font class="fixd">struct pci_dev</font> is being
16348 resumed. It is always called after suspend has been called. This function is
16349 optional; a driver does not have to provide it.</div>
16350 <br>
16351 In summary, to create a proper <font class="fixd">struct pci_driver</font> structure, only four fields need to
16352 be initialized:<br>
16353 <pre>
16354 static struct pci_driver pci_driver = {
16355 .name = "pci_skel",
16356 .id_table = ids,
16357 .probe = probe,
16358 .remove = remove,
16359 };
16360 </pre>
16361 To register the <font class="fixd">struct pci_driver</font> with the PCI core, a call to <i>pci_register_driver </i>is
16362 made with a pointer to the <font class="fixd">struct pci_driver</font>. This is traditionally done in the module
16363 initialization code for the PCI driver:<br>
16364 <pre>
16365 static int __init pci_skel_init(void)
16366 {
16367 return pci_register_driver(&pci_driver);
16368 }
16369 </pre>
16370 Note that the <i>pci_register_driver </i>function either returns a negative error number or 0
16371 if everything was registered successfully. It does not return the number of devices
16372 that were bound to the driver or an error number if no devices were bound to the<br>
16373 <br>
16374 <A name="313"></a><font color="blue">PAGE 313</font><br>
16375 <br>
16376 driver. This is a change from kernels prior to the 2.6 release and was done because of
16377 the following situations:<br>
16378 <ul>
16379 <li> On systems that support PCI hotplug, or CardBus systems, a PCI device can
16380 appear or disappear at any point in time. It is helpful if drivers can be loaded
16381 before the device appears, to reduce the time it takes to initialize a device.
16382 <li> The 2.6 kernel allows new PCI IDs to be dynamically allocated to a driver after it
16383 has been loaded. This is done through the file <font class="fixd">new_id</font> that is created in all PCI
16384 driver directories in sysfs. This is very useful if a new device is being used that
16385 the kernel doesn't know about just yet. A user can write the PCI ID values to the
16386 <i>new_id </i>file, and then the driver binds to the new device. If a driver was not
16387 allowed to load until a device was present in the system, this interface would not
16388 be able to work.
16389 </ul>
16390 When the PCI driver is to be unloaded, the <font class="fixd">struct pci_driver</font> needs to be unregistered
16391 from the kernel. This is done with a call to <i>pci_unregister_driver</i>. When this call
16392 happens, any PCI devices that were currently bound to this driver are removed, and
16393 the <i>remove </i>function for this PCI driver is called before the <i>pci_unregister_driver </i>function
16394 returns.<br>
16395 <pre>
16396 static void __exit pci_skel_exit(void)
16397 {
16398 pci_unregister_driver(&pci_driver);
16399 }
16400 </pre>
16401 <a name="OldStylePCIProbing"></a><font color="red"><b>Old-Style PCI Probing</b></font><br>
16402 <br>
16403 In older kernel versions, the function, <i>pci_register_driver</i>, was not always used by
16404 PCI drivers. Instead, they would either walk the list of PCI devices in the system by
16405 hand, or they would call a function that could search for a specific PCI device. The
16406 ability to walk the list of PCI devices in the system within a driver has been removed
16407 from the 2.6 kernel in order to prevent drivers from crashing the kernel if they happened
16408 to modify the PCI device lists while a device was being removed at the same
16409 time.<br>
16410 <br>
16411 If the ability to find a specific PCI device is really needed, the following functions are
16412 available:<br>
16413 <br>
16414 <font class="fixd">struct pci_dev *pci_get_device(unsigned int vendor, unsigned int device, struct pci_dev *from);</font><br>
16415 <div class="bq">
16416 This function scans the list of PCI devices currently present in the system, and if
16417 the input arguments match the specified vendor and device IDs, it increments
16418 the reference count on the <font class="fixd">struct pci_dev</font> variable found, and returns it to the
16419 caller. This prevents the structure from disappearing without any notice and
16420 ensures that the kernel does not oops. After the driver is done with the <font class="fixd">struct
16421 pci_dev</font> returned by the function, it must call the function <i>pci_dev_put </i>to decrement</div>
16422 <br>
16423 <A name="314"></a><font color="blue">PAGE 314</font><br>
16424 <br>
16425 <div class="bq">the usage count properly back to allow the kernel to clean up the device if
16426 it is removed.<br>
16427 <br>
16428 The <font class="fixd">from</font> argument is used to get hold of multiple devices with the same signature;
16429 the argument should point to the last device that has been found, so that
16430 the search can continue instead of restarting from the head of the list. To find
16431 the first device, <font class="fixd">from</font> is specified as <font class="fixd">NULL</font>. If no (further) device is found, <font class="fixd">NULL</font> is
16432 returned.<br>
16433 <br>
16434 An example of how to use this function properly is:<br>
16435 <pre>
16436 struct pci_dev *dev;
16437 dev = pci_get_device(PCI_VENDOR_FOO, PCI_DEVICE_FOO, NULL);
16438 if (dev) {
16439 /* Use the PCI device */
16440 ...
16441 pci_dev_put(dev);
16442 }
16443 </pre>
16444 This function can not be called from interrupt context. If it is, a warning is
16445 printed out to the system log.</div>
16446 <br>
16447 <font class="fixd">struct pci_dev *pci_get_subsys(unsigned int vendor, unsigned int device,
16448 unsigned int ss_vendor, unsigned int ss_device, struct pci_dev *from);</font><br>
16449 <div class="bq">
16450 This function works just like <i>pci_get_device</i>, but it allows the subsystem vendor
16451 and subsystem device IDs to be specified when looking for the device.<br>
16452 <br>
16453 This function can not be called from interrupt context. If it is, a warning is
16454 printed out to the system log.</div>
16455 <br>
16456 <font class="fixd">struct pci_dev *pci_get_slot(struct pci_bus *bus, unsigned int devfn);</font><br>
16457 <div class="bq">
16458 This function searches the list of PCI devices in the system on the specified
16459 struct <font class="fixd">pci_bus</font> for the specified device and function number of the PCI device. If
16460 a device is found that matches, its reference count is incremented and a pointer
16461 to it is returned. When the caller is finished accessing the struct pci_dev, it must
16462 call <i>pci_dev_put</i>.</div>
16463 <br>
16464 All of these functions can not be called from interrupt context. If they are, a warning
16465 is printed out to the system log.<br>
16466 <br>
16467 <a name="EnablingThePCIDevice"></a><font color="red"><b>Enabling the PCI Device</b></font><br>
16468 <br>
16469 In the <i>probe </i>function for the PCI driver, before the driver can access any device resource
16470 (I/O region or interrupt) of the PCI device, the driver must call the <i>pci_enable_device
16471 </i>function:<br>
16472 <br>
16473 <font class="fixd">int pci_enable_device(struct pci_dev *dev);</font><br>
16474 <div class="bq">
16475 This function actually enables the device. It wakes up the device and in some
16476 cases also assigns its interrupt line and I/O regions. This happens, for example,
16477 with CardBus devices (which have been made completely equivalent to PCI at
16478 the driver level).</div>
16479 <br>
16480 <A name="315"></a><font color="blue">PAGE 315</font><br>
16481 <br>
16482 <a name="AccessingTheConfigurationSpace"></a><font color="red"><b>Accessing the Configuration Space</b></font><br>
16483 <br>
16484 After the driver has detected the device, it usually needs to read from or write to the
16485 three address spaces: memory, port, and configuration. In particular, accessing the
16486 configuration space is vital to the driver, because it is the only way it can find out
16487 where the device is mapped in memory and in the I/O space.<br>
16488 <br>
16489 Because the microprocessor has no way to access the configuration space directly,
16490 the computer vendor has to provide a way to do it. To access configuration space,
16491 the CPU must write and read registers in the PCI controller, but the exact implementation
16492 is vendor dependent and not relevant to this discussion, because Linux offers a
16493 standard interface to access the configuration space.<br>
16494 <br>
16495 As far as the driver is concerned, the configuration space can be accessed through 8bit,
16496 16-bit, or 32-bit data transfers. The relevant functions are prototyped in <i><linux/
16497 pci.h></i>:<br>
16498 <br>
16499 <font class="fixd">int pci_read_config_byte(struct pci_dev *dev, int where, u8 *val);<br>
16500 int pci_read_config_word(struct pci_dev *dev, int where, u16 *val);<br>
16501 int pci_read_config_dword(struct pci_dev *dev, int where, u32 *val);</font><br>
16502 <div class="bq">
16503 Read one, two, or four bytes from the configuration space of the device identified
16504 by <font class="fixd">dev.</font> The <font class="fixd">where</font> argument is the byte offset from the beginning of the configuration
16505 space. The value fetched from the configuration space is returned
16506 through the <font class="fixd">val</font> pointer, and the return value of the functions is an error code.
16507 The <i>word </i>and <i>dword </i>functions convert the value just read from little-endian to
16508 the native byte order of the processor, so you need not deal with byte ordering.</div>
16509 <br>
16510 <font class="fixd">int pci_write_config_byte(struct pci_dev *dev, int where, u8 val);<br>
16511 int pci_write_config_word(struct pci_dev *dev, int where, u16 val);<br>
16512 int pci_write_config_dword(struct pci_dev *dev, int where, u32 val);</font><br>
16513 <div class="bq">
16514 Write one, two, or four bytes to the configuration space. The device is identified
16515 by <font class="fixd">dev </font>as usual, and the value being written is passed as <font class="fixd">val.</font> The <i>word </i>and
16516 <i>dword </i>functions convert the value to little-endian before writing to the peripheral
16517 device.</div>
16518 <br>
16519 All of the previous functions are implemented as inline functions that really call the
16520 following functions. Feel free to use these functions instead of the above in case the
16521 driver does not have access to a <font class="fixd">struct pci_dev</font> at any paticular moment in time:<br>
16522 <br>
16523 <font class="fixd">int pci_bus_read_config_byte (struct pci_bus *bus, unsigned int devfn, int where, u8 *val);<br>
16524 int pci_bus_read_config_word (struct pci_bus *bus, unsigned int devfn, int where, u16 *val);<br>
16525 int pci_bus_read_config_dword (struct pci_bus *bus, unsigned int devfn, int where, u32 *val);</font><br>
16526 <div class="bq">
16527 Just like the <i>pci_read_ </i>functions, but <font class="fixd">struct pci_bus *</font> and <font class="fixd">devfn</font> variables are
16528 needed instead of a <font class="fixd">struct pci_dev *.</font></div>
16529 <br>
16530 <A name="316"></a><font color="blue">PAGE 316</font><br>
16531 <br>
16532 <font class="fixd">int pci_bus_write_config_byte (struct pci_bus *bus, unsigned int devfn, int where, u8 val);<br>
16533 int pci_bus_write_config_word (struct pci_bus *bus, unsigned int devfn, int where, u16 val);<br>
16534 int pci_bus_write_config_dword (struct pci_bus *bus, unsigned int devfn, int where, u32 val);</font><br>
16535 <div class="bq">
16536 Just like the <i>pci_write_ </i>functions, but <font class="fixd">struct pci_bus *</font> and <font class="fixd">devfn</font> variables are
16537 needed instead of a <font class="fixd">struct pci_dev *.</font></div>
16538 <br>
16539 The best way to address the configuration variables using the <i>pci_read_ </i>functions is
16540 by means of the symbolic names defined in <i><linux/pci.h></i>. For example, the following
16541 small function retrieves the revision ID of a device by passing the symbolic name
16542 for where to <i>pci_read_config_byte</i>:<br>
16543 <pre>
16544 static unsigned char skel_get_revision(struct pci_dev *dev)
16545 {
16546 u8 revision;
16548 pci_read_config_byte(dev, PCI_REVISION_ID, &revision);
16549 return revision;
16550 }
16551 </pre>
16552 <a name="AccessingTheIOAndMemorySpaces"></a><font color="red"><b>Accessing the I/O and Memory Spaces</b></font><br>
16553 <br>
16554 A PCI device implements up to six I/O address regions. Each region consists of either
16555 memory or I/O locations. Most devices implement their I/O registers in memory
16556 regions, because it's generally a saner approach (as explained in the section "I/O
16557 Ports and I/O Memory," in Chapter 9). However, unlike normal memory, I/O registers
16558 should not be cached by the CPU because each access can have side effects. The
16559 PCI device that implements I/O registers as a memory region marks the difference by
16560 setting a "memory-is-prefetchable" bit in its configuration register.* If the memory
16561 region is marked as prefetchable, the CPU can cache its contents and do all sorts of
16562 optimization with it; nonprefetchable memory access, on the other hand, can't be
16563 optimized because each access can have side effects, just as with I/O ports. Peripherals
16564 that map their control registers to a memory address range declare that range as
16565 nonprefetchable, whereas something like video memory on PCI boards is prefetchable.
16566 In this section, we use the word <i>region </i>to refer to a generic I/O address space
16567 that is memory-mapped or port-mapped.<br>
16568 <br>
16569 An interface board reports the size and current location of its regions using configuration
16570 registers--the six 32-bit registers shown in Figure 12-2, whose symbolic names
16571 are <font class="fixd">PCI_BASE_ADDRESS_0</font> through <font class="fixd">PCI_BASE_ADDRESS_5.</font> Since the I/O space defined by
16572 PCI is a 32-bit address space, it makes sense to use the same configuration interface<br>
16573 <br>
16574 * The information lives in one of the low-order bits of the base address PCI registers.
16575 The bits are defined in <i><linux/pci.h></i>.<br>
16576 <br>
16577 <A name="317"></a><font color="blue">PAGE 317</font><br>
16578 <br>
16579 for memory and I/O. If the device uses a 64-bit address bus, it can declare regions in
16580 the 64-bit memory space by using two consecutive <font class="fixd">PCI_BASE_ADDRESS</font> registers for each
16581 region, low bits first. It is possible for one device to offer both 32-bit regions and 64bit
16582 regions.<br>
16583 <br>
16584 In the kernel, the I/O regions of PCI devices have been integrated into the generic
16585 resource management. For this reason, you don't need to access the configuration
16586 variables in order to know where your device is mapped in memory or I/O space.
16587 The preferred interface for getting region information consists of the following
16588 functions:<br>
16589 <br>
16590 <font class="fixd">unsigned long pci_resource_start(struct pci_dev *dev, int bar);</font><br>
16591 <div class="bq">
16592 The function returns the first address (memory address or I/O port number)
16593 associated with one of the six PCI I/O regions. The region is selected by the integer
16594 <font class="fixd">bar</font> (the base address register), ranging from 0-5 (inclusive).</div>
16595 <br>
16596 <font class="fixd">unsigned long pci_resource_end(struct pci_dev *dev, int bar);</font><br>
16597 <div class="bq">
16598 The function returns the last address that is part of the I/O region number <font class="fixd">bar.</font>
16599 Note that this is the last usable address, not the first address after the region.</div>
16600 <br>
16601 <font class="fixd">unsigned long pci_resource_flags(struct pci_dev *dev, int bar);</font><br>
16602 <div class="bq">
16603 This function returns the flags associated with this resource.</div>
16604 <br>
16605 Resource flags are used to define some features of the individual resource. For PCI
16606 resources associated with PCI I/O regions, the information is extracted from the base
16607 address registers, but can come from elsewhere for resources not associated with PCI
16608 devices.<br>
16609 <br>
16610 All resource flags are defined in <i><linux/ioport.h></i>; the most important are:<br>
16611 <br>
16612 <font class="fixd">IORESOURCE_IO<br>
16613 IORESOURCE_MEM</font><br>
16614 <div class="bq">
16615 If the associated I/O region exists, one and only one of these flags is set.</div>
16616 <br>
16617 <font class="fixd">IORESOURCE_PREFETCH<br>
16618 IORESOURCE_READONLY</font><br>
16619 <div class="bq">
16620 These flags tell whether a memory region is prefetchable and/or write protected.
16621 The latter flag is never set for PCI resources.</div>
16622 <br>
16623 By making use of the <i>pci_resource_ </i>functions, a device driver can completely ignore
16624 the underlying PCI registers, since the system already used them to structure
16625 resource information.<br>
16626 <br>
16627 <a name="PCIInterrupts"></a><font color="red"><b>PCI Interrupts</b></font><br>
16628 <br>
16629 As far as interrupts are concerned, PCI is easy to handle. By the time Linux boots,
16630 the computer's firmware has already assigned a unique interrupt number to the
16631 device, and the driver just needs to use it. The interrupt number is stored in configuration
16632 register 60 (<font class="fixd">PCI_INTERRUPT_LINE</font>), which is one byte wide. This allows for as<br>
16633 <br>
16634 <A name="318"></a><font color="blue">PAGE 318</font><br>
16635 <br>
16636 many as 256 interrupt lines, but the actual limit depends on the CPU being used.
16637 The driver doesn't need to bother checking the interrupt number, because the value
16638 found in <font class="fixd">PCI_INTERRUPT_LINE</font> is guaranteed to be the right one.<br>
16639 <br>
16640 If the device doesn't support interrupts, register 61 (<font class="fixd">PCI_INTERRUPT_PIN</font>) is 0; otherwise,
16641 it's nonzero. However, since the driver knows if its device is interrupt driven or
16642 not, it doesn't usually need to read <font class="fixd">PCI_INTERRUPT_PIN</font>.<br>
16643 <br>
16644 Thus, PCI-specific code for dealing with interrupts just needs to read the configuration
16645 byte to obtain the interrupt number that is saved in a local variable, as shown in
16646 the following code. Beyond that, the information in Chapter 10 applies.<br>
16647 <pre>
16648 result = pci_read_config_byte(dev, PCI_INTERRUPT_LINE, &myirq);
16649 if (result) {
16650 /* deal with error */
16651 }
16652 </pre>
16653 The rest of this section provides additional information for the curious reader but
16654 isn't needed for writing drivers.<br>
16655 <br>
16656 A PCI connector has four interrupt pins, and peripheral boards can use any or all of
16657 them. Each pin is individually routed to the motherboard's interrupt controller, so
16658 interrupts can be shared without any electrical problems. The interrupt controller is
16659 then responsible for mapping the interrupt wires (pins) to the processor's hardware;
16660 this platform-dependent operation is left to the controller in order to achieve platform
16661 independence in the bus itself.<br>
16662 <br>
16663 The read-only configuration register located at <font class="fixd">PCI_INTERRUPT_PIN</font> is used to tell the
16664 computer which single pin is actually used. It's worth remembering that each device
16665 board can host up to eight devices; each device uses a single interrupt pin and reports
16666 it in its own configuration register. Different devices on the same device board can
16667 use different interrupt pins or share the same one.<br>
16668 <br>
16669 The <font class="fixd">PCI_INTERRUPT_LINE</font> register, on the other hand, is read/write. When the computer
16670 is booted, the firmware scans its PCI devices and sets the register for each
16671 device according to how the interrupt pin is routed for its PCI slot. The value is
16672 assigned by the firmware, because only the firmware knows how the motherboard
16673 routes the different interrupt pins to the processor. For the device driver, however,
16674 the <font class="fixd">PCI_INTERRUPT_LINE</font> register is read-only. Interestingly, recent versions of the
16675 Linux kernel under some circumstances can assign interrupt lines without resorting
16676 to the BIOS.<br>
16677 <br>
16678 <a name="HardwareAbstractions"></a><font color="red"><b>Hardware Abstractions</b></font><br>
16679 <br>
16680 We complete the discussion of PCI by taking a quick look at how the system handles
16681 the plethora of PCI controllers available on the marketplace. This is just an
16682 informational section, meant to show the curious reader how the object-oriented layout
16683 of the kernel extends down to the lowest levels.<br>
16684 <br>
16685 <A name="319"></a><font color="blue">PAGE 319</font><br>
16686 <br>
16687 The mechanism used to implement hardware abstraction is the usual structure containing
16688 methods. It's a powerful technique that adds just the minimal overhead of
16689 dereferencing a pointer to the normal overhead of a function call. In the case of PCI
16690 management, the only hardware-dependent operations are the ones that read and
16691 write configuration registers, because everything else in the PCI world is accomplished
16692 by directly reading and writing the I/O and memory address spaces, and
16693 those are under direct control of the CPU.<br>
16694 <br>
16695 Thus, the relevant structure for configuration register access includes only two fields:<br>
16696 <pre>
16697 struct pci_ops {
16698 int (*read)(struct pci_bus *bus, unsigned int devfn, int where, int size,
16699 u32 *val);
16700 int (*write)(struct pci_bus *bus, unsigned int devfn, int where, int size,
16701 u32 val);
16702 };
16703 </pre>
16704 The structure is defined in <i><linux/pci.h> </i>and used by <i>drivers/pci/pci.c</i>, where the
16705 actual public functions are defined.<br>
16706 <br>
16707 The two functions that act on the PCI configuration space have more overhead
16708 than dereferencing a pointer; they use cascading pointers due to the high object-orientedness
16709 of the code, but the overhead is not an issue in operations that are
16710 performed quite rarely and never in speed-critical paths. The actual implementation
16711 of <i>pci_read_config_byte(dev, where, val)</i>, for instance, expands to:<br>
16712 <pre>
16713 dev->bus->ops->read(bus, devfn, where, 8, val);
16714 </pre>
16715 The various PCI buses in the system are detected at system boot, and that's when the
16716 struct <font class="fixd">pci_bus</font> items are created and associated with their features, including the ops
16717 field.<br>
16718 <br>
16719 Implementing hardware abstraction via "hardware operations" data structures is typical
16720 in the Linux kernel. One important example is the <font class="fixd">struct alpha_machine_vector</font>
16721 data structure. It is defined in <i><asm-alpha/machvec.h> </i>and takes care of everything
16722 that may change across different Alpha-based computers.<br>
16723 <br>
16724 <a name="ALookBackISA"></a><font color="red"><b>A Look Back: ISA</b></font><br>
16725 <br>
16726 The ISA bus is quite old in design and is a notoriously poor performer, but it still
16727 holds a good part of the market for extension devices. If speed is not important and
16728 you want to support old motherboards, an ISA implementation is preferable to PCI.
16729 An additional advantage of this old standard is that if you are an electronic hobbyist,
16730 you can easily build your own ISA devices, something definitely not possible with
16731 PCI.<br>
16732 <br>
16733 <A name="320"></a><font color="blue">PAGE 320</font><br>
16734 <br>
16735 On the other hand, a great disadvantage of ISA is that it's tightly bound to the PC
16736 architecture; the interface bus has all the limitations of the 80286 processor and
16737 causes endless pain to system programmers. The other great problem with the ISA
16738 design (inherited from the original IBM PC) is the lack of geographical addressing,
16739 which has led to many problems and lengthy unplug-rejumper-plug-test cycles to
16740 add new devices. It's interesting to note that even the oldest Apple II computers were
16741 already exploiting geographical addressing, and they featured jumperless expansion
16742 boards.<br>
16743 <br>
16744 Despite its great disadvantages, ISA is still used in several unexpected places. For
16745 example, the VR41xx series of MIPS processors used in several palmtops features an
16746 ISA-compatible expansion bus, strange as it seems. The reason behind these unexpected
16747 uses of ISA is the extreme low cost of some legacy hardware, such as 8390based
16748 Ethernet cards, so a CPU with ISA electrical signaling can easily exploit the
16749 awful, but cheap, PC devices.<br>
16750 <br>
16751 <a name="HardwareResources"></a><font color="red"><b>Hardware Resources</b></font><br>
16752 <br>
16753 An ISA device can be equipped with I/O ports, memory areas, and interrupt lines.<br>
16754 <br>
16755 Even though the x86 processors support 64 KB of I/O port memory (i.e., the processor
16756 asserts 16 address lines), some old PC hardware decodes only the lowest 10
16757 address lines. This limits the usable address space to 1024 ports, because any address
16758 in the range 1 KB to 64 KB is mistaken for a low address by any device that decodes
16759 only the low address lines. Some peripherals circumvent this limitation by mapping
16760 only one port into the low kilobyte and using the high address lines to select between
16761 different device registers. For example, a device mapped at <font class="fixd">0x340</font> can safely use port
16762 <font class="fixd">0x740, 0xB40,</font> and so on.<br>
16763 <br>
16764 If the availability of I/O ports is limited, memory access is still worse. An ISA device
16765 can use only the memory range between 640 KB and 1 MB and between 15 MB and
16766 16 MB for I/O register and device control. The 640-KB to 1-MB range is used by the
16767 PC BIOS, by VGA-compatible video boards, and by various other devices, leaving little
16768 space available for new devices. Memory at 15 MB, on the other hand, is not
16769 directly supported by Linux, and hacking the kernel to support it is a waste of programming
16770 time nowadays.<br>
16771 <br>
16772 The third resource available to ISA device boards is interrupt lines. A limited number
16773 of interrupt lines is routed to the ISA bus, and they are shared by all the interface
16774 boards. As a result, if devices aren't properly configured, they can find themselves
16775 using the same interrupt lines.<br>
16776 <br>
16777 <A name="321"></a><font color="blue">PAGE 321</font><br>
16778 <br>
16779 Although the original ISA specification doesn't allow interrupt sharing across
16780 devices, most device boards allow it.* Interrupt sharing at the software level is
16781 described in the section "Interrupt Sharing," in Chapter 10.<br>
16782 <br>
16783 <a name="ISAProgramming"></a><font color="red"><b>ISA Programming</b></font><br>
16784 <br>
16785 As far as programming is concerned, there's no specific aid in the kernel or the BIOS
16786 to ease access to ISA devices (like there is, for example, for PCI). The only facilities
16787 you can use are the registries of I/O ports and IRQ lines, described in the section
16788 "Installing an Interrupt Handler" in Chapter 10.<br>
16789 <br>
16790 The programming techniques shown throughout the first part of this book apply to
16791 ISA devices; the driver can probe for I/O ports, and the interrupt line must be auto-detected
16792 with one of the techniques shown in the section "Auto-Detecting the IRQ Number" in Chapter 10.<br>
16793 <br>
16794 The helper functions <i>isa_readb </i>and friends have been briefly introduced in the section
16795 "Using I/O Memory" in Chapter 9, and there's nothing more to say about them.<br>
16796 <br>
16797 <a name="ThePlugandPlaySpecification"></a><font color="red"><b>The Plug-and-Play Specification</b></font><br>
16798 <br>
16799 Some new ISA device boards follow peculiar design rules and require a special initialization
16800 sequence intended to simplify installation and configuration of add-on interface
16801 boards. The specification for the design of these boards is called <i>plug and play
16802 </i>(PnP) and consists of a cumbersome rule set for building and configuring jumperless
16803 ISA devices. PnP devices implement relocatable I/O regions; the PC's BIOS is responsible
16804 for the relocation--reminiscent of PCI.<br>
16805 <br>
16806 In short, the goal of PnP is to obtain the same flexibility found in PCI devices without
16807 changing the underlying electrical interface (the ISA bus). To this end, the specs
16808 define a set of device-independent configuration registers and a way to geographically
16809 address the interface boards, even though the physical bus doesn't carry perboard
16810 (geographical) wiring--every ISA signal line connects to every available slot.<br>
16811 <br>
16812 Geographical addressing works by assigning a small integer, called the <i>card select
16813 number </i>(CSN), to each PnP peripheral in the computer. Each PnP device features a
16814 unique serial identifier, 64 bits wide, that is hardwired into the peripheral board.
16815 CSN assignment uses the unique serial number to identify the PnP devices. But the
16816 CSNs can be assigned safely only at boot time, which requires the BIOS to be PnP<br>
16817 <br>
16818 * The problem with interrupt sharing is a matter of electrical engineering: if a device
16819 drives the signal line inactive--by applying a low-impedance voltage level--the interrupt
16820 can't be shared. If, on the other hand, the device uses a pull-up resistor to the inactive
16821 logic level, sharing is possible. This is the norm nowadays. However, there's still a
16822 potential risk of losing interrupt events since ISA interrupts are edge triggered instead of
16823 level triggered. Edge-triggered interrupts are easier to implement in hardware but don't
16824 lend themselves to safe sharing.<br>
16825 <br>
16826 <A name="322"></a><font color="blue">PAGE 322</font><br>
16827 <br>
16828 aware. For this reason, old computers require the user to obtain and insert a specific
16829 configuration diskette, even if the device is PnP capable.<br>
16830 <br>
16831 Interface boards following the PnP specs are complicated at the hardware level. They
16832 are much more elaborate than PCI boards and require complex software. It's not
16833 unusual to have difficulty installing these devices, and even if the installation goes
16834 well, you still face the performance constraints and the limited I/O space of the ISA
16835 bus. It's much better to install PCI devices whenever possible and enjoy the new
16836 technology instead.<br>
16837 <br>
16838 If you are interested in the PnP configuration software, you can browse <i>drivers/net/
16839 3c509.c</i>, whose probing function deals with PnP devices. The 2.6 kernel saw a lot of
16840 work in the PnP device support area, so a lot of the inflexible interfaces have been
16841 cleaned up compared to previous kernel releases.<br>
16842 <br>
16843 <a name="PC104AndPC104"></a><font color="red"><b>PC/104 and PC/104+</b></font><br>
16844 <br>
16845 Currently in the industrial world, two bus architectures are quite fashionable: PC/104
16846 and PC/104+. Both are standard in PC-class single-board computers.<br>
16847 <br>
16848 Both standards refer to specific form factors for printed circuit boards, as well as
16849 electrical/mechanical specifications for board interconnections. The practical advantage
16850 of these buses is that they allow circuit boards to be stacked vertically using a
16851 plug-and-socket kind of connector on one side of the device.<br>
16852 <br>
16853 The electrical and logical layout of the two buses is identical to ISA (PC/104) and
16854 PCI (PC/104+), so software won't notice any difference between the usual desktop
16855 buses and these two.<br>
16856 <br>
16857 <a name="OtherPCBuses"></a><font color="red"><b>Other PC Buses</b></font><br>
16858 <br>
16859 PCI and ISA are the most commonly used peripheral interfaces in the PC world, but
16860 they aren't the only ones. Here's a summary of the features of other buses found in
16861 the PC market.<br>
16862 <br>
16863 <a name="MCA"></a><font color="red"><b>MCA</b></font><br>
16864 <br>
16865 Micro Channel Architecture (MCA) is an IBM standard used in PS/2 computers and
16866 some laptops. At the hardware level, Micro Channel has more features than ISA. It
16867 supports multimaster DMA, 32-bit address and data lines, shared interrupt lines, and
16868 geographical addressing to access per-board configuration registers. Such registers
16869 are called <i>Programmable Option Select </i>(POS), but they don't have all the features of
16870 the PCI registers. Linux support for Micro Channel includes functions that are
16871 exported to modules.<br>
16872 <br>
16873 <A name="323"></a><font color="blue">PAGE 323</font><br>
16874 <br>
16875 A device driver can read the integer value <font class="fixd">MCA_bus</font> to see if it is running on a Micro
16876 Channel computer. If the symbol is a preprocessor macro, the macro <font class="fixd">MCA_bus__is_a_macro </font>
16877 is defined as well. If <font class="fixd">MCA_bus__is_a_macro</font> is undefined, then <font class="fixd">MCA_bus</font> is an integer
16878 variable exported to modularized code. Both <font class="fixd">MCA_BUS</font> and <font class="fixd">MCA_bus__is_a_macro</font>
16879 are defined in <i><asm/processor.h></i>.<br>
16880 <br>
16881 <a name="EISA"></a><font color="red"><b>EISA</b></font><br>
16882 <br>
16883 The Extended ISA (EISA) bus is a 32-bit extension to ISA, with a compatible interface
16884 connector; ISA device boards can be plugged into an EISA connector. The additional
16885 wires are routed under the ISA contacts.<br>
16886 <br>
16887 Like PCI and MCA, the EISA bus is designed to host jumperless devices, and it has
16888 the same features as MCA: 32-bit address and data lines, multimaster DMA, and
16889 shared interrupt lines. EISA devices are configured by software, but they don't need
16890 any particular operating system support. EISA drivers already exist in the Linux kernel
16891 for Ethernet devices and SCSI controllers.<br>
16892 <br>
16893 An EISA driver checks the value <font class="fixd">EISA_bus</font> to determine if the host computer carries
16894 an EISA bus. Like <font class="fixd">MCA_bus, EISA_bus</font> is either a macro or a variable, depending on
16895 whether <font class="fixd">EISA_bus__is_a_macro</font> is defined. Both symbols are defined in <i><asm/
16896 processor.h></i>.<br>
16897 <br>
16898 The kernel has full EISA support for devices with sysfs and resource management
16899 functionality. This is located in the <i>drivers/eisa</i> directory.<br>
16900 <br>
16901 <a name="VLB"></a><font color="red"><b>VLB</b></font><br>
16902 <br>
16903 Another extension to ISA is the VESA Local Bus (VLB) interface bus, which extends
16904 the ISA connectors by adding a third lengthwise slot. A device can just plug into this
16905 extra connector (without plugging in the two associated ISA connectors), because
16906 the VLB slot duplicates all important signals from the ISA connectors. Such "stand alone"
16907 VLB peripherals not using the ISA slot are rare, because most devices need to
16908 reach the back panel so that their external connectors are available.<br>
16909 <br>
16910 The VESA bus is much more limited in its capabilities than the EISA, MCA, and PCI
16911 buses and is disappearing from the market. No special kernel support exists for VLB.
16912 However, both the Lance Ethernet driver and the IDE disk driver in Linux 2.0 can
16913 deal with VLB versions of their devices.<br>
16914 <br>
16915 <a name="SBus"></a><font color="red"><b>SBus</b></font><br>
16916 <br>
16917 While most computers nowadays are equipped with a PCI or ISA interface bus, most
16918 older SPARC-based workstations use SBus to connect their peripherals.<br>
16919 <br>
16920 <A name="324"></a><font color="blue">PAGE 324</font><br>
16921 <br>
16922 SBus is quite an advanced design, although it has been around for a long time. It is
16923 meant to be processor independent (even though only SPARC computers use it) and
16924 is optimized for I/O peripheral boards. In other words, you can't plug additional
16925 RAM into SBus slots (RAM expansion boards have long been forgotten even in the
16926 ISA world, and PCI does not support them either). This optimization is meant to
16927 simplify the design of both hardware devices and system software, at the expense of
16928 some additional complexity in the motherboard.<br>
16929 <br>
16930 This I/O bias of the bus results in peripherals using <i>virtual </i>addresses to transfer data,
16931 thus bypassing the need to allocate a contiguous DMA buffer. The motherboard is
16932 responsible for decoding the virtual addresses and mapping them to physical
16933 addresses. This requires attaching an MMU (memory management unit) to the bus;
16934 the chipset in charge of the task is called IOMMU. Although somehow more complex
16935 than using physical addresses on the interface bus, this design is greatly simplified
16936 by the fact that SPARC processors have always been designed by keeping the
16937 MMU core separate from the CPU core (either physically or at least conceptually).
16938 Actually, this design choice is shared by other smart processor designs and is beneficial
16939 overall. Another feature of this bus is that device boards exploit massive geographical
16940 addressing, so there's no need to implement an address decoder in every
16941 peripheral or to deal with address conflicts.<br>
16942 <br>
16943 SBus peripherals use the Forth language in their PROMs to initialize themselves.
16944 Forth was chosen because the interpreter is lightweight and, therefore, can be easily
16945 implemented in the firmware of any computer system. In addition, the SBus specification
16946 outlines the boot process, so that compliant I/O devices fit easily into the system
16947 and are recognized at system boot. This was a great step to support multiplatform
16948 devices; it's a completely different world from the PC-centric ISA stuff we
16949 were used to. However, it didn't succeed for a variety of commercial reasons.<br>
16950 <br>
16951 Although current kernel versions offer quite full-featured support for SBus devices,
16952 the bus is used so little nowadays that it's not worth covering in detail here. Interested
16953 readers can look at source files in <i>arch/sparc/kernel</i> and <i>arch/sparc/mm</i>.<br>
16954 <br>
16955 <a name="NuBus"></a><font color="red"><b>NuBus</b></font><br>
16956 <br>
16957 Another interesting, but nearly forgotten, interface bus is NuBus. It is found on older
16958 Mac computers (those with the M68k family of CPUs).<br>
16959 <br>
16960 All of the bus is memory-mapped (like everything with the M68k), and the devices
16961 are only geographically addressed. This is good and typical of Apple, as the much<br>
16962 <br>
16963 <A name="325"></a><font color="blue">PAGE 325</font><br>
16964 <br>
16965 older Apple II already had a similar bus layout. What is bad is that it's almost impossible
16966 to find documentation on NuBus, due to the close-everything policy Apple has
16967 always followed with its Mac computers (and unlike the previous Apple II, whose
16968 source code and schematics were available at little cost).<br>
16969 <br>
16970 The file <i>drivers/nubus/nubus.c </i>includes almost everything we know about this bus,
16971 and it's interesting reading; it shows how much hard reverse engineering developers
16972 had to do.<br>
16973 <br>
16974 <a name="ExternalBuses"></a><font color="red"><b>External Buses</b></font><br>
16975 <br>
16976 One of the most recent entries in the field of interface buses is the whole class of
16977 external buses. This includes USB, FireWire, and IEEE1284 (parallel-port-based
16978 external bus). These interfaces are somewhat similar to older and not-so-external
16979 technology, such as PCMCIA/CardBus and even SCSI.<br>
16980 <br>
16981 Conceptually, these buses are neither full-featured interface buses (like PCI is) nor
16982 dumb communication channels (like the serial ports are). It's hard to classify the
16983 software that is needed to exploit their features, as it's usually split into two levels:
16984 the driver for the hardware controller (like drivers for PCI SCSI adaptors or PCI controllers
16985 introduced in the section "The PCI Interface") and the driver for the specific
16986 "client" device (like <i>sd.c </i>handles generic SCSI disks and so-called PCI drivers deal
16987 with cards plugged in the bus).<br>
16988 <br>
16989 <a name="QuickReference12"></a><font color="red"><b>Quick Reference</b></font><br>
16990 <br>
16991 This section summarizes the symbols introduced in the chapter:<br>
16992 <br>
16993 <font class="fixd">#include <linux/pci.h></font><br>
16994 <div class="bq">
16995 Header that includes symbolic names for the PCI registers and several vendor
16996 and device ID values.</div>
16997 <br>
16998 <font class="fixd">struct pci_dev;</font><br>
16999 <div class="bq">
17000 Structure that represents a PCI device within the kernel.</div>
17001 <br>
17002 <font class="fixd">struct pci_driver;</font><br>
17003 <div class="bq">
17004 Structure that represents a PCI driver. All PCI drivers must define this.</div>
17005 <br>
17006 <font class="fixd">struct pci_device_id;</font><br>
17007 <div class="bq">
17008 Structure that describes the types of PCI devices this driver supports.</div>
17009 <br>
17010 <font class="fixd">int pci_register_driver(struct pci_driver *drv);<br>
17011 int pci_module_init(struct pci_driver *drv);<br>
17012 void pci_unregister_driver(struct pci_driver *drv);</font><br>
17013 <div class="bq">
17014 Functions that register or unregister a PCI driver from the kernel.</div>
17015 <br>
17016 <A name="326"></a><font color="blue">PAGE 326</font><br>
17017 <br>
17018 <font class="fixd">struct pci_dev *pci_find_device(unsigned int vendor, unsigned int device, struct pci_dev *from);<br>
17019 struct pci_dev *pci_find_device_reverse(unsigned int vendor, unsigned int device, const struct pci_dev *from);<br>
17020 struct pci_dev *pci_find_subsys (unsigned int vendor, unsigned int device, unsigned int ss_vendor, unsigned int ss_device, const struct pci_dev *from);<br>
17021 struct pci_dev *pci_find_class(unsigned int class, struct pci_dev *from);</font><br>
17022 <div class="bq">
17023 Functions that search the device list for devices with a specific signature or those
17024 belonging to a specific class. The return value is <font class="fixd">NULL</font> if none is found. <font class="fixd">from</font> is
17025 used to continue a search; it must be <font class="fixd">NULL</font> the first time you call either function,
17026 and it must point to the device just found if you are searching for more devices.
17027 These functions are not recommended to be used, use the <font class="fixd">pci_get_</font> variants
17028 instead.</div>
17029 <br>
17030 <font class="fixd">struct pci_dev *pci_get_device(unsigned int vendor, unsigned int device, struct pci_dev *from);<br>
17031 struct pci_dev *pci_get_subsys(unsigned int vendor, unsigned int device, unsigned int ss_vendor, unsigned int ss_device, struct pci_dev *from);<br>
17032 struct pci_dev *pci_get_slot(struct pci_bus *bus, unsigned int devfn);</font><br>
17033 <div class="bq">
17034 Functions that search the device list for devices with a specific signature or
17035 belonging to a specific class. The return value is <font class="fixd">NULL</font> if none is found. <font class="fixd">from</font> is
17036 used to continue a search; it must be <font class="fixd">NULL</font> the first time you call either function,
17037 and it must point to the device just found if you are searching for more devices.
17038 The structure returned has its reference count incremented, and after the caller is
17039 finished with it, the function <i>pci_dev_put</i> must be called.</div>
17040 <br>
17041 <font class="fixd">int pci_read_config_byte(struct pci_dev *dev, int where, u8 *val);<br>
17042 int pci_read_config_word(struct pci_dev *dev, int where, u16 *val);<br>
17043 int pci_read_config_dword(struct pci_dev *dev, int where, u32 *val);<br>
17044 int pci_write_config_byte (struct pci_dev *dev, int where, u8 *val);<br>
17045 int pci_write_config_word (struct pci_dev *dev, int where, u16 *val);<br>
17046 int pci_write_config_dword (struct pci_dev *dev, int where, u32 *val);</font><br>
17047 <div class="bq">
17048 Functions that read or write a PCI configuration register. Although the Linux
17049 kernel takes care of byte ordering, the programmer must be careful about byte
17050 ordering when assembling multibyte values from individual bytes. The PCI bus
17051 is little-endian.</div>
17052 <br>
17053 <font class="fixd">int pci_enable_device(struct pci_dev *dev);</font><br>
17054 <div class="bq">
17055 Enables a PCI device.</div>
17056 <br>
17057 <font class="fixd">unsigned long pci_resource_start(struct pci_dev *dev, int bar);<br>
17058 unsigned long pci_resource_end(struct pci_dev *dev, int bar);<br>
17059 unsigned long pci_resource_flags(struct pci_dev *dev, int bar);</font><br>
17060 <div class="bq">
17061 Functions that handle PCI device resources.</div>
17062 <br>
17063 <A name="327"></a><font color="blue">PAGE 327</font><br>
17064 <br>
17065 <a name="CHAPTER13"></a><font color="red"><b>CHAPTER 13</b></font><br>
17066 <br>
17067 <a name="USBDrivers"></a><font color="#7519FF" size="+1"><b>USB Drivers</b></font><br>
17068 <br>
17069 The universal serial bus (USB) is a connection between a host computer and a number
17070 of peripheral devices. It was originally created to replace a wide range of slow
17071 and different buses--the parallel, serial, and keyboard connections--with a single
17072 bus type that all devices could connect to.* USB has grown beyond these slow connections
17073 and now supports almost every type of device that can be connected to a
17074 PC. The latest revision of the USB specification added high-speed connections with a
17075 theoretical speed limit of 480 MBps.<br>
17076 <br>
17077 Topologically, a USB subsystem is not laid out as a bus; it is rather a tree built out of
17078 several point-to-point links. The links are four-wire cables (ground, power, and two
17079 signal wires) that connect a device and a hub, just like twisted-pair Ethernet. The
17080 USB host controller is in charge of asking every USB device if it has any data to send.
17081 Because of this topology, a USB device can never start sending data without first
17082 being asked to by the host controller. This configuration allows for a very easy plugand-play
17083 type of system, whereby devices can be automatically configured by the
17084 host computer.<br>
17085 <br>
17086 The bus is very simple at the technological level, as it's a single-master implementation
17087 in which the host computer polls the various peripheral devices. Despite this
17088 intrinsic limitation, the bus has some interesting features, such as the ability for a
17089 device to request a fixed bandwidth for its data transfers in order to reliably support
17090 video and audio I/O. Another important feature of USB is that it acts merely as a
17091 communication channel between the device and the host, without requiring specific
17092 meaning or structure to the data it delivers.†<br>
17093 <br>
17094 * Portions of this chapter are based on the in-kernel documentation for the Linux kernel USB code, which were
17095 written by the kernel USB developers and released under the GPL.<br>
17096 <br>
17097 † Actually, some structure is there, but it mostly reduces to a requirement for the communication to fit into
17098 one of a few predefined classes: a keyboard won't allocate bandwidth, for example, while some video cameras
17099 will.<br>
17100 <br>
17101 <A name="328"></a><font color="blue">PAGE 328</font><br>
17102 <br>
17103 The USB protocol specifications define a set of standards that any device of a specific
17104 type can follow. If a device follows that standard, then a special driver for that
17105 device is not necessary. These different types are called classes and consist of things
17106 like storage devices, keyboards, mice, joysticks, network devices, and modems.
17107 Other types of devices that do not fit into these classes require a special vendor-specific
17108 driver to be written for that specific device. Video devices and USB-to-serial
17109 devices are a good example where there is no defined standard, and a driver is
17110 needed for every different device from different manufacturers.<br>
17111 <br>
17112 These features, together with the inherent hotplug capability of the design, make
17113 USB a handy, low-cost mechanism to connect (and disconnect) several devices to the
17114 computer without the need to shut the system down, open the cover, and swear over
17115 screws and wires.<br>
17116 <br>
17117 The Linux kernel supports two main types of USB drivers: drivers on a host system
17118 and drivers on a device. The USB drivers for a host system control the USB devices
17119 that are plugged into it, from the host's point of view (a common USB host is a desktop
17120 computer.) The USB drivers in a device, control how that single device looks to
17121 the host computer as a USB device. As the term "USB device drivers" is very confusing,
17122 the USB developers have created the term "USB gadget drivers" to describe the
17123 drivers that control a USB device that connects to a computer (remember that Linux
17124 also runs in those tiny embedded devices, too.) This chapter details how the USB system
17125 that runs on a desktop computer works. USB gadget drivers are outside the
17126 realm of this book at this point in time.<br>
17127 <br>
17128 As Figure 13-1 shows, USB drivers live between the different kernel subsytems
17129 (block, net, char, etc.) and the USB hardware controllers. The USB core provides an
17130 interface for USB drivers to use to access and control the USB hardware, without
17131 having to worry about the different types of USB hardware controllers that are
17132 present on the system.<br>
17133 <br>
17134 <a name="USBDeviceBasics"></a><font color="red"><b>USB Device Basics</b></font><br>
17135 <br>
17136 A USB device is a very complex thing, as described in the official USB documentation
17137 (available at <a href="http://www.usb.org" target="_blank"><i>http://www.usb.org</i></a>). Fortunately, the Linux kernel provides a subsystem
17138 called the <i>USB core </i>to handle most of the complexity. This chapter describes
17139 the interaction between a driver and the USB core. Figure 13-2 shows how USB
17140 devices consist of configurations, interfaces, and endpoints and how USB drivers
17141 bind to USB interfaces, not the entire USB device.<br>
17142 <br>
17143 <a name="Endpoints"></a><font color="red"><b>Endpoints</b></font><br>
17144 <br>
17145 The most basic form of USB communication is through something called an <i>endpoint</i>.
17146 A USB endpoint can carry data in only one direction, either from the host<br>
17147 <br>
17148 <A name="329"></a><font color="blue">PAGE 329</font><br>
17149 <br>
17150 <center>
17151 <img src="fig13-1.gif">
17152 </center>
17153 <br>
17154 <i>Figure 13-1. USB driver overview</i><br>
17155 <br>
17156 <center>
17157 <img src="fig13-2.gif">
17158 </center>
17159 <br>
17160 <i>Figure 13-2. USB device overview</i><br>
17161 <br>
17162 computer to the device (called an <i>OUT </i>endpoint) or from the device to the host computer
17163 (called an <i>IN</i> endpoint). Endpoints can be thought of as unidirectional pipes.<br>
17164 <br>
17165 A USB endpoint can be one of four different types that describe how the data is
17166 transmitted:<br>
17167 <br>
17168 <i>CONTROL</i><br>
17169 <div class="bq">
17170 Control endpoints are used to allow access to different parts of the USB device.
17171 They are commonly used for configuring the device, retrieving information
17172 about the device, sending commands to the device, or retrieving status reports
17173 about the device. These endpoints are usually small in size. Every USB device has</div>
17174 <br>
17175 <A name="330"></a><font color="blue">PAGE 330</font><br>
17176 <br>
17177 <div class="bq">a control endpoint called "endpoint 0" that is used by the USB core to configure
17178 the device at insertion time. These transfers are guaranteed by the USB protocol
17179 to always have enough reserved bandwidth to make it through to the device.</div>
17180 <br>
17181 <i>INTERRUPT</i><br>
17182 <div class="bq">
17183 Interrupt endpoints transfer small amounts of data at a fixed rate every time the
17184 USB host asks the device for data. These endpoints are the primary transport
17185 method for USB keyboards and mice. They are also commonly used to send data
17186 to USB devices to control the device, but are not generally used to transfer large
17187 amounts of data. These transfers are guaranteed by the USB protocol to always
17188 have enough reserved bandwidth to make it through.</div>
17189 <br>
17190 <i>BULK</i><br>
17191 <div class="bq">
17192 Bulk endpoints transfer large amounts of data. These endpoints are usually
17193 much larger (they can hold more characters at once) than interrupt endpoints.
17194 They are common for devices that need to transfer any data that must get
17195 through with no data loss. These transfers are not guaranteed by the USB protocol
17196 to always make it through in a specific amount of time. If there is not enough
17197 room on the bus to send the whole BULK packet, it is split up across multiple
17198 transfers to or from the device. These endpoints are common on printers, storage,
17199 and network devices.</div>
17200 <br>
17201 <i>ISOCHRONOUS</i><br>
17202 <div class="bq">
17203 Isochronous endpoints also transfer large amounts of data, but the data is not
17204 always guaranteed to make it through. These endpoints are used in devices that
17205 can handle loss of data, and rely more on keepinga constant stream of data
17206 flowing. Real-time data collections, such as audio and video devices, almost
17207 always use these endpoints.</div>
17208 <br>
17209 Control and bulk endpoints are used for asynchronous data transfers, whenever the
17210 driver decides to use them. Interrupt and isochronous endpoints are periodic. This
17211 means that these endpoints are set up to transfer data at fixed times continuously,
17212 which causes their bandwidth to be reserved by the USB core.<br>
17213 <br>
17214 USB endpoints are described in the kernel with the structure <font class="fixd">struct usb_host_endpoint</font>.
17215 This structure contains the real endpoint information in another structure called
17216 <font class="fixd">struct usb_endpoint_descriptor</font>. The latter structure contains all of the USB-specific
17217 data in the exact format that the device itself specified. The fields of this structure that
17218 drivers care about are:<br>
17219 <br>
17220 <font class="fixd">bEndpointAddress</font><br>
17221 <div class="bq">
17222 This is the USB address of this specific endpoint. Also included in this 8-bit
17223 value is the direction of the endpoint. The bitmasks <font class="fixd">USB_DIR_OUT</font> and <font class="fixd">USB_DIR_IN</font>
17224 can be placed against this field to determine if the data for this endpoint is
17225 directed to the device or to the host.</div>
17226 <br>
17227 <font class="fixd">bmAttributes</font><br>
17228 <div class="bq">
17229 This is the type of endpoint. The bitmask <font class="fixd">USB_ENDPOINT_XFERTYPE_MASK</font> should
17230 be placed against this value in order to determine if the endpoint is of type</div>
17231 <br>
17232 <A name="331"></a><font color="blue">PAGE 331</font><br>
17233 <br>
17234 <div class="bq"><font class="fixd">USB_ENDPOINT_XFER_ISOC, USB_ENDPOINT_XFER_BULK,</font> or of
17235 type <font class="fixd">USB_ENDPOINT_XFER_INT</font>. These macros define a isochronous, bulk,
17236 and interrupt endpoint, respectively.</div>
17237 <br>
17238 <font class="fixd">wMaxPacketSize</font><br>
17239 <div class="bq">
17240 This is the maximum size in bytes that this endpoint can handle at once. Note
17241 that it is possible for a driver to send amounts of data to an endpoint that is bigger
17242 than this value, but the data will be divided up into <font class="fixd">wMaxPacketSize</font> chunks
17243 when actually transmitted to the device. For high-speed devices, this field can be
17244 used to support a high-bandwidth mode for the endpoint by using a few extra
17245 bits in the upper part of the value. See the USB specification for more details
17246 about how this is done.</div>
17247 <br>
17248 <font class="fixd">bInterval</font><br>
17249 <div class="bq">
17250 If this endpoint is of type interrupt, this value is the interval setting for the endpoint--that
17251 is, the time between interrupt requests for the endpoint. The value is
17252 represented in milliseconds.</div>
17253 <br>
17254 The fields of this structure do not have a "traditional" Linux kernel naming scheme.
17255 This is because these fields directly correspond to the field names in the USB specification.
17256 The USB kernel programmers felt that it was more important to use the specified
17257 names, so as to reduce confusion when reading the specification, than it was to
17258 have variable names that look familiar to Linux programmers.<br>
17259 <br>
17260 <a name="Interfaces"></a><font color="red"><b>Interfaces</b></font><br>
17261 <br>
17262 USB endpoints are bundled up into <i>interfaces</i>. USB interfaces handle only one type of
17263 a USB logical connection, such as a mouse, a keyboard, or a audio stream. Some USB
17264 devices have multiple interfaces, such as a USB speaker that might consist of two
17265 interfaces: a USB keyboard for the buttons and a USB audio stream. Because a USB
17266 interface represents basic functionality, each USB driver controls an interface; so, for
17267 the speaker example, Linux needs two different drivers for one hardware device.<br>
17268 <br>
17269 USB interfaces may have alternate settings, which are different choices for parameters
17270 of the interface. The initial state of a interface is in the first setting, numbered 0.
17271 Alternate settings can be used to control individual endpoints in different ways, such
17272 as to reserve different amounts of USB bandwidth for the device. Each device with an
17273 isochronous endpoint uses alternate settings for the same interface.<br>
17274 <br>
17275 USB interfaces are described in the kernel with the struct <font class="fixd">usb_interface</font> structure.
17276 This structure is what the USB core passes to USB drivers and is what the USB driver
17277 then is in charge of controlling. The important fields in this structure are:<br>
17278 <br>
17279 <font class="fixd">struct usb_host_interface *altsetting</font><br>
17280 <div class="bq">
17281 An array of interface structures containing all of the alternate settings that may
17282 be selected for this interface. Each struct <font class="fixd">usb_host_interface</font> consists of a set of</div>
17283 <br>
17284 <A name="332"></a><font color="blue">PAGE 332</font><br>
17285 <br>
17286 <div class="bq">endpoint configurations as defined by the struct <font class="fixd">usb_host_endpoint</font> structure
17287 described above. Note that these interface structures are in no particular order.</div>
17288 <br>
17289 <font class="fixd">unsigned num_altsetting</font><br>
17290 <div class="bq">
17291 The number of alternate settings pointed to by the <font class="fixd">altsetting</font> pointer.</div>
17292 <br>
17293 <font class="fixd">struct usb_host_interface *cur_altsetting</font><br>
17294 <div class="bq">
17295 A pointer into the array <font class="fixd">altsetting,</font> denoting the currently active setting for this
17296 interface.</div>
17297 <br>
17298 <font class="fixd">int minor</font><br>
17299 <div class="bq">
17300 If the USB driver bound to this interface uses the USB major number, this variable
17301 contains the minor number assigned by the USB core to the interface. This
17302 is valid only after a successful call to <font class="fixd">usb_register_dev</font> (described later in this
17303 chapter).</div>
17304 <br>
17305 There are other fields in the <font class="fixd">struct usb_interface</font> structure, but USB drivers do not
17306 need to be aware of them.<br>
17307 <br>
17308 <a name="Configurations"></a><font color="red"><b>Configurations</b></font><br>
17309 <br>
17310 USB interfaces are themselves bundled up into <i>configurations</i>. A USB device can have
17311 multiple configurations and might switch between them in order to change the state
17312 of the device. For example, some devices that allow firmware to be downloaded to
17313 them contain multiple configurations to accomplish this. A single configuration can
17314 be enabled only at one point in time. Linux does not handle multiple configuration
17315 USB devices very well, but, thankfully, they are rare.<br>
17316 <br>
17317 Linux describes USB configurations with the structure <font class="fixd">struct usb_host_config</font> and
17318 entire USB devices with the structure <font class="fixd">struct usb_device</font>. USB device drivers do not
17319 generally ever need to read or write to any values in these structures, so they are not
17320 defined in detail here. The curious reader can find descriptions of them in the file
17321 <i>include/linux/usb.h</i> in the kernel source tree.<br>
17322 <br>
17323 A USB device driver commonly has to convert data from a given struct usb_interface
17324 structure into a <font class="fixd">struct usb_device</font> structure that the USB core needs for a wide range of
17325 function calls. To do this, the function <i>interface_to_usbdev </i>is provided. Hopefully, in the
17326 future, all USB calls that currently need a <font class="fixd">struct usb_device</font> will be converted to take a
17327 <font class="fixd">struct usb_interface</font> parameter and will not require the drivers to do the conversion.<br>
17328 <br>
17329 So to summarize, USB devices are quite complex and are made up of lots of different
17330 logical units. The relationships among these units can be simply described as follows:<br>
17331 <ul>
17332 <li> Devices usually have one or more configurations.
17333 <li> Configurations often have one or more interfaces.
17334 <li> Interfaces usually have one or more settings.
17335 <li> Interfaces have zero or more endpoints.
17336 </ul>
17337 <A name="333"></a><font color="blue">PAGE 333</font><br>
17338 <br>
17339 <a name="USBAndSysfs"></a><font color="red"><b>USB and Sysfs</b></font><br>
17340 <br>
17341 Due to the complexity of a single USB physical device, the representation of that
17342 device in sysfs is also quite complex. Both the physical USB device (as represented by
17343 a <font class="fixd">struct usb_device</font>) and the individual USB interfaces (as represented by a <font class="fixd">struct
17344 usb_interface</font>) are shown in sysfs as individual devices. (This is because both of
17345 those structures contain a <font class="fixd">struct device</font> structure.) As an example, for a simple USB
17346 mouse that contains only one USB interface, the following would be the sysfs directory
17347 tree for that device:<br>
17348 <pre>
17349 /sys/devices/pci0000:00/0000:00:09.0/usb2/2-1
17350 |-- 2-1:1.0
17351 | |-- bAlternateSetting
17352 | |-- bInterfaceClass
17353 | |-- bInterfaceNumber
17354 | |-- bInterfaceProtocol
17355 | |-- bInterfaceSubClass
17356 | |-- bNumEndpoints
17357 | |-- detach_state
17358 | |-- iInterface
17359 | `-- power
17360 | `-- state
17361 |-- bConfigurationValue
17362 |-- bDeviceClass
17363 |-- bDeviceProtocol
17364 |-- bDeviceSubClass
17365 |-- bMaxPower
17366 |-- bNumConfigurations
17367 |-- bNumInterfaces
17368 |-- bcdDevice
17369 |-- bmAttributes
17370 |-- detach_state
17371 |-- devnum
17372 |-- idProduct
17373 |-- idVendor
17374 |-- maxchild
17375 |-- power
17376 | `-- state
17377 |-- speed
17378 `-- version
17379 </pre>
17380 The <font class="fixd">struct usb_device</font> is represented in the tree at:<br>
17381 <pre>
17382 /sys/devices/pci0000:00/0000:00:09.0/usb2/2-1
17383 </pre>
17384 while the USB interface for the mouse--the interface that the USB mouse driver is
17385 bound to--is located at the directory:<br>
17386 <pre>
17387 /sys/devices/pci0000:00/0000:00:09.0/usb2/2-1/2-1:1.0
17388 </pre>
17389 To help understand what this longdevice path means, we describe how the kernel
17390 labels the USB devices.<br>
17391 <br>
17392 <A name="334"></a><font color="blue">PAGE 334</font><br>
17393 <br>
17394 The first USB device is a root hub. This is the USB controller, usually contained in a
17395 PCI device. The controller is so named because it controls the whole USB bus connected
17396 to it. The controller is a bridge between the PCI bus and the USB bus, as well
17397 as being the first USB device on that bus.<br>
17398 <br>
17399 All root hubs are assigned a unique number by the USB core. In our example, the
17400 root hub is called <font class="fixd">usb2,</font> as it is the second root hub that was registered with the USB
17401 core. There is no limit on the number of root hubs that can be contained in a single
17402 system at any time.<br>
17403 <br>
17404 Every device that is on a USB bus takes the number of the root hub as the first number
17405 in its name. That is followed by a - character and then the number of the port
17406 that the device is plugged into. As the device in our example is plugged into the first
17407 port, a <font class="fixd">1</font> is added to the name. So the device name for the main USB mouse device is
17408 <font class="fixd">2-1.</font> Because this USB device contains one interface, that causes another device in the
17409 tree to be added to the sysfs path. The naming scheme for USB interfaces is the
17410 device name up to this point: in our example, it's <font class="fixd">2-1</font> followed by a colon and the
17411 USB configuration number, then a period and the interface number. So for this
17412 example, the device name is <font class="fixd">2-1:1.0</font> because it is the first configuration and has
17413 interface number zero.<br>
17414 <br>
17415 So to summarize, the USB sysfs device naming scheme is:<br>
17416 <pre>
17417 <i>root_hub</i>-<i>hub_port</i>:<i>config</i>.<i>interface</i>
17418 </pre>
17419 As the devices go further down in the USB tree, and as more and more USB hubs are
17420 used, the hub port number is added to the string following the previous hub port
17421 number in the chain. For a two-deep tree, the device name looks like:<br>
17422 <pre>
17423 <i>root_hub</i>-<i>hub_port</i>-<i>hub_port</i>:<i>config</i>.<i>interface</i>
17424 </pre>
17425 As can be seen in the previous directory listing of the USB device and interface, all of
17426 the USB specific information is available directly through sysfs (for example, the idVendor,
17427 idProduct, and bMaxPower information). One of these files, <i>bConfigurationValue</i>,
17428 can be written to in order to change the active USB configuration that is being used.
17429 This is useful for devices that have multiple configurations, when the kernel is unable
17430 to determine what configuration to select in order to properly operate the device. A
17431 number of USB modems need to have the proper configuration value written to this file
17432 in order to have the correct USB driver bind to the device.<br>
17433 <br>
17434 Sysfs does not expose all of the different parts of a USB device, as it stops at the interface
17435 level. Any alternate configurations that the device may contain are not shown, as
17436 well as the details of the endpoints associated with the interfaces. This information
17437 can be found in the <i>usbfs </i>filesystem, which is mounted in the <i>/proc/bus/usb/ </i>directory
17438 on the system. The file <i>/proc/bus/usb/devices </i>does show all of the same information
17439 exposed in sysfs, as well as the alternate configuration and endpoint information<br>
17440 <br>
17441 <A name="335"></a><font color="blue">PAGE 335</font><br>
17442 <br>
17443 for all USB devices that are present in the system. <i>usbfs </i>also allows user-space programs
17444 to directly talk to USB devices, which has enabled a lot of kernel drivers to be
17445 moved out to user space, where it is easier to maintain and debug. The USB scanner
17446 driver is a good example of this, as it is no longer present in the kernel because its
17447 functionality is now contained in the user-space SANE library programs.<br>
17448 <br>
17449 <a name="USBUrbs"></a><font color="red"><b>USB Urbs</b></font><br>
17450 <br>
17451 The USB code in the Linux kernel communicates with all USB devices using something called
17452 a <i>urb </i>(USB request block). This request block is described with the
17453 struct urb structure and can be found in the <i>include/linux/usb.h </i>file.<br>
17454 <br>
17455 A urb is used to send or receive data to or from a specific USB endpoint on a specific
17456 USB device in an asynchronous manner. It is used much like a kiocb structure is used
17457 in the filesystem async I/O code or as a <font class="fixd">struct skbuff</font> is used in the networking code.
17458 A USB device driver may allocate many urbs for a single endpoint or may reuse a single
17459 urb for many different endpoints, depending on the need of the driver. Every endpoint
17460 in a device can handle a queue of urbs, so that multiple urbs can be sent to the
17461 same endpoint before the queue is empty. The typical lifecycle of a urb is as follows:<br>
17462 <ul>
17463 <li> Created by a USB device driver.
17464 <li> Assigned to a specific endpoint of a specific USB device.
17465 <li> Submitted to the USB core, by the USB device driver.
17466 <li> Submitted to the specific USB host controller driver for the specified device by the USB core.
17467 <li> Processed by the USB host controller driver that makes a USB transfer to the device.
17468 <li> When the urb is completed, the USB host controller driver notifies the USB device driver.
17469 </ul>
17470 Urbs can also be canceled any time by the driver that submitted the urb, or by the
17471 USB core if the device is removed from the system. urbs are dynamically created and
17472 contain an internal reference count that enables them to be automatically freed when
17473 the last user of the urb releases it.<br>
17474 <br>
17475 The procedure described in this chapter for handling urbs is useful, because it permits
17476 streaming and other complex, overlapping communications that allow drivers
17477 to achieve the highest possible data transfer speeds. But less cumbersome procedures
17478 are available if you just want to send individual bulk or control messages and
17479 do not care about data throughput rates. (See the section "USB Transfers Without Urbs.")<br>
17480 <br>
17481 <A name="336"></a><font color="blue">PAGE 336</font><br>
17482 <br>
17483 <a name="StructUrb"></a><font color="red"><b>struct urb</b></font><br>
17484 <br>
17485 The fields of the <font class="fixd">struct urb</font> structure that matter to a USB device driver are:<br>
17486 <br>
17487 <font class="fixd">struct usb_device *dev</font><br>
17488 <br>
17489 Pointer to the <font class="fixd">struct usb_device</font> to which this urb is sent. This variable must be
17490 initialized by the USB driver before the urb can be sent to the USB core.<br>
17491 <br>
17492 <font class="fixd">unsigned int pipe</font><br>
17493 <div class="bq">
17494 Endpoint information for the specific <font class="fixd">struct usb_device</font> that this urb is to be
17495 sent to. This variable must be initialized by the USB driver before the urb can be sent to the USB core.<br>
17496 <br>
17497 To set fields of this structure, the driver uses the following functions as appropriate,
17498 depending on the direction of traffic. Note that every endpoint can be of only one type.<br>
17499 <br>
17500 <font class="fixd">unsigned int usb_sndctrlpipe(struct usb_device *dev, unsigned int endpoint)</font><br>
17501 <div class="bq">
17502 Specifies a control OUT endpoint for the specified USB device with the specified endpoint number.</div>
17503 <br>
17504 <font class="fixd">unsigned int usb_rcvctrlpipe(struct usb_device *dev, unsigned int endpoint)</font><br>
17505 <div class="bq">
17506 Specifies a control IN endpoint for the specified USB device with the specified endpoint number.</div>
17507 <br>
17508 <font class="fixd">unsigned int usb_sndbulkpipe(struct usb_device *dev, unsigned int endpoint)</font><br>
17509 <div class="bq">
17510 Specifies a bulk OUT endpoint for the specified USB device with the specified endpoint number.</div>
17511 <br>
17512 <font class="fixd">unsigned int usb_rcvbulkpipe(struct usb_device *dev, unsigned int endpoint)</font><br>
17513 <div class="bq">
17514 Specifies a bulk IN endpoint for the specified USB device with the specified endpoint number.</div>
17515 <br>
17516 <font class="fixd">unsigned int usb_sndintpipe(struct usb_device *dev, unsigned int endpoint)</font><br>
17517 <div class="bq">
17518 Specifies an interrupt OUT endpoint for the specified USB device with the specified endpoint number.</div>
17519 <br>
17520 <font class="fixd">unsigned int usb_rcvintpipe(struct usb_device *dev, unsigned int endpoint)</font><br>
17521 <div class="bq">
17522 Specifies an interrupt IN endpoint for the specified USB device with the specified endpoint number.</div></div>
17523 <br>
17524 <A name="337"></a><font color="blue">PAGE 337</font><br>
17525 <br>
17526 <div class="bq">
17527 <font class="fixd">unsigned int usb_sndisocpipe(struct usb_device *dev, unsigned int endpoint)</font><br>
17528 <div class="bq">
17529 Specifies an isochronous OUT endpoint for the specified USB device with
17530 the specified endpoint number.</div>
17531 <br>
17532 <font class="fixd">unsigned int usb_rcvisocpipe(struct usb_device *dev, unsigned int endpoint)</font><br>
17533 <div class="bq">
17534 Specifies an isochronous IN endpoint for the specified USB device with the
17535 specified endpoint number.</div></div>
17536 <br>
17537 <font class="fixd">unsigned int transfer_flags</font><br>
17538 <div class="bq">
17539 This variable can be set to a number of different bit values, depending on what
17540 the USB driver wants to happen to the urb. The available values are:<br>
17541 <br>
17542 <font class="fixd">URB_SHORT_NOT_OK</font><br>
17543 <div class="bq">
17544 When set, it specifies that any short read on an IN endpoint that might
17545 occur should be treated as an error by the USB core. This value is useful only
17546 for urbs that are to be read from the USB device, not for write urbs.</div>
17547 <br>
17548 <font class="fixd">URB_ISO_ASAP</font><br>
17549 <div class="bq">
17550 If the urb is isochronous, this bit can be set if the driver wants the urb to be
17551 scheduled, as soon as the bandwidth utilization allows it to be, and to set
17552 the <font class="fixd">start_frame</font> variable in the urb at that point. If this bit is not set for an
17553 isochronous urb, the driver must specify the <font class="fixd">start_frame</font> value and must be
17554 able to recover properly if the transfer cannot start at that moment. See the
17555 upcoming section about isochronous urbs for more information.</div>
17556 <br>
17557 <font class="fixd">URB_NO_TRANSFER_DMA_MAP</font><br>
17558 <div class="bq">
17559 Should be set when the urb contains a DMA buffer to be transferred. The
17560 USB core uses the buffer pointed to by the <font class="fixd">transfer_dma</font> variable and not the
17561 buffer pointed to by the <font class="fixd">transfer_buffer</font> variable.</div>
17562 <br>
17563 <font class="fixd">URB_NO_SETUP_DMA_MAP</font><br>
17564 <div class="bq">
17565 Like the <font class="fixd">URB_NO_TRANSFER_DMA_MAP</font> bit, this bit is used for control urbs that
17566 have a DMA buffer already set up. If it is set, the USB core uses the buffer
17567 pointed to by the <font class="fixd">setup_dma</font> variable instead of the <font class="fixd">setup_packet</font> variable.</div>
17568 <br>
17569 <font class="fixd">URB_ASYNC_UNLINK</font><br>
17570 <div class="bq">
17571 If set, the call to <i>usb_unlink_urb </i>for this urb returns almost immediately,
17572 and the urb is unlinked in the background. Otherwise, the function waits
17573 until the urb is completely unlinked and finished before returning. Use this
17574 bit with care, because it can make synchronization issues very difficult to
17575 debug.</div></div>
17576 <br>
17577 <A name="338"></a><font color="blue">PAGE 338</font><br>
17578 <br>
17579 <div class="bq">
17580 <font class="fixd">URB_NO_FSBR</font><br>
17581 <div class="bq">
17582 Used by only the UHCI USB Host controller driver and tells it to not try to
17583 do Front Side Bus Reclamation logic. This bit should generally not be set,
17584 because machines with a UHCI host controller create a lot of CPU overhead,
17585 and the PCI bus is saturated waiting on a urb that sets this bit.</div>
17586 <br>
17587 <font class="fixd">URB_ZERO_PACKET</font><br>
17588 <div class="bq">
17589 If set, a bulk out urb finishes by sending a short packet containing no data
17590 when the data is aligned to an endpoint packet boundary. This is needed by
17591 some broken USB devices (such as a number of USB to IR devices) in order
17592 to work properly.</div>
17593 <br>
17594 <font class="fixd">URB_NO_INTERRUPT</font><br>
17595 <div class="bq">
17596 If set, the hardware may not generate an interrupt when the urb is finished.
17597 This bit should be used with care and only when queuing multiple urbs to
17598 the same endpoint. The USB core functions use this in order to do DMA
17599 buffer transfers.</div></div>
17600 <br>
17601 <font class="fixd">void *transfer_buffer</font><br>
17602 <div class="bq">
17603 Pointer to the buffer to be used when sending data to the device (for an OUT
17604 urb) or when receiving data from the device (for an IN urb). In order for the host
17605 controller to properly access this buffer, it must be created with a call to <font class="fixd">kmalloc,</font>
17606 not on the stack or statically. For control endpoints, this buffer is for the data
17607 stage of the transfer.</div>
17608 <br>
17609 <font class="fixd">dma_addr_t transfer_dma</font><br>
17610 <div class="bq">
17611 Buffer to be used to transfer data to the USB device using DMA.</div>
17612 <br>
17613 <font class="fixd">int transfer_buffer_length</font><br>
17614 <div class="bq">
17615 The length of the buffer pointed to by the <font class="fixd">transfer_buffer</font> or the <font class="fixd">transfer_dma</font>
17616 variable (as only one can be used for a urb). If this is 0, neither transfer buffers
17617 are used by the USB core.<br>
17618 <br>
17619 For an OUT endpoint, if the endpoint maximum size is smaller than the value
17620 specified in this variable, the transfer to the USB device is broken up into smaller
17621 chunks in order to properly transfer the data. This large transfer occurs in consecutive
17622 USB frames. It is much faster to submit a large block of data in one urb,
17623 and have the USB host controller split it up into smaller pieces, than it is to send
17624 smaller buffers in consecutive order.</div>
17625 <br>
17626 <font class="fixd">unsigned char *setup_packet</font><br>
17627 <div class="bq">
17628 Pointer to the setup packet for a control urb. It is transferred before the data in
17629 the transfer buffer. This variable is valid only for control urbs.</div>
17630 <br>
17631 <font class="fixd">dma_addr_t setup_dma</font><br>
17632 <div class="bq">
17633 DMA buffer for the setup packet for a control urb. It is transferred before the
17634 data in the normal transfer buffer. This variable is valid only for control urbs.</div>
17635 <br>
17636 <A name="339"></a><font color="blue">PAGE 339</font><br>
17637 <br>
17638 <font class="fixd">usb_complete_t complete</font><br>
17639 <div class="bq">
17640 Pointer to the completion handler function that is called by the USB core when
17641 the urb is completely transferred or when an error occurs to the urb. Within this
17642 function, the USB driver may inspect the urb, free it, or resubmit it for another
17643 transfer. (See the section "CompletingUrbs: The Completion Callback Handler"
17644 for more details about the completion handler.)
17645 <br>
17646 The <font class="fixd">usb_complete_t</font> typedef is defined as:<br>
17647 <pre>typedef void (*usb_complete_t)(struct urb *, struct pt_regs *);</pre>
17648 </div>
17649 <font class="fixd">void *context</font><br>
17650 <div class="bq">
17651 Pointer to a data blob that can be set by the USB driver. It can be used in the
17652 completion handler when the urb is returned to the driver. See the following section
17653 for more details about this variable.</div>
17654 <br>
17655 <font class="fixd">int actual_length</font><br>
17656 <div class="bq">
17657 When the urb is finished, this variable is set to the actual length of the data
17658 either sent by the urb (for OUT urbs) or received by the urb (for IN urbs.) For
17659 IN urbs, this must be used instead of the <font class="fixd">transfer_buffer_length</font> variable,
17660 because the data received could be smaller than the whole buffer size.</div>
17661 <br>
17662 <font class="fixd">int status</font><br>
17663 <div class="bq">
17664 When the urb is finished, or being processed by the USB core, this variable is set
17665 to the current status of the urb. The only time a USB driver can safely access this
17666 variable is in the urb completion handler function (described in the section
17667 "CompletingUrbs: The Completion Callback Handler"). This restriction is to
17668 prevent race conditions that occur while the urb is being processed by the USB
17669 core. For isochronous urbs, a successful value (0) in this variable merely indicates
17670 whether the urb has been unlinked. To obtain a detailed status on isochronous
17671 urbs, the <font class="fixd">iso_frame_desc</font> variables should be checked.<br>
17672 <br>
17673 Valid values for this variable include:<br>
17674 <br>
17675 <font class="fixd">0</font><br>
17676 <div class="bq">
17677 The urb transfer was successful.</div>
17678 <br>
17679 <font class="fixd">-ENOENT</font><br>
17680 <div class="bq">
17681 The urb was stopped by a call to <i>usb_kill_urb</i>.</div>
17682 <br>
17683 <font class="fixd">-ECONNRESET</font><br>
17684 <div class="bq">
17685 The urb was unlinked by a call to <i>usb_unlink_urb</i>, and the transfer_flags
17686 variable of the urb was set to <font class="fixd">URB_ASYNC_UNLINK</font>.</div>
17687 <br>
17688 <font class="fixd">-EINPROGRESS</font><br>
17689 <div class="bq">
17690 The urb is still being processed by the USB host controllers. If your driver
17691 ever sees this value, it is a bug in your driver.</div>
17692 <br>
17693 <font class="fixd">-EPROTO</font><br>
17694 <div class="bq">
17695 One of the following errors occurred with this urb:</div>
17696 <ul>
17697 <li> A bitstuff error happened during the transfer.
17698 <li> No response packet was received in time by the hardware.
17699 </ul></div>
17700 <A name="340"></a><font color="blue">PAGE 340</font><br>
17701 <br>
17702 <div class="bq">
17703 <font class="fixd">-EILSEQ</font><br>
17704 <div class="bq">
17705 There was a CRC mismatch in the urb transfer.</div>
17706 <br>
17707 <font class="fixd">-EPIPE</font><br>
17708 <div class="bq">
17709 The endpoint is now stalled. If the endpoint involved is not a control endpoint,
17710 this error can be cleared through a call to the function <i>usb_clear_halt</i>.</div>
17711 <br>
17712 <font class="fixd">-ECOMM</font><br>
17713 <div class="bq">
17714 Data was received faster during the transfer than it could be written to system
17715 memory. This error value happens only for an IN urb.</div>
17716 <br>
17717 <font class="fixd">-ENOSR</font><br>
17718 <div class="bq">
17719 Data could not be retrieved from the system memory during the transfer fast
17720 enough to keep up with the requested USB data rate. This error value happens
17721 only for an OUT urb.</div>
17722 <br>
17723 <font class="fixd">-EOVERFLOW</font><br>
17724 <div class="bq">
17725 A "babble" error happened to the urb. A "babble" error occurs when the
17726 endpoint receives more data than the endpoint's specified maximum packet
17727 size.</div>
17728 <br>
17729 <font class="fixd">-EREMOTEIO</font><br>
17730 <div class="bq">
17731 Occurs only if the <font class="fixd">URB_SHORT_NOT_OK</font> flag is set in the urb's transfer_flags
17732 variable and means that the full amount of data requested by the urb was
17733 not received.</div>
17734 <br>
17735 <font class="fixd">-ENODEV</font><br>
17736 <div class="bq">
17737 The USB device is now gone from the system.</div>
17738 <br>
17739 <font class="fixd">-EXDEV</font><br>
17740 <div class="bq">
17741 Occurs only for a isochronous urb and means that the transfer was only partially
17742 completed. In order to determine what was transferred, the driver
17743 must look at the individual frame status.</div>
17744 <br>
17745 <font class="fixd">-EINVAL</font><br>
17746 <div class="bq">
17747 Something very bad happened with the urb. The USB kernel documentation
17748 describes what this value means:<br>
17749 <pre>
17750 ISO madness, if this happens: Log off and go home
17751 </pre>
17752 It also can happen if a parameter is incorrectly set in the urb stucture or if an
17753 incorrect function parameter in the <i>usb_submit_urb </i>call submitted the urb to
17754 the USB core.</div>
17755 <br>
17756 <font class="fixd">-ESHUTDOWN</font><br>
17757 <div class="bq">
17758 There was a severe error with the USB host controller driver; it has now
17759 been disabled, or the device was disconnected from the system, and the urb
17760 was submitted after the device was removed. It can also occur if the configuration
17761 was changed for the device, while the urb was submitted to the
17762 device.</div></div>
17763 <br>
17764 <A name="341"></a><font color="blue">PAGE 341</font><br>
17765 <br>
17766 <div class="bq">Generally, the error values <font class="fixd">-EPROTO, -EILSEQ,</font> and <font class="fixd">-EOVERFLOW</font> indicate hardware
17767 problems with the device, the device firmware, or the cable connecting the device to the computer.</div>
17768 <br>
17769 <font class="fixd">int start_frame</font><br>
17770 <div class="bq">
17771 Sets or returns the initial frame number for isochronous transfers to use.</div>
17772 <br>
17773 <font class="fixd">int interval</font><br>
17774 <div class="bq">
17775 The interval at which the urb is polled. This is valid only for interrupt or isochronous
17776 urbs. The value's units differ depending on the speed of the device. For
17777 low-speed and full-speed devices, the units are frames, which are equivalent to
17778 milliseconds. For devices, the units are in microframes, which is equivalent to
17779 units of 1/8 milliseconds. This value must be set by the USB driver for isochronous
17780 or interrupt urbs before the urb is sent to the USB core.</div>
17781 <br>
17782 <font class="fixd">int number_of_packets</font><br>
17783 <div class="bq">
17784 Valid only for isochronous urbs and specifies the number of isochronous transfer
17785 buffers to be handled by this urb. This value must be set by the USB driver
17786 for isochronous urbs before the urb is sent to the USB core.</div>
17787 <br>
17788 <font class="fixd">int error_count</font><br>
17789 <div class="bq">
17790 Set by the USB core only for isochronous urbs after their completion. It specifies
17791 the number of isochronous transfers that reported any type of error.</div>
17792 <br>
17793 <font class="fixd">struct usb_iso_packet_descriptor iso_frame_desc[0]</font><br>
17794 <div class="bq">
17795 Valid only for isochronous urbs. This variable is an array of the <font class="fixd">struct usb_iso_packet_descriptor</font>
17796 structures that make up this urb. This structure allows a single
17797 urb to define a number of isochronous transfers at once. It is also used to collect
17798 the transfer status of each individual transfer.<br>
17799 <br>
17800 The <font class="fixd">struct usb_iso_packet_descriptor</font> is made up of the following fields:<br>
17801 <br>
17802 <font class="fixd">unsigned int offset</font><br>
17803 <div class="bq">
17804 The offset into the transfer buffer (starting at 0 for the first byte) where this
17805 packet's data is located.</div>
17806 <br>
17807 <font class="fixd">unsigned int length</font><br>
17808 <div class="bq">
17809 The length of the transfer buffer for this packet.</div>
17810 <br>
17811 <font class="fixd">unsigned int actual_length</font><br>
17812 <div class="bq">
17813 The length of the data received into the transfer buffer for this isochronous
17814 packet.</div>
17815 <br>
17816 <font class="fixd">unsigned int status</font><br>
17817 <div class="bq">
17818 The status of the individual isochronous transfer of this packet. It can take
17819 the same return values as the main <font class="fixd">struct urb</font> structure's status variable.</div></div>
17820 <br>
17821 <a name="CreatingAndDestroyingUrbs"></a><font color="red"><b>Creating and Destroying Urbs</b></font><br>
17822 <br>
17823 The <font class="fixd">struct urb</font> structure must never be created statically in a driver or within
17824 another structure, because that would break the reference counting scheme used by<br>
17825 <br>
17826 <A name="342"></a><font color="blue">PAGE 342</font><br>
17827 <br>
17828 the USB core for urbs. It must be created with a call to the <i>usb_alloc_urb </i>function.
17829 This function has the prototype:<br>
17830 <pre>
17831 struct urb *usb_alloc_urb(int iso_packets, int mem_flags);
17832 </pre>
17833 The first parameter, <font class="fixd">iso_packets,</font> is the number of isochronous packets this urb
17834 should contain. If you do not want to create an isochronous urb, this variable should
17835 be set to 0. The second parameter, <font class="fixd">mem_flags,</font> is the same type of flag that is passed
17836 to the <i>kmalloc </i>function call to allocate memory from the kernel (see the section "The
17837 Flags Argument" in Chapter 8 for the details on these flags). If the function is successful
17838 in allocating enough space for the urb, a pointer to the urb is returned to the
17839 caller. If the return value is <font class="fixd">NULL</font>, some error occurred within the USB core, and the
17840 driver needs to clean up properly.<br>
17841 <br>
17842 After a urb has been created, it must be properly initialized before it can be used by
17843 the USB core. See the next sections for how to initialize different types of urbs.<br>
17844 <br>
17845 In order to tell the USB core that the driver is finished with the urb, the driver must
17846 call the <i>usb_free_urb</i> function. This function only has one argument:<br>
17847 <pre>
17848 void usb_free_urb(struct urb *urb);
17849 </pre>
17850 The argument is a pointer to the <font class="fixd">struct urb</font> you want to release. After this function
17851 is called, the urb structure is gone, and the driver cannot access it any more.<br>
17852 <br>
17853 <a name="InterruptUrbs"></a><font color="red"><b>Interrupt urbs</b></font><br>
17854 <br>
17855 The function <i>usb_fill_int_urb </i>is a helper function to properly initialize a urb to be
17856 sent to a interrupt endpoint of a USB device:<br>
17857 <pre>
17858 void usb_fill_int_urb(struct urb *urb, struct usb_device *dev,
17859 unsigned int pipe, void *transfer_buffer,
17860 int buffer_length, usb_complete_t complete,
17861 void *context, int interval);
17862 </pre>
17863 This function contains a lot of parameters:<br>
17864 <br>
17865 <font class="fixd">struct urb *urb</font><br>
17866 <div class="bq">
17867 A pointer to the urb to be initialized.</div>
17868 <br>
17869 <font class="fixd">struct usb_device *dev</font><br>
17870 <div class="bq">
17871 The USB device to which this urb is to be sent.</div>
17872 <br>
17873 <font class="fixd">unsigned int pipe</font><br>
17874 <div class="bq">
17875 The specific endpoint of the USB device to which this urb is to be sent. This
17876 value is created with the previously mentioned <i>usb_sndintpipe </i>or <i>usb_rcvintpipe
17877 </i>functions.</div>
17878 <br>
17879 <font class="fixd">void *transfer_buffer</font><br>
17880 <div class="bq">
17881 A pointer to the buffer from which outgoing data is taken or into which incoming data
17882 is received. Note that this can not be a static buffer and must be created
17883 with a call to <i>kmalloc</i>.</div>
17884 <br>
17885 <A name="343"></a><font color="blue">PAGE 343</font><br>
17886 <br>
17887 <font class="fixd">int buffer_length</font><br>
17888 <div class="bq">
17889 The length of the buffer pointed to by the <font class="fixd">transfer_buffer</font> pointer.</div>
17890 <br>
17891 <font class="fixd">usb_complete_t complete</font><br>
17892 <div class="bq">
17893 Pointer to the completion handler that is called when this urb is completed.</div>
17894 <br>
17895 <font class="fixd">void *context</font><br>
17896 <div class="bq">
17897 Pointer to the blob that is added to the urb structure for later retrieval by the
17898 completion handler function.</div>
17899 <br>
17900 <font class="fixd">int interval</font><br>
17901 <div class="bq">
17902 The interval at which that this urb should be scheduled. See the previous
17903 description of the <font class="fixd">struct urb</font> structure to find the proper units for this value.</div>
17904 <br>
17905 <a name="BulkUrbs"></a><font color="red"><b>Bulk urbs</b></font><br>
17906 <br>
17907 Bulk urbs are initialized much like interrupt urbs. The function that does this is
17908 <i>usb_fill_bulk_urb</i>, and it looks like:<br>
17909 <pre>
17910 void usb_fill_bulk_urb(struct urb *urb, struct usb_device *dev,
17911 unsigned int pipe, void *transfer_buffer,
17912 int buffer_length, usb_complete_t complete,
17913 void *context);
17914 </pre>
17915 The function parameters are all the same as in the <i>usb_fill_int_urb </i>function. However,
17916 there is no interval parameter because bulk urbs have no interval value. Please
17917 note that the <font class="fixd">unsigned int pipe</font> variable must be initialized with a call to the <i>usb_sndbulkpipe</i>
17918 or <i>usb_rcvbulkpipe</i> function.<br>
17919 <br>
17920 The <i>usb_fill_int_urb </i>function does not set the <font class="fixd">transfer_flags</font> variable in the urb, so
17921 any modification to this field has to be done by the driver itself.<br>
17922 <br>
17923 <a name="ControlUrbs"></a><font color="red"><b>Control urbs</b></font><br>
17924 <br>
17925 Control urbs are initialized almost the same way as bulk urbs, with a call to the function
17926 <i>usb_fill_control_urb</i>:<br>
17927 <pre>
17928 void usb_fill_control_urb(struct urb *urb, struct usb_device *dev,
17929 unsigned int pipe, unsigned char *setup_packet,
17930 void *transfer_buffer, int buffer_length,
17931 usb_complete_t complete, void *context);
17932 </pre>
17933 The function parameters are all the same as in the <i>usb_fill_bulk_urb </i>function, except
17934 that there is a new parameter, <font class="fixd">unsigned char *setup_packet,</font> which must point to the
17935 setup packet data that is to be sent to the endpoint. Also, the <font class="fixd">unsigned int pipe</font> variable
17936 must be initialized with a call to the <i>usb_sndctrlpipe</i> or <i>usb_rcvictrlpipe</i> function.<br>
17937 <br>
17938 The <i>usb_fill_control_urb </i>function does not set the <font class="fixd">transfer_flags</font> variable in the urb,
17939 so any modification to this field has to be done by the driver itself. Most drivers do
17940 not use this function, as it is much simpler to use the synchronous API calls as
17941 described in the section "USB Transfers Without Urbs."<br>
17942 <br>
17943 <A name="344"></a><font color="blue">PAGE 344</font><br>
17944 <br>
17945 <a name="IsochronousUrbs"></a><font color="red"><b>Isochronous urbs</b></font><br>
17946 <br>
17947 Isochronous urbs unfortunately do not have an initializer function like the interrupt,
17948 control, and bulk urbs do. So they must be initialized "by hand" in the driver before
17949 they can be submitted to the USB core. The following is an example of how to properly
17950 initialize this type of urb. It was taken from the <i>konicawc.c </i>kernel driver located
17951 in the <i>drivers/usb/media</i> directory in the main kernel source tree.<br>
17952 <pre>
17953 urb->dev = dev;
17954 urb->context = uvd;
17955 urb->pipe = usb_rcvisocpipe(dev, uvd->video_endp-1);
17956 urb->interval = 1;
17957 urb->transfer_flags = URB_ISO_ASAP;
17958 urb->transfer_buffer = cam->sts_buf[i];
17959 urb->complete = konicawc_isoc_irq;
17960 urb->number_of_packets = FRAMES_PER_DESC;
17961 urb->transfer_buffer_length = FRAMES_PER_DESC;
17962 for (j=0; j < FRAMES_PER_DESC; j++) {
17963 urb->iso_frame_desc[j].offset = j;
17964 urb->iso_frame_desc[j].length = 1;
17965 }
17966 </pre>
17967 <a name="SubmittingUrbs"></a><font color="red"><b>Submitting Urbs</b></font><br>
17968 <br>
17969 Once the urb has been properly created and initialized by the USB driver, it is ready
17970 to be submitted to the USB core to be sent out to the USB device. This is done with a
17971 call to the function <i>usb_submit_urb</i>:<br>
17972 <pre>
17973 int usb_submit_urb(struct urb *urb, int mem_flags);
17974 </pre>
17975 The urb parameter is a pointer to the urb that is to be sent to the device. The <font class="fixd">mem_flags</font>
17976 parameter is equivalent to the same parameter that is passed to the <i>kmalloc </i>call and is
17977 used to tell the USB core how to allocate any memory buffers at this moment in time.<br>
17978 <br>
17979 After a urb has been submitted to the USB core successfully, it should never try to
17980 access any fields of the urb structure until the <i>complete</i> function is called.<br>
17981 <br>
17982 Because the function <i>usb_submit_urb </i>can be called at any time (including from
17983 within an interrupt context), the specification of the <font class="fixd">mem_flags</font> variable must be correct.
17984 There are really only three valid values that should be used, depending on when
17985 <i>usb_submit_urb</i> is being called:<br>
17986 <br>
17987 <font class="fixd">GFP_ATOMIC</font><br>
17988 <div class="bq">
17989 This value should be used whenever the following are true:<br>
17990 <ul>
17991 <li> The caller is within a urb completion handler, an interrupt, a bottom half, a tasklet, or a timer callback.
17992 <li> The caller is holding a spinlock or rwlock. Note that if a semaphore is being held, this value is not necessary.
17993 <li> The <font class="fixd">current->state</font> is not <font class="fixd">TASK_RUNNING</font>. The state is
17994 always <font class="fixd">TASK_RUNNING</font> unless the driver has changed the current state itself.
17995 </ul></div>
17996 <A name="345"></a><font color="blue">PAGE 345</font><br>
17997 <br>
17998 <font class="fixd">GFP_NOIO</font><br>
17999 <div class="bq">
18000 This value should be used if the driver is in the block I/O patch. It should also be
18001 used in the error handling path of all storage-type devices.</div>
18002 <br>
18003 <font class="fixd">GFP_KERNEL</font><br>
18004 <div class="bq">
18005 This should be used for all other situations that do not fall into one of the previously
18006 mentioned categories.</div>
18007 <br>
18008 <a name="CompletingUrbsTheCompletionCallbackHandler"></a><font color="red"><b>Completing Urbs: The Completion Callback Handler</b></font><br>
18009 <br>
18010 If the call to <i>usb_submit_urb </i>was successful, transferring control of the urb to the
18011 USB core, the function returns 0; otherwise, a negative error number is returned. If
18012 the function succeeds, the completion handler of the urb (as specified by the <i>complete
18013 </i>function pointer) is called exactly once when the urb is completed. When this
18014 function is called, the USB core is finished with the URB, and control of it is now
18015 returned to the device driver.<br>
18016 <br>
18017 There are only three ways a urb can be finished and have the <i>complete </i>function
18018 called:<br>
18019 <ul>
18020 <li> The urb is successfully sent to the device, and the device returns the proper
18021 acknowledgment. For an OUT urb, the data was successfully sent, and for an IN
18022 urb, the requested data was successfully received. If this has happened, the
18023 <font class="fixd">status</font> variable in the urb is set to 0.
18024 <li> Some kind of error happened when sending or receiving data from the device.
18025 This is noted by the error value in the <font class="fixd">status</font> variable in the urb structure.
18026 <li> The urb was "unlinked" from the USB core. This happens either when the driver
18027 tells the USB core to cancel a submitted urb with a call to <i>usb_unlink_urb </i>or
18028 <i>usb_kill_urb</i>, or when a device is removed from the system and a urb had been
18029 submitted to it.
18030 </ul>
18031 An example of how to test for the different return values within a urb completion call
18032 is shown later in this chapter.<br>
18033 <br>
18034 <a name="CancelingUrbs"></a><font color="red"><b>Canceling Urbs</b></font><br>
18035 <br>
18036 To stop a urb that has been submitted to the USB core, the functions <i>usb_kill_urb </i>or
18037 <i>usb_unlink_urb</i> should be called:<br>
18038 <pre>
18039 int usb_kill_urb(struct urb *urb);
18040 int usb_unlink_urb(struct urb *urb);
18041 </pre>
18042 The <font class="fixd">urb</font> parameter for both of these functions is a pointer to the urb that is to be
18043 canceled.<br>
18044 <br>
18045 <A name="346"></a><font color="blue">PAGE 346</font><br>
18046 <br>
18047 When the function is <i>usb_kill_urb</i>, the urb lifecycle is stopped. This function is
18048 usually used when the device is disconnected from the system, in the disconnect
18049 callback.<br>
18050 <br>
18051 For some drivers, the <i>usb_unlink_urb </i>function should be used to tell the USB core to
18052 stop an urb. This function does not wait for the urb to be fully stopped before
18053 returning to the caller. This is useful for stopping the urb while in an interrupt handler
18054 or when a spinlock is held, as waiting for a urb to fully stop requires the ability
18055 for the USB core to put the calling process to sleep. This function requires
18056 that the <font class="fixd">URB_ASYNC_UNLINK</font> flag value be set in the urb that is being asked to be
18057 stopped in order to work properly.<br>
18058 <br>
18059 <a name="WritingAUSBDriver"></a><font color="red"><b>Writing a USB Driver</b></font><br>
18060 <br>
18061 The approach to writing a USB device driver is similar to a <font class="fixd">pci_driver:</font> the driver registers
18062 its driver object with the USB subsystem and later uses vendor and device identifiers
18063 to tell if its hardware has been installed.<br>
18064 <br>
18065 <a name="WhatDevicesDoesTheDriverSupport"></a><font color="red"><b>What Devices Does the Driver Support?</b></font><br>
18066 <br>
18067 The <font class="fixd">struct usb_device_id</font> structure provides a list of different types of USB devices
18068 that this driver supports. This list is used by the USB core to decide which driver to
18069 give a device to, and by the hotplug scripts to decide which driver to automatically
18070 load when a specific device is plugged into the system.<br>
18071 <br>
18072 The struct <font class="fixd">usb_device_id</font> structure is defined with the following fields:<br>
18073 <br>
18074 <font class="fixd">__u16 match_flags</font><br>
18075 <div class="bq">
18076 Determines which of the following fields in the structure the device should be
18077 matched against. This is a bit field defined by the different <font class="fixd">USB_DEVICE_ID_MATCH_*</font>
18078 values specified in the <i>include/linux/mod_devicetable.h </i>file. This field is usually
18079 never set directly but is initialized by the <font class="fixd">USB_DEVICE</font> type macros described later.</div>
18080 <br>
18081 <font class="fixd">__u16 idVendor</font><br>
18082 <div class="bq">
18083 The USB vendor ID for the device. This number is assigned by the USB forum to
18084 its members and cannot be made up by anyone else.</div>
18085 <br>
18086 <font class="fixd">__u16 idProduct</font><br>
18087 <div class="bq">
18088 The USB product ID for the device. All vendors that have a vendor ID assigned
18089 to them can manage their product IDs however they choose to.</div>
18090 <br>
18091 <font class="fixd">__u16 bcdDevice_lo<br>
18092 __u16 bcdDevice_hi</font><br>
18093 <div class="bq">
18094 Define the low and high ends of the range of the vendor-assigned product version
18095 number. The <font class="fixd">bcdDevice_hi</font> value is inclusive; its value is the number of the
18096 highest-numbered device. Both of these values are expressed in binary-coded</div>
18097 <br>
18098 <A name="347"></a><font color="blue">PAGE 347</font><br>
18099 <br>
18100 <div class="bq">decimal (BCD) form. These variables, combined with the <font class="fixd">idVendor</font> and
18101 <font class="fixd">idProduct,</font> are used to define a specific version of a device.</div>
18102 <br>
18103 <font class="fixd">__u8 bDeviceClass<br>
18104 __u8 bDeviceSubClass<br>
18105 __u8 bDeviceProtocol</font><br>
18106 <div class="bq">
18107 Define the class, subclass, and protocol of the device, respectively. These numbers
18108 are assigned by the USB forum and are defined in the USB specification.
18109 These values specify the behavior for the whole device, including all interfaces
18110 on this device.</div>
18111 <br>
18112 <font class="fixd">__u8 bInterfaceClass<br>
18113 __u8 bInterfaceSubClass<br>
18114 __u8 bInterfaceProtocol</font><br>
18115 <div class="bq">
18116 Much like the device-specific values above, these define the class, subclass, and
18117 protocol of the individual interface, respectively. These numbers are assigned by
18118 the USB forum and are defined in the USB specification.</div>
18119 <br>
18120 <font class="fixd">kernel_ulong_t driver_info</font><br>
18121 <div class="bq">
18122 This value is not used to match against, but it holds information that the driver
18123 can use to differentiate the different devices from each other in the <font class="fixd">probe</font> callback
18124 function to the USB driver.</div>
18125 <br>
18126 As with PCI devices, there are a number of macros that are used to initialize this
18127 structure:<br>
18128 <br>
18129 <font class="fixd">USB_DEVICE(vendor, product)</font><br>
18130 <div class="bq">
18131 Creates a struct <font class="fixd">usb_device_id</font> that can be used to match only the specified vendor
18132 and product ID values. This is very commonly used for USB devices that
18133 need a specific driver.</div>
18134 <br>
18135 <font class="fixd">USB_DEVICE_VER(vendor, product, lo, hi)</font><br>
18136 <div class="bq">
18137 Creates a struct <font class="fixd">usb_device_id</font> that can be used to match only the specified vendor
18138 and product ID values within a version range.</div>
18139 <br>
18140 <font class="fixd">USB_DEVICE_INFO(class, subclass, protocol)</font><br>
18141 <div class="bq">
18142 Creates a struct <font class="fixd">usb_device_id</font> that can be used to match a specific class of USB
18143 devices.</div>
18144 <br>
18145 <font class="fixd">USB_INTERFACE_INFO(class, subclass, protocol)</font><br>
18146 <div class="bq">
18147 Creates a struct <font class="fixd">usb_device_id</font> that can be used to match a specific class of USB
18148 interfaces.</div>
18149 <br>
18150 So, for a simple USB device driver that controls only a single USB device from a single
18151 vendor, the struct <font class="fixd">usb_device_id</font> table would be defined as:<br>
18152 <pre>
18153 /* table of devices that work with this driver */
18154 static struct usb_device_id skel_table [ ] = {
18155 { USB_DEVICE(USB_SKEL_VENDOR_ID, USB_SKEL_PRODUCT_ID) },
18156 { } /* Terminating entry */
18157 };
18158 MODULE_DEVICE_TABLE (usb, skel_table);
18159 </pre>
18160 <A name="348"></a><font color="blue">PAGE 348</font><br>
18161 <br>
18162 As with a PCI driver, the <font class="fixd">MODULE_DEVICE_TABLE</font> macro is necessary to allow user-space
18163 tools to figure out what devices this driver can control. But for USB drivers, the string
18164 <font class="fixd">usb</font> must be the first value in the macro.<br>
18165 <br>
18166 <a name="RegisteringAUSBDriver"></a><font color="red"><b>Registering a USB Driver</b></font><br>
18167 <br>
18168 The main structure that all USB drivers must create is a <font class="fixd">struct usb_driver</font>. This
18169 structure must be filled out by the USB driver and consists of a number of function
18170 callbacks and variables that describe the USB driver to the USB core code:<br>
18171 <br>
18172 <font class="fixd">struct module *owner</font><br>
18173 <div class="bq">
18174 Pointer to the module owner of this driver. The USB core uses it to properly reference
18175 count this USB driver so that it is not unloaded at inopportune moments.
18176 The variable should be set to the <font class="fixd">THIS_MODULE</font> macro.</div>
18177 <br>
18178 <font class="fixd">const char *name</font><br>
18179 <div class="bq">
18180 Pointer to the name of the driver. It must be unique among all USB drivers in the
18181 kernel and is normally set to the same name as the module name of the driver. It
18182 shows up in sysfs under <i>/sys/bus/usb/drivers/</i> when the driver is in the kernel.</div>
18183 <br>
18184 <font class="fixd">const struct usb_device_id *id_table</font><br>
18185 <div class="bq">
18186 Pointer to the <font class="fixd">struct usb_device_id</font> table that contains a list of all of the different
18187 kinds of USB devices this driver can accept. If this variable is not set, the
18188 probe function callback in the USB driver is never called. If you want your driver
18189 always to be called for every USB device in the system, create a entry that sets
18190 only the <font class="fixd">driver_info</font> field:</div>
18191 <pre>
18192 static struct usb_device_id usb_ids[ ] = {
18193 {.driver_info = 42},
18194 { }
18195 };
18196 </pre>
18197 <font class="fixd">int (*probe) (struct usb_interface *intf, const struct usb_device_id *id)</font><br>
18198 <div class="bq">
18199 Pointer to the probe function in the USB driver. This function (described in the
18200 section "probe and disconnect in Detail") is called by the USB core when it
18201 thinks it has a <font class="fixd">struct usb_interface</font> that this driver can handle. A pointer to the
18202 <font class="fixd">struct usb_device_id</font> that the USB core used to make this decision is also passed
18203 to this function. If the USB driver claims the <font class="fixd">struct usb_interface</font> that is passed
18204 to it, it should initialize the device properly and return 0. If the driver does not
18205 want to claim the device, or an error occurs, it should return a negative error value.</div>
18206 <br>
18207 <font class="fixd">void (*disconnect) (struct usb_interface *intf)</font><br>
18208 <div class="bq">
18209 Pointer to the disconnect function in the USB driver. This function (described in
18210 the section "probe and disconnect in Detail") is called by the USB core when the
18211 <font class="fixd">struct usb_interface</font> has been removed from the system or when the driver is
18212 being unloaded from the USB core.</div>
18213 <br>
18214 <A name="349"></a><font color="blue">PAGE 349</font><br>
18215 <br>
18216 So, to create a value <font class="fixd">struct usb_driver</font> structure, only five fields need to be initialized:<br>
18217 <pre>
18218 static struct usb_driver skel_driver = {
18219 .owner = THIS_MODULE,
18220 .name = "skeleton",
18221 .id_table = skel_table,
18222 .probe = skel_probe,
18223 .disconnect = skel_disconnect,
18224 };
18225 </pre>
18226 The <font class="fixd">struct usb_driver</font> does contain a few more callbacks, which are generally not
18227 used very often, and are not required in order for a USB driver to work properly:<br>
18228 <br>
18229 <font class="fixd">int (*ioctl) (struct usb_interface *intf, unsigned int code, void *buf)</font><br>
18230 <div class="bq">
18231 Pointer to an <i>ioctl </i>function in the USB driver. If it is present, it is called when a
18232 user-space program makes a <i>ioctl </i>call on the <i>usbfs </i>filesystem device entry associated
18233 with a USB device attached to this USB driver. In practice, only the USB hub
18234 driver uses this ioctl, as there is no other real need for any other USB driver to use it.</div>
18235 <br>
18236 <font class="fixd">int (*suspend) (struct usb_interface *intf, u32 state)</font><br>
18237 <div class="bq">
18238 Pointer to a suspend function in the USB driver. It is called when the device is to
18239 be suspended by the USB core.</div>
18240 <br>
18241 <font class="fixd">int (*resume) (struct usb_interface *intf)</font><br>
18242 <div class="bq">
18243 Pointer to a resume function in the USB driver. It is called when the device is
18244 being resumed by the USB core.</div>
18245 <br>
18246 To register the <font class="fixd">struct usb_driver</font> with the USB core, a call to <i>usb_register_driver </i>is
18247 made with a pointer to the <font class="fixd">struct usb_driver</font>. This is traditionally done in the module
18248 initialization code for the USB driver:<br>
18249 <pre>
18250 static int __init usb_skel_init(void)
18251 {
18252 int result;
18254 /* register this driver with the USB subsystem */
18255 result = usb_register(&skel_driver);
18256 if (result)
18257 err("usb_register failed. Error number %d", result);
18259 return result;
18260 }
18261 </pre>
18262 When the USB driver is to be unloaded, the <font class="fixd">struct usb_driver</font> needs to be unregistered
18263 from the kernel. This is done with a call to <i>usb_deregister_driver</i>. When this
18264 call happens, any USB interfaces that were currently bound to this driver are disconnected,
18265 and the <i>disconnect</i> function is called for them.<br>
18266 <pre>
18267 static void __exit usb_skel_exit(void)
18268 {
18269 /* deregister this driver with the USB subsystem */
18270 usb_deregister(&skel_driver);
18271 }
18272 </pre>
18273 <A name="350"></a><font color="blue">PAGE 350</font><br>
18274 <br>
18275 <a name="ProbeAndDisconnectInDetail"></a><font color="red"><b>probe and disconnect in Detail</b></font><br>
18276 <br>
18277 In the <font class="fixd">struct usb_driver</font> structure described in the previous section, the driver specified
18278 two functions that the USB core calls at appropriate times. The <i>probe </i>function is
18279 called when a device is installed that the USB core thinks this driver should handle;
18280 the <i>probe </i>function should perform checks on the information passed to it about the
18281 device and decide whether the driver is really appropriate for that device. The <i>disconnect
18282 </i>function is called when the driver should no longer control the device for some
18283 reason and can do clean-up.<br>
18284 <br>
18285 Both the <i>probe </i>and <i>disconnect </i>function callbacks are called in the context of the USB
18286 hub kernel thread, so it is legal to sleep within them. However, it is recommended
18287 that the majority of work be done when the device is opened by a user if possible, in
18288 order to keep the USB probingtime to a minimum. This is because the USB core
18289 handles the addition and removal of USB devices within a single thread, so any slow
18290 device driver can cause the USB device detection time to slow down and become
18291 noticeable by the user.<br>
18292 <br>
18293 In the <i>probe </i>function callback, the USB driver should initialize any local structures
18294 that it might use to manage the USB device. It should also save any information that
18295 it needs about the device to the local structure, as it is usually easier to do so at this
18296 time. As an example, USB drivers usually want to detect what the endpoint address
18297 and buffer sizes are for the device, as they are needed in order to communicate with
18298 the device. Here is some example code that detects both IN and OUT endpoints of
18299 BULK type and saves some information about them in a local device structure:<br>
18300 <pre>
18301 /* set up the endpoint information */
18302 /* use only the first bulk-in and bulk-out endpoints */
18303 iface_desc = interface->cur_altsetting;
18304 for (i = 0; i < iface_desc->desc.bNumEndpoints; ++i) {
18305 endpoint = &iface_desc->endpoint[i].desc;
18307 if (!dev->bulk_in_endpointAddr &&
18308 (endpoint->bEndpointAddress & USB_DIR_IN) &&
18309 ((endpoint->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK)
18310 = = USB_ENDPOINT_XFER_BULK)) {
18311 /* we found a bulk in endpoint */
18312 buffer_size = endpoint->wMaxPacketSize;
18313 dev->bulk_in_size = buffer_size;
18314 dev->bulk_in_endpointAddr = endpoint->bEndpointAddress;
18315 dev->bulk_in_buffer = kmalloc(buffer_size, GFP_KERNEL);
18316 if (!dev->bulk_in_buffer) {
18317 err("Could not allocate bulk_in_buffer");
18318 goto error;
18319 }
18320 }
18322 if (!dev->bulk_out_endpointAddr &&
18323 !(endpoint->bEndpointAddress & USB_DIR_IN) &&
18324 ((endpoint->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK)
18325 </pre>
18326 <A name="351"></a><font color="blue">PAGE 351</font><br>
18327 <pre>
18328 = = USB_ENDPOINT_XFER_BULK)) {
18329 /* we found a bulk out endpoint */
18330 dev->bulk_out_endpointAddr = endpoint->bEndpointAddress;
18331 }
18332 }
18333 if (!(dev->bulk_in_endpointAddr && dev->bulk_out_endpointAddr)) {
18334 err("Could not find both bulk-in and bulk-out endpoints");
18335 goto error;
18336 }
18337 </pre>
18338 This block of code first loops over every endpoint that is present in this interface and
18339 assigns a local pointer to the endpoint structure to make it easier to access later:<br>
18340 <pre>
18341 for (i = 0; i < iface_desc->desc.bNumEndpoints; ++i) {
18342 endpoint = &iface_desc->endpoint[i].desc;
18343 </pre>
18344 Then, after we have an endpoint, and we have not found a bulk IN type endpoint
18345 already, we look to see if this endpoint's direction is IN. That can be tested by seeing
18346 whether the bitmask <font class="fixd">USB_DIR_IN</font> is contained in the <font class="fixd">bEndpointAddress </font>endpoint variable.
18347 If this is true, we determine whether the endpoint type is bulk or not, by first
18348 maskingoff the <font class="fixd">bmAttributes</font> variable with the <font class="fixd">USB_ENDPOINT_XFERTYPE_MASK</font> bitmask,
18349 and then checking if it matches the value <font class="fixd">USB_ENDPOINT_XFER_BULK:</font><br>
18350 <pre>
18351 if (!dev->bulk_in_endpointAddr &&
18352 (endpoint->bEndpointAddress & USB_DIR_IN) &&
18353 ((endpoint->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK)
18354 = = USB_ENDPOINT_XFER_BULK)) {
18355 </pre>
18356 If all of these tests are true, the driver knows it found the proper type of endpoint
18357 and can save the information about the endpoint that it will later need to communicate
18358 over it in a local structure:<br>
18359 <pre>
18360 /* we found a bulk in endpoint */
18361 buffer_size = endpoint->wMaxPacketSize;
18362 dev->bulk_in_size = buffer_size;
18363 dev->bulk_in_endpointAddr = endpoint->bEndpointAddress;
18364 dev->bulk_in_buffer = kmalloc(buffer_size, GFP_KERNEL);
18365 if (!dev->bulk_in_buffer) {
18366 err("Could not allocate bulk_in_buffer");
18367 goto error;
18368 }
18369 </pre>
18370 Because the USB driver needs to retrieve the local data structure that is associated
18371 with this <font class="fixd">struct usb_interface</font> later in the lifecycle of the device, the function
18372 <i>usb_set_intfdata</i> can be called:<br>
18373 <pre>
18374 /* save our data pointer in this interface device */
18375 usb_set_intfdata(interface, dev);
18376 </pre>
18377 This function accepts a pointer to any data type and saves it in the <font class="fixd">struct usb_interface</font>
18378 structure for later access. To retrieve the data, the function <i>usb_get_intfdata </i>should
18379 be called:<br>
18380 <pre>
18381 struct usb_skel *dev;
18382 struct usb_interface *interface;
18383 </pre>
18384 <A name="352"></a><font color="blue">PAGE 352</font><br>
18385 <pre>
18386 int subminor;
18387 int retval = 0;
18389 subminor = iminor(inode);
18391 interface = usb_find_interface(&skel_driver, subminor);
18392 if (!interface) {
18393 err ("%s - error, can't find device for minor %d",
18394 __FUNCTION__, subminor);
18395 retval = -ENODEV;
18396 goto exit;
18397 }
18399 dev = usb_get_intfdata(interface);
18400 if (!dev) {
18401 retval = -ENODEV;
18402 goto exit;
18403 }
18404 </pre>
18405 <i>usb_get_intfdata </i>is usually called in the <i>open </i>function of the USB driver and again in
18406 the <i>disconnect </i>function. Thanks to these two functions, USB drivers do not need to
18407 keep a static array of pointers that store the individual device structures for all current
18408 devices in the system. The indirect reference to device information allows an
18409 unlimited number of devices to be supported by any USB driver.<br>
18410 <br>
18411 If the USB driver is not associated with another type of subsystem that handles the
18412 user interaction with the device (such as input, tty, video, etc.), the driver can use the
18413 USB major number in order to use the traditional char driver interface with user
18414 space. To do this, the USB driver must call the <i>usb_register_dev </i>function in the <i>probe
18415 </i>function when it wants to register a device with the USB core. Make sure that the
18416 device and driver are in a proper state to handle a user wanting to access the device
18417 as soon as this function is called.<br>
18418 <pre>
18419 /* we can register the device now, as it is ready */
18420 retval = usb_register_dev(interface, &skel_class);
18421 if (retval) {
18422 /* something prevented us from registering this driver */
18423 err("Not able to get a minor for this device.");
18424 usb_set_intfdata(interface, NULL);
18425 goto error;
18426 }
18427 </pre>
18428 The <i>usb_register_dev </i>function requires a pointer to a <font class="fixd">struct usb_interface</font> and a
18429 pointer to a struct <font class="fixd">usb_class_driver</font>. This struct <font class="fixd">usb_class_driver</font> is used to define
18430 a number of different parameters that the USB driver wants the USB core to know
18431 when registering for a minor number. This structure consists of the following variables:<br>
18432 <br>
18433 <font class="fixd">char *name</font><br>
18434 <div class="bq">
18435 The name that sysfs uses to describe the device. A leading pathname, if present,
18436 is used only in devfs and is not covered in this book. If the number of the device
18437 needs to be in the name, the characters <font class="fixd">%d</font> should be in the name string. For</div>
18438 <br>
18439 <A name="353"></a><font color="blue">PAGE 353</font><br>
18440 <br>
18441 <div class="bq">example, to create the devfs name <font class="fixd">usb/foo1</font> and the sysfs class name <font class="fixd">foo1,</font> the
18442 name string should be set to <font class="fixd">usb/foo%d.</font></div>
18443 <br>
18444 <font class="fixd">struct file_operations *fops;</font><br>
18445 <div class="bq">
18446 Pointer to the <font class="fixd">struct file_operations</font> that this driver has defined to use to register
18447 as the character device. See Chapter 3 for more information about this structure.</div>
18448 <br>
18449 <font class="fixd">mode_t mode;</font><br>
18450 <div class="bq">
18451 The mode for the devfs file to be created for this driver; unused otherwise. A typical
18452 setting for this variable would be the value <font class="fixd">S_IRUSR</font> combined with the value
18453 <font class="fixd">S_IWUSR,</font> which would provide only read and write access by the owner of the
18454 device file.</div>
18455 <br>
18456 <font class="fixd">int minor_base;</font><br>
18457 <div class="bq">
18458 This is the start of the assigned minor range for this driver. All devices associated
18459 with this driver are created with unique, increasing minor numbers beginning with
18460 this value. Only 16 devices are allowed to be associated with this
18461 driver at any one time unless the <font class="fixd">CONFIG_USB_DYNAMIC_MINORS</font> configuration
18462 option has been enabled for the kernel. If so, this variable is ignored, and all
18463 minor numbers for the device are allocated on a first-come, first-served manner.
18464 It is recommended that systems that have enabled this option use a program
18465 such as <i>udev </i>to manage the device nodes in the system, as a static <i>/dev </i>tree will
18466 not work properly.</div>
18467 <br>
18468 When the USB device is disconnected, all resources associated with the device
18469 should be cleaned up, if possible. At this time, if <i>usb_register_dev </i>has been called to
18470 allocate a minor number for this USB device during the <i>probe </i>function, the function
18471 <i>usb_deregister_dev</i> must be called to give the minor number back to the USB core.<br>
18472 <br>
18473 In the <i>disconnect </i>function, it is also important to retrieve from the interface any data
18474 that was previously set with a call to <i>usb_set_intfdata</i>. Then set the data pointer in
18475 the <font class="fixd">struct usb_interface</font> structure to <font class="fixd">NULL</font> to prevent any further mistakes in accessing
18476 the data improperly:<br>
18477 <pre>
18478 static void skel_disconnect(struct usb_interface *interface)
18479 {
18480 struct usb_skel *dev;
18481 int minor = interface->minor;
18483 /* prevent skel_open( ) from racing skel_disconnect( ) */
18484 lock_kernel( );
18486 dev = usb_get_intfdata(interface);
18487 usb_set_intfdata(interface, NULL);
18489 /* give back our minor */
18490 usb_deregister_dev(interface, &skel_class);
18492 unlock_kernel( );
18493 </pre>
18494 <A name="354"></a><font color="blue">PAGE 354</font>
18495 <pre>
18496 /* decrement our usage count */
18497 kref_put(&dev->kref, skel_delete);
18499 info("USB Skeleton #%d now disconnected", minor);
18500 }
18501 </pre>
18502 Note the call to <i>lock_kernel </i>in the previous code snippet. This takes the big kernel
18503 lock, so that the <i>disconnect </i>callback does not encounter a race condition with the
18504 open call when trying to get a pointer to the correct interface data structure. Because
18505 the open is called with the bigkernel lock taken, if the <i>disconnect </i>also takes that same
18506 lock, only one portion of the driver can access and then set the interface data pointer.<br>
18507 <br>
18508 Just before the <i>disconnect </i>function is called for a USB device, all urbs that are currently
18509 in transmission for the device are canceled by the USB core, so the driver does
18510 not have to explicitly call <i>usb_kill_urb </i>for these urbs. If a driver tries to submit a urb
18511 to a USB device after it has been disconnected with a call to <i>usb_submit_urb</i>, the submission
18512 will fail with an error value of <font class="fixd">-EPIPE.</font><br>
18513 <br>
18514 <a name="SubmittingAndControllingAUrb"></a><font color="red"><b>Submitting and Controlling a Urb</b></font><br>
18515 <br>
18516 When the driver has data to send to the USB device (as typically happens in a driver's
18517 write function), a urb must be allocated for transmitting the data to the device:<br>
18518 <pre>
18519 urb = usb_alloc_urb(0, GFP_KERNEL);
18520 if (!urb) {
18521 retval = -ENOMEM;
18522 goto error;
18523 }
18524 </pre>
18525 After the urb is allocated successfully, a DMA buffer should also be created to send
18526 the data to the device in the most efficient manner, and the data that is passed to the
18527 driver should be copied into that buffer:<br>
18528 <pre>
18529 buf = usb_buffer_alloc(dev->udev, count, GFP_KERNEL, &urb->transfer_dma);
18530 if (!buf) {
18531 retval = -ENOMEM;
18532 goto error;
18533 }
18534 if (copy_from_user(buf, user_buffer, count)) {
18535 retval = -EFAULT;
18536 goto error;
18537 }
18538 </pre>
18539 Once the data is properly copied from the user space into the local buffer, the urb
18540 must be initialized correctly before it can be submitted to the USB core:<br>
18541 <pre>
18542 /* initialize the urb properly */
18543 usb_fill_bulk_urb(urb, dev->udev,
18544 usb_sndbulkpipe(dev->udev, dev->bulk_out_endpointAddr),
18545 buf, count, skel_write_bulk_callback, dev);
18546 urb->transfer_flags |= URB_NO_TRANSFER_DMA_MAP;
18547 </pre>
18548 <A name="355"></a><font color="blue">PAGE 355</font><br>
18549 <br>
18550 Now that the urb is properly allocated, the data is properly copied, and the urb is
18551 properly initialized, it can be submitted to the USB core to be transmitted to the
18552 device:<br>
18553 <pre>
18554 /* send the data out the bulk port */
18555 retval = usb_submit_urb(urb, GFP_KERNEL);
18556 if (retval) {
18557 err("%s - failed submitting write urb, error %d", __FUNCTION__, retval);
18558 goto error;
18559 }
18560 </pre>
18561 After the urb is successfully transmitted to the USB device (or something happens in
18562 transmission), the urb callback is called by the USB core. In our example, we initialized
18563 the urb to point to the function <i>skel_write_bulk_callback</i>, and that is the function
18564 that is called:<br>
18565 <pre>
18566 static void skel_write_bulk_callback(struct urb *urb, struct pt_regs *regs)
18567 {
18568 /* sync/async unlink faults aren't errors */
18569 if (urb->status &&
18570 !(urb->status = = -ENOENT ||
18571 urb->status = = -ECONNRESET ||
18572 urb->status = = -ESHUTDOWN)) {
18573 dbg("%s - nonzero write bulk status received: %d",
18574 __FUNCTION__, urb->status);
18575 }
18577 /* free up our allocated buffer */
18578 usb_buffer_free(urb->dev, urb->transfer_buffer_length,
18579 urb->transfer_buffer, urb->transfer_dma);
18580 }
18581 </pre>
18582 The first thing the callback function does is check the status of the urb to determine
18583 if this urb completed successfully or not. The error values, <font class="fixd">-ENOENT, -ECONNRESET,</font> and
18584 <font class="fixd">-ESHUTDOWN</font> are not real transmission errors, just reports about conditions accompanying a
18585 successful transmission. (See the list of possible errors for urbs detailed in the
18586 section "<font class="fixd">struct urb</font>.") Then the callback frees up the allocated buffer that was
18587 assigned to this urb to transmit.<br>
18588 <br>
18589 It's common for another urb to be submitted to the device while the urb callback
18590 function is running. This is useful when streaming data to a device. Remember that
18591 the urb callback is running in interrupt context, so it should do any memory allocation,
18592 hold any semaphores, or do anything else that could cause the process to sleep.
18593 When submitting a urb from within a callback, use the <font class="fixd">GFP_ATOMIC</font> flag to tell the
18594 USB core to not sleep if it needs to allocate new memory chunks during the submission
18595 process.<br>
18596 <br>
18597 <A name="356"></a><font color="blue">PAGE 356</font><br>
18598 <br>
18599 <a name="USBTransfersWithoutUrbs"></a><font color="red"><b>USB Transfers Without Urbs</b></font><br>
18600 <br>
18601 Sometimes a USB driver does not want to go through all of the hassle of creating a
18602 <font class="fixd">struct urb</font>, initializing it, and then waiting for the urb completion function to run,
18603 just to send or receive some simple USB data. Two functions are available to provide
18604 a simpler interface.<br>
18605 <br>
18606 <a name="Usbbulkmsg"></a><font color="red"><b>usb_bulk_msg</b></font><br>
18607 <br>
18608 <i>usb_bulk_msg </i>creates a USB bulk urb and sends it to the specified device, then waits
18609 for it to complete before returning to the caller. It is defined as:<br>
18610 <pre>
18611 int usb_bulk_msg(struct usb_device *usb_dev, unsigned int pipe,
18612 void *data, int len, int *actual_length,
18613 int timeout);
18614 </pre>
18615 The parameters of this function are:<br>
18616 <br>
18617 <font class="fixd">struct usb_device *usb_dev</font><br>
18618 <div class="bq">
18619 A pointer to the USB device to send the bulk message to.</div>
18620 <br>
18621 <font class="fixd">unsigned int pipe</font><br>
18622 <div class="bq">
18623 The specific endpoint of the USB device to which this bulk message is to be sent.
18624 This value is created with a call to either <i>usb_sndbulkpipe</i> or <i>usb_rcvbulkpipe</i>.</div>
18625 <br>
18626 <font class="fixd">void *data</font><br>
18627 <div class="bq">
18628 A pointer to the data to send to the device if this is an OUT endpoint. If this is
18629 an IN endpoint, this is a pointer to where the data should be placed after being
18630 read from the device.</div>
18631 <br>
18632 <font class="fixd">int len</font><br>
18633 <div class="bq">
18634 The length of the buffer that is pointed to by the data parameter.</div>
18635 <br>
18636 <font class="fixd">int *actual_length</font><br>
18637 <div class="bq">
18638 A pointer to where the function places the actual number of bytes that have
18639 either been transferred to the device or received from the device, depending on
18640 the direction of the endpoint.</div>
18641 <br>
18642 <font class="fixd">int timeout</font><br>
18643 <div class="bq">
18644 The amount of time, in jiffies, that should be waited before timing out. If this
18645 value is 0, the function waits forever for the message to complete.</div>
18646 <br>
18647 If the function is successful, the return value is 0; otherwise, a negative error number
18648 is returned. This error number matches up with the error numbers previously
18649 described for urbs in the section "<font class="fixd">struct urb</font>." If successful, the <font class="fixd">actual_length</font> parameter
18650 contains the number of bytes that were transferred or received from this message.<br>
18651 <br>
18652 The following is an example of using this function call:<br>
18653 <pre>
18654 /* do a blocking bulk read to get data from the device */
18655 retval = usb_bulk_msg(dev->udev,
18656 usb_rcvbulkpipe(dev->udev, dev->bulk_in_endpointAddr),
18657 </pre>
18658 <A name="357"></a><font color="blue">PAGE 357</font><br>
18659 <pre>
18660 dev->bulk_in_buffer,
18661 min(dev->bulk_in_size, count),
18662 &count, HZ*10);
18664 /* if the read was successful, copy the data to user space */
18665 if (!retval) {
18666 if (copy_to_user(buffer, dev->bulk_in_buffer, count))
18667 retval = -EFAULT;
18668 else
18669 retval = count;
18670 }
18671 </pre>
18672 This example shows a simple bulk read from an IN endpoint. If the read is successful,
18673 the data is then copied to user space. This is typically done in a <font class="fixd">read</font> function for
18674 a USB driver.<br>
18675 <br>
18676 The <i>usb_bulk_msg </i>function cannot be called from within interrupt context or with a
18677 spinlock held. Also, this function cannot be canceled by any other function, so be
18678 careful when using it; make sure that your driver's <i>disconnect </i>knows enough to wait
18679 for the call to complete before allowing itself to be unloaded from memory.<br>
18680 <br>
18681 <a name="Usbcontrolmsg"></a><font color="red"><b>usb_control_msg</b></font><br>
18682 <br>
18683 The <i>usb_control_msg </i>function works just like the <i>usb_bulk_msg </i>function, except it
18684 allows a driver to send and receive USB control messages:<br>
18685 <pre>
18686 int usb_control_msg(struct usb_device *dev, unsigned int pipe,
18687 __u8 request, __u8 requesttype,
18688 __u16 value, __u16 index,
18689 void *data, __u16 size, int timeout);
18690 </pre>
18691 The parameters of this function are almost the same as <i>usb_bulk_msg</i>, with a few
18692 important differences:<br>
18693 <br>
18694 <font class="fixd">struct usb_device *dev</font><br>
18695 <div class="bq">
18696 A pointer to the USB device to send the control message to.</div>
18697 <br>
18698 <font class="fixd">unsigned int pipe</font><br>
18699 <div class="bq">
18700 The specific endpoint of the USB device that this control message is to be sent
18701 to. This value is created with a call to either <i>usb_sndctrlpipe</i> or <i>usb_rcvctrlpipe</i>.</div>
18702 <br>
18703 <font class="fixd">__u8 request</font><br>
18704 <div class="bq">
18705 The USB request value for the control message.</div>
18706 <br>
18707 <font class="fixd">__u8 requesttype</font><br>
18708 <div class="bq">
18709 The USB request type value for the control message</div>
18710 <br>
18711 <font class="fixd">__u16 value</font><br>
18712 <div class="bq">
18713 The USB message value for the control message.</div>
18714 <br>
18715 <font class="fixd">__u16 index</font><br>
18716 <div class="bq">
18717 The USB message index value for the control message.</div>
18718 <br>
18719 <A name="358"></a><font color="blue">PAGE 358</font><br>
18720 <br>
18721 <font class="fixd">void *data</font><br>
18722 <div class="bq">
18723 A pointer to the data to send to the device if this is an OUT endpoint. If this is
18724 an IN endpoint, this is a pointer to where the data should be placed after being
18725 read from the device.</div>
18726 <br>
18727 <font class="fixd">__u16 size</font><br>
18728 <div class="bq">
18729 The size of the buffer that is pointed to by the data parameter.</div>
18730 <br>
18731 <font class="fixd">int timeout</font><br>
18732 <div class="bq">
18733 The amount of time, in jiffies, that should be waited before timing out. If this
18734 value is 0, the function will wait forever for the message to complete.</div>
18735 <br>
18736 If the function is successful, it returns the number of bytes that were transferred to or
18737 from the device. If it is not successful, it returns a negative error number.<br>
18738 <br>
18739 The parameters <font class="fixd">request, requesttype, value,</font> and <font class="fixd">index</font> all directly map to the USB
18740 specification for how a USB control message is defined. For more information on the
18741 valid values for these parameters and how they are used, see Chapter 9 of the USB
18742 specification.<br>
18743 <br>
18744 Like the function <i>usb_bulk_msg</i>, the function <i>usb_control_msg </i>cannot be called from
18745 within interrupt context or with a spinlock held. Also, this function cannot be canceled
18746 by any other function, so be careful when using it; make sure that your driver
18747 <i>disconnect </i>function knows enough to wait for the call to complete before allowing
18748 itself to be unloaded from memory.<br>
18749 <br>
18750 <a name="OtherUSBDataFunctions"></a><font color="red"><b>Other USB Data Functions</b></font><br>
18751 <br>
18752 A number of helper functions in the USB core can be used to retrieve standard information
18753 from all USB devices. These functions cannot be called from within interrupt
18754 context or with a spinlock held.<br>
18755 <br>
18756 The function <i>usb_get_descriptor </i>retrieves the specified USB descriptor from the specified
18757 device. The function is defined as:<br>
18758 <pre>
18759 int usb_get_descriptor(struct usb_device *dev, unsigned char type,
18760 unsigned char index, void *buf, int size);
18761 </pre>
18762 This function can be used by a USB driver to retrieve from the struct usb_device
18763 structure any of the device descriptors that are not already present in the existing
18764 <font class="fixd">struct usb_device</font> and <font class="fixd">struct usb_interface</font> structures, such as audio descriptors or
18765 other class specific information. The parameters of the function are:<br>
18766 <br>
18767 <font class="fixd">struct usb_device *usb_dev</font><br>
18768 <div class="bq">
18769 A pointer to the USB device that the descriptor should be retrieved from.</div>
18770 <br>
18771 <font class="fixd">unsigned char type<</font>br>
18772 <div class="bq">
18773 The descriptor type. This type is described in the USB specification and can be
18774 one of the following types:<br>
18775 <pre>
18776 USB_DT_DEVICE
18777 USB_DT_CONFIG
18778 </pre></div>
18779 <A name="359"></a><font color="blue">PAGE 359</font><br>
18780 <div class="bq"><pre>
18781 USB_DT_STRING
18782 USB_DT_INTERFACE
18783 USB_DT_ENDPOINT
18784 USB_DT_DEVICE_QUALIFIER
18785 USB_DT_OTHER_SPEED_CONFIG
18786 USB_DT_INTERFACE_POWER
18787 USB_DT_OTG
18788 USB_DT_DEBUG
18789 USB_DT_INTERFACE_ASSOCIATION
18790 USB_DT_CS_DEVICE
18791 USB_DT_CS_CONFIG
18792 USB_DT_CS_STRING
18793 USB_DT_CS_INTERFACE
18794 USB_DT_CS_ENDPOINT
18795 </pre></div>
18796 <font class="fixd">unsigned char index</font><br>
18797 <div class="bq">
18798 The number of the descriptor that should be retrieved from the device.</div>
18799 <br>
18800 <font class="fixd">void *buf</font><br>
18801 <div class="bq">
18802 A pointer to the buffer to which you copy the descriptor.</div>
18803 <br>
18804 <font class="fixd">int size</font><br>
18805 <div class="bq">
18806 The size of the memory pointed to by the <font class="fixd">buf</font> variable.</div>
18807 <br>
18808 If this function is successful, it returns the number of bytes read from the device.
18809 Otherwise, it returns a negative error number returned by the underlying call to
18810 <i>usb_control_msg</i> that this function makes.<br>
18811 <br>
18812 One of the more common uses for the <i>usb_get_descriptor </i>call is to retrieve a string
18813 from the USB device. Because this is quite common, there is a helper function for it
18814 called <i>usb_get_string</i>:<br>
18815 <pre>
18816 int usb_get_string(struct usb_device *dev, unsigned short langid,
18817 unsigned char index, void *buf, int size);
18818 </pre>
18819 If successful, this function returns the number of bytes received by the device for the
18820 string. Otherwise, it returns a negative error number returned by the underlying call
18821 to <i>usb_control_msg</i> that this function makes.<br>
18822 <br>
18823 If this function is successful, it returns a string-encoded in the UTF-16LE format (Unicode,
18824 16 bits per character, in little-endian byte order) in the buffer pointed to by the buf
18825 parameter. As this format is usually not very useful, there is another function, called
18826 <i>usb_string</i>, that returns a string that is read from a USB device and is already converted
18827 into an ISO 8859-1 format string. This character set is a 8-bit subset of Unicode and is
18828 the most common format for strings in English and other Western European languages.
18829 As this is typically the format that the USB device's strings are in, it is recommended
18830 that the <i>usb_string</i> function be used instead of the <i>usb_get_string</i> function.<br>
18831 <br>
18832 <A name="360"></a><font color="blue">PAGE 360</font><br>
18833 <br>
18834 <a name="QuickReference13"></a><font color="red"><b>Quick Reference</b></font><br>
18835 <br>
18836 This section summarizes the symbols introduced in the chapter:<br>
18837 <br>
18838 <font class="fixd">#include <linux/usb.h></font><br>
18839 <div class="bq">
18840 Header file where everything related to USB resides. It must be included by all
18841 USB device drivers.</div>
18842 <br>
18843 <font class="fixd">struct usb_driver;</font><br>
18844 <div class="bq">
18845 Structure that describes a USB driver.</div>
18846 <br>
18847 <font class="fixd">struct usb_device_id;</font><br>
18848 <div class="bq">
18849 Structure that describes the types of USB devices this driver supports.</div>
18850 <br>
18851 <font class="fixd">int usb_register(struct usb_driver *d);<br>
18852 void usb_deregister(struct usb_driver *d);</font><br>
18853 <div class="bq">
18854 Functions used to register and unregister a USB driver from the USB core.</div>
18855 <br>
18856 <font class="fixd">struct usb_device *interface_to_usbdev(struct usb_interface *intf);</font><br>
18857 <div class="bq">
18858 Retrieves the controlling struct usb_device * out of a struct usb_interface *.</div>
18859 <br>
18860 <font class="fixd">struct usb_device;</font><br>
18861 <div class="bq">
18862 Structure that controls an entire USB device.</div>
18863 <br>
18864 <font class="fixd">struct usb_interface;</font><br>
18865 <div class="bq">
18866 Main USB device structure that all USB drivers use to communicate with the
18867 USB core.</div>
18868 <br>
18869 <font class="fixd">void usb_set_intfdata(struct usb_interface *intf, void *data);<br>
18870 void *usb_get_intfdata(struct usb_interface *intf);</font><br>
18871 <div class="bq">
18872 Functions to set and get access to the private data pointer section within the
18873 <font class="fixd">struct usb_interface</font>.</div>
18874 <br>
18875 <font class="fixd">struct usb_class_driver;</font><br>
18876 <div class="bq">
18877 A structure that describes a USB driver that wants to use the USB major number
18878 to communicate with user-space programs.</div>
18879 <br>
18880 <font class="fixd">int usb_register_dev(struct usb_interface *intf, struct usb_class_driver
18881 *class_driver);<br>
18882 void usb_deregister_dev(struct usb_interface *intf, struct usb_class_driver
18883 *class_driver);</font><br>
18884 <div class="bq">
18885 Functions used to register and unregister a specific struct usb_interface * structure
18886 with a struct usb_class_driver * structure.</div>
18887 <br>
18888 <font class="fixd">struct urb;</font><br>
18889 <div class="bq">
18890 Structure that describes a USB data transmission.</div>
18891 <br>
18892 <font class="fixd">struct urb *usb_alloc_urb(int iso_packets, int mem_flags);<br>
18893 void usb_free_urb(struct urb *urb);</font><br>
18894 <div class="bq">
18895 Functions used to create and destroy a struct usb urb *.</div>
18896 <br>
18897 <A name="361"></a><font color="blue">PAGE 361</font><br>
18898 <br>
18899 <font class="fixd">int usb_submit_urb(struct urb *urb, int mem_flags);<br>
18900 int usb_kill_urb(struct urb *urb);<br>
18901 int usb_unlink_urb(struct urb *urb);</font><br>
18902 <div class="bq">
18903 Functions used to start and stop a USB data transmission.</div>
18904 <br>
18905 <font class="fixd">void usb_fill_int_urb(struct urb *urb, struct usb_device *dev, unsigned int
18906 pipe, void *transfer_buffer, int buffer_length, usb_complete_t complete,
18907 void *context, int interval);<br>
18908 void usb_fill_bulk_urb(struct urb *urb, struct usb_device *dev, unsigned int
18909 pipe, void *transfer_buffer, int buffer_length, usb_complete_t complete,
18910 void *context);<br>
18911 void usb_fill_control_urb(struct urb *urb, struct usb_device *dev, unsigned
18912 int pipe, unsigned char *setup_packet, void *transfer_buffer, int
18913 buffer_ length, usb_complete_t complete, void *context);</font><br>
18914 <div class="bq">
18915 Functions used to initialize a struct urb before it is submitted to the USB core.</div>
18916 <br>
18917 <font class="fixd">int usb_bulk_msg(struct usb_device *usb_dev, unsigned int pipe, void *data,
18918 int len, int *actual_length, int timeout);<br>
18919 int usb_control_msg(struct usb_device *dev, unsigned int pipe, __u8 request,
18920 __u8 requesttype, __u16 value, __u16 index, void *data, __u16 size,
18921 int timeout);</font><br>
18922 <div class="bq">
18923 Functions used to send or receive USB data without having to use a struct urb.</div>
18924 <br>
18925 <A name="362"></a><font color="blue">PAGE 362</font><br>
18926 <br>
18927 <a name="CHAPTER14"></a><font color="red"><b>CHAPTER 14</b></font><br>
18928 <br>
18929 <a name="TheLinuxDeviceModel"></a><font color="#7519FF" size="+1"><b>The Linux Device Model</b></font><br>
18930 <br>
18931 One of the stated goals for the 2.5 development cycle was the creation of a unified
18932 device model for the kernel. Previous kernels had no single data structure to which
18933 they could turn to obtain information about how the system is put together. Despite
18934 this lack of information, things worked well for some time. The demands of newer
18935 systems, with their more complicated topologies and need to support features such
18936 as power management, made it clear, however, that a general abstraction describing
18937 the structure of the system was needed.<br>
18938 <br>
18939 The 2.6 device model provides that abstraction. It is now used within the kernel to
18940 support a wide variety of tasks, including:<br>
18941 <br>
18942 <i>Power management and system shutdown</i><br>
18943 <div class="bq">
18944 These require an understanding of the system's structure. For example, a USB
18945 host adaptor cannot be shut down before dealing with all of the devices connected
18946 to that adaptor. The device model enables a traversal of the system's
18947 hardware in the right order.</div>
18948 <br>
18949 <i>Communications with user space</i><br>
18950 <div class="bq">
18951 The implementation of the sysfs virtual filesystem is tightly tied into the device
18952 model and exposes the structure represented by it. The provision of information
18953 about the system to user space and knobs for changing operating parameters is
18954 increasingly done through sysfs and, therefore, through the device model.</div>
18955 <br>
18956 <i>Hotpluggable devices</i><br>
18957 <div class="bq">
18958 Computer hardware is increasingly dynamic; peripherals can come and go at the
18959 whim of the user. The hotplug mechanism used within the kernel to handle and
18960 (especially) communicate with user space about the plugging and unplugging of
18961 devices is managed through the device model.</div>
18962 <br>
18963 <i>Device classes</i><br>
18964 <div class="bq">
18965 Many parts of the system have little interest in how devices are connected, but
18966 they need to know what kinds of devices are available. The device model
18967 includes a mechanism for assigning devices to <i>classes</i>, which describe those</div>
18968 <br>
18969 <A name="363"></a><font color="blue">PAGE 363</font><br>
18970 <br>
18971 <div class="bq">devices at a higher, functional level and allow them to be discovered from user
18972 space.</div>
18973 <br>
18974 <i>Object lifecycles</i><br>
18975 <div class="bq">
18976 Many of the functions described above, including hotplug support and sysfs,
18977 complicate the creation and manipulation of objects created within the kernel.
18978 The implementation of the device model required the creation of a set of mechanisms
18979 for dealing with object lifecycles, their relationships to each other, and
18980 their representation in user space.</div>
18981 <br>
18982 The Linux device model is a complex data structure. For example, consider
18983 Figure 14-1, which shows (in simplified form) a tiny piece of the device model structure
18984 associated with a USB mouse. Down the center of the diagram, we see the part
18985 of the core "devices" tree that shows how the mouse is connected to the system. The
18986 "bus" tree tracks what is connected to each bus, while the subtree under "classes"
18987 concerns itself with the functions provided by the devices, regardless of how they are
18988 connected. The device model tree on even a simple system contains hundreds of
18989 nodes like those shown in the diagram; it is a difficult data structure to visualize as a
18990 whole.<br>
18991 <br><br>
18992 <center>
18993 <img src="fig14-1.gif">
18994 </center>
18995 <br>
18996 <i>Figure 14-1. A small piece of the device model</i><br>
18997 <br>
18998 For the most part, the Linux device model code takes care of all these considerations
18999 without imposing itself upon driver authors. It sits mostly in the background; direct
19000 interaction with the device model is generally handled by bus-level logic and various
19001 other kernel subsystems. As a result, many driver authors can ignore the device
19002 model entirely, and trust it to take care of itself.<br>
19003 <br>
19004 There are times, however, when an understanding of the device model is a good
19005 thing to have. There are times when the device model "leaks out" from behind the
19006 other layers; for example, the generic DMA code (which we encounter in<br>
19007 <br>
19008 <A name="364"></a><font color="blue">PAGE 364</font><br>
19009 <br>
19010 Chapter 15) works with <font class="fixd">struct device.</font> You may want to use some of the capabilities
19011 provided by the device model, such as the reference counting and related features
19012 provided by kobjects. Communication with user space via sysfs is also a device
19013 model function; this chapter explains how that communication works.<br>
19014 <br>
19015 We start, however, with a bottom-up presentation of the device model. The complexity
19016 of the device model makes it hard to understand by starting with a high-level
19017 view. Our hope is that, by showing how the low-level device components work, we
19018 can prepare you for the challenge of grasping how those components are used to
19019 build the larger structure.<br>
19020 <br>
19021 For many readers, this chapter can be treated as advanced material that need not be
19022 read the first time through. Those who are interested in how the Linux device model
19023 works are encouraged to press ahead, however, as we get into the low-level details.<br>
19024 <br>
19025 <a name="KobjectsKsetsAndSubsystems"></a><font color="red"><b>Kobjects, Ksets, and Subsystems</b></font><br>
19026 <br>
19027 The <i>kobject </i>is the fundamental structure that holds the device model together. It was
19028 initially conceived as a simple reference counter, but its responsibilities have grown
19029 over time, and so have its fields. The tasks handled by <font class="fixd">struct kobject</font> and its supporting
19030 code now include:<br>
19031 <br>
19032 <i>Reference counting of objects</i><br>
19033 <div class="bq">
19034 Often, when a kernel object is created, there is no way to know just how long it
19035 will exist. One way of tracking the lifecycle of such objects is through reference
19036 counting. When no code in the kernel holds a reference to a given object, that
19037 object has finished its useful life and can be deleted.</div>
19038 <br>
19039 <i>Sysfs representation</i><br>
19040 <div class="bq">
19041 Every object that shows up in sysfs has, underneath it, a kobject that interacts
19042 with the kernel to create its visible representation.</div>
19043 <br>
19044 <i>Data structure glue</i><br>
19045 <div class="bq">
19046 The device model is, in its entirety, a fiendishly complicated data structure made
19047 up of multiple hierarchies with numerous links between them. The kobject
19048 implements this structure and holds it together.</div>
19049 <br>
19050 <i>Hotplug event handling</i><br>
19051 <div class="bq">
19052 The kobject subsystem handles the generation of events that notify user space
19053 about the comings and goings of hardware on the system.</div>
19054 <br>
19055 One might conclude from the preceding list that the kobject is a complicated structure.
19056 One would be right. By looking at one piece at a time, however, it is possible to
19057 understand this structure and how it works.<br>
19058 <br>
19059 <A name="365"></a><font color="blue">PAGE 365</font><br>
19060 <br>
19061 <a name="KobjectBasics"></a><font color="red"><b>Kobject Basics</b></font><br>
19062 <br>
19063 A kobject has the type <font class="fixd">struct kobject;</font> it is defined in <i><linux/kobject.h></i>. That file
19064 also includes declarations for a number of other structures related to kobjects and, of
19065 course, a long list of functions for manipulating them.<br>
19066 <br>
19067 <a name="EmbeddingKobjects"></a><font color="red"><b>Embedding kobjects</b></font><br>
19068 <br>
19069 Before we get into the details, it is worth taking a moment to understand how kobjects
19070 are used. If you look back at the list of functions handled by kobjects, you see
19071 that they are all services performed on behalf of other objects. A kobject, in other
19072 words, is of little interest on its own; it exists only to tie a higher-level object into the
19073 device model.<br>
19074 <br>
19075 Thus, it is rare (even unknown) for kernel code to create a stand alone kobject;
19076 instead, kobjects are used to control access to a larger, domain-specific object. To
19077 this end, kobjects are found embedded in other structures. If you are used to thinking
19078 of things in object-oriented terms, kobjects can be seen as a top-level, abstract
19079 class from which other classes are derived. A kobject implements a set of capabilities
19080 that are not particularly useful by themselves but that are nice to have in other
19081 objects. The C language does not allow for the direct expression of inheritance, so
19082 other techniques--such as embedding one structure in another--must be used.<br>
19083 <br>
19084 As an example, let's look back at <font class="fixd">struct cdev</font>, which we encountered in Chapter 3.
19085 That structure, as found in the 2.6.10 kernel, looks like this:<br>
19086 <pre>
19087 struct cdev {
19088 struct kobject kobj;
19089 struct module *owner;
19090 struct file_operations *ops;
19091 struct list_head list;
19092 dev_t dev;
19093 unsigned int count;
19094 };
19095 </pre>
19096 As we can see, the <font class="fixd">cdev</font> structure has a kobject embedded within it. If you have one
19097 of these structures, finding its embedded kobject is just a matter of using the <font class="fixd">kobj</font>
19098 field. Code that works with kobjects often has the opposite problem, however: given
19099 a <font class="fixd">struct kobject</font> pointer, what is the pointer to the containing structure? You should
19100 avoid tricks (such as assuming that the kobject is at the beginning of the structure),
19101 and, instead, use the <i>container_of </i>macro (introduced in the section "The open
19102 Method" in Chapter 3). So the way to convert a pointer to a <font class="fixd">struct kobject</font> called <font class="fixd">kp</font>
19103 embedded within a <font class="fixd">struct cdev</font> would be:<br>
19104 <pre>
19105 struct cdev *device = container_of(kp, struct cdev, kobj);
19106 </pre>
19107 Programmers often define a simple macro for "back-casting" kobject pointers to the
19108 containing type.<br>
19109 <br>
19110 <A name="366"></a><font color="blue">PAGE 366</font><br>
19111 <br>
19112 <a name="KobjectInitialization"></a><font color="red"><b>Kobject initialization</b></font><br>
19113 <br>
19114 This book has presented a number of types with simple mechanisms for initialization
19115 at compile or runtime. The initialization of a kobject is a bit more complicated,
19116 especially when all of its functions are used. Regardless of how a kobject is used,
19117 however, a few steps must be performed.<br>
19118 <br>
19119 The first of those is to simply set the entire kobject to 0, usually with a call to <i>memset</i>.
19120 Often this initialization happens as part of the zeroing of the structure into which
19121 the kobject is embedded. Failure to zero out a kobject often leads to very strange
19122 crashes further down the line; it is not a step you want to skip.<br>
19123 <br>
19124 The next step is to set up some of the internal fields with a call to <i>kobject_init( )</i>:<br>
19125 <pre>
19126 void kobject_init(struct kobject *kobj);
19127 </pre>
19128 Among other things, <i>kobject_init </i>sets the kobject's reference count to one. Calling
19129 <i>kobject_init </i>is not sufficient, however. Kobject users must, at a minimum, set the
19130 name of the kobject; this is the name that is used in sysfs entries. If you dig through
19131 the kernel source, you can find the code that copies a string directly into the kobject's
19132 name field, but that approach should be avoided. Instead, use:<br>
19133 <pre>
19134 int kobject_set_name(struct kobject *kobj, const char *format, ...);
19135 </pre>
19136 This function takes a <i>printk</i>-style variable argument list. Believe it or not, it is actually
19137 possible for this operation to fail (it may try to allocate memory); conscientious
19138 code should check the return value and react accordingly.<br>
19139 <br>
19140 The other kobject fields that should be set, directly or indirectly, by the creator are
19141 <font class="fixd">ktype, kset,</font> and <font class="fixd">parent.</font> We will get to these later in this chapter.<br>
19142 <br>
19143 <a name="ReferenceCountManipulation"></a><font color="red"><b>Reference count manipulation</b></font><br>
19144 <br>
19145 One of the key functions of a kobject is to serve as a reference counter for the object
19146 in which it is embedded. As long as references to the object exist, the object (and the
19147 code that supports it) must continue to exist. The low-level functions for manipulating
19148 a kobject's reference counts are:<br>
19149 <pre>
19150 struct kobject *kobject_get(struct kobject *kobj);
19151 void kobject_put(struct kobject *kobj);
19152 </pre>
19153 A successful call to <i>kobject_get </i>increments the kobject's reference counter and
19154 returns a pointer to the kobject. If, however, the kobject is already in the process of
19155 being destroyed, the operation fails, and <i>kobject_get </i>returns <font class="fixd">NULL</font>. This return value
19156 must always be tested, or no end of unpleasant race conditions could result.<br>
19157 <br>
19158 When a reference is released, the call to <i>kobject_put </i>decrements the reference count
19159 and, possibly, frees the object. Remember that <i>kobject_init </i>sets the reference count to
19160 one; so when you create a kobject, you should make sure that the corresponding
19161 <i>kobject_put</i> call is made when that initial reference is no longer needed.<br>
19162 <br>
19163 <A name="367"></a><font color="blue">PAGE 367</font><br>
19164 <br>
19165 Note that, in many cases, the reference count in the kobject itself may not be sufficient
19166 to prevent race conditions. The existence of a kobject (and its containing structure)
19167 may well, for example, require the continued existence of the module that
19168 created that kobject. It would not do to unload that module while the kobject is still
19169 being passed around. That is why the <font class="fixd">cdev</font> structure we saw above
19170 contains a <font class="fixd">struct module</font> pointer. Reference counting for <font class="fixd">struct cdev</font> is implemented as follows:<br>
19171 <pre>
19172 struct kobject *cdev_get(struct cdev *p)
19173 {
19174 struct module *owner = p->owner;
19175 struct kobject *kobj;
19177 if (owner && !try_module_get(owner))
19178 return NULL;
19179 kobj = kobject_get(&p->kobj);
19180 if (!kobj)
19181 module_put(owner);
19182 return kobj;
19183 }
19184 </pre>
19185 Creating a reference to a <font class="fixd">cdev</font> structure requires creating a reference also to the module
19186 that owns it. So <i>cdev_get </i>uses <i>try_module_get </i>to attempt to increment that module's
19187 usage count. If that operation succeeds, <i>kobject_get </i>is used to increment the
19188 kobject's reference count as well. That operation could fail, of course, so the code
19189 checks the return value from <i>kobject_get </i>and releases its reference to the module if
19190 things don't work out.<br>
19191 <br>
19192 <a name="ReleaseFunctionsAndKobjectTypes"></a><font color="red"><b>Release functions and kobject types</b></font><br>
19193 <br>
19194 One important thing still missing from the discussion is what happens to a kobject
19195 when its reference count reaches 0. The code that created the kobject generally does
19196 not know when that will happen; if it did, there would be little point in using a reference
19197 count in the first place. Even predictable object life cycles become more complicated
19198 when sysfs is brought in; user-space programs can keep a reference to a kobject
19199 (by keeping one of its associated sysfs files open) for an arbitrary period of time.<br>
19200 <br>
19201 The end result is that a structure protected by a kobject cannot be freed at any single, predictable
19202 point in the driver's lifecycle, but in code that must be prepared to
19203 run at whatever moment the kobject's reference count goes to 0. The reference count
19204 is not under the direct control of the code that created the kobject. So that code must
19205 be notified asynchronously whenever the last reference to one of its kobjects goes
19206 away.<br>
19207 <br>
19208 This notification is done through a kobject's <i>release </i>method. Usually, this method
19209 has a form such as:<br>
19210 <pre>
19211 void my_object_release(struct kobject *kobj)
19212 {
19213 struct my_object *mine = container_of(kobj, struct my_object, kobj);
19214 </pre>
19215 <A name="368"></a><font color="blue">PAGE 368</font><br>
19216 <pre>
19217 /* Perform any additional cleanup on this object, then... */
19218 kfree(mine);
19219 }
19220 </pre>
19221 One important point cannot be overstated: every kobject must have a <i>release
19222 </i>method, and the kobject must persist (in a consistent state) until that method is
19223 called. If these constraints are not met, the code is flawed. It risks freeing the object
19224 when it is still in use, or it fails to release the object after the last reference is
19225 returned.<br>
19226 <br>
19227 Interestingly, the <i>release </i>method is not stored in the kobject itself; instead, it is associated
19228 with the type of the structure that contains the kobject. This type is tracked
19229 with a structure of type <font class="fixd">struct kobj_type</font>, often simply called a "ktype." This structure
19230 looks like the following:<br>
19231 <pre>
19232 struct kobj_type {
19233 void (*release)(struct kobject *);
19234 struct sysfs_ops *sysfs_ops;
19235 struct attribute **default_attrs;
19236 };
19237 </pre>
19238 The release field in <font class="fixd">struct kobj_type</font> is, of course, a pointer to the <i>release </i>method
19239 for this type of kobject. We will come back to the other two fields (sysfs_ops and
19240 default_attrs) later in this chapter.<br>
19241 <br>
19242 Every kobject needs to have an associated <font class="fixd">kobj_type</font> structure. Confusingly, the
19243 pointer to this structure can be found in two different places. The kobject structure
19244 itself contains a field (called <font class="fixd">ktype</font>) that can contain this pointer. If, however, this
19245 kobject is a member of a kset, the <font class="fixd">kobj_type</font> pointer is provided by that kset instead.
19246 (We will look at ksets in the next section.) Meanwhile, the macro:<br>
19247 <pre>
19248 struct kobj_type *get_ktype(struct kobject *kobj);
19249 </pre>
19250 finds the <font class="fixd">kobj_type</font> pointer for a given kobject.<br>
19251 <br>
19252 <a name="KobjectHierarchiesKsetsAndSubsystems"></a><font color="red"><b>Kobject Hierarchies, Ksets, and Subsystems</b></font><br>
19253 <br>
19254 The kobject structure is often used to link together objects into a hierarchical structure
19255 that matches the structure of the subsystem being modeled. There are two separate
19256 mechanisms for this linking: the parent pointer and ksets.<br>
19257 <br>
19258 The parent field in <font class="fixd">struct kobject</font> is a pointer to another kobject--the one representing
19259 the next level up in the hierarchy. If, for example, a kobject represents a USB
19260 device, its <font class="fixd">parent</font> pointer may indicate the object representing the hub into which the
19261 device is plugged.<br>
19262 <br>
19263 The main use for the parent pointer is to position the object in the sysfs hierarchy.
19264 We'll see how this works in the section "Low-Level Sysfs Operations."<br>
19265 <br>
19266 <A name="369"></a><font color="blue">PAGE 369</font><br>
19267 <br>
19268 <a name="Ksets"></a><font color="red"><b>Ksets</b></font><br>
19269 <br>
19270 In many ways, a kset looks like an extension of the <font class="fixd">kobj_type</font> structure; a kset is a
19271 collection of kobjects embedded within structures of the same type. However, while
19272 <font class="fixd">struct kobj_type</font> concerns itself with the type of an object, <font class="fixd">struct kset</font> is concerned
19273 with aggregation and collection. The two concepts have been separated so that
19274 objects of identical type can appear in distinct sets.<br>
19275 <br>
19276 Therefore, the main function of a kset is containment; it can be thought of as the
19277 top-level container class for kobjects. In fact, each kset contains its own kobject
19278 internally, and it can, in many ways, be treated the same way as a kobject. It is worth
19279 noting that ksets are always represented in sysfs; once a kset has been set up and
19280 added to the system, there will be a sysfs directory for it. Kobjects do not necessarily
19281 show up in sysfs, but every kobject that is a member of a kset is represented there.<br>
19282 <br>
19283 Adding a kobject to a kset is usually done when the object is created; it is a two-step
19284 process. The kobject's <font class="fixd">kset</font> field must be pointed at the kset of interest; then the
19285 kobject should be passed to:<br>
19286 <pre>
19287 int kobject_add(struct kobject *kobj);
19288 </pre>
19289 As always, programmers should be aware that this function can fail (in which case it
19290 returns a negative error code) and respond accordingly. There is a convenience function
19291 provided by the kernel:<br>
19292 <pre>
19293 extern int kobject_register(struct kobject *kobj);
19294 </pre>
19295 This function is simply a combination of <i>kobject_init</i> and <i>kobject_add</i>.<br>
19296 <br>
19297 When a kobject is passed to <i>kobject_add</i>, its reference count is incremented. Containment
19298 within the kset is, after all, a reference to the object. At some point, the
19299 kobject will probably have to be removed from the kset to clear that reference; that is
19300 done with:<br>
19301 <pre>
19302 void kobject_del(struct kobject *kobj);
19303 </pre>
19304 There is also a <i>kobject_unregister </i>function, which is a combination of <i>kobject_del </i>and
19305 <i>kobject_put</i>.<br>
19306 <br>
19307 A kset keeps its children in a standard kernel linked list. In almost all cases, the contained
19308 kobjects also have pointers to the kset (or, strictly, its embedded kobject) in
19309 their parent's fields. So, typically, a kset and its kobjects look something like what
19310 you see in Figure 14-2. Bear in mind that:<br>
19311 <ul>
19312 <li> All of the contained kobjects in the diagram are actually embedded within some
19313 other type, possibly even other ksets.
19314 <li> It is not required that a kobject's parent be the containing kset (although any
19315 other organization would be strange and rare).
19316 </ul>
19317 <A name="370"></a><font color="blue">PAGE 370</font><br>
19318 <br>
19319 <center>
19320 <img src="fig14-2.gif">
19321 </center>
19322 <br>
19323 <i>Figure 14-2. A simple kset hierarchy</i><br>
19324 <br>
19325 <a name="OperationsOnKsets"></a><font color="red"><b>Operations on ksets</b></font><br>
19326 <br>
19327 For initialization and setup, ksets have an interface very similar to that of kobjects.
19328 The following functions exist:<br>
19329 <pre>
19330 void kset_init(struct kset *kset);
19331 int kset_add(struct kset *kset);
19332 int kset_register(struct kset *kset);
19333 void kset_unregister(struct kset *kset);
19334 </pre>
19335 For the most part, these functions just call the analogous <i>kobject_ </i>function on the
19336 kset's embedded kobject.<br>
19337 <br>
19338 To manage the reference counts of ksets, the situation is about the same:<br>
19339 <pre>
19340 struct kset *kset_get(struct kset *kset);
19341 void kset_put(struct kset *kset);
19342 </pre>
19343 A kset also has a name, which is stored in the embedded kobject. So, if you have a
19344 kset called <font class="fixd">my_set,</font> you would set its name with:<br>
19345 <pre>
19346 kobject_set_name(&my_set->kobj, "The name");
19347 </pre>
19348 Ksets also have a pointer (in the <font class="fixd">ktype</font> field) to the <font class="fixd">kobj_type</font> structure describing the
19349 kobjects it contains. This type is used in preference to the <font class="fixd">ktype</font> field in a kobject
19350 itself. As a result, in typical usage, the <font class="fixd">ktype</font> field in <font class="fixd">struct kobject</font> is left <font class="fixd">NULL</font>,
19351 because the same field within the kset is the one actually used.<br>
19352 <br>
19353 Finally, a kset contains a subsystem pointer (called subsys). So it's time to talk about
19354 subsystems.<br>
19355 <br>
19356 <a name="Subsystems"></a><font color="red"><b>Subsystems</b></font><br>
19357 <br>
19358 A subsystem is a representation for a high-level portion of the kernel as a whole. Subsystems
19359 usually (but not always) show up at the top of the sysfs hierarchy. Some
19360 example subsystems in the kernel include <font class="fixd">block_subsys</font> (<i>/sys/block</i>, for block
19361 devices), <font class="fixd">devices_subsys</font> (<i>/sys/devices</i>, the core device hierarchy), and a specific subsystem
19362 for every bus type known to the kernel. A driver author almost never needs to<br>
19363 <br>
19364 <A name="371"></a><font color="blue">PAGE 371</font><br>
19365 <br>
19366 create a new subsystem; if you feel tempted to do so, think again. What you probably
19367 want, in the end, is to add a new class, as discussed in the section "Classes."<br>
19368 <br>
19369 A subsystem is represented by a simple structure:<br>
19370 <pre>
19371 struct subsystem {
19372 struct kset kset;
19373 struct rw_semaphore rwsem;
19374 };
19375 </pre>
19376 A subsystem, thus, is really just a wrapper around a kset, with a semaphore thrown in.<br>
19377 <br>
19378 Every kset must belong to a subsystem. The subsystem membership helps establish
19379 the kset's position in the hierarchy, but, more importantly, the subsystem's <font class="fixd">rwsem</font>
19380 semaphore is used to serialize access to a kset's internal-linked list. This membership
19381 is represented by the <font class="fixd">subsys</font> pointer in <font class="fixd">struct kset</font>. Thus, one can find each
19382 kset's containing subsystem from the kset's structure, but one cannot find the multiple
19383 ksets contained in a subsystem directly from the subsystem structure.<br>
19384 <br>
19385 Subsystems are often declared with a special macro:<br>
19386 <pre>
19387 decl_subsys(name, struct kobj_type *type,
19388 struct kset_hotplug_ops *hotplug_ops);
19389 </pre>
19390 This macro creates a <font class="fixd">struct subsystem</font> with a name formed by taking the <font class="fixd">name</font> given
19391 to the macro and appending <font class="fixd">_subsys</font> to it. The macro also initializes the internal kset
19392 with the given <font class="fixd">type</font> and <font class="fixd">hotplug_ops</font>. (We discuss hotplug operations later in this
19393 chapter.)<br>
19394 <br>
19395 Subsystems have the usual list of setup and teardown functions:<br>
19396 <pre>
19397 void subsystem_init(struct subsystem *subsys);
19398 int subsystem_register(struct subsystem *subsys);
19399 void subsystem_unregister(struct subsystem *subsys);
19400 struct subsystem *subsys_get(struct subsystem *subsys)
19401 void subsys_put(struct subsystem *subsys);
19402 </pre>
19403 Most of these operations just act upon the subsystem's kset.<br>
19404 <br>
19405 <a name="LowLevelSysfsOperations"></a><font color="red"><b>Low-Level Sysfs Operations</b></font><br>
19406 <br>
19407 Kobjects are the mechanism behind the sysfs virtual filesystem. For every directory
19408 found in sysfs, there is a kobject lurking somewhere within the kernel. Every kobject
19409 of interest also exports one or more <i>attributes</i>, which appear in that kobject's sysfs
19410 directory as files containing kernel-generated information. This section examines
19411 how kobjects and sysfs interact at a low level.<br>
19412 <br>
19413 Code that works with sysfs should include <i><linux/sysfs.h></i>.<br>
19414 <br>
19415 Getting a kobject to show up in sysfs is simply a matter of calling <i>kobject_add</i>. We
19416 have already seen that function as the way to add a kobject to a kset; creating entries<br>
19417 <br>
19418 <A name="372"></a><font color="blue">PAGE 372</font><br>
19419 <br>
19420 in sysfs is also part of its job. There are a couple of things worth knowing about how
19421 the sysfs entry is created:<br>
19422 <ul>
19423 <li> Sysfs entries for kobjects are always directories, so a call to <i>kobject_add </i>results in
19424 the creation of a directory in sysfs. Usually that directory contains one or more
19425 attributes; we see how attributes are specified shortly.
19426 <li> The name assigned to the kobject (with <i>kobject_set_name</i>) is the name used for
19427 the sysfs directory. Thus, kobjects that appear in the same part of the sysfs hierarchy
19428 must have unique names. Names assigned to kobjects should also be reasonable
19429 file names: they cannot contain the slash character, and the use of white
19430 space is strongly discouraged.
19431 <li> The sysfs entry is located in the directory corresponding to the kobject's <font class="fixd">parent</font>
19432 pointer. If <font class="fixd">parent</font> is <font class="fixd">NULL</font> when <i>kobject_add </i>is called, it is set to the kobject
19433 embedded in the new kobject's kset; thus, the sysfs hierarchy usually matches
19434 the internal hierarchy created with ksets. If both <font class="fixd">parent</font> and <font class="fixd">kset</font> are <font class="fixd">NULL</font>, the
19435 sysfs directory is created at the top level, which is almost certainly not what you want.
19436 </ul>
19437 Using the mechanisms we have described so far, we can use a kobject to create an
19438 empty directory in sysfs. Usually, you want to do something a little more interesting
19439 than that, so it is time to look at the implementation of attributes.<br>
19440 <br>
19441 <a name="DefaultAttributes"></a><font color="red"><b>Default Attributes</b></font><br>
19442 <br>
19443 When created, every kobject is given a set of default attributes. These attributes are
19444 specified by way of the <font class="fixd">kobj_type</font> structure. That structure, remember, looks like
19445 this:<br>
19446 <pre>
19447 struct kobj_type {
19448 void (*release)(struct kobject *);
19449 struct sysfs_ops *sysfs_ops;
19450 struct attribute **default_attrs;
19451 };
19452 </pre>
19453 The <font class="fixd">default_attrs</font> field lists the attributes to be created for every kobject of this
19454 type, and <font class="fixd">sysfs_ops</font> provides the methods to implement those attributes. We start
19455 with <font class="fixd">default_attrs,</font> which points to an array of pointers to attribute structures:<br>
19456 <pre>
19457 struct attribute {
19458 char *name;
19459 struct module *owner;
19460 mode_t mode;
19461 };
19462 </pre>
19463 In this structure, <font class="fixd">name</font> is the name of the attribute (as it appears within the kobject's
19464 sysfs directory), <font class="fixd">owner</font> is a pointer to the module (if any) that is responsible for the
19465 implementation of this attribute, and <font class="fixd">mode</font> is the protection bits that are to be applied
19466 to this attribute. The mode is usually <font class="fixd">S_IRUGO</font> for read-only attributes; if the attribute<br>
19467 <br>
19468 <A name="373"></a><font color="blue">PAGE 373</font><br>
19469 <br>
19470 is writable, you can toss in <font class="fixd">S_IWUSR</font> to give write access to root only (the macros for
19471 modes are defined in <i><linux/stat.h></i>). The last entry in the <font class="fixd">default_attrs</font> list must be
19472 zero-filled.<br>
19473 <br>
19474 The <font class="fixd">default_attrs</font> array says what the attributes are but does not tell sysfs how to
19475 actually implement those attributes. That task falls to the <font class="fixd">kobj_type->sysfs_ops</font> field,
19476 which points to a structure defined as:<br>
19477 <pre>
19478 struct sysfs_ops {
19479 ssize_t (*show)(struct kobject *kobj, struct attribute *attr,
19480 char *buffer);
19481 ssize_t (*store)(struct kobject *kobj, struct attribute *attr,
19482 const char *buffer, size_t size);
19483 };
19484 </pre>
19485 Whenever an attribute is read from user space, the <i>show </i>method is called with a
19486 pointer to the kobject and the appropriate <font class="fixd">attribute</font> structure. That method should
19487 encode the value of the given attribute into <font class="fixd">buffer,</font> being sure not to overrun it (it is
19488 <font class="fixd">PAGE_SIZE</font> bytes), and return the actual length of the returned data. The conventions
19489 for sysfs state that each attribute should contain a single, human-readable value; if
19490 you have a lot of information to return, you may want to consider splitting it into
19491 multiple attributes.<br>
19492 <br>
19493 The same <i>show </i>method is used for all attributes associated with a given kobject. The
19494 <font class="fixd">attr</font> pointer passed into the function can be used to determine which attribute is
19495 being requested. Some <i>show </i>methods include a series of tests on the attribute name.
19496 Other implementations embed the <font class="fixd">attribute</font> structure within another structure that
19497 contains the information needed to return the attribute's value; in this case,
19498 <i>container_of </i>may be used within the <i>show </i>method to obtain a pointer to the embedding
19499 structure.<br>
19500 <br>
19501 The <i>store </i>method is similar; it should decode the data stored in <font class="fixd">buffer</font> (<font class="fixd">size</font> contains
19502 the length of that data, which does not exceed <font class="fixd">PAGE_SIZE</font>), store and respond to
19503 the new value in whatever way makes sense, and return the number of bytes actually
19504 decoded. The <i>store </i>method can be called only if the attribute's permissions allow
19505 writes. When writing a <i>store </i>method, never forget that you are receiving arbitrary
19506 information from user space; you should validate it very carefully before taking any
19507 action in response. If the incoming data does not match expectations, return a negative
19508 error value rather than possibly doing something unwanted and unrecoverable.
19509 If your device exports a <font class="fixd">self_destruct</font> attribute, you should require that a specific
19510 string be written there to invoke that functionality; an accidental, random write
19511 should yield only an error.<br>
19512 <br>
19513 <a name="NondefaultAttributes"></a><font color="red"><b>Nondefault Attributes</b></font><br>
19514 <br>
19515 In many cases, the kobject type's <font class="fixd">default_attrs</font> field describes all the attributes that
19516 kobject will ever have. But that's not a restriction in the design; attributes can be<br>
19517 <br>
19518 <A name="374"></a><font color="blue">PAGE 374</font><br>
19519 <br>
19520 added and removed to kobjects at will. If you wish to add a new attribute to a kobject's
19521 sysfs directory, simply fill in an <font class="fixd">attribute</font> structure and pass it to:<br>
19522 <pre>
19523 int sysfs_create_file(struct kobject *kobj, struct attribute *attr);
19524 </pre>
19525 If all goes well, the file is created with the name given in the <font class="fixd">attribute</font> structure, and
19526 the return value is 0; otherwise, the usual negative error code is returned.<br>
19527 <br>
19528 Note that the same <i>show( ) </i>and <i>store( ) </i>functions are called to implement operations
19529 on the new attribute. Before you add a new, nondefault attribute to a kobject, you
19530 should take whatever steps are necessary to ensure that those functions know how to
19531 implement that attribute.<br>
19532 <br>
19533 To remove an attribute, call:<br>
19534 <pre>
19535 int sysfs_remove_file(struct kobject *kobj, struct attribute *attr);
19536 </pre>
19537 After the call, the attribute no longer appears in the kobject's sysfs entry. Do be
19538 aware, however, that a user-space process could have an open file descriptor for that
19539 attribute and that <i>show </i>and <i>store </i>calls are still possible after the attribute has been
19540 removed.<br>
19541 <br>
19542 <a name="BinaryAttributes"></a><font color="red"><b>Binary Attributes</b></font><br>
19543 <br>
19544 The sysfs conventions call for all attributes to contain a single value in a human-readable
19545 text format. That said, there is an occasional, rare need for the creation of
19546 attributes that can handle larger chunks of binary data. That need really only comes
19547 about when data must be passed, untouched, between user space and the device. For
19548 example, uploading firmware to devices requires this feature. When such a device is
19549 encountered in the system, a user-space program can be started (via the hotplug
19550 mechanism); that program then passes the firmware code to the kernel via a binary
19551 sysfs attribute, as is shown in the section "The Kernel Firmware Interface."<br>
19552 <br>
19553 Binary attributes are described with a <font class="fixd">bin_attribute</font> structure:<br>
19554 <pre>
19555 struct bin_attribute {
19556 struct attribute attr;
19557 size_t size;
19558 ssize_t (*read)(struct kobject *kobj, char *buffer,
19559 loff_t pos, size_t size);
19560 ssize_t (*write)(struct kobject *kobj, char *buffer,
19561 loff_t pos, size_t size);
19562 };
19563 </pre>
19564 Here, <font class="fixd">attr</font> is an <font class="fixd">attribute</font> structure giving the name, owner, and permissions for the
19565 binary attribute, and <font class="fixd">size</font> is the maximum size of the binary attribute (or 0 if there is
19566 no maximum). The <i>read </i>and <i>write </i>methods work similarly to the normal char driver
19567 equivalents; they can be called multiple times for a single load with a maximum of
19568 one page worth of data in each call. There is no way for sysfs to signal the last of a set<br>
19569 <br>
19570 <A name="375"></a><font color="blue">PAGE 375</font><br>
19571 <br>
19572 of write operations, so code implementing a binary attribute must be able to determine
19573 the end of the data some other way.<br>
19574 <br>
19575 Binary attributes must be created explicitly; they cannot be set up as default
19576 attributes. To create a binary attribute, call:<br>
19577 <pre>
19578 int sysfs_create_bin_file(struct kobject *kobj,
19579 struct bin_attribute *attr);
19580 </pre>
19581 Binary attributes can be removed with:<br>
19582 <pre>
19583 int sysfs_remove_bin_file(struct kobject *kobj,
19584 struct bin_attribute *attr);
19585 </pre>
19586 <a name="SymbolicLinks"></a><font color="red"><b>Symbolic Links</b></font><br>
19587 <br>
19588 The sysfs filesystem has the usual tree structure, reflecting the hierarchical organization
19589 of the kobjects it represents. The relationships between objects in the kernel are
19590 often more complicated than that, however. For example, one sysfs subtree (<i>/sys/
19591 devices</i>) represents all of the devices known to the system, while other subtrees
19592 (under <i>/sys/bus</i>) represent the device drivers. These trees do not, however, represent
19593 the relationships between the drivers and the devices they manage. Showing these
19594 additional relationships requires extra pointers which, in sysfs, are implemented
19595 through symbolic links.<br>
19596 <br>
19597 Creating a symbolic link within sysfs is easy:<br>
19598 <pre>
19599 int sysfs_create_link(struct kobject *kobj, struct kobject *target,
19600 char *name);
19601 </pre>
19602 This function creates a link (called <font class="fixd">name</font>) pointing to target's sysfs entry as an
19603 attribute of <font class="fixd">kobj.</font> It is a relative link, so it works regardless of where sysfs is mounted
19604 on any particular system.<br>
19605 <br>
19606 The link persists even if <font class="fixd">target</font> is removed from the system. If you are creating symbolic
19607 links to other kobjects, you should probably have a way of knowing about
19608 changes to those kobjects, or some sort of assurance that the target kobjects will not
19609 disappear. The consequences (dead symbolic links within sysfs) are not particularly
19610 grave, but they are not representative of the best programming style and can cause
19611 confusion in user space.<br>
19612 <br>
19613 Symbolic links can be removed with:<br>
19614 <pre>
19615 void sysfs_remove_link(struct kobject *kobj, char *name);
19616 </pre>
19617 <a name="HotplugEventGeneration"></a><font color="red"><b>Hotplug Event Generation</b></font><br>
19618 <br>
19619 A <i>hotplug event </i>is a notification to user space from the kernel that something has
19620 changed in the system's configuration. They are generated whenever a kobject is created
19621 or destroyed. Such events are generated, for example, when a digital camera is<br>
19622 <br>
19623 <A name="376"></a><font color="blue">PAGE 376</font><br>
19624 <br>
19625 plugged in with a USB cable, when a user switches console modes, or when a disk is
19626 repartitioned. Hotplug events turn into an invocation of <i>/sbin/hotplug</i>, which can
19627 respond to each event by loading drivers, creating device nodes, mounting partitions,
19628 or taking any other action that is appropriate.<br>
19629 <br>
19630 The last major kobject function we look at is the generation of these events. The
19631 actual event generation takes place when a kobject is passed to <i>kobject_add </i>or
19632 <i>kobject_del</i>. Before the event is handed to user space, code associated with the kobject
19633 (or, more specifically, the kset to which it belongs) has the opportunity to add
19634 information for user space or to disable event generation entirely.<br>
19635 <br>
19636 <a name="HotplugOperations"></a><font color="red"><b>Hotplug Operations</b></font><br>
19637 <br>
19638 Actual control of hotplug events is exercised by way of a set of methods stored in the
19639 <font class="fixd">kset_hotplug_ops</font> structure:<br>
19640 <pre>
19641 struct kset_hotplug_ops {
19642 int (*filter)(struct kset *kset, struct kobject *kobj);
19643 char *(*name)(struct kset *kset, struct kobject *kobj);
19644 int (*hotplug)(struct kset *kset, struct kobject *kobj,
19645 char **envp, int num_envp, char *buffer,
19646 int buffer_size);
19647 };
19648 </pre>
19649 A pointer to this structure is found in the <font class="fixd">hotplug_ops</font> field of the kset structure. If a
19650 given kobject is not contained within a kset, the kernel searchs up through the hierarchy
19651 (via the parent pointer) until it finds a kobject that <i>does </i>have a kset; that kset's
19652 hotplug operations are then used.<br>
19653 <br>
19654 The <i>filter </i>hotplug operation is called whenever the kernel is considering generating
19655 an event for a given kobject. If <i>filter </i>returns 0, the event is not created. This method,
19656 therefore, gives the kset code an opportunity to decide which events should be
19657 passed on to user space and which should not.<br>
19658 <br>
19659 As an example of how this method might be used, consider the block subsystem.
19660 There are at least three types of kobjects used there, representing disks, partitions,
19661 and request queues. User space may want to react to the addition of a disk or a partition, but
19662 it does not normally care about request queues. So the <i>filter </i>method allows
19663 event generation only for kobjects representing disks and partitions. It looks like this:<br>
19664 <pre>
19665 static int block_hotplug_filter(struct kset *kset, struct kobject *kobj)
19666 {
19667 struct kobj_type *ktype = get_ktype(kobj);
19669 return ((ktype = = &ktype_block) || (ktype = = &ktype_part));
19670 }
19671 </pre>
19672 Here, a quick test on the type of kobject is sufficient to decide whether the event
19673 should be generated or not.<br>
19674 <br>
19675 <A name="377"></a><font color="blue">PAGE 377</font><br>
19676 <br>
19677 When the user-space hotplug program is invoked, it is passed to the name of the relevant
19678 subsystem as its one and only parameter. The <i>name </i>hotplug method is charged
19679 with providing that name. It should return a simple string suitable for passing to user
19680 space.<br>
19681 <br>
19682 Everything else that the hotplug script might want to know is passed in the environment.
19683 The final hotplug method (<i>hotplug</i>) gives an opportunity to add useful environment
19684 variables prior to the invocation of that script. Again, this method's
19685 prototype is:<br>
19686 <pre>
19687 int (*hotplug)(struct kset *kset, struct kobject *kobj,
19688 char **envp, int num_envp, char *buffer,
19689 int buffer_size);
19690 </pre>
19691 As usual, <font class="fixd">kset</font> and <font class="fixd">kobject</font> describe the object for which the event is being generated.
19692 The <font class="fixd">envp</font> array is a place to store additional environment variable definitions (in
19693 the usual <font class="fixd">NAME=value</font> format); it has <font class="fixd">num_envp</font> entries available. The variables themselves
19694 should be encoded into <font class="fixd">buffer,</font> which is <font class="fixd">buffer_size</font> bytes long. If you add
19695 any variables to <font class="fixd">envp,</font> be sure to add a <font class="fixd">NULL</font> entry after your last addition so that the
19696 kernel knows where the end is. The return value should normally be 0; any nonzero
19697 return aborts the generation of the hotplug event.<br>
19698 <br>
19699 The generation of hotplug events (like much of the work in the device model) is usually
19700 handled by logic at the bus driver level.<br>
19701 <br>
19702 <a name="BusesDevicesAndDrivers"></a><font color="red"><b>Buses, Devices, and Drivers</b></font><br>
19703 <br>
19704 So far, we have seen a great deal of low-level infrastructures and a relative shortage of
19705 examples. We try to make up for that in the rest of this chapter as we get into the
19706 higher levels of the Linux device model. To that end, we introduce a new virtual bus,
19707 which we call <i>lddbus</i>,* and modify the <i>scullp</i> driver to "connect" to that bus.<br>
19708 <br>
19709 Once again, much of the material covered here will never be needed by many driver
19710 authors. Details at this level are generally handled at the bus level, and few authors
19711 need to add a new bus type. This information is useful, however, for anybody wondering
19712 what is happening inside the PCI, USB, etc. layers or who needs to make
19713 changes at that level.<br>
19714 <br>
19715 <a name="Buses"></a><font color="red"><b>Buses</b></font><br>
19716 <br>
19717 A bus is a channel between the processor and one or more devices. For the purposes
19718 of the device model, all devices are connected via a bus, even if it is an internal, virtual, "platform"
19719 bus. Buses can plug into each other--a USB controller is usually a<br>
19720 <br>
19721 * The logical name for this bus, of course, would have been "sbus," but that name was
19722 already taken by a real, physical bus.<br>
19723 <br>
19724 <A name="378"></a><font color="blue">PAGE 378</font><br>
19725 <br>
19726 PCI device, for example. The device model represents the actual connections
19727 between buses and the devices they control.<br>
19728 <br>
19729 In the Linux device model, a bus is represented by the <font class="fixd">bus_type</font> structure, defined in
19730 <i><linux/device.h></i>. This structure looks like:<br>
19731 <pre>
19732 struct bus_type {
19733 char *name;
19734 struct subsystem subsys;
19735 struct kset drivers;
19736 struct kset devices;
19737 int (*match)(struct device *dev, struct device_driver *drv);
19738 struct device *(*add)(struct device * parent, char * bus_id);
19739 int (*hotplug) (struct device *dev, char **envp,
19740 int num_envp, char *buffer, int buffer_size);
19741 /* Some fields omitted */
19742 };
19743 </pre>
19744 The <font class="fixd">name</font> field is the name of the bus, something such as <font class="fixd">pci.</font> You can see from the
19745 structure that each bus is its own subsystem; these subsystems do not live at the top
19746 level in sysfs, however. Instead, they are found underneath the <font class="fixd">bus</font> subsystem. A bus
19747 contains two ksets, representing the known drivers for that bus and all devices
19748 plugged into the bus. Then, there is a set of methods that we will get to shortly.<br>
19749 <br>
19750 <a name="BusRegistration"></a><font color="red"><b>Bus registration</b></font><br>
19751 <br>
19752 As we mentioned, the example source includes a virtual bus implementation called
19753 <i>lddbus</i>. This bus sets up its <font class="fixd">bus_type</font> structure as follows:<br>
19754 <pre>
19755 struct bus_type ldd_bus_type = {
19756 .name = "ldd",
19757 .match = ldd_match,
19758 .hotplug = ldd_hotplug,
19759 };
19760 </pre>
19761 Note that very few of the <font class="fixd">bus_type</font> fields require initialization; most of that is handled
19762 by the device model core. We do have to specify the name of the bus, however,
19763 and any methods that go along with it.<br>
19764 <br>
19765 Inevitably, a new bus must be registered with the system via a call to <i>bus_register</i>.
19766 The <i>lddbus</i> code does so in this way:<br>
19767 <pre>
19768 ret = bus_register(&ldd_bus_type);
19769 if (ret)
19770 return ret;
19771 </pre>
19772 This call can fail, of course, so the return value must always be checked. If it succeeds, the
19773 new bus subsystem has been added to the system; it is visible in sysfs
19774 under <i>/sys/bus</i>, and it is possible to start adding devices.<br>
19775 <br>
19776 Should it be necessary to remove a bus from the system (when the associated module
19777 is removed, for example), <i>bus_unregister</i> should be called:<br>
19778 <pre>
19779 void bus_unregister(struct bus_type *bus);
19780 </pre>
19781 <A name="379"></a><font color="blue">PAGE 379</font><br>
19782 <br>
19783 <a name="BusMethods"></a><font color="red"><b>Bus methods</b></font><br>
19784 <br>
19785 There are several methods defined for the <font class="fixd">bus_type</font> structure; they allow the bus code
19786 to serve as an intermediary between the device core and individual drivers. The
19787 methods defined in the 2.6.10 kernel are:<br>
19788 <br>
19789 <font class="fixd">int (*match)(struct device *device, struct device_driver *driver);</font><br>
19790 <div class="bq">
19791 This method is called, perhaps multiple times, whenever a new device or driver
19792 is added for this bus. It should return a nonzero value if the given device can be
19793 handled by the given driver. (We get to the details of the <font class="fixd">device</font>
19794 and <font class="fixd">device_driver</font> structures shortly). This function must be handled at the bus level,
19795 because that is where the proper logic exists; the core kernel cannot know how
19796 to match devices and drivers for every possible bus type.</div>
19797 <br>
19798 <font class="fixd">int (*hotplug) (struct device *device, char **envp, int num_envp, char *buffer, int buffer_size);</font><br>
19799 <div class="bq">
19800 This method allows the bus to add variables to the environment prior to the generation
19801 of a hotplug event in user space. The parameters are the same as for the kset
19802 <i>hotplug</i> method (described in the earlier section "Hotplug Event Generation").</div>
19803 <br>
19804 The <i>lddbus </i>driver has a very simple <i>match </i>function, which simply compares the
19805 driver and device names:<br>
19806 <pre>
19807 static int ldd_match(struct device *dev, struct device_driver *driver)
19808 {
19809 return !strncmp(dev->bus_id, driver->name, strlen(driver->name));
19810 }
19811 </pre>
19812 When real hardware is involved, the <i>match </i>function usually makes some sort of comparison
19813 between the hardware ID provided by the device itself and the IDs supported
19814 by the driver.<br>
19815 <br>
19816 The <i>lddbus hotplug</i> method looks like this:<br>
19817 <pre>
19818 static int ldd_hotplug(struct device *dev, char **envp, int num_envp,
19819 char *buffer, int buffer_size)
19820 {
19821 envp[0] = buffer;
19822 if (snprintf(buffer, buffer_size, "LDDBUS_VERSION=%s",
19823 Version) >= buffer_size)
19824 return -ENOMEM;
19825 envp[1] = NULL;
19826 return 0;
19827 }
19828 </pre>
19829 Here, we add in the current revision number of the <i>lddbus </i>source, just in case anybody
19830 is curious.<br>
19831 <br>
19832 <a name="IteratingOverDevicesAndDrivers"></a><font color="red"><b>Iterating over devices and drivers</b></font><br>
19833 <br>
19834 If you are writing bus-level code, you may find yourself having to perform some
19835 operation on all devices or drivers that have been registered with your bus. It may be<br>
19836 <br>
19837 <A name="380"></a><font color="blue">PAGE 380</font><br>
19838 <br>
19839 tempting to dig directly into the structures in the <font class="fixd">bus_type</font> structure, but it is better
19840 to use the helper functions that have been provided.<br>
19841 <br>
19842 To operate on every device known to the bus, use:<br>
19843 <pre>
19844 int bus_for_each_dev(struct bus_type *bus, struct device *start,
19845 void *data, int (*fn)(struct device *, void *));
19846 </pre>
19847 This function iterates over every device on <font class="fixd">bus,</font> passing the associated <font class="fixd">device structure</font>
19848 to <font class="fixd">fn,</font> along with the value passed in as <font class="fixd">data.</font> If start is <font class="fixd">NULL</font>, the iteration begins
19849 with the first device on the bus; otherwise iteration starts with the first device after
19850 <font class="fixd">start.</font> If fn returns a nonzero value, iteration stops and that value is returned from
19851 <i>bus_for_each_dev</i>.<br>
19852 <br>
19853 There is a similar function for iterating over drivers:<br>
19854 <pre>
19855 int bus_for_each_drv(struct bus_type *bus, struct device_driver *start,
19856 void *data, int (*fn)(struct device_driver *, void *));
19857 </pre>
19858 This function works just like <i>bus_for_each_dev</i>, except, of course, that it works with
19859 drivers instead.<br>
19860 <br>
19861 It should be noted that both of these functions hold the bus subsystem's reader/writer
19862 semaphore for the duration of the work. So an attempt to use the two of them
19863 together will deadlock--each will be trying to obtain the same semaphore. Operations
19864 that modify the bus (such as unregistering devices) will also lock up. So, use the
19865 <i>bus_for_each</i> functions with some care.<br>
19866 <br>
19867 <a name="BusAttributes"></a><font color="red"><b>Bus attributes</b></font><br>
19868 <br>
19869 Almost every layer in the Linux device model provides an interface for the addition
19870 of attributes, and the bus layer is no exception. The <font class="fixd">bus_attribute</font> type is defined in
19871 <i><linux/device.h></i> as follows:<br>
19872 <pre>
19873 struct bus_attribute {
19874 struct attribute attr;
19875 ssize_t (*show)(struct bus_type *bus, char *buf);
19876 ssize_t (*store)(struct bus_type *bus, const char *buf,
19877 size_t count);
19878 };
19879 </pre>
19880 We have already seen <font class="fixd">struct attribute</font> in the section "Default Attributes." The
19881 <font class="fixd">bus_attribute</font> type also includes two methods for displaying and setting the value
19882 of the attribute. Most device model layers above the kobject level work this way.<br>
19883 <br>
19884 A convenience macro has been provided for the compile-time creation and initialization
19885 of <font class="fixd">bus_attribute</font> structures:<br>
19886 <pre>
19887 BUS_ATTR(name, mode, show, store);
19888 </pre>
19889 This macro declares a structure, generating its name by prepending the string <font class="fixd">bus_attr_</font>
19890 to the given <font class="fixd">name.</font><br>
19891 <br>
19892 <A name="381"></a><font color="blue">PAGE 381</font><br>
19893 <br>
19894 Any attributes belonging to a bus should be created explicitly with <i>bus_create_file</i>:<br>
19895 <pre>
19896 int bus_create_file(struct bus_type *bus, struct bus_attribute *attr);
19897 </pre>
19898 Attributes can also be removed with:<br>
19899 <pre>
19900 void bus_remove_file(struct bus_type *bus, struct bus_attribute *attr);
19901 </pre>
19902 The <i>lddbus </i>driver creates a simple attribute file containing, once again, the source
19903 version number. The <i>show</i> method and <font class="fixd">bus_attribute</font> structure are set up as follows:<br>
19904 <pre>
19905 static ssize_t show_bus_version(struct bus_type *bus, char *buf)
19906 {
19907 return snprintf(buf, PAGE_SIZE, "%s\n", Version);
19908 }
19910 static BUS_ATTR(version, S_IRUGO, show_bus_version, NULL);
19911 </pre>
19912 Creating the attribute file is done at module load time:<br>
19913 <pre>
19914 if (bus_create_file(&ldd_bus_type, &bus_attr_version))
19915 printk(KERN_NOTICE "Unable to create version attribute\n");
19916 </pre>
19917 This call creates an attribute file (<i>/sys/bus/ldd/version</i>) containing the revision number
19918 for the <i>lddbus</i> code.<br>
19919 <br>
19920 <a name="Devices"></a><font color="red"><b>Devices</b></font><br>
19921 <br>
19922 At the lowest level, every device in a Linux system is represented by an instance of
19923 <font class="fixd">struct device:</font><br>
19924 <pre>
19925 struct device {
19926 struct device *parent;
19927 struct kobject kobj;
19928 char bus_id[BUS_ID_SIZE];
19929 struct bus_type *bus;
19930 struct device_driver *driver;
19931 void *driver_data;
19932 void (*release)(struct device *dev);
19933 /* Several fields omitted */
19934 };
19935 </pre>
19936 There are many other <font class="fixd">struct device</font> fields that are of interest only to the device core
19937 code. These fields, however, are worth knowing about:<br>
19938 <br>
19939 <font class="fixd">struct device *parent</font><br>
19940 <div class="bq">
19941 The device's "parent" device--the device to which it is attached. In most cases, a
19942 parent device is some sort of bus or host controller. If <font class="fixd">parent</font> is <font class="fixd">NULL</font>, the device
19943 is a top-level device, which is not usually what you want.</div>
19944 <br>
19945 <font class="fixd">struct kobject kobj;</font><br>
19946 <div class="bq">
19947 The kobject that represents this device and links it into the hierarchy. Note that,
19948 as a general rule, <font class="fixd">device->kobj->parent</font> is equal to <font class="fixd">&device->parent->kobj.</font></div>
19949 <br>
19950 <A name="382"></a><font color="blue">PAGE 382</font><br>
19951 <br>
19952 <font class="fixd">char bus_id[BUS_ID_SIZE];</font><br>
19953 <div class="bq">
19954 A string that uniquely identifies this device on the bus. PCI devices, for example, use
19955 the standard PCI ID format containing the domain, bus, device, and function numbers.</div>
19956 <br>
19957 <font class="fixd">struct bus_type *bus;</font><br>
19958 <div class="bq">
19959 Identifies which kind of bus the device sits on.</div>
19960 <br>
19961 <font class="fixd">struct device_driver *driver;</font><br>
19962 <div class="bq">
19963 The driver that manages this device; we examine <font class="fixd">struct device_driver</font> in the next section.</div>
19964 <br>
19965 <font class="fixd">void *driver_data;</font><br>
19966 <div class="bq">
19967 A private data field that may be used by the device driver.</div>
19968 <br>
19969 <font class="fixd">void (*release)(struct device *dev);</font><br>
19970 <div class="bq">
19971 The method is called when the last reference to the device is removed; it is called
19972 from the embedded kobject's <i>release </i>method. All device structures registered with
19973 the core must have a <i>release</i> method, or the kernel prints out scary complaints.</div>
19974 <br>
19975 At a minimum, the <font class="fixd">parent, bus_id, bus,</font> and <font class="fixd">release</font> fields must be set before the
19976 device structure can be registered.<br>
19977 <br>
19978 <a name="DeviceRegistration"></a><font color="red"><b>Device registration</b></font><br>
19979 <br>
19980 The usual set of registration and unregistration functions exists:<br>
19981 <pre>
19982 int device_register(struct device *dev);
19983 void device_unregister(struct device *dev);
19984 </pre>
19985 We have seen how the <i>lddbus </i>code registers its bus type. However, an actual bus is a
19986 device and must be registered separately. For simplicity, the <i>lddbus </i>module supports
19987 only a single virtual bus, so the driver sets up its device at compile time:<br>
19988 <pre>
19989 static void ldd_bus_release(struct device *dev)
19990 {
19991 printk(KERN_DEBUG "lddbus release\n");
19992 }
19994 struct device ldd_bus = {
19995 .bus_id = "ldd0",
19996 .release = ldd_bus_release
19997 };
19998 </pre>
19999 This is a top-level bus, so the <font class="fixd">parent</font> and <font class="fixd">bus</font> fields are left <font class="fixd">NULL</font>. We have a simple,
20000 no-op <i>release </i>method, and, as the first (and only) bus, its name is <font class="fixd">ldd0.</font> This bus
20001 device is registered with:<br>
20002 <pre>
20003 ret = device_register(&ldd_bus);
20004 if (ret)
20005 printk(KERN_NOTICE "Unable to register ldd0\n");
20006 </pre>
20007 Once that call is complete, the new bus can be seen under <i>/sys/devices </i>in sysfs. Any
20008 devices added to this bus then shows up under <i>/sys/devices/ldd0/</i>.<br>
20009 <br>
20010 <A name="383"></a><font color="blue">PAGE 383</font><br>
20011 <br>
20012 <a name="DeviceAttributes"></a><font color="red"><b>Device attributes</b></font><br>
20013 <br>
20014 Device entries in sysfs can have attributes. The relevant structure is:<br>
20015 <pre>
20016 struct device_attribute {
20017 struct attribute attr;
20018 ssize_t (*show)(struct device *dev, char *buf);
20019 ssize_t (*store)(struct device *dev, const char *buf,
20020 size_t count);
20021 };
20022 </pre>
20023 These attribute structures can be set up at compile time with this macro:<br>
20024 <pre>
20025 DEVICE_ATTR(name, mode, show, store);
20026 </pre>
20027 The resulting structure is named by prepending <font class="fixd">dev_attr_</font> to the given <font class="fixd">name.</font> The
20028 actual management of attribute files is handled with the usual pair of functions:<br>
20029 <pre>
20030 int device_create_file(struct device *device,
20031 struct device_attribute *entry);
20032 void device_remove_file(struct device *dev,
20033 struct device_attribute *attr);
20034 </pre>
20035 The <font class="fixd">dev_attrs</font> field of <font class="fixd">struct bus_type</font> points to a list of default attributes created for
20036 every device added to that bus.<br>
20037 <br>
20038 <a name="DeviceStructureEmbedding"></a><font color="red"><b>Device structure embedding</b></font><br>
20039 <br>
20040 The <font class="fixd">device</font> structure contains the information that the device model core needs to
20041 model the system. Most subsystems, however, track additional information about
20042 the devices they host. As a result, it is rare for devices to be represented by bare
20043 device structures; instead, that structure, like kobject structures, is usually embedded
20044 within a higher-level representation of the device. If you look at the definitions of
20045 <font class="fixd">struct pci_dev</font> or <font class="fixd">struct usb_device,</font> you will find a <font class="fixd">struct device</font> buried inside.
20046 Usually, low-level drivers are not even aware of that <font class="fixd">struct device,</font> but there can be
20047 exceptions.<br>
20048 <br>
20049 The <i>lddbus </i>driver creates its own device type (<font class="fixd">struct ldd_device</font>) and expects individual
20050 device drivers to register their devices using that type. It is a simple structure:<br>
20051 <pre>
20052 struct ldd_device {
20053 char *name;
20054 struct ldd_driver *driver;
20055 struct device dev;
20056 };
20058 #define to_ldd_device(dev) container_of(dev, struct ldd_device, dev);
20059 </pre>
20060 This structure allows the driver to provide an actual name for the device (which can be
20061 distinct from its bus ID, stored in the <font class="fixd">device</font> structure) and a pointer to driver information.
20062 Structures for real devices usually also contain information about the vendor,
20063 device model, device configuration, resources used, and so on. Good examples can be<br>
20064 <br>
20065 <A name="384"></a><font color="blue">PAGE 384</font><br>
20066 <br>
20067 found in <font class="fixd">struct pci_dev</font> (<i><linux/pci.h></i>) or <font class="fixd">struct usb_device</font> (<i><linux/usb.h></i>). A convenience
20068 macro (<i>to_ldd_device</i>) is also defined for <font class="fixd">struct ldd_device</font> to make it easy to
20069 turn pointers to the embedded device structure into <font class="fixd">ldd_device</font> pointers.<br>
20070 <br>
20071 The registration interface exported by <i>lddbus</i> looks like this:<br>
20072 <pre>
20073 int register_ldd_device(struct ldd_device *ldddev)
20074 {
20075 ldddev->dev.bus = &ldd_bus_type;
20076 ldddev->dev.parent = &ldd_bus;
20077 ldddev->dev.release = ldd_dev_release;
20078 strncpy(ldddev->dev.bus_id, ldddev->name, BUS_ID_SIZE);
20079 return device_register(&ldddev->dev);
20080 }
20081 EXPORT_SYMBOL(register_ldd_device);
20082 </pre>
20083 Here, we simply fill in some of the embedded <font class="fixd">device</font> structure fields (which individual
20084 drivers should not need to know about), and register the device with the driver
20085 core. If we wanted to add bus-specific attributes to the device, we could do so here.<br>
20086 <br>
20087 To show how this interface is used, let us introduce another sample driver, which we
20088 have called <i>sculld</i>. It is yet another variant on the <i>scullp </i>driver first introduced in
20089 Chapter 8. It implements the usual memory area device, but <i>sculld </i>also works with
20090 the Linux device model by way of the <i>lddbus</i> interface.<br>
20091 <br>
20092 The <i>sculld </i>driver adds an attribute of its own to its device entry; this attribute, called
20093 dev, simply contains the associated device number. This attribute could be used by a
20094 module loading the script or the hotplug subsystem to automatically create device
20095 nodes when the device is added to the system. The setup for this attribute follows the
20096 usual patterns:<br>
20097 <pre>
20098 static ssize_t sculld_show_dev(struct device *ddev, char *buf)
20099 {
20100 struct sculld_dev *dev = ddev->driver_data;
20102 return print_dev_t(buf, dev->cdev.dev);
20103 }
20105 static DEVICE_ATTR(dev, S_IRUGO, sculld_show_dev, NULL);
20106 </pre>
20107 Then, at initialization time, the device is registered, and the <font class="fixd">dev</font> attribute is created
20108 through the following function:<br>
20109 <pre>
20110 static void sculld_register_dev(struct sculld_dev *dev, int index)
20111 {
20112 sprintf(dev->devname, "sculld%d", index);
20113 dev->ldev.name = dev->devname;
20114 dev->ldev.driver = &sculld_driver;
20115 dev->ldev.dev.driver_data = dev;
20116 register_ldd_device(&dev->ldev);
20117 device_create_file(&dev->ldev.dev, &dev_attr_dev);
20118 }
20119 </pre>
20120 <A name="385"></a><font color="blue">PAGE 385</font><br>
20121 <br>
20122 Note that we make use of the <font class="fixd">driver_data</font> field to store the pointer to our own, internal
20123 device structure.<br>
20124 <br>
20125 <a name="DeviceDrivers"></a><font color="red"><b>Device Drivers</b></font><br>
20126 <br>
20127 The device model tracks all of the drivers known to the system. The main reason for
20128 this tracking is to enable the driver core to match up drivers with new devices. Once
20129 drivers are known objects within the system, however, a number of other things
20130 become possible. Device drivers can export information and configuration variables
20131 that are independent of any specific device, for example.<br>
20132 <br>
20133 Drivers are defined by the following structure:<br>
20134 <pre>
20135 struct device_driver {
20136 char *name;
20137 struct bus_type *bus;
20138 struct kobject kobj;
20139 struct list_head devices;
20140 int (*probe)(struct device *dev);
20141 int (*remove)(struct device *dev);
20142 void (*shutdown) (struct device *dev);
20143 };
20144 </pre>
20145 Once again, several of the structure's fields have been omitted (see <i><linux/device.h>
20146 </i>for the full story). Here, <font class="fixd">name</font> is the name of the driver (it shows up in sysfs), <font class="fixd">bus</font> is
20147 the type of bus this driver works with, <font class="fixd">kobj</font> is the inevitable kobject, <font class="fixd">devices</font> is a list
20148 of all devices currently bound to this driver, <i>probe </i>is a function called to query the
20149 existence of a specific device (and whether this driver can work with it), <font class="fixd">remove</font> is
20150 called when the device is removed from the system, and <font class="fixd">shutdown</font> is called at shutdown
20151 time to quiesce the device.<br>
20152 <br>
20153 The form of the functions for working with <font class="fixd">device_driver</font> structures should be looking
20154 familiar by now (so we cover them very quickly). The registration functions are:<br>
20155 <pre>
20156 int driver_register(struct device_driver *drv);
20157 void driver_unregister(struct device_driver *drv);
20158 </pre>
20159 The usual attribute structure exists:<br>
20160 <pre>
20161 struct driver_attribute {
20162 struct attribute attr;
20163 ssize_t (*show)(struct device_driver *drv, char *buf);
20164 ssize_t (*store)(struct device_driver *drv, const char *buf,
20165 size_t count);
20166 };
20167 DRIVER_ATTR(name, mode, show, store);
20168 </pre>
20169 And attribute files are created in the usual way:<br>
20170 <pre>
20171 int driver_create_file(struct device_driver *drv,
20172 struct driver_attribute *attr);
20173 void driver_remove_file(struct device_driver *drv,
20174 struct driver_attribute *attr);
20175 </pre>
20176 <A name="386"></a><font color="blue">PAGE 386</font><br>
20177 <br>
20178 The <font class="fixd">bus_type</font> structure contains a field (<font class="fixd">drv_attrs</font>) that points to a set of default
20179 attributes, which are created for all drivers associated with that bus.<br>
20180 <br>
20181 <a name="DriverStructureEmbedding"></a><font color="red"><b>Driver structure embedding</b></font><br>
20182 <br>
20183 As is the case with most driver core structures, the <font class="fixd">device_driver</font> structure is usually
20184 found embedded within a higher-level, bus-specific structure. The <i>lddbus </i>subsystem
20185 would never go against such a trend, so it has defined its own <font class="fixd">ldd_driver</font> structure:<br>
20186 <pre>
20187 struct ldd_driver {
20188 char *version;
20189 struct module *module;
20190 struct device_driver driver;
20191 struct driver_attribute version_attr;
20192 };
20194 #define to_ldd_driver(drv) container_of(drv, struct ldd_driver, driver);
20195 </pre>
20196 Here, we require each driver to provide its current software version, and <i>lddbus
20197 </i>exports that version string for every driver it knows about. The bus-specific driver
20198 registration function is:<br>
20199 <pre>
20200 int register_ldd_driver(struct ldd_driver *driver)
20201 {
20202 int ret;
20204 driver->driver.bus = &ldd_bus_type;
20205 ret = driver_register(&driver->driver);
20206 if (ret)
20207 return ret;
20208 driver->version_attr.attr.name = "version";
20209 driver->version_attr.attr.owner = driver->module;
20210 driver->version_attr.attr.mode = S_IRUGO;
20211 driver->version_attr.show = show_version;
20212 driver->version_attr.store = NULL;
20213 return driver_create_file(&driver->driver, &driver->version_attr);
20214 }
20215 </pre>
20216 The first half of the function simply registers the low-level <font class="fixd">device_driver</font> structure
20217 with the core; the rest sets up the <font class="fixd">version</font> attribute. Since this attribute is created at
20218 runtime, we can't use the <font class="fixd">DRIVER_ATTR</font> macro; instead, the <font class="fixd">driver_attribute</font> structure
20219 must be filled in by hand. Note that we set the owner of the attribute to the
20220 driver module, rather than the <i>lddbus </i>module; the reason for this can be seen in the
20221 implementation of the <i>show</i> function for this attribute:<br>
20222 <pre>
20223 static ssize_t show_version(struct device_driver *driver, char *buf)
20224 {
20225 struct ldd_driver *ldriver = to_ldd_driver(driver);
20227 sprintf(buf, "%s\n", ldriver->version);
20228 return strlen(buf);
20229 }
20230 </pre>
20231 <A name="387"></a><font color="blue">PAGE 387</font><br>
20232 <br>
20233 One might think that the attribute owner should be the <i>lddbus </i>module, since the
20234 function that implements the attribute is defined there. This function, however, is
20235 working with the <font class="fixd">ldd_driver</font> structure created (and owned) by the driver itself. If
20236 that structure were to go away while a user-space process tried to read the version
20237 number, things could get messy. Designating the driver module as the owner of the
20238 attribute prevents the module from being unloaded, while user-space holds the
20239 attribute file open. Since each driver module creates a reference to the <i>lddbus </i>module,
20240 we can be sure that <i>lddbus</i> will not be unloaded at an inopportune time.<br>
20241 <br>
20242 For completeness, <i>sculld</i> creates its <font class="fixd">ldd_driver</font> structure as follows:<br>
20243 <pre>
20244 static struct ldd_driver sculld_driver = {
20245 .version = "$Revision: 1.1 $",
20246 .module = THIS_MODULE,
20247 .driver = {
20248 .name = "sculld",
20249 },
20250 };
20251 </pre>
20252 A simple call to <i>register_ldd_driver </i>adds it to the system. Once initialization is complete,
20253 the driver information can be seen in sysfs:<br>
20254 <pre>
20255 $ <b>tree /sys/bus/ldd/drivers
20256 </b>/sys/bus/ldd/drivers
20257 `-- sculld
20258 |-- sculld0 -> ../../../../devices/ldd0/sculld0
20259 |-- sculld1 -> ../../../../devices/ldd0/sculld1
20260 |-- sculld2 -> ../../../../devices/ldd0/sculld2
20261 |-- sculld3 -> ../../../../devices/ldd0/sculld3
20262 `-- version
20263 </pre>
20264 <a name="Classes"></a><font color="red"><b>Classes</b></font><br>
20265 <br>
20266 The final device model concept we examine in this chapter is the <i>class</i>. A class is a
20267 higher-level view of a device that abstracts out low-level implementation details.
20268 Drivers may see a SCSI disk or an ATA disk, but, at the class level, they are all simply
20269 disks. Classes allow user space to work with devices based on what they do,
20270 rather than how they are connected or how they work.<br>
20271 <br>
20272 Almost all classes show up in sysfs under <i>/sys/class</i>. Thus, for example, all network
20273 interfaces can be found under <i>/sys/class/net</i>, regardless of the type of interface. Input
20274 devices can be found in <i>/sys/class/input</i>, and serial devices are in <i>/sys/class/tty</i>. The
20275 one exception is block devices, which can be found under <i>/sys/block </i>for historical
20276 reasons.<br>
20277 <br>
20278 Class membership is usually handled by high-level code without the need for explicit
20279 support from drivers. When the <i>sbull </i>driver (see Chapter 16) creates a virtual disk
20280 device, it automatically appears in <i>/sys/block</i>. The <i>snull </i>network driver (see
20281 Chapter 17) does not have to do anything special for its interfaces to be represented<br>
20282 <br>
20283 <A name="388"></a><font color="blue">PAGE 388</font><br>
20284 <br>
20285 in <i>/sys/class/net</i>. There will be times, however, when drivers end up dealing with
20286 classes directly.<br>
20287 <br>
20288 In many cases, the class subsystem is the best way of exporting information to user
20289 space. When a subsystem creates a class, it owns the class entirely, so there is no
20290 need to worry about which module owns the attributes found there. It also takes very little
20291 time wandering around in the more hardware-oriented parts of sysfs to realize that it
20292 can be an unfriendly place for direct browsing. Users more happily find information in
20293 <i>/sys/class/some-widget</i> than under, say,<br>
20294 <br>
20295 <i>/sys/devices/pci0000:00/0000:00:10.0/usb2/2-0:1.0</i>.<br>
20296 <br>
20297 The driver core exports two distinct interfaces for managing classes. The <i>class_simple
20298 </i>routines are designed to make it as easy as possible to add new classes to the system;
20299 their main purpose, usually, is to expose attributes containing device numbers to
20300 enable the automatic creation of device nodes. The regular class interface is more
20301 complex but offers more features as well. We start with the simple version.<br>
20302 <br>
20303 <a name="TheClasssimpleInterface"></a><font color="red"><b>The <font class="fixd">class_simple</font> Interface</b></font><br>
20304 <br>
20305 The <i>class_simple </i>interface was intended to be so easy to use that nobody would have
20306 any excuse for not exporting, at a minimum, an attribute containing a device's
20307 assigned number. Using this interface is simply a matter of a couple of function calls,
20308 with little of the usual boilerplate associated with the Linux device model.<br>
20309 <br>
20310 The first step is to create the class itself. That is accomplished with a call to <i>class_
20311 simple_create</i>:<br>
20312 <pre>
20313 struct class_simple *class_simple_create(struct module *owner, char *name);
20314 </pre>
20315 This function creates a class with the given <font class="fixd">name.</font> The operation can fail, of course, so
20316 the return value should always be checked (using <i><font class="fixd">IS_ERR</font></i>, described in the section
20317 "Pointers and Error Values" in Chapter 1) before continuing.<br>
20318 <br>
20319 A simple class can be destroyed with:<br>
20320 <pre>
20321 void class_simple_destroy(struct class_simple *cs);
20322 </pre>
20323 The real purpose of creating a simple class is to add devices to it; that task is
20324 achieved with:<br>
20325 <pre>
20326 struct class_device *class_simple_device_add(struct class_simple *cs,
20327 dev_t devnum,
20328 struct device *device,
20329 const char *fmt, ...);
20330 </pre>
20331 Here, <font class="fixd">cs</font> is the previously created simple class, <font class="fixd">devnum</font> is the assigned device number,
20332 device is the <font class="fixd">struct device</font> representing this device, and the remaining parameters
20333 are a <i>printk</i>-style format string and arguments to create the device name. This call
20334 adds an entry to the class containing one attribute, <font class="fixd">dev,</font> which holds the device number.
20335 If the <font class="fixd">device</font> parameter is not <font class="fixd">NULL</font>, a symbolic link (called device) points to the
20336 device's entry under <i>/sys/devices</i>.<br>
20337 <br>
20338 <A name="389"></a><font color="blue">PAGE 389</font><br>
20339 <br>
20340 It is possible to add other attributes to a device entry. It is just a matter of using
20341 <i>class_device_create_file</i>, which we discuss in the next section with the rest of the full
20342 class subsystem.<br>
20343 <br>
20344 Classes generate hotplug events when devices come and go. If your driver needs to
20345 add variables to the environment for the user-space event handler, it can set up a hotplug
20346 callback with:<br>
20347 <pre>
20348 int class_simple_set_hotplug(struct class_simple *cs,
20349 int (*hotplug)(struct class_device *dev,
20350 char **envp, int num_envp,
20351 char *buffer, int buffer_size));
20352 </pre>
20353 When your device goes away, the class entry should be removed with:<br>
20354 <pre>
20355 void class_simple_device_remove(dev_t dev);
20356 </pre>
20357 Note that the <font class="fixd">class_device</font> structure returned by <i>class_simple_device_add </i>is not
20358 needed here; the device number (which should certainly be unique) is sufficient.<br>
20359 <br>
20360 <a name="TheFullClassInterface"></a><font color="red"><b>The Full Class Interface</b></font><br>
20361 <br>
20362 The <i>class_simple </i>interface suffices for many needs, but sometimes more flexibility is
20363 required. The following discussion describes how to use the full class mechanism,
20364 upon which <i>class_simple </i>is based. It is brief: the class functions and structures follow
20365 the same patterns as the rest of the device model, so there is little that is truly
20366 new here.<br>
20367 <br>
20368 <a name="ManagingClasses"></a><font color="red"><b>Managing classes</b></font><br>
20369 <br>
20370 A class is defined by an instance of <font class="fixd">struct class</font>:<br>
20371 <pre>
20372 struct class {
20373 char *name;
20374 struct class_attribute *class_attrs;
20375 struct class_device_attribute *class_dev_attrs;
20376 int (*hotplug)(struct class_device *dev, char **envp,
20377 int num_envp, char *buffer, int buffer_size);
20378 void (*release)(struct class_device *dev);
20379 void (*class_release)(struct class *class);
20380 /* Some fields omitted */
20381 };
20382 </pre>
20383 Each class needs a unique <font class="fixd">name,</font> which is how this class appears under <i>/sys/class</i>.
20384 When the class is registered, all of the attributes listed in the (<font class="fixd">NULL</font>-terminated) array
20385 pointed to by <font class="fixd">class_attrs</font> is created. There is also a set of default attributes for every
20386 device added to the class; <font class="fixd">class_dev_attrs</font> points to those. There is the usual <i>hotplug
20387 </i>function for adding variables to the environment when events are generated.
20388 There are also two <i>release </i>methods: <i>release </i>is called whenever a device is removed
20389 from the class, while <i>class_release</i> is called when the class itself is released.<br>
20390 <br>
20391 <A name="390"></a><font color="blue">PAGE 390</font><br>
20392 <br>
20393 The registration functions are:<br>
20394 <pre>
20395 int class_register(struct class *cls);
20396 void class_unregister(struct class *cls);
20397 </pre>
20398 The interface for working with attributes should not surprise anybody at this point:<br>
20399 <pre>
20400 struct class_attribute {
20401 struct attribute attr;
20402 ssize_t (*show)(struct class *cls, char *buf);
20403 ssize_t (*store)(struct class *cls, const char *buf, size_t count);
20404 };
20406 CLASS_ATTR(name, mode, show, store);
20408 int class_create_file(struct class *cls,
20409 const struct class_attribute *attr);
20410 void class_remove_file(struct class *cls,
20411 const struct class_attribute *attr);
20412 </pre>
20413 <a name="ClassDevices"></a><font color="red"><b>Class devices</b></font><br>
20414 <br>
20415 The real purpose of a class is to serve as a container for the devices that are members
20416 of that class. A member is represented by <font class="fixd">struct class_device</font>:<br>
20417 <pre>
20418 struct class_device {
20419 struct kobject kobj;
20420 struct class *class;
20421 struct device *dev;
20422 void *class_data;
20423 char class_id[BUS_ID_SIZE];
20424 };
20425 </pre>
20426 The <font class="fixd">class_id</font> field holds the name of this device as it appears in sysfs. The class
20427 pointer should point to the class holding this device, and <font class="fixd">dev</font> should point to the
20428 associated <font class="fixd">device</font> structure. Setting <font class="fixd">dev</font> is optional; if it is <font class="fixd">non-NULL</font>, it is used to create
20429 a symbolic link from the class entry to the corresponding entry under <i>/sys/devices</i>,
20430 making it easy to find the device entry in user space. The class can use <font class="fixd">class_data</font> to
20431 hold a private pointer.<br>
20432 <br>
20433 The usual registration functions have been provided:<br>
20434 <pre>
20435 int class_device_register(struct class_device *cd);
20436 void class_device_unregister(struct class_device *cd);
20437 </pre>
20438 The class device interface also allows the renaming of an already registered entry:<br>
20439 <pre>
20440 int class_device_rename(struct class_device *cd, char *new_name);
20441 </pre>
20442 Class device entries have attributes:<br>
20443 <pre>
20444 struct class_device_attribute {
20445 struct attribute attr;
20446 ssize_t (*show)(struct class_device *cls, char *buf);
20447 ssize_t (*store)(struct class_device *cls, const char *buf,
20448 size_t count);
20449 };
20450 </pre>
20451 <A name="391"></a><font color="blue">PAGE 391</font><br>
20452 <pre>
20453 CLASS_DEVICE_ATTR(name, mode, show, store);
20455 int class_device_create_file(struct class_device *cls,
20456 const struct class_device_attribute *attr);
20457 void class_device_remove_file(struct class_device *cls,
20458 const struct class_device_attribute *attr);
20459 </pre>
20460 A default set of attributes, in the class's <font class="fixd">class_dev_attrs</font> field, is created when the
20461 class device is registered; <i>class_device_create_file </i>may be used to create additional
20462 attributes. Attributes may also be added to class devices created with the <i>class_simple
20463 </i>interface.<br>
20464 <br>
20465 <a name="ClassInterfaces"></a><font color="red"><b>Class interfaces</b></font><br>
20466 <br>
20467 The class subsystem has an additional concept not found in other parts of the Linux
20468 device model. This mechanism is called an <i>interface</i>, but it is, perhaps, best thought
20469 of as a sort of trigger mechanism that can be used to get notification when devices
20470 enter or leave the class.<br>
20471 <br>
20472 An interface is represented by:<br>
20473 <pre>
20474 struct class_interface {
20475 struct class *class;
20476 int (*add) (struct class_device *cd);
20477 void (*remove) (struct class_device *cd);
20478 };
20479 </pre>
20480 Interfaces can be registered and unregistered with:<br>
20481 <pre>
20482 int class_interface_register(struct class_interface *intf);
20483 void class_interface_unregister(struct class_interface *intf);
20484 </pre>
20485 The functioning of an interface is straightforward. Whenever a class device is added
20486 to the <font class="fixd">class</font> specified in the <font class="fixd">class_interface</font> structure, the interface's <i>add </i>function is
20487 called. That function can perform any additional setup required for that device; this
20488 setup often takes the form of adding more attributes, but other applications are possible.
20489 When the device is removed from the class, the <i>remove </i>method is called to perform
20490 any required cleanup.<br>
20491 <br>
20492 Multiple interfaces can be registered for a class.<br>
20493 <br>
20494 <a name="PuttingItAllTogether"></a><font color="red"><b>Putting It All Together</b></font><br>
20495 <br>
20496 To better understand what the driver model does, let us walk through the steps of a
20497 device's lifecycle within the kernel. We describe how the PCI subsystem interacts
20498 with the driver model, the basic concepts of how a driver is added and removed, and
20499 how a device is added and removed from the system. These details, while describing
20500 the PCI kernel code specifically, apply to all other subsystems that use the driver core
20501 to manage their drivers and devices.<br>
20502 <br>
20503 <A name="392"></a><font color="blue">PAGE 392</font><br>
20504 <br>
20505 The interaction between the PCI core, driver core, and the individual PCI drivers is
20506 quite complex, as Figure 14-3 shows.<br>
20507 <br><br>
20508 <center>
20509 <img src="fig14-3.gif">
20510 </center>
20511 <br>
20512 <i>Figure 14-3. Device-creation process</i><br>
20513 <br>
20514 <a name="AddADevice"></a><font color="red"><b>Add a Device</b></font><br>
20515 <br>
20516 The PCI subsystem declares a single <font class="fixd">struct bus_type</font> called <font class="fixd">pci_bus_type,</font> which is
20517 initialized with the following values:<br>
20518 <pre>
20519 struct bus_type pci_bus_type = {
20520 .name = "pci",
20521 .match = pci_bus_match,
20522 .hotplug = pci_hotplug,
20523 .suspend = pci_device_suspend,
20524 .resume = pci_device_resume,
20525 .dev_attrs = pci_dev_attrs,
20526 };
20527 </pre>
20528 This <font class="fixd">pci_bus_type</font> variable is registered with the driver core when the PCI subsystem
20529 is loaded in the kernel with a call to <i>bus_register</i>. When that happens, the driver core
20530 creates a sysfs directory in <i>/sys/bus/pci </i>that consists of two directories: <i>devices </i>and
20531 <i>drivers</i>.<br>
20532 <br>
20533 All PCI drivers must define a <font class="fixd">struct pci_driver</font> variable that defines the different
20534 functions that this PCI driver can do (for more information about the PCI subsystem<br>
20535 <br>
20536 <A name="393"></a><font color="blue">PAGE 393</font><br>
20537 <br>
20538 and how to write a PCI driver, see Chapter 12). That structure contains a
20539 <font class="fixd">struct device_driver</font> that is then initialized by the PCI core when the PCI driver is registered:<br>
20540 <pre>
20541 /* initialize common driver fields */
20542 drv->driver.name = drv->name;
20543 drv->driver.bus = &pci_bus_type;
20544 drv->driver.probe = pci_device_probe;
20545 drv->driver.remove = pci_device_remove;
20546 drv->driver.kobj.ktype = &pci_driver_kobj_type;
20547 </pre>
20548 This code sets up the bus for the driver to point to the <font class="fixd">pci_bus_type</font> and points the
20549 <i>probe </i>and <i>remove </i>functions to point to functions within the PCI core. The <font class="fixd">ktype</font> for
20550 the driver's <font class="fixd">kobject</font> is set to the variable <font class="fixd">pci_driver_kobj_type,</font> in order for the PCI
20551 driver's attribute files to work properly. Then the PCI core registers the PCI driver
20552 with the driver core:<br>
20553 <pre>
20554 /* register with core */
20555 error = driver_register(&drv->driver);
20556 </pre>
20557 The driver is now ready to be bound to any PCI devices it supports.<br>
20558 <br>
20559 The PCI core, with help from the architecture-specific code that actually talks to the
20560 PCI bus, starts probing the PCI address space, looking for all PCI devices. When
20561 a PCI device is found, the PCI core creates a new variable in memory of type
20562 <font class="fixd">struct pci_dev</font>. A portion of the <font class="fixd">struct pci_dev</font> structure looks like the following:<br>
20563 <pre>
20564 struct pci_dev {
20565 /* ... */
20566 unsigned int devfn;
20567 unsigned short vendor;
20568 unsigned short device;
20569 unsigned short subsystem_vendor;
20570 unsigned short subsystem_device;
20571 unsigned int class;
20572 /* ... */
20573 struct pci_driver *driver;
20574 /* ... */
20575 struct device dev;
20576 /* ... */
20577 };
20578 </pre>
20579 The bus-specific fields of this PCI device are initialized by the PCI core (the <font class="fixd">devfn,
20580 vendor, device,</font> and other fields), and the <font class="fixd">struct device</font> variable's <font class="fixd">parent</font> variable is
20581 set to the PCI bus device that this PCI device lives on. The <font class="fixd">bus</font> variable is set to point
20582 at the <font class="fixd">pci_bus_type</font> structure. Then the <font class="fixd">name</font> and <font class="fixd">bus_id</font> variables are set, depending
20583 on the name and ID that is read from the PCI device.<br>
20584 <br>
20585 After the PCI device structure is initialized, the device is registered with the driver
20586 core with a call to:<br>
20587 <pre>
20588 device_register(&dev->dev);
20589 </pre>
20590 <A name="394"></a><font color="blue">PAGE 394</font><br>
20591 <br>
20592 Within the <i>device_register </i>function, the driver core initializes a number of the
20593 device's fields, registers the device's kobject with the kobject core (which causes a
20594 hotplug event to be generated, but we discuss that later in this chapter), and then
20595 adds the device to the list of devices that are held by the device's parent. This is done
20596 so that all devices can be walked in the proper order, always knowing where in the
20597 hierarchy of devices each one lives.<br>
20598 <br>
20599 The device is then added to the bus-specific list of all devices, in this example, the
20600 <font class="fixd">pci_bus_type</font> list. Then the list of all drivers that are registered with the bus is walked,
20601 and the <i>match </i>function of the bus is called for every driver, specifying this device. For
20602 the <font class="fixd">pci_bus_type</font> bus, the <i>match </i>function was set to point to the <i>pci_bus_match </i>function
20603 by the PCI core before the device was submitted to the driver core.<br>
20604 <br>
20605 The <i>pci_bus_match </i>function casts the <font class="fixd">struct device</font> that was passed to it by the
20606 driver core, back into a <font class="fixd">struct pci_dev</font>. It also casts the <font class="fixd">struct device_driver</font> back
20607 into a <font class="fixd">struct pci_driver</font> and then looks at the PCI device-specific information of the
20608 device and driver to see if the driver states that it can support this kind of device. If
20609 the match is not successful, the function returns 0 back to the driver core, and the
20610 driver core moves on to the next driver in its list.<br>
20611 <br>
20612 If the match is successful, the function returns 1 back to the driver core. This causes
20613 the driver core to set the <font class="fixd">driver</font> pointer in the <font class="fixd">struct device</font> to point to this driver,
20614 and then it calls the <i>probe</i> function that is specified in the <font class="fixd">struct device_driver</font>.<br>
20615 <br>
20616 Earlier, before the PCI driver was registered with the driver core, the <font class="fixd">probe</font> variable
20617 was set to point at the <i>pci_device_probe </i>function. This function casts (yet again) the
20618 <font class="fixd">struct device</font> back into a <font class="fixd">struct pci_dev</font> and the <font class="fixd">struct driver</font> that is set in the
20619 device back into a <font class="fixd">struct pci_driver</font>. It again verifies that this driver states that it can
20620 support this device (which seems to be a redundant extra check for some unknown
20621 reason), increments the reference count of the device, and then calls the PCI driver's
20622 <i>probe</i> function with a pointer to the <font class="fixd">struct pci_dev</font> structure it should bind to.<br>
20623 <br>
20624 If the PCI driver's <i>probe </i>function determines that it can not handle this device for
20625 some reason, it returns a negative error value, which is propagated back to the driver
20626 core and causes it to continue looking through the list of drivers to match one up
20627 with this device. If the <i>probe </i>function can claim the device, it does all the initialization
20628 that it needs to do to handle the device properly, and then it returns 0 back up
20629 to the driver core. This causes the driver core to add the device to the list of all
20630 devices currently bound by this specific driver and creates a symlink within the
20631 driver's directory in sysfs to the device that it is now controlling. This symlink allows
20632 users to see exactly which devices are bound to which devices. This can be seen as:<br>
20633 <pre>
20634 $ tree /sys/bus/pci
20635 /sys/bus/pci/
20636 |-- devices
20637 | |-- 0000:00:00.0 -> ../../../devices/pci0000:00/0000:00:00.0
20638 | |-- 0000:00:00.1 -> ../../../devices/pci0000:00/0000:00:00.1
20639 | |-- 0000:00:00.2 -> ../../../devices/pci0000:00/0000:00:00.2
20640 </pre>
20641 <A name="395"></a><font color="blue">PAGE 395</font><br>
20642 <pre>
20643 | |-- 0000:00:02.0 -> ../../../devices/pci0000:00/0000:00:02.0
20644 | |-- 0000:00:04.0 -> ../../../devices/pci0000:00/0000:00:04.0
20645 | |-- 0000:00:06.0 -> ../../../devices/pci0000:00/0000:00:06.0
20646 | |-- 0000:00:07.0 -> ../../../devices/pci0000:00/0000:00:07.0
20647 | |-- 0000:00:09.0 -> ../../../devices/pci0000:00/0000:00:09.0
20648 | |-- 0000:00:09.1 -> ../../../devices/pci0000:00/0000:00:09.1
20649 | |-- 0000:00:09.2 -> ../../../devices/pci0000:00/0000:00:09.2
20650 | |-- 0000:00:0c.0 -> ../../../devices/pci0000:00/0000:00:0c.0
20651 | |-- 0000:00:0f.0 -> ../../../devices/pci0000:00/0000:00:0f.0
20652 | |-- 0000:00:10.0 -> ../../../devices/pci0000:00/0000:00:10.0
20653 | |-- 0000:00:12.0 -> ../../../devices/pci0000:00/0000:00:12.0
20654 | |-- 0000:00:13.0 -> ../../../devices/pci0000:00/0000:00:13.0
20655 | `-- 0000:00:14.0 -> ../../../devices/pci0000:00/0000:00:14.0
20656 `-- drivers
20657 |-- ALI15x3_IDE
20658 | `-- 0000:00:0f.0 -> ../../../../devices/pci0000:00/0000:00:0f.0
20659 |-- ehci_hcd
20660 | `-- 0000:00:09.2 -> ../../../../devices/pci0000:00/0000:00:09.2
20661 |-- ohci_hcd
20662 | |-- 0000:00:02.0 -> ../../../../devices/pci0000:00/0000:00:02.0
20663 | |-- 0000:00:09.0 -> ../../../../devices/pci0000:00/0000:00:09.0
20664 | `-- 0000:00:09.1 -> ../../../../devices/pci0000:00/0000:00:09.1
20665 |-- orinoco_pci
20666 | `-- 0000:00:12.0 -> ../../../../devices/pci0000:00/0000:00:12.0
20667 |-- radeonfb
20668 | `-- 0000:00:14.0 -> ../../../../devices/pci0000:00/0000:00:14.0
20669 |-- serial
20670 `-- trident
20671 `-- 0000:00:04.0 -> ../../../../devices/pci0000:00/0000:00:04.0
20672 </pre>
20673 <a name="RemoveADevice"></a><font color="red"><b>Remove a Device</b></font><br>
20674 <br>
20675 A PCI device can be removed from a system in a number of different ways. All CardBus
20676 devices are really PCI devices in a different physical form factor, and the kernel
20677 PCI core does not differentiate between them. Systems that allow the removal or
20678 addition of PCI devices while the machine is still running are becoming more popular, and
20679 Linux supports them. There is also a fake PCI Hotplug driver that allows
20680 developers to test to see if their PCI driver properly handles the removal of a device
20681 while the system is running. This module is called <font class="fixd">fakephp</font> and causes the kernel to
20682 think the PCI device is gone, but it does not allow users to physically remove a PCI
20683 device from a system that does not have the proper hardware to do so. See the documentation
20684 with this driver for more information on how to use it to test your PCI
20685 drivers.<br>
20686 <br>
20687 The PCI core exerts a lot less effort to remove a device than it does to add it. When a
20688 PCI device is to be removed, the <i>pci_remove_bus_device </i>function is called. This function
20689 does some PCI-specific cleanups and housekeeping, and then calls the <i>device_unregister
20690 </i>function with a pointer to the <font class="fixd">struct pci_dev's struct device</font> member.<br>
20691 <br>
20692 <A name="396"></a><font color="blue">PAGE 396</font><br>
20693 <br>
20694 In the <i>device_unregister </i>function, the driver core merely unlinks the sysfs files from
20695 the driver bound to the device (if there was one), removes the device from its internal
20696 list of devices, and calls <i>kobject_del </i>with a pointer to the <font class="fixd">struct kobject</font> that is
20697 contained in the <font class="fixd">struct device</font> structure. That function makes a hotplug call to user
20698 space stating that the kobject is now removed from the system, and then it deletes all
20699 sysfs files associated with the kobject and the sysfs directory itself that the kobject
20700 had originally created.<br>
20701 <br>
20702 The <i>kobject_del </i>function also removes the kobject reference of the device itself. If
20703 that reference was the last one (meaning no user-space files were open for the sysfs
20704 entry of the device), then the <i>release </i>function for the PCI device itself, <i>pci_release_dev</i>,
20705 is called. That function merely frees up the memory that the <font class="fixd">struct pci_dev</font> took up.<br>
20706 <br>
20707 After this, all sysfs entries associated with the device are removed, and the memory
20708 associated with the device is released. The PCI device is now totally removed from
20709 the system.<br>
20710 <br>
20711 <a name="AddADriver"></a><font color="red"><b>Add a Driver</b></font><br>
20712 <br>
20713 A PCI driver is added to the PCI core when it calls the <i>pci_register_driver </i>function.
20714 This function merely initializes the <font class="fixd">struct device_driver</font> structure that is contained
20715 within the <font class="fixd">struct pci_driver</font> structure, as previously mentioned in the section
20716 about adding a device. Then the PCI core calls the <i>driver_register </i>function in the
20717 driver core with a pointer to the <font class="fixd">struct device_driver</font> structure contained in the
20718 <font class="fixd">struct pci_driver</font> structure.<br>
20719 <br>
20720 The <i>driver_register </i>function initializes a few locks in the <font class="fixd">struct device_driver</font> structure, and
20721 then calls the <i>bus_add_driver </i>function. This function does the following
20722 steps:<br>
20723 <ul>
20724 <li> Looks up the bus that the driver is to be associated with. If this bus is not found,
20725 the function instantly returns.
20726 <li> The driver's sysfs directory is created based on the name of the driver and the
20727 bus that it is associated with.
20728 <li> The bus's internal lock is grabbed, and then all devices that have been registered
20729 </ul>
20730 with the bus are walked, and the match function is called for them, just like
20731 when a new device is added. If that match function succeeds, then the rest of the
20732 binding process occurs, as described in the previous section.
20734 <a name="RemoveADriver"></a><font color="red"><b>Remove a Driver</b></font><br>
20735 <br>
20736 Removing a driver is a very simple action. For a PCI driver, the driver calls the
20737 <i>pci_unregister_driver </i>function. This function merely calls the driver core function
20738 <i>driver_unregister</i>, with a pointer to the <font class="fixd">struct device_driver</font> portion of the struct
20739 <font class="fixd">pci_driver</font> structure passed to it.<br>
20740 <br>
20741 <A name="397"></a><font color="blue">PAGE 397</font><br>
20742 <br>
20743 The <i>driver_unregister </i>function handles some basic housekeeping by cleaning up
20744 some sysfs attributes that were attached to the driver's entry in the sysfs tree. It then
20745 iterates over all devices that were attached to this driver and calls the <i>release </i>function
20746 for it. This happens exactly like the previously mentioned <i>release </i>function for
20747 when a device is removed from the system.<br>
20748 <br>
20749 After all devices are unbound from the driver, the driver code does this unique bit of
20750 logic:<br>
20751 <pre>
20752 down(&drv->unload_sem);
20753 up(&drv->unload_sem);
20754 </pre>
20755 This is done right before returning to the caller of the function. This lock is grabbed
20756 because the code needs to wait for all reference counts on this driver to be dropped
20757 to 0 before it is safe to return. This is needed because the <i>driver_unregister </i>function is
20758 most commonly called as the exit path of a module that is being unloaded. The module
20759 needs to remain in memory for as long as the driver is being referenced by devices
20760 and by waiting for this lock to be freed, this allows the kernel to know when it is safe
20761 to remove the driver from memory.<br>
20762 <br>
20763 <a name="Hotplug"></a><font color="red"><b>Hotplug</b></font><br>
20764 <br>
20765 There are two different ways to view hotplugging. The kernel views hotplugging as
20766 an interaction between the hardware, the kernel, and the kernel driver. Users view
20767 hotplugging as the interaction between the kernel and user space through the program
20768 called <i>/sbin/hotplug</i>. This program is called by the kernel when it wants to
20769 notify user space that some type of hotplug event has just happened within the kernel.<br>
20770 <br>
20771 <a name="DynamicDevices"></a><font color="red"><b>Dynamic Devices</b></font><br>
20772 <br>
20773 The most commonly used meaning of the term "hotplug" happens when discussing
20774 the fact that most all computer systems can now handle devices appearing or disappearing
20775 while the system is powered on. This is very different from the computer systems
20776 of only a few years ago, where the programmers knew that they needed to scan
20777 for all devices only at boot time, and they never had to worry about their devices disappearing
20778 until the power was turned off to the whole machine. Now, with the
20779 advent of USB, CardBus, PCMCIA, IEEE1394, and PCI Hotplug controllers, the
20780 Linux kernel needs to be able to reliably run no matter what hardware is added or
20781 removed from the system. This places an added burden on the device driver author,
20782 as they must now always handle a device being suddenly ripped out from underneath
20783 them without any notice.<br>
20784 <br>
20785 Each different bus type handles the loss of a device in a different way. For example,
20786 when a PCI, CardBus, or PCMCIA device is removed from the system, it is usually a
20787 while before the driver is notified of this action through its <i>remove </i>function. Before
20788 that happens, all reads from the PCI bus return all bits set. This means that drivers<br>
20789 <br>
20790 <A name="398"></a><font color="blue">PAGE 398</font><br>
20791 <br>
20792 need to always check the value of the data they read from the PCI bus and properly
20793 be able to handle a <font class="fixd">0xff</font> value.<br>
20794 <br>
20795 An example of this can be seen in the <i>drivers/usb/host/ehci-hcd.c </i>driver, which is a
20796 PCI driver for a USB 2.0 (high-speed) controller card. It has the following code in its
20797 main handshake loop to detect if the controller card has been removed from the system:<br>
20798 <pre>
20799 result = readl(ptr);
20800 if (result = = ~(u32)0) /* card removed */
20801 return -ENODEV;
20802 </pre>
20803 For USB drivers, when the device that a USB driver is bound to is removed from the
20804 system, any pending urbs that were submitted to the device start failing with the
20805 error <font class="fixd">-ENODEV</font>. The driver needs to recognize this error and properly clean up any
20806 pending I/O if it occurs.<br>
20807 <br>
20808 Hotpluggable devices are not limited only to traditional devices such as mice, keyboards, and
20809 network cards. There are numerous systems that now support removal
20810 and addition of entire CPUs and memory sticks. Fortunately the Linux kernel properly
20811 handles the addition and removal of such core "system" devices so that individual
20812 device drivers do not need to pay attention to these things.<br>
20813 <br>
20814 <a name="TheSbinhotplugUtility"></a><font color="red"><b>The /sbin/hotplug Utility</b></font><br>
20815 <br>
20816 As alluded to earlier in this chapter, whenever a device is added or removed from the
20817 system, a "hotplug event" is generated. This means that the kernel calls the userspace
20818 program <i>/sbin/hotplug</i>. This program is typically a very small bash script that
20819 merely passes execution on to a list of other programs that are placed in the <i>/etc/hotplug.d/</i>
20820 directory tree. For most Linux distributions, this script looks like the following:<br>
20821 <pre>
20822 DIR="/etc/hotplug.d"
20823 for I in "${DIR}/$1/"*.hotplug "${DIR}/"default/*.hotplug ; do
20824 if [ -f $I ]; then
20825 test -x $I && $I $1 ;
20826 fi
20827 done
20828 exit 1
20829 </pre>
20830 In other words, the script searches for all programs bearing a <i>.hotplug </i>suffix that
20831 might be interested in this event and invokes them, passing to them a number of different
20832 environment variables that have been set by the kernel. More details about
20833 how the <i>/sbin/hotplug </i>script works can be found in the comments in the program and
20834 in the <i>hotplug(8)</i> manpage.<br>
20835 <br>
20836 <A name="399"></a><font color="blue">PAGE 399</font><br>
20837 <br>
20838 As mentioned previously, <i>/sbin/hotplug </i>is called whenever a kobject is created or
20839 destroyed. The hotplug program is called with a single command-line argument providing
20840 a name for the event. The core kernel and specific subsystem involved also set
20841 a series of environment variables (described below) with information on what has
20842 just occurred. These variables are used by the hotplug programs to determine what
20843 has just happened in the kernel, and if there is any specific action that should take
20844 place.<br>
20845 <br>
20846 The command-line argument passed to <i>/sbin/hotplug </i>is the name associated with this
20847 hotplug event, as determined by the kset assigned to the kobject. This name can be
20848 set by a call to the <i>name </i>function that is part of the kset's <font class="fixd">hotplug_ops</font> structure
20849 described earlier in this chapter; if that function is not present or never called, the
20850 name is that of the kset itself.<br>
20851 <br>
20852 The default environment variables that are always set for the <i>/sbin/hotplug </i>program
20853 are:<br>
20854 <br>
20855 <font class="fixd">ACTION</font><br>
20856 <div class="bq">
20857 The string <font class="fixd">add</font> or <font class="fixd">remove,</font> depending on whether the object in question was just
20858 created or destroyed.</div>
20859 <br>
20860 <font class="fixd">DEVPATH</font><br>
20861 <div class="bq">
20862 A directory path, within the sysfs filesystem, that points to the kobject that is
20863 being either created or destroyed. Note that the mount point of the sysfs filesystem
20864 is not added to this path, so it is up to the user-space program to determine
20865 that.</div>
20866 <br>
20867 <font class="fixd">SEQNUM</font><br>
20868 <div class="bq">
20869 The sequence number for this hotplug event. The sequence number is a 64-bit
20870 number that is incremented for every hotplug event that is generated. This
20871 allows user space to sort the hotplug events in the order in which the kernel generates
20872 them, as it is possible for a user-space program to be run out of order.</div>
20873 <br>
20874 <font class="fixd">SUBSYSTEM</font><br>
20875 <div class="bq">
20876 The same string passed as the command-line argument as described above.</div>
20877 <br>
20878 A number of the different bus subsystems all add their own environment variables to
20879 the <i>/sbin/hotplug </i>call, when devices associated with the bus are added or removed
20880 from the system. They do this in their <i>hotplug </i>callback that is specified in the struct
20881 <font class="fixd">kset_hotplug_ops</font> assigned to their bus (as described in the section "Hotplug Operations").
20882 This allows user space to be able to automatically load any necessary module
20883 that might be needed to control the device that has been found by the bus. Here is a
20884 list of the different bus types and what environment variables they add to the <i>/sbin/
20885 hotplug</i> call.<br>
20886 <br>
20887 <A name="400"></a><font color="blue">PAGE 400</font><br>
20888 <br>
20889 <a name="IEEE1394FireWire"></a><font color="red"><b>IEEE1394 (FireWire)</b></font><br>
20890 <br>
20891 Any devices on the IEEE1394 bus, also known as Firewire, have the <i>/sbin/hotplug
20892 </i>parameter name and the <font class="fixd">SUBSYSTEM</font> environment variable set to the value <font class="fixd">ieee1394.</font>
20893 The <font class="fixd">ieee1394</font> subsystem also always adds the following four environment variables:<br>
20894 <br>
20895 <font class="fixd">VENDOR_ID</font><br>
20896 <div class="bq">
20897 The 24-bit vendor ID for the IEEE1394 device</div>
20898 <br>
20899 <font class="fixd">MODEL_ID</font><br>
20900 <div class="bq">
20901 The 24-bit model ID for the IEEE1394 device</div>
20902 <br>
20903 <font class="fixd">GUID</font><br>
20904 <div class="bq">
20905 The 64-bit GUID for the device</div>
20906 <br>
20907 <font class="fixd">SPECIFIER_ID</font><br>
20908 <div class="bq">
20909 The 24-bit value specifying the owner of the protocol spec for this device</div>
20910 <br>
20911 <font class="fixd">VERSION</font><br>
20912 <div class="bq">
20913 The value that specifies the version of the protocol spec for this device</div>
20914 <br>
20915 <a name="Networking"></a><font color="red"><b>Networking</b></font><br>
20916 <br>
20917 All network devices create a hotplug event when the device is registered or unregistered
20918 in the kernel. The <i>/sbin/hotplug </i>call has the parameter name and the <font class="fixd">SUBSYSTEM</font>
20919 environment variable set to the value <font class="fixd">net,</font> and just adds the following environment
20920 variable:<br>
20921 <br>
20922 <font class="fixd">INTERFACE</font><br>
20923 <div class="bq">
20924 The name of the interface that has been registered or unregistered from the kernel.
20925 Examples of this are <font class="fixd">lo</font> and <font class="fixd">eth0.</font></div>
20926 <br>
20927 <a name="PCI"></a><font color="red"><b>PCI</b></font><br>
20928 <br>
20929 Any devices on the PCI bus have the parameter name and the <font class="fixd">SUBSYSTEM</font> environment
20930 variable set to the value <font class="fixd">pci.</font> The PCI subsystem also always adds the following
20931 four environment variables:<br>
20932 <br>
20933 <font class="fixd">PCI_CLASS</font><br>
20934 <div class="bq">
20935 The PCI class number for the device, in hex.</div>
20936 <br>
20937 <font class="fixd">PCI_ID</font><br>
20938 <div class="bq">
20939 The PCI vendor and device IDs for the device, in hex, combined in the format
20940 <font class="fixd">vendor:device.</font></div>
20941 <br>
20942 <font class="fixd">PCI_SUBSYS_ID</font><br>
20943 <div class="bq">
20944 The PCI subsystem vendor and subsystem device IDs, combined in the format
20945 <font class="fixd">subsys_vendor:subsys_device.</font></div>
20946 <br>
20947 <font class="fixd">PCI_SLOT_NAME</font><br>
20948 <div class="bq">
20949 The PCI slot "name" that is given to the device by the kernel. It is in the format
20950 <font class="fixd">domain:bus:slot:function.</font> An example might be <font class="fixd">0000:00:0d.0.</font></div>
20951 <br>
20952 <A name="401"></a><font color="blue">PAGE 401</font><br>
20953 <br>
20954 <a name="Input"></a><font color="red"><b>Input</b></font><br>
20955 <br>
20956 For all input devices (mice, keyboards, joysticks, etc.), a hotplug event is generated
20957 when the device is added and removed from the kernel. The <i>/sbin/hotplug </i>parameter
20958 and the <font class="fixd">SUBSYSTEM</font> environment variable are set to the value <font class="fixd">input.</font> The input subsystem
20959 also always adds the following environment variable:<br>
20960 <br>
20961 <font class="fixd">PRODUCT</font><br>
20962 <div class="bq">
20963 A multivalue string listing values in hex with no leading zeros. It is in the format
20964 <font class="fixd">bustype:vendor:product:version.</font></div>
20965 <br>
20966 The following environment variables may be present, if the device supports it:<br>
20967 <br>
20968 <font class="fixd">NAME</font><br>
20969 <div class="bq">
20970 The name of the input device as given by the device.</div>
20971 <br>
20972 <font class="fixd">PHYS</font><br>
20973 <div class="bq">
20974 The device's physical address that the input subsystem gave to this device. It is
20975 supposed to be stable, depending on the bus position into which the device was
20976 plugged.</div>
20977 <br>
20978 <font class="fixd">EV<br>
20979 KEY<br>
20980 REL<br>
20981 ABS<br>
20982 MSC<br>
20983 LED<br>
20984 SND<br>
20985 FF</font><br>
20986 <div class="bq">
20987 These all come from the input device descriptor and are set to the appropriate
20988 values if the specific input device supports it.</div>
20989 <br>
20990 <a name="USB"></a><font color="red"><b>USB</b></font><br>
20991 <br>
20992 Any devices on the USB bus have the parameter name and the <font class="fixd">SUBSYSTEM</font> environment
20993 variable set to the value <font class="fixd">usb.</font> The USB subsystem also always adds the following
20994 environment variables:<br>
20995 <br>
20996 <font class="fixd">PRODUCT</font><br>
20997 <div class="bq">
20998 A string in the format <font class="fixd">idVendor/idProduct/bcdDevice</font> that specifies those USB
20999 device-specific fields</div>
21000 <br>
21001 <font class="fixd">TYPE</font><br>
21002 <div class="bq">
21003 A string in the format <font class="fixd">bDeviceClass/bDeviceSubClass/bDeviceProtocol</font> that specifies
21004 those USB device-specific fields</div>
21005 <br>
21006 If the <font class="fixd">bDeviceClass</font> field is set to 0, the following environment variable is also set:<br>
21007 <br>
21008 <font class="fixd">INTERFACE</font><br>
21009 <div class="bq">
21010 A string in the format <font class="fixd">bInterfaceClass/bInterfaceSubClass/bInterfaceProtocol</font>
21011 that specifies those USB device-specific fields.</div>
21012 <br>
21013 <A name="402"></a><font color="blue">PAGE 402</font><br>
21014 <br>
21015 If the kernel build option, <font class="fixd">CONFIG_USB_DEVICEFS,</font> which selects the <font class="fixd">usbfs</font> filesystem to
21016 be built in the kernel, is selected, the following environment variable is also set:<br>
21017 <br>
21018 <font class="fixd">DEVICE</font><br>
21019 <div class="bq">
21020 A string that shows where in the <font class="fixd">usbfs</font> filesystem the device is located. This
21021 string is in the format <font class="fixd">/proc/bus/usb/USB_BUS_NUMBER/USB_DEVICE_NUMBER,</font> in
21022 which <font class="fixd">USB_BUS_NUMBER</font> is the three-digit number of the USB bus that the device is
21023 on, and <font class="fixd">USB_DEVICE_NUMBER</font> is the three-digit number that has been assigned by
21024 the kernel to that USB device.</div>
21025 <br>
21026 <a name="SCSI"></a><font color="red"><b>SCSI</b></font><br>
21027 <br>
21028 All SCSI devices create a hotplug event when the SCSI device is created or removed
21029 from the kernel. The <i>/sbin/hotplug </i>call has the parameter name and the <font class="fixd">SUBSYSTEM</font>
21030 environment variable set to the value scsi for every SCSI device that is added or
21031 removed from the system. There are no additional environment variables added by
21032 the SCSI system, but it is mentioned here because there is a SCSI-specific user-space
21033 script that can determine what SCSI drivers (disk, tape, generic, etc.) should be
21034 loaded for the specified SCSI device.<br>
21035 <br>
21036 <a name="LaptopDockingStations"></a><font color="red"><b>Laptop docking stations</b></font><br>
21037 <br>
21038 If a Plug-and-Play-supported laptop docking station is added or removed from the
21039 running Linux system (by inserting the laptop into the station, or removing it), a hotplug
21040 event is created. The <i>/sbin/hotplug </i>call has the parameter name and the
21041 <font class="fixd">SUBSYSTEM</font> environment variable set to the value dock. No other environment variables
21042 are set.<br>
21043 <br>
21044 <a name="S390AndZSeries"></a><font color="red"><b>S/390 and zSeries</b></font><br>
21045 <br>
21046 On the S/390 architecture, the channel bus architecture supports a wide range of
21047 hardware, all of which generate <i>/sbin/hotplug </i>events when they are added or removed
21048 from the Linux virtual system. These devices all have the <i>/sbin/hotplug </i>parameter
21049 name and the <font class="fixd">SUBSYSTEM</font> environment variable set to the value dasd. No other environment
21050 variables are set.<br>
21051 <br>
21052 <a name="UsingSbinhotplug"></a><font color="red"><b>Using /sbin/hotplug</b></font><br>
21053 <br>
21054 Now that the Linux kernel is calling <i>/sbin/hotplug </i>for every device added and
21055 removed from the kernel, a number of very useful tools have been created in user
21056 space that take advantage of this. Two of the most popular tools are the Linux Hotplug
21057 scripts and <i>udev</i>.<br>
21058 <br>
21059 <A name="403"></a><font color="blue">PAGE 403</font><br>
21060 <br>
21061 <a name="LinuxHotplugScripts"></a><font color="red"><b>Linux hotplug scripts</b></font><br>
21062 <br>
21063 The Linux hotplug scripts started out as the very first user of the <i>/sbin/hotplug </i>call.
21064 These scripts look at the different environment variables that the kernel sets to
21065 describe the device that was just discovered and then tries to find a kernel module
21066 that matches up with that device.<br>
21067 <br>
21068 As has been described before, when a driver uses the <font class="fixd">MODULE_DEVICE_TABLE</font> macro, the
21069 program, <font class="fixd">depmod</font>, takes that information and creates the files located in <i>/lib/module/
21070 KERNEL_VERSION/modules.*map</i>. The * is different, depending on the bus type
21071 that the driver supports. Currently, the module map files are generated for drivers
21072 that work for devices that support the PCI, USB, IEEE1394, INPUT, ISAPNP, and
21073 CCW subsystems.<br>
21074 <br>
21075 The hotplug scripts use these module map text files to determine what module to try
21076 to load to support the device that was recently discovered by the kernel. They load
21077 all modules and do not stop at the first match, in order to let the kernel work out
21078 what module works best. These scripts do not unload any modules when devices are
21079 removed. If they were to try to do that, they could accidentally shut down devices
21080 that were also controlled by the same driver of the device that was removed.<br>
21081 <br>
21082 Note, now that the <font class="fixd">modprobe</font> program can read the <font class="fixd">MODULE_DEVICE_TABLE</font> information
21083 directly from the modules without the need of the module map files, the hotplug
21084 scripts might be reduced to a small wrapper around the modprobe program.<br>
21085 <br>
21086 <a name="Udev"></a><font color="red"><b>udev</b></font><br>
21087 <br>
21088 One of the main reasons for creating the unified driver model in the kernel was to
21089 allow user space to manage the <i>/dev </i>tree in a dynamic fashion. This had previously
21090 been done in user space with the implementation of devfs, but that code base has
21091 slowly rotted away, due to a lack of an active maintainer and some unfixable core
21092 bugs. A number of kernel developers realized that if all device information was
21093 exported to user space, it could perform all the necessary management of the <i>/dev
21094 </i>tree.<br>
21095 <br>
21096 devfs has some very fundamental flaws in its design. It requires every device driver to
21097 be modified to support it, and it requires that device driver to specify the name and
21098 location within the <i>/dev </i>tree where it is placed. It also does not properly handle
21099 dynamic major and minor numbers, and it does not allow user space to override the
21100 naming of a device in a simple manner, forcing the device naming policy to reside
21101 within the kernel and not in user space. Linux kernel developers really hate having
21102 policy within the kernel, and since the devfs naming policy does not follow the Linux
21103 Standard Base specification, it really bothers them.<br>
21104 <br>
21105 As the Linux kernel started to be installed on huge servers, a lot of users ran into the
21106 problem of how to manage very large numbers of devices. Disk drive arrays of over
21107 10,000 unique devices presented the very difficult task of ensuring that a specific disk<br>
21108 <br>
21109 <A name="404"></a><font color="blue">PAGE 404</font><br>
21110 <br>
21111 was always named with the same exact name, no matter where it was placed in the
21112 disk array or when it was discovered by the kernel. This same problem also plagued
21113 desktop users who tried to plug two USB printers into their system and then realized
21114 that they had no way of ensuring that the printer known as <i>/dev/lpt0 </i>would not
21115 change and be assigned to the other printer if the system was rebooted.<br>
21116 <br>
21117 So, <i>udev </i>was created. It relies on all device information being exported to user space
21118 through sysfs and on being notified by <i>/sbin/hotplug </i>that a device was added or
21119 removed. Policy decisions, such as what name to give a device, can be specified in
21120 user space, outside of the kernel. This ensures that the naming policy is removed
21121 from the kernel and allows a large amount of flexibility about the name of each
21122 device.<br>
21123 <br>
21124 For more information on how to use <i>udev </i>and how to configure it, please see the
21125 documentation that comes included with the <i>udev</i> package in your distribution.<br>
21126 <br>
21127 All that a device driver needs to do, for <i>udev </i>to work properly with it, is ensure that
21128 any major and minor numbers assigned to a device controlled by the driver are
21129 exported to user space through sysfs. For any driver that uses a subsystem to assign it
21130 a major and minor number, this is already done by the subsystem, and the driver
21131 doesn't have to do any work. Examples of subsystems that do this are the tty, misc,
21132 usb, input, scsi, block, i2c, network, and frame buffer subsystems. If your driver handles
21133 getting a major and minor number on its own, through a call to the <i>cdev_init
21134 </i>function or the older <i>register_chrdev </i>function, the driver needs to be modified in
21135 order for <i>udev</i> to work properly with it.<br>
21136 <br>
21137 <i>udev </i>looks for a file called dev in the <i>/class/ </i>tree of sysfs, in order to determine what
21138 major and minor number is assigned to a specific device when it is called by the kernel
21139 through the <i>/sbin/hotplug </i>interface. A device driver merely needs to create that file
21140 for every device it controls. The <font class="fixd">class_simple</font> interface is usually the easiest way to
21141 do this.<br>
21142 <br>
21143 As mentioned in the section "The <font class="fixd">class_simple</font> Interface," the first step in using
21144 the <font class="fixd">class_simple</font> interface is to create a <font class="fixd">struct class_simple</font> with a call to the
21145 <i>class_simple_create</i> function:<br>
21146 <pre>
21147 static struct class_simple *foo_class;
21148 ...
21149 foo_class = class_simple_create(THIS_MODULE, "foo");
21150 if (IS_ERR(foo_class)) {
21151 printk(KERN_ERR "Error creating foo class.\n");
21152 goto error;
21153 }
21154 </pre>
21155 This code creates a directory in sysfs in <i>/sys/class/foo</i>.<br>
21156 <br>
21157 Whenever a new device is found by your driver, and you assign it a minor number as
21158 described in Chapter 3, the driver should call the <i>class_simple_device_add</i> function:<br>
21159 <pre>
21160 class_simple_device_add(foo_class, MKDEV(FOO_MAJOR, minor), NULL, "foo%d", minor);
21161 </pre>
21162 <A name="405"></a><font color="blue">PAGE 405</font><br>
21163 <br>
21164 This code causes a subdirectory under <i>/sys/class/foo </i>to be created called <i>fooN</i>, where
21165 <i>N </i>is the minor number for this device. There is one file created in this directory, <i>dev</i>,
21166 which is exactly what <i>udev</i> needs in order to create a device node for your device.<br>
21167 <br>
21168 When your driver is unbound from a device, and you give up the minor number that
21169 it was attached to, a call to <i>class_simple_device_remove </i>is needed to remove the sysfs
21170 entries for this device:<br>
21171 <pre>
21172 class_simple_device_remove(MKDEV(FOO_MAJOR, minor));
21173 </pre>
21174 Later, when your entire driver is being shut down, a call to <i>class_simple_destroy </i>is
21175 needed to remove the class that you created originally with the call to <i>class_simple_
21176 create</i>:<br>
21177 <pre>
21178 class_simple_destroy(foo_class);
21179 </pre>
21180 The <i>dev </i>file that is created by the call to <i>class_simple_device_add </i>consists of the
21181 major and minor numbers, separated by a : character. If your driver does not want to
21182 use the <font class="fixd">class_simple</font> interface because you want to provide other files within the
21183 class directory for the subsystem, use the <i>print_dev_t </i>function to properly format the
21184 major and minor number for the specific device.<br>
21185 <br>
21186 <a name="DealingWithFirmware"></a><font color="red"><b>Dealing with Firmware</b></font><br>
21187 <br>
21188 As a driver author, you may find yourself confronted with a device that must have
21189 firmware downloaded into it before it functions properly. The competition in many
21190 parts of the hardware market is so intense that even the cost of a bit of EEPROM for
21191 the device's controlling firmware is more than the manufacturer is willing to spend.
21192 So the firmware is distributed on a CD with the hardware, and the operating system
21193 is charged with conveying the firmware to the device itself.<br>
21194 <br>
21195 You may be tempted to solve the firmware problem with a declaration like this:<br>
21196 <pre>
21197 static char my_firmware[ ] = { 0x34, 0x78, 0xa4, ... };
21198 </pre>
21199 That approach is almost certainly a mistake, however. Coding firmware into a driver
21200 bloats the driver code, makes upgrading the firmware hard, and is very likely to run
21201 into licensing problems. It is highly unlikely that the vendor has released the firmware
21202 image under the GPL, so mixing it with GPL-licensed code is usually a mistake.
21203 For this reason, drivers containing wired-in firmware are unlikely to be accepted into
21204 the mainline kernel or included by Linux distributors.<br>
21205 <br>
21206 <a name="TheKernelFirmwareInterface"></a><font color="red"><b>The Kernel Firmware Interface</b></font><br>
21207 <br>
21208 The proper solution is to obtain the firmware from user space when you need it.
21209 Please resist the temptation to try to open a file containing firmware directly from
21210 kernel space, however; that is an error-prone operation, and it puts policy (in the<br>
21211 <br>
21212 <A name="406"></a><font color="blue">PAGE 406</font><br>
21213 <br>
21214 form of a file name) into the kernel. Instead, the correct approach is to use the firmware
21215 interface, which was created just for this purpose:<br>
21216 <pre>
21217 #include <linux/firmware.h>
21218 int request_firmware(const struct firmware **fw, char *name,
21219 struct device *device);
21220 </pre>
21221 A call to <i>request_firmware </i>requests that user space locate and provide a firmware
21222 image to the kernel; we look at the details of how it works in a moment. The <font class="fixd">name</font>
21223 should identify the firmware that is desired; the normal usage is the name of the
21224 firmware file as provided by the vendor. Something like <i>my_firmware.bin </i>is typical. If
21225 the firmware is successfully loaded, the return value is 0 (otherwise the usual error
21226 code is returned), and the <font class="fixd">fw</font> argument is pointed to one of these structures:<br>
21227 <pre>
21228 struct firmware {
21229 size_t size;
21230 u8 *data;
21231 };
21232 </pre>
21233 That structure contains the actual firmware, which can now be downloaded to the
21234 device. Be aware that this firmware is unchecked data from user space; you should
21235 apply any and all tests you can think of to convince yourself that it is a proper firmware
21236 image before sending it to the hardware. Device firmware usually contains identification
21237 strings, checksums, and so on; check them all before trusting the data.<br>
21238 <br>
21239 After you have sent the firmware to the device, you should release the in-kernel
21240 structure with:<br>
21241 <pre>
21242 void release_firmware(struct firmware *fw);
21243 </pre>
21244 Since <i>request_firmware </i>asks user space to help, it is guaranteed to sleep before
21245 returning. If your driver is not in a position to sleep when it must ask for firmware,
21246 the asynchronous alternative may be used:<br>
21247 <pre>
21248 int request_firmware_nowait(struct module *module,
21249 char *name, struct device *device, void *context,
21250 void (*cont)(const struct firmware *fw, void *context));
21251 </pre>
21252 The additional arguments here are <font class="fixd">module</font> (which will almost always be <font class="fixd">THIS_MODULE</font>),
21253 <font class="fixd">context</font> (a private data pointer that is not used by the firmware subsystem), and cont.
21254 If all goes well, <i>request_firmware_nowait </i>begins the firmware load process and
21255 returns 0. At some future time, cont will be called with the result of the load. If the
21256 firmware load fails for some reason, <font class="fixd">fw</font> is <font class="fixd">NULL</font>.<br>
21257 <br>
21258 <A name="407"></a><font color="blue">PAGE 407</font><br>
21259 <br>
21260 <a name="HowItWorks"></a><font color="red"><b>How It Works</b></font><br>
21261 <br>
21262 The firmware subsystem works with sysfs and the hotplug mechanism. When a call
21263 is made to <i>request_firmware</i>, a new directory is created under <i>/sys/class/firmware
21264 </i>using your device's name. That directory contains three attributes:<br>
21265 <br>
21266 <font class="fixd">loading</font><br>
21267 <div class="bq">
21268 This attribute should be set to one by the user-space process that is loading the
21269 firmware. When the load process is complete, it should be set to 0. Writing a
21270 value of <font class="fixd">-1</font> to <font class="fixd">loading</font> aborts the firmware loading process.</div>
21271 <br>
21272 <font class="fixd">data</font><br>
21273 <div class="bq">
21274 <font class="fixd">data</font> is a binary attribute that receives the firmware data itself. After setting
21275 <font class="fixd">loading,</font> the user-space process should write the firmware to this attribute.</div>
21276 <br>
21277 <font class="fixd">device</font><br>
21278 <div class="bq">
21279 This attribute is a symbolic link to the associated entry under <i>/sys/devices</i>.</div>
21280 <br>
21281 Once the sysfs entries have been created, the kernel generates a hotplug event for
21282 your device. The environment passed to the hotplug handler includes a variable
21283 <font class="fixd">FIRMWARE,</font> which is set to the name provided to <i>request_firmware</i>. The handler should
21284 locate the firmware file, and copy it into the kernel using the attributes provided. If
21285 the file cannot be found, the handler should set the <i>loading</i> attribute to <font class="fixd">-1.</font><br>
21286 <br>
21287 If a firmware request is not serviced within 10 seconds, the kernel gives up and
21288 returns a failure status to the driver. That time-out period can be changed via the
21289 sysfs attribute <i>/sys/class/firmware/timeout</i>.<br>
21290 <br>
21291 Using the <i>request_firmware </i>interface allows you to distribute the device firmware
21292 with your driver. When properly integrated into the hotplug mechanism, the firmware
21293 loading subsystem allows devices to simply work "out of the box." It is clearly
21294 the best way of handling the problem.<br>
21295 <br>
21296 Please indulge us as we pass on one more warning, however: device firmware should
21297 not be distributed without the permission of the manufacturer. Many manufacturers
21298 will agree to license their firmware under reasonable terms when asked politely;
21299 some others can be less cooperative. Either way, copying and distributing their firmware
21300 without permission is a violation of copyright law and an invitation for trouble.<br>
21301 <br>
21302 <a name="QuickReference14"></a><font color="red"><b>Quick Reference</b></font><br>
21303 <br>
21304 Many functions have been introduced in this chapter; here is a quick summary of
21305 them all.<br>
21306 <br>
21307 <A name="408"></a><font color="blue">PAGE 408</font><br>
21308 <br>
21309 <a name="Kobjects"></a><font color="red"><b>Kobjects</b></font><br>
21310 <br>
21311 <font class="fixd">#include <linux/kobject.h></font><br>
21312 <div class="bq">
21313 The include file containing definitions for kobjects, related structures, and
21314 functions.</div>
21315 <br>
21316 <font class="fixd">void kobject_init(struct kobject *kobj);<br>
21317 int kobject_set_name(struct kobject *kobj, const char *format, ...);</font><br>
21318 <div class="bq">
21319 Functions for kobject initialization.</div>
21320 <br>
21321 <font class="fixd">struct kobject *kobject_get(struct kobject *kobj);<br>
21322 void kobject_put(struct kobject *kobj);</font><br>
21323 <div class="bq">
21324 Functions that manage reference counts for kobjects.</div>
21325 <br>
21326 <font class="fixd">struct kobj_type;<br>
21327 struct kobj_type *get_ktype(struct kobject *kobj);</font><br>
21328 <div class="bq">
21329 Represents the type of structure within which a kobject is embedded. Use
21330 <i>get_ktype</i> to get the <font class="fixd">kobj_type</font> associated with a given kobject.</div>
21331 <br>
21332 <font class="fixd">int kobject_add(struct kobject *kobj);<br>
21333 extern int kobject_register(struct kobject *kobj);<br>
21334 void kobject_del(struct kobject *kobj);<br>
21335 void kobject_unregister(struct kobject *kobj);</font><br>
21336 <div class="bq">
21337 <i>kobject_add </i>adds a kobject to the system, handling kset membership, sysfs representation, and
21338 hotplug event generation. <i>kobject_register </i>is a convenience function
21339 that combines <i>kobject_init </i>and <i>kobject_add</i>. Use <i>kobject_del </i>to remove a
21340 kobject or <i>kobject_unregister</i>, which combines <i>kobject_del</i> and <i>kobject_put</i>.</div>
21341 <br>
21342 <font class="fixd">void kset_init(struct kset *kset);<br>
21343 int kset_add(struct kset *kset);<br>
21344 int kset_register(struct kset *kset);<br>
21345 void kset_unregister(struct kset *kset);</font><br>
21346 <div class="bq">
21347 Initialization and registration functions for ksets.</div>
21348 <br>
21349 <font class="fixd">decl_subsys(name, type, hotplug_ops);</font><br>
21350 <div class="bq">
21351 A macro that makes it easier to declare subsystems.</div>
21352 <br>
21353 <font class="fixd">void subsystem_init(struct subsystem *subsys);<br>
21354 int subsystem_register(struct subsystem *subsys);<br>
21355 void subsystem_unregister(struct subsystem *subsys);<br>
21356 struct subsystem *subsys_get(struct subsystem *subsys)<br>
21357 void subsys_put(struct subsystem *subsys);</font><br>
21358 <div class="bq">
21359 Operations on subsystems.</div>
21360 <br>
21361 <A name="409"></a><font color="blue">PAGE 409</font><br>
21362 <br>
21363 <a name="SysfsOperations"></a><font color="red"><b>Sysfs Operations</b></font><br>
21364 <br>
21365 <font class="fixd">#include <linux/sysfs.h></font><br>
21366 <div class="bq">
21367 The include file containing declarations for sysfs.</div>
21368 <br>
21369 <font class="fixd">int sysfs_create_file(struct kobject *kobj, struct attribute *attr);<br>
21370 int sysfs_remove_file(struct kobject *kobj, struct attribute *attr);<br>
21371 int sysfs_create_bin_file(struct kobject *kobj, struct bin_attribute *attr);<br>
21372 int sysfs_remove_bin_file(struct kobject *kobj, struct bin_attribute *attr);<br>
21373 int sysfs_create_link(struct kobject *kobj, struct kobject *target, char *name);<br>
21374 void sysfs_remove_link(struct kobject *kobj, char *name);</font><br>
21375 <div class="bq">
21376 Functions for creating and removing attribute files associated with a kobject.</div>
21377 <br>
21378 <a name="BusesDevicesAndDrivers2"></a><font color="red"><b>Buses, Devices, and Drivers</b></font><br>
21379 <br>
21380 <font class="fixd">int bus_register(struct bus_type *bus);<br>
21381 void bus_unregister(struct bus_type *bus);</font><br>
21382 <div class="bq">
21383 Functions that perform registration and unregistration of buses in the device
21384 model.</div>
21385 <br>
21386 <font class="fixd">int bus_for_each_dev(struct bus_type *bus, struct device *start, void *data, int (*fn)(struct device *, void *));<br>
21387 int bus_for_each_drv(struct bus_type *bus, struct device_driver *start, void *data, int (*fn)(struct device_driver *, void *));</font><br>
21388 <div class="bq">
21389 Functions that iterate over each of the devices and drivers, respectively, that are
21390 attached to the given bus.</div>
21391 <br>
21392 <font class="fixd">BUS_ATTR(name, mode, show, store);<br>
21393 int bus_create_file(struct bus_type *bus, struct bus_attribute *attr);<br>
21394 void bus_remove_file(struct bus_type *bus, struct bus_attribute *attr);</font><br>
21395 <div class="bq">
21396 The <i><font class="fixd">BUS_ATTR</font> </i>macro may be used to declare a <font class="fixd">bus_attribute</font> structure, which
21397 may then be added and removed with the above two functions.</div>
21398 <br>
21399 <font class="fixd">int device_register(struct device *dev);<br>
21400 void device_unregister(struct device *dev);</font><br>
21401 <div class="bq">
21402 Functions that handle device registration.</div>
21403 <br>
21404 <font class="fixd">DEVICE_ATTR(name, mode, show, store);<br>
21405 int device_create_file(struct device *device, struct device_attribute *entry);<br>
21406 void device_remove_file(struct device *dev, struct device_attribute *attr);</font><br>
21407 <div class="bq">
21408 Macros and functions that deal with device attributes.</div>
21409 <br>
21410 <A name="410"></a><font color="blue">PAGE 410</font><br>
21411 <br>
21412 <font class="fixd">int driver_register(struct device_driver *drv);<br>
21413 void driver_unregister(struct device_driver *drv);</font><br>
21414 <div class="bq">
21415 Functions that register and unregister a device driver.</div>
21416 <br>
21417 <font class="fixd">DRIVER_ATTR(name, mode, show, store);<br>
21418 int driver_create_file(struct device_driver *drv, struct driver_attribute *attr);<br>
21419 void driver_remove_file(struct device_driver *drv, struct driver_attribute *attr);</font><br>
21420 <div class="bq">
21421 Macros and functions that manage driver attributes.</div>
21422 <br>
21423 <a name="Classes2"></a><font color="red"><b>Classes</b></font><br>
21424 <br>
21425 <font class="fixd">struct class_simple *class_simple_create(struct module *owner, char *name);<br>
21426 void class_simple_destroy(struct class_simple *cs);<br>
21427 struct class_device *class_simple_device_add(struct class_simple *cs, dev_t devnum, struct device *device, const char *fmt, ...);<br>
21428 void class_simple_device_remove(dev_t dev);<br>
21429 int class_simple_set_hotplug(struct class_simple *cs, int (*hotplug)(struct class_device *dev, char **envp, int num_envp, char *buffer, int buffer_size));</font><br>
21430 <div class="bq">
21431 Functions that implement the <font class="fixd">class_simple</font> interface; they manage simple class
21432 entries containing a dev attribute and little else.</div>
21433 <br>
21434 <font class="fixd">int class_register(struct class *cls);<br>
21435 void class_unregister(struct class *cls);</font><br>
21436 <div class="bq">
21437 Registration and unregistration of classes.</div>
21438 <br>
21439 <font class="fixd">CLASS_ATTR(name, mode, show, store);<br>
21440 int class_create_file(struct class *cls, const struct class_attribute *attr);<br>
21441 void class_remove_file(struct class *cls, const struct class_attribute *attr);</font><br>
21442 <div class="bq">
21443 The usual macros and functions for dealing with class attributes.</div>
21444 <br>
21445 <font class="fixd">int class_device_register(struct class_device *cd);<br>
21446 void class_device_unregister(struct class_device *cd);<br>
21447 int class_device_rename(struct class_device *cd, char *new_name);<br>
21448 CLASS_DEVICE_ATTR(name, mode, show, store);<br>
21449 int class_device_create_file(struct class_device *cls, const struct class_device_attribute *attr);<br>
21450 void class_device_remove_file(struct class_device *cls, const struct class_device_attribute *attr);</font><br>
21451 <div class="bq">
21452 Functions and macros that implement the class device interface.</div>
21453 <br>
21454 <font class="fixd">int class_interface_register(struct class_interface *intf);<br>
21455 void class_interface_unregister(struct class_interface *intf);</font><br>
21456 <div class="bq">
21457 Functions that add an interface to a class (or remove it).</div>
21458 <br>
21459 <A name="411"></a><font color="blue">PAGE 411</font><br>
21460 <br>
21461 <a name="Firmware"></a><font color="red"><b>Firmware</b></font><br>
21462 <br>
21463 <font class="fixd">#include <linux/firmware.h><br>
21464 int request_firmware(const struct firmware **fw, char *name, struct device *device);<br>
21465 int request_firmware_nowait(struct module *module, char *name, struct device *device, void *context, void (*cont)(const struct firmware *fw, void *context));<br>
21466 void release_firmware(struct firmware *fw);</font><br>
21467 <div class="bq">
21468 Functions that implement the kernel firmware-loading interface.</div>
21469 <br>
21470 <A name="412"></a><font color="blue">PAGE 412</font><br>
21471 <br>
21472 <a name="CHAPTER15"></a><font color="red"><b>CHAPTER 15</b></font><br>
21473 <br>
21474 <a name="MemoryMappingbrandDMA"></a><font color="#7519FF" size="+1"><b>Memory Mapping and DMA</b></font><br>
21475 <br>
21476 This chapter delves into the area of Linux memory management, with an emphasis
21477 on techniques that are useful to the device driver writer. Many types of driver programming
21478 require some understanding of how the virtual memory subsystem works;
21479 the material we cover in this chapter comes in handy more than once as we get into
21480 some of the more complex and performance-critical subsystems. The virtual memory
21481 subsystem is also a highly interesting part of the core Linux kernel and, therefore,
21482 it merits a look.<br>
21483 <br>
21484 The material in this chapter is divided into three sections:<br>
21485 <ul>
21486 <li> The first covers the implementation of the <i>mmap </i>system call, which allows the
21487 mapping of device memory directly into a user process's address space. Not all
21488 devices require <i>mmap </i>support, but, for some, mapping device memory can yield
21489 significant performance improvements.
21490 <li> We then look at crossing the boundary from the other direction with a discussion of direct access to user-space pages. Relatively few drivers need this capability;
21491 in many cases, the kernel performs this sort of mapping without the driver
21492 even being aware of it. But an awareness of how to map user-space memory into
21493 the kernel (with <i>get_user_pages</i>) can be useful.
21494 <li> The final section covers direct memory access (DMA) I/O operations, which provide peripherals with direct access to system memory.
21495 </ul>
21496 Of course, all of these techniques require an understanding of how Linux memory
21497 management works, so we start with an overview of that subsystem.<br>
21498 <br>
21499 <a name="MemoryManagementInLinux"></a><font color="red"><b>Memory Management in Linux</b></font><br>
21500 <br>
21501 Rather than describing the theory of memory management in operating systems, this
21502 section tries to pinpoint the main features of the Linux implementation. Although
21503 you do not need to be a Linux virtual memory guru to implement <i>mmap</i>, a basic
21504 overview of how things work is useful. What follows is a fairly lengthy description of<br>
21505 <br>
21506 <A name="413"></a><font color="blue">PAGE 413</font><br>
21507 <br>
21508 the data structures used by the kernel to manage memory. Once the necessary background
21509 has been covered, we can get into working with these structures.<br>
21510 <br>
21511 <a name="AddressTypes"></a><font color="red"><b>Address Types</b></font><br>
21512 <br>
21513 Linux is, of course, a virtual memory system, meaning that the addresses seen by
21514 user programs do not directly correspond to the physical addresses used by the hardware.
21515 Virtual memory introduces a layer of indirection that allows a number of nice
21516 things. With virtual memory, programs running on the system can allocate far more
21517 memory than is physically available; indeed, even a single process can have a virtual
21518 address space larger than the system's physical memory. Virtual memory also allows
21519 the program to play a number of tricks with the process's address space, including
21520 mapping the program's memory to device memory.<br>
21521 <br>
21522 Thus far, we have talked about virtual and physical addresses, but a number of the
21523 details have been glossed over. The Linux system deals with several types of
21524 addresses, each with its own semantics. Unfortunately, the kernel code is not always
21525 very clear on exactly which type of address is being used in each situation, so the
21526 programmer must be careful.<br>
21527 <br>
21528 The following is a list of address types used in Linux. Figure 15-1 shows how these
21529 address types relate to physical memory.<br>
21530 <br>
21531 <i>User virtual addresses</i><br>
21532 <div class="bq">
21533 These are the regular addresses seen by user-space programs. User addresses are
21534 either 32 or 64 bits in length, depending on the underlying hardware architecture,
21535 and each process has its own virtual address space.</div>
21536 <br>
21537 <i>Physical addresses</i><br>
21538 <div class="bq">
21539 The addresses used between the processor and the system's memory. Physical
21540 addresses are 32- or 64-bit quantities; even 32-bit systems can use larger physical
21541 addresses in some situations.</div>
21542 <br>
21543 <i>Bus addresses</i><br>
21544 <div class="bq">
21545 The addresses used between peripheral buses and memory. Often, they are the
21546 same as the physical addresses used by the processor, but that is not necessarily
21547 the case. Some architectures can provide an I/O memory management unit
21548 (IOMMU) that remaps addresses between a bus and main memory. An IOMMU
21549 can make life easier in a number of ways (making a buffer scattered in memory
21550 appear contiguous to the device, for example), but programming the IOMMU is
21551 an extra step that must be performed when setting up DMA operations. Bus
21552 addresses are highly architecture dependent, of course.</div>
21553 <br>
21554 <i>Kernel logical addresses</i><br>
21555 <div class="bq">
21556 These make up the normal address space of the kernel. These addresses map
21557 some portion (perhaps all) of main memory and are often treated as if they were
21558 physical addresses. On most architectures, logical addresses and their associated</div>
21559 <br>
21560 <A name="414"></a><font color="blue">PAGE 414</font><br>
21561 <br>
21562 <div class="bq">physical addresses differ only by a constant offset. Logical addresses use the
21563 hardware's native pointer size and, therefore, may be unable to address all of
21564 physical memory on heavily equipped 32-bit systems. Logical addresses are usually
21565 stored in variables of type <font class="fixd">unsigned long</font> or <font class="fixd">void *.</font> Memory returned from
21566 <i>kmalloc</i> has a kernel logical address.</div>
21567 <br>
21568 <i>Kernel virtual addresses</i><br>
21569 <div class="bq">
21570 Kernel virtual addresses are similar to logical addresses in that they are a mapping
21571 from a kernel-space address to a physical address. Kernel virtual addresses
21572 do not necessarily have the linear, one-to-one mapping to physical addresses that
21573 characterize the logical address space, however. All logical addresses <i>are </i>kernel
21574 virtual addresses, but many kernel virtual addresses are not logical addresses.
21575 For example, memory allocated by <i>vmalloc </i>has a virtual address (but no direct
21576 physical mapping). The <i>kmap </i>function (described later in this chapter) also
21577 returns virtual addresses. Virtual addresses are usually stored in pointer variables.</div>
21578 <br><br>
21579 <center>
21580 <img src="fig15-1.gif">
21581 </center>
21582 <br>
21583 <i>Figure 15-1. Address types used in Linux</i><br>
21584 <br>
21585 If you have a logical address, the macro <i>__pa( ) </i>(defined in <i><asm/page.h></i>) returns its
21586 associated physical address. Physical addresses can be mapped back to logical
21587 addresses with <i>__va( )</i>, but only for low-memory pages.<br>
21588 <br>
21589 <A name="415"></a><font color="blue">PAGE 415</font><br>
21590 <br>
21591 Different kernel functions require different types of addresses. It would be nice if
21592 there were different C types defined, so that the required address types were explicit,
21593 but we have no such luck. In this chapter, we try to be clear on which types of
21594 addresses are used where.<br>
21595 <br>
21596 <a name="PhysicalAddressesAndPages"></a><font color="red"><b>Physical Addresses and Pages</b></font><br>
21597 <br>
21598 Physical memory is divided into discrete units called <i>pages</i>. Much of the system's
21599 internal handling of memory is done on a per-page basis. Page size varies from one
21600 architecture to the next, although most systems currently use 4096-byte pages. The
21601 constant <font class="fixd">PAGE_SIZE</font> (defined in <i><asm/page.h></i>) gives the page size on any given
21602 architecture.<br>
21603 <br>
21604 If you look at a memory address--virtual or physical--it is divisible into a page number
21605 and an offset within the page. If 4096-byte pages are being used, for example, the
21606 12 least-significant bits are the offset, and the remaining, higher bits indicate the
21607 page number. If you discard the offset and shift the rest of an offset to the right, the
21608 result is called a <i>page frame number </i>(PFN). Shifting bits to convert between page
21609 frame numbers and addresses is a fairly common operation; the macro <font class="fixd">PAGE_SHIFT</font>
21610 tells how many bits must be shifted to make this conversion.<br>
21611 <br>
21612 <a name="HighAndLowMemory"></a><font color="red"><b>High and Low Memory</b></font><br>
21613 <br>
21614 The difference between logical and kernel virtual addresses is highlighted on 32-bit
21615 systems that are equipped with large amounts of memory. With 32 bits, it is possible
21616 to address 4 GB of memory. Linux on 32-bit systems has, until recently, been limited
21617 to substantially less memory than that, however, because of the way it sets up
21618 the virtual address space.<br>
21619 <br>
21620 The kernel (on the x86 architecture, in the default configuration) splits the 4-GB virtual
21621 address space between user-space and the kernel; the same set of mappings is
21622 used in both contexts. A typical split dedicates 3 GB to user space, and 1 GB for kernel
21623 space.* The kernel's code and data structures must fit into that space, but the biggest
21624 consumer of kernel address space is virtual mappings for physical memory. The
21625 kernel cannot directly manipulate memory that is not mapped into the kernel's
21626 address space. The kernel, in other words, needs its own virtual address for any
21627 memory it must touch directly. Thus, for many years, the maximum amount of physical
21628 memory that could be handled by the kernel was the amount that could be
21629 mapped into the kernel's portion of the virtual address space, minus the space<br>
21630 <br>
21631 * Many non-x86 architectures are able to efficiently do without the kernel/user-space split described here, so
21632 they can work with up to a 4-GB kernel address space on 32-bit systems. The constraints described in this
21633 section still apply to such systems when more than 4 GB of memory are installed, however.<br>
21634 <br>
21635 <A name="416"></a><font color="blue">PAGE 416</font><br>
21636 <br>
21637 needed for the kernel code itself. As a result, x86-based Linux systems could work
21638 with a maximum of a little under 1 GB of physical memory.<br>
21639 <br>
21640 In response to commercial pressure to support more memory while not breaking 32bit
21641 application and the system's compatibility, the processor manufacturers have
21642 added "address extension" features to their products. The result is that, in many
21643 cases, even 32-bit processors can address more than 4 GB of physical memory. The
21644 limitation on how much memory can be directly mapped with logical addresses
21645 remains, however. Only the lowest portion of memory (up to 1 or 2 GB, depending
21646 on the hardware and the kernel configuration) has logical addresses;* the rest (high
21647 memory) does not. Before accessing a specific high-memory page, the kernel must set
21648 up an explicit virtual mapping to make that page available in the kernel's address
21649 space. Thus, many kernel data structures must be placed in low memory; high memory
21650 tends to be reserved for user-space process pages.<br>
21651 <br>
21652 The term "high memory" can be confusing to some, especially since it has other
21653 meanings in the PC world. So, to make things clear, we'll define the terms here:<br>
21654 <br>
21655 <i>Low memory</i><br>
21656 <div class="bq">
21657 Memory for which logical addresses exist in kernel space. On almost every system
21658 you will likely encounter, all memory is low memory.</div>
21659 <br>
21660 <i>High memory</i><br>
21661 <div class="bq">
21662 Memory for which logical addresses do not exist, because it is beyond the
21663 address range set aside for kernel virtual addresses.</div>
21664 <br>
21665 On i386 systems, the boundary between low and high memory is usually set at just
21666 under 1 GB, although that boundary can be changed at kernel configuration time.
21667 This boundary is not related in any way to the old 640 KB limit found on the original
21668 PC, and its placement is not dictated by the hardware. It is, instead, a limit set by
21669 the kernel itself as it splits the 32-bit address space between kernel and user space.<br>
21670 <br>
21671 We will point out limitations on the use of high memory as we come to them in this
21672 chapter.<br>
21673 <br>
21674 <a name="TheMemoryMapAndStructPage"></a><font color="red"><b>The Memory Map and Struct Page</b></font><br>
21675 <br>
21676 Historically, the kernel has used logical addresses to refer to pages of physical memory.
21677 The addition of high-memory support, however, has exposed an obvious problem
21678 with that approach--logical addresses are not available for high memory.
21679 Therefore, kernel functions that deal with memory are increasingly using pointers to
21680 struct page (defined in <i><linux/mm.h></i>) instead. This data structure is used to keep
21681 track of just about everything the kernel needs to know about physical memory;<br>
21682 <br>
21683 * The 2.6 kernel (with an added patch) can support a "4G/4G" mode on x86 hardware, which enables
21684 larger kernel and user virtual address spaces at a mild performance cost.<br>
21685 <br>
21686 <A name="417"></a><font color="blue">PAGE 417</font><br>
21687 <br>
21688 there is one <font class="fixd">struct page</font> for each physical page on the system. Some of the fields of
21689 this structure include the following:<br>
21690 <br>
21691 <font class="fixd">atomic_t count;</font><br>
21692 <div class="bq">
21693 The number of references there are to this page. When the count drops to 0, the
21694 page is returned to the free list.</div>
21695 <br>
21696 <font class="fixd">void *virtual;</font><br>
21697 <div class="bq">
21698 The kernel virtual address of the page, if it is mapped; <font class="fixd">NULL</font>, otherwise. Low memory
21699 pages are always mapped; high-memory pages usually are not. This
21700 field does not appear on all architectures; it generally is compiled only where the
21701 kernel virtual address of a page cannot be easily calculated. If you want to look
21702 at this field, the proper method is to use the <i>page_address </i>macro, described
21703 below.</div>
21704 <br>
21705 <font class="fixd">unsigned long flags;</font><br>
21706 <div class="bq">
21707 A set of bit flags describing the status of the page. These include <font class="fixd">PG_locked,</font>
21708 which indicates that the page has been locked in memory, and <font class="fixd">PG_reserved,</font>
21709 which prevents the memory management system from working with the page at
21710 all.</div>
21711 <br>
21712 There is much more information within <font class="fixd">struct page</font>, but it is part of the deeper
21713 black magic of memory management and is not of concern to driver writers.<br>
21714 <br>
21715 The kernel maintains one or more arrays of <font class="fixd">struct page</font> entries that track all of the
21716 physical memory on the system. On some systems, there is a single array called <font class="fixd">mem_map</font>.
21717 On some systems, however, the situation is more complicated. Nonuniform memory
21718 access (NUMA) systems and those with widely discontiguous physical memory may
21719 have more than one memory map array, so code that is meant to be portable should
21720 avoid direct access to the array whenever possible. Fortunately, it is usually quite easy to
21721 just work with <font class="fixd">struct page</font> pointers without worrying about where they come from.<br>
21722 <br>
21723 Some functions and macros are defined for translating between <font class="fixd">struct page</font> pointers
21724 and virtual addresses:<br>
21725 <br>
21726 <font class="fixd">struct page *virt_to_page(void *kaddr);</font><br>
21727 <div class="bq">
21728 This macro, defined in <i><asm/page.h></i>, takes a kernel logical address and returns
21729 its associated <font class="fixd">struct page</font> pointer. Since it requires a logical address, it does not
21730 work with memory from <i>vmalloc</i> or high memory.</div>
21731 <br>
21732 <font class="fixd">struct page *pfn_to_page(int pfn);</font><br>
21733 <div class="bq">
21734 Returns the <font class="fixd">struct page</font> pointer for the given page frame number. If necessary,
21735 it checks a page frame number for validity with <i>pfn_valid </i>before passing it to
21736 <i>pfn_to_page</i>.</div>
21737 <br>
21738 <font class="fixd">void *page_address(struct page *page);</font><br>
21739 <div class="bq">
21740 Returns the kernel virtual address of this page, if such an address exists. For high
21741 memory, that address exists only if the page has been mapped. This function is</div>
21742 <br>
21743 <A name="418"></a><font color="blue">PAGE 418</font><br>
21744 <br>
21745 <div class="bq">defined in <i><linux/mm.h></i>. In most situations, you want to use a version of <i>kmap
21746 </i>rather than <i>page_address</i>.</div>
21747 <br>
21748 <font class="fixd">#include <linux/highmem.h><br>
21749 void *kmap(struct page *page);<br>
21750 void kunmap(struct page *page);</font><br>
21751 <div class="bq">
21752 <i>kmap </i>returns a kernel virtual address for any page in the system. For low-memory
21753 pages, it just returns the logical address of the page; for high-memory pages,
21754 <i>kmap </i>creates a special mapping in a dedicated part of the kernel address space.
21755 Mappings created with <i>kmap </i>should always be freed with <i>kunmap</i>; a limited
21756 number of such mappings is available, so it is better not to hold on to them for
21757 too long. <i>kmap </i>calls maintain a counter, so if two or more functions both call
21758 <i>kmap </i>on the same page, the right thing happens. Note also that <i>kmap </i>can sleep
21759 if no mappings are available.</div>
21760 <br>
21761 <font class="fixd">#include <linux/highmem.h><br>
21762 #include <asm/kmap_types.h><br>
21763 void *kmap_atomic(struct page *page, enum km_type type);<br>
21764 void kunmap_atomic(void *addr, enum km_type type);</font><br>
21765 <div class="bq">
21766 <i>kmap_atomic </i>is a high-performance form of <i>kmap</i>. Each architecture maintains a
21767 small list of slots (dedicated page table entries) for atomic kmaps; a caller of
21768 <i>kmap_atomic </i>must tell the system which of those slots to use in the type argument.
21769 The only slots that make sense for drivers are <font class="fixd">KM_USER0</font> and <font class="fixd">KM_USER1</font> (for
21770 code running directly from a call from user space), and <font class="fixd">KM_IRQ0</font> and <font class="fixd">KM_IRQ1</font> (for
21771 interrupt handlers). Note that atomic kmaps must be handled atomically; your
21772 code cannot sleep while holding one. Note also that nothing in the kernel keeps
21773 two functions from trying to use the same slot and interfering with each other
21774 (although there is a unique set of slots for each CPU). In practice, contention for
21775 atomic kmap slots seems to not be a problem.</div>
21776 <br>
21777 We see some uses of these functions when we get into the example code, later in this
21778 chapter and in subsequent chapters.<br>
21779 <br>
21780 <a name="PageTables"></a><font color="red"><b>Page Tables</b></font><br>
21781 <br>
21782 On any modern system, the processor must have a mechanism for translating virtual
21783 addresses into its corresponding physical addresses. This mechanism is called a <i>page
21784 table</i>; it is essentially a multilevel tree-structured array containing virtual-to-physical
21785 mappings and a few associated flags. The Linux kernel maintains a set of page tables
21786 even on architectures that do not use such tables directly.<br>
21787 <br>
21788 A number of operations commonly performed by device drivers can involve manipulating
21789 page tables. Fortunately for the driver author, the 2.6 kernel has eliminated
21790 any need to work with page tables directly. As a result, we do not describe them in
21791 any detail; curious readers may want to have a look at <i>Understanding The Linux Kernel</i>
21792 by Daniel P. Bovet and Marco Cesati (O'Reilly) for the full story.<br>
21793 <br>
21794 <A name="419"></a><font color="blue">PAGE 419</font><br>
21795 <br>
21796 <a name="VirtualMemoryAreas"></a><font color="red"><b>Virtual Memory Areas</b></font><br>
21797 <br>
21798 The virtual memory area (VMA) is the kernel data structure used to manage distinct
21799 regions of a process's address space. A VMA represents a homogeneous region in the
21800 virtual memory of a process: a contiguous range of virtual addresses that have the
21801 same permission flags and are backed up by the same object (a file, say, or swap
21802 space). It corresponds loosely to the concept of a "segment," although it is better
21803 described as "a memory object with its own properties." The memory map of a process
21804 is made up of (at least) the following areas:<br>
21805 <ul>
21806 <li> An area for the program's executable code (often called text)
21807 <li> Multiple areas for data, including initialized data (that which has an explicitly
21808 assigned value at the beginning of execution), uninitialized data (BSS),* and the
21809 program stack
21810 <li> One area for each active memory mapping
21811 </ul>
21812 The memory areas of a process can be seen by looking in <i>/proc/<pid/maps> </i>(in which
21813 <i>pid</i>, of course, is replaced by a process ID). <i>/proc/self </i>is a special case of <i>/proc/pid</i>,
21814 because it always refers to the current process. As an example, here are a couple of
21815 memory maps (to which we have added short comments in italics):<br>
21816 <pre>
21817 # <b>cat /proc/1/maps</b>
21818 <i>look at init</i>
21819 08048000-0804e000 r-xp 00000000 03:01 64652 /sbin/init <i>text</i>
21820 0804e000-0804f000 rw-p 00006000 03:01 64652 /sbin/init <i>data</i>
21821 0804f000-08053000 rwxp 00000000 00:00 0 <i>zero-mapped BSS</i>
21822 40000000-40015000 r-xp 00000000 03:01 96278 /lib/ld-2.3.2.so <i>text</i>
21823 40015000-40016000 rw-p 00014000 03:01 96278 /lib/ld-2.3.2.so <i>data</i>
21824 40016000-40017000 rw-p 00000000 00:00 0 <i>BSS for ld.so</i>
21825 42000000-4212e000 r-xp 00000000 03:01 80290 /lib/tls/libc-2.3.2.so <i>text</i>
21826 4212e000-42131000 rw-p 0012e000 03:01 80290 /lib/tls/libc-2.3.2.so <i>data</i>
21827 42131000-42133000 rw-p 00000000 00:00 0 <i>BSS for libc</i>
21828 bffff000-c0000000 rwxp 00000000 00:00 0 <i>Stack segment</i>
21829 ffffe000-fffff000 ---p 00000000 00:00 0 <i>vsyscall page</i>
21831 # rsh wolf cat /proc/self/maps #### x86-64 (trimmed)
21832 00400000-00405000 r-xp 00000000 03:01 1596291 /bin/cat <i>text</i>
21833 00504000-00505000 rw-p 00004000 03:01 1596291 /bin/cat <i>data</i>
21834 00505000-00526000 rwxp 00505000 00:00 0 <i>bss</i>
21835 3252200000-3252214000 r-xp 00000000 03:01 1237890 /lib64/ld-2.3.3.so
21836 3252300000-3252301000 r--p 00100000 03:01 1237890 /lib64/ld-2.3.3.so
21837 3252301000-3252302000 rw-p 00101000 03:01 1237890 /lib64/ld-2.3.3.so
21838 7fbfffe000-7fc0000000 rw-p 7fbfffe000 00:00 0 <i>stack</i>
21839 ffffffffff600000-ffffffffffe00000 ---p 00000000 00:00 0 <i>vsyscall</i>
21840 </pre>
21841 The fields in each line are:<br>
21842 <pre>
21843 <i>start</i>-<i>end perm offset major</i>:<i>minor inode image</i>
21844 </pre>
21845 * The name <i>BSS </i>is a historical relic from an old assembly operator meaning "block started by symbol."
21846 The BSS segment of executable files isn't stored on disk, and the kernel maps the zero page to the BSS address
21847 range.<br>
21848 <br>
21849 <A name="420"></a><font color="blue">PAGE 420</font><br>
21850 <br>
21851 Each field in <i>/proc/*/maps </i>(except the image name) corresponds to a field in struct
21852 <font class="fixd">vm_area_struct:</font><br>
21853 <br>
21854 <font class="fixd">start<br>
21855 end</font><br>
21856 <div class="bq">
21857 The beginning and ending virtual addresses for this memory area.</div>
21858 <br>
21859 <font class="fixd">perm</font><br>
21860 <div class="bq">
21861 A bit mask with the memory area's read, write, and execute permissions. This
21862 field describes what the process is allowed to do with pages belonging to the
21863 area. The last character in the field is either <font class="fixd">p</font> for "private" or <font class="fixd">s</font> for "shared."</div>
21864 <br>
21865 <font class="fixd">offset</font><br>
21866 <div class="bq">
21867 Where the memory area begins in the file that it is mapped to. An offset of 0
21868 means that the beginning of the memory area corresponds to the beginning of
21869 the file.</div>
21870 <br>
21871 <font class="fixd">major<br>
21872 minor</font><br>
21873 <div class="bq">
21874 The major and minor numbers of the device holding the file that has been
21875 mapped. Confusingly, for device mappings, the major and minor numbers refer
21876 to the disk partition holding the device special file that was opened by the user,
21877 and not the device itself.</div>
21878 <br>
21879 <font class="fixd">inode</font><br>
21880 <div class="bq">
21881 The <font class="fixd">inode</font> number of the mapped file.</div>
21882 <br>
21883 <font class="fixd">image</font><br>
21884 <div class="bq">
21885 The name of the file (usually an executable image) that has been mapped.</div>
21886 <br>
21887 <a name="TheVmareastructStructure"></a><font color="red"><b>The <font class="fixd">vm_area_struct</font> structure</b></font><br>
21888 <br>
21889 When a user-space process calls <i>mmap </i>to map device memory into its address space,
21890 the system responds by creating a new VMA to represent that mapping. A driver that
21891 supports <i>mmap </i>(and, thus, that implements the <i>mmap </i>method) needs to help that
21892 process by completing the initialization of that VMA. The driver writer should, therefore,
21893 have at least a minimal understanding of VMAs in order to support <i>mmap</i>.<br>
21894 <br>
21895 Let's look at the most important fields in struct <font class="fixd">vm_area_struct</font> (defined in <i><linux/
21896 mm.h></i>). These fields may be used by device drivers in their <i>mmap </i>implementation.
21897 Note that the kernel maintains lists and trees of VMAs to optimize area lookup, and
21898 several fields of <font class="fixd">vm_area_struct</font> are used to maintain this organization. Therefore,
21899 VMAs can't be created at will by a driver, or the structures break. The main fields of<br>
21900 <br>
21901 <A name="421"></a><font color="blue">PAGE 421</font><br>
21902 <br>
21903 VMAs are as follows (note the similarity between these fields and the <i>/proc </i>output we
21904 just saw):<br>
21905 <br>
21906 <font class="fixd">unsigned long vm_start;<br>
21907 unsigned long vm_end;</font><br>
21908 <div class="bq">
21909 The virtual address range covered by this VMA. These fields are the first two
21910 fields shown in <i>/proc/*/maps</i>.</div>
21911 <br>
21912 <font class="fixd">struct file *vm_file;</font><br>
21913 <div class="bq">
21914 A pointer to the <font class="fixd">struct file</font> structure associated with this area (if any).</div>
21915 <br>
21916 <font class="fixd">unsigned long vm_pgoff;</font><br>
21917 <div class="bq">
21918 The offset of the area in the file, in pages. When a file or device is mapped, this is
21919 the file position of the first page mapped in this area.</div>
21920 <br>
21921 <font class="fixd">unsigned long vm_flags;</font><br>
21922 <div class="bq">
21923 A set of flags describing this area. The flags of the most interest to device driver
21924 writers are <font class="fixd">VM_IO</font> and <font class="fixd">VM_RESERVED</font>. <font class="fixd">VM_IO</font> marks a VMA as being a memory-mapped
21925 I/O region. Among other things, the <font class="fixd">VM_IO</font> flag prevents the region from
21926 being included in process core dumps. <font class="fixd">VM_RESERVED</font> tells the memory management
21927 system not to attempt to swap out this VMA; it should be set in most
21928 device mappings.</div>
21929 <br>
21930 <font class="fixd">struct vm_operations_struct *vm_ops;</font><br>
21931 <div class="bq">
21932 A set of functions that the kernel may invoke to operate on this memory area. Its
21933 presence indicates that the memory area is a kernel "object," like the <font class="fixd">struct file</font>
21934 we have been using throughout the book.</div>
21935 <br>
21936 <font class="fixd">void *vm_private_data;</font><br>
21937 <div class="bq">
21938 A field that may be used by the driver to store its own information.</div>
21939 <br>
21940 Like struct <font class="fixd">vm_area_struct,</font> the <font class="fixd">vm_operations_struct</font> is defined in <i><linux/mm.h></i>; it
21941 includes the operations listed below. These operations are the only ones needed to
21942 handle the process's memory needs, and they are listed in the order they are
21943 declared. Later in this chapter, some of these functions are implemented.<br>
21944 <br>
21945 <font class="fixd">void (*open)(struct vm_area_struct *vma);</font><br>
21946 <div class="bq">
21947 The <i>open </i>method is called by the kernel to allow the subsystem implementing
21948 the VMA to initialize the area. This method is invoked any time a new reference
21949 to the VMA is made (when a process forks, for example). The one exception
21950 happens when the VMA is first created by <i>mmap</i>; in this case, the driver's <i>mmap
21951 </i>method is called instead.</div>
21952 <br>
21953 <font class="fixd">void (*close)(struct vm_area_struct *vma);</font><br>
21954 <div class="bq">
21955 When an area is destroyed, the kernel calls its <i>close </i>operation. Note that there's
21956 no usage count associated with VMAs; the area is opened and closed exactly
21957 once by each process that uses it.</div>
21958 <br>
21959 <A name="422"></a><font color="blue">PAGE 422</font><br>
21960 <br>
21961 <font class="fixd">struct page *(*nopage)(struct vm_area_struct *vma, unsigned long address, int *type);</font><br>
21962 <div class="bq">
21963 When a process tries to access a page that belongs to a valid VMA, but that is
21964 currently not in memory, the <i>nopage </i>method is called (if it is defined) for the
21965 related area. The method returns the <font class="fixd">struct page</font> pointer for the physical page
21966 after, perhaps, having read it in from secondary storage. If the <i>nopage </i>method
21967 isn't defined for the area, an empty page is allocated by the kernel.</div>
21968 <br>
21969 <font class="fixd">int (*populate)(struct vm_area_struct *vm, unsigned long address, unsigned long len, pgprot_t prot, unsigned long pgoff, int nonblock);</font><br>
21970 <div class="bq">
21971 This method allows the kernel to "prefault" pages into memory before they are
21972 accessed by user space. There is generally no need for drivers to implement the
21973 <i>populate</i> method.</div>
21974 <br>
21975 <a name="TheProcessMemoryMap"></a><font color="red"><b>The Process Memory Map</b></font><br>
21976 <br>
21977 The final piece of the memory management puzzle is the process memory map structure,
21978 which holds all of the other data structures together. Each process in the system
21979 (with the exception of a few kernel-space helper threads) has a <font class="fixd">struct mm_struct</font>
21980 (defined in <i><linux/sched.h></i>) that contains the process's list of virtual memory areas,
21981 page tables, and various other bits of memory management housekeeping information,
21982 along with a semaphore (<font class="fixd">mmap_sem</font>) and a spinlock (<font class="fixd">page_table_lock</font>). The
21983 pointer to this structure is found in the task structure; in the rare cases where a driver
21984 needs to access it, the usual way is to use <font class="fixd">current->mm.</font> Note that the memory management
21985 structure can be shared between processes; the Linux implementation of
21986 threads works in this way, for example.<br>
21987 <br>
21988 That concludes our overview of Linux memory management data structures. With
21989 that out of the way, we can now proceed to the implementation of the <i>mmap </i>system
21990 call.<br>
21991 <br>
21992 <a name="TheMmapDeviceOperation"></a><font color="red"><b>The mmap Device Operation</b></font><br>
21993 <br>
21994 Memory mapping is one of the most interesting features of modern Unix systems. As
21995 far as drivers are concerned, memory mapping can be implemented to provide user
21996 programs with direct access to device memory.<br>
21997 <br>
21998 A definitive example of <i>mmap </i>usage can be seen by looking at a subset of the virtual
21999 memory areas for the X Window System server:<br>
22000 <pre>
22001 <b>cat /proc/731/maps</b>
22002 000a0000-000c0000 rwxs 000a0000 03:01 282652 /dev/mem
22003 000f0000-00100000 r-xs 000f0000 03:01 282652 /dev/mem
22004 00400000-005c0000 r-xp 00000000 03:01 1366927 /usr/X11R6/bin/Xorg
22005 006bf000-006f7000 rw-p 001bf000 03:01 1366927 /usr/X11R6/bin/Xorg
22006 2a95828000-2a958a8000 rw-s fcc00000 03:01 282652 /dev/mem
22007 2a958a8000-2a9d8a8000 rw-s e8000000 03:01 282652 /dev/mem
22008 ...
22009 </pre>
22010 <A name="423"></a><font color="blue">PAGE 423</font><br>
22011 <br>
22012 The full list of the X server's VMAs is lengthy, but most of the entries are not of interest
22013 here. We do see, however, four separate mappings of <i>/dev/mem</i>, which give some
22014 insight into how the X server works with the video card. The first mapping is at
22015 <font class="fixd">a0000,</font> which is the standard location for video RAM in the 640-KB ISA hole. Further
22016 down, we see a large mapping at <font class="fixd">e8000000,</font> an address which is above the highest
22017 RAM address on the system. This is a direct mapping of the video memory on the
22018 adapter.<br>
22019 <br>
22020 These regions can also be seen in <i>/proc/iomem</i>:<br>
22021 <pre>
22022 000a0000-000bffff : Video RAM area
22023 000c0000-000ccfff : Video ROM
22024 000d1000-000d1fff : Adapter ROM
22025 000f0000-000fffff : System ROM
22026 d7f00000-f7efffff : PCI Bus #01
22027 e8000000-efffffff : 0000:01:00.0
22028 fc700000-fccfffff : PCI Bus #01
22029 fcc00000-fcc0ffff : 0000:01:00.0
22030 </pre>
22031 Mapping a device means associating a range of user-space addresses to device memory.
22032 Whenever the program reads or writes in the assigned address range, it is actually
22033 accessing the device. In the X server example, using <i>mmap </i>allows quick and easy
22034 access to the video card's memory. For a performance-critical application like this,
22035 direct access makes a large difference.<br>
22036 <br>
22037 As you might suspect, not every device lends itself to the <i>mmap </i>abstraction; it makes
22038 no sense, for instance, for serial ports and other stream-oriented devices. Another
22039 limitation of <i>mmap </i>is that mapping is <font class="fixd">PAGE_SIZE</font> grained. The kernel can manage virtual
22040 addresses only at the level of page tables; therefore, the mapped area must be a
22041 multiple of <font class="fixd">PAGE_SIZE</font> and must live in physical memory starting at an address that is
22042 a multiple of <font class="fixd">PAGE_SIZE</font>. The kernel forces size granularity by making a region slightly
22043 bigger if its size isn't a multiple of the page size.<br>
22044 <br>
22045 These limits are not a big constraint for drivers, because the program accessing the
22046 device is device dependent anyway. Since the program must know about how the
22047 device works, the programmer is not unduly bothered by the need to see to details
22048 like page alignment. A bigger constraint exists when ISA devices are used on some
22049 non-x86 platforms, because their hardware view of ISA may not be contiguous. For
22050 example, some Alpha computers see ISA memory as a scattered set of 8-bit, 16-bit,
22051 or 32-bit items, with no direct mapping. In such cases, you can't use <i>mmap </i>at all.
22052 The inability to perform direct mapping of ISA addresses to Alpha addresses is due
22053 to the incompatible data transfer specifications of the two systems. Whereas early
22054 Alpha processors could issue only 32-bit and 64-bit memory accesses, ISA can do
22055 only 8-bit and 16-bit transfers, and there's no way to transparently map one protocol
22056 onto the other.<br>
22057 <br>
22058 There are sound advantages to using <i>mmap </i>when it's feasible to do so. For instance,
22059 we have already looked at the X server, which transfers a lot of data to and from<br>
22060 <br>
22061 <A name="424"></a><font color="blue">PAGE 424</font><br>
22062 <br>
22063 video memory; mapping the graphic display to user space dramatically improves the
22064 throughput, as opposed to an <i>lseek</i>/<i>write </i>implementation. Another typical example
22065 is a program controlling a PCI device. Most PCI peripherals map their control registers
22066 to a memory address, and a high-performance application might prefer to have
22067 direct access to the registers instead of repeatedly having to call <i>ioctl </i>to get its work
22068 done.<br>
22069 <br>
22070 The <i>mmap </i>method is part of the <font class="fixd">file_operations</font> structure and is invoked when the
22071 <i>mmap </i>system call is issued. With <i>mmap</i>, the kernel performs a good deal of work
22072 before the actual method is invoked, and, therefore, the prototype of the method is
22073 quite different from that of the system call. This is unlike calls such as <i>ioctl </i>and <i>poll</i>,
22074 where the kernel does not do much before calling the method.<br>
22075 <br>
22076 The system call is declared as follows (as described in the <i>mmap(2)</i> manual page):<br>
22077 <pre>
22078 mmap (caddr_t addr, size_t len, int prot, int flags, int fd, off_t offset)
22079 </pre>
22080 On the other hand, the file operation is declared as:<br>
22081 <pre>
22082 int (*mmap) (struct file *filp, struct vm_area_struct *vma);
22083 </pre>
22084 The <font class="fixd">filp</font> argument in the method is the same as that introduced in Chapter 3, while
22085 vma contains the information about the virtual address range that is used to access
22086 the device. Therefore, much of the work has been done by the kernel; to implement
22087 <i>mmap</i>, the driver only has to build suitable page tables for the address range and, if
22088 necessary, replace <font class="fixd">vma->vm_ops</font> with a new set of operations.<br>
22089 <br>
22090 There are two ways of building the page tables: doing it all at once with a function
22091 called <font class="fixd">remap_pfn_range</font> or doing it a page at a time via the <i>nopage </i>VMA method.
22092 Each method has its advantages and limitations. We start with the "all at once"
22093 approach, which is simpler. From there, we add the complications needed for a real world
22094 implementation.<br>
22095 <br>
22096 <a name="UsingRemappfnrange"></a><font color="red"><b>Using remap_pfn_range</b></font><br>
22097 <br>
22098 The job of building new page tables to map a range of physical addresses is handled
22099 by <i>remap_pfn_range</i> and <i>io_remap_page_range</i>, which have the following prototypes:<br>
22100 <pre>
22101 int remap_pfn_range(struct vm_area_struct *vma,
22102 unsigned long virt_addr, unsigned long pfn,
22103 unsigned long size, pgprot_t prot);
22104 int io_remap_page_range(struct vm_area_struct *vma,
22105 unsigned long virt_addr, unsigned long phys_addr,
22106 unsigned long size, pgprot_t prot);
22107 </pre>
22108 <A name="425"></a><font color="blue">PAGE 425</font><br>
22109 <br>
22110 The value returned by the function is the usual 0 or a negative error code. Let's look
22111 at the exact meaning of the function's arguments:<br>
22112 <br>
22113 <font class="fixd">vma</font><br>
22114 <div class="bq">
22115 The virtual memory area into which the page range is being mapped.</div>
22116 <br>
22117 <font class="fixd">virt_addr</font><br>
22118 <div class="bq">
22119 The user virtual address where remapping should begin. The function builds
22120 page tables for the virtual address range between <font class="fixd">virt_addr</font> and <font class="fixd">virt_addr+size.</font></div>
22121 <br>
22122 <font class="fixd">pfn</font><br>
22123 <div class="bq">
22124 The page frame number corresponding to the physical address to which the virtual
22125 address should be mapped. The page frame number is simply the physical
22126 address right-shifted by <font class="fixd">PAGE_SHIFT</font> bits. For most uses, the <font class="fixd">vm_pgoff</font> field of the
22127 VMA structure contains exactly the value you need. The function affects physical
22128 addresses from <font class="fixd">(pfn<<PAGE_SHIFT)</font> to <font class="fixd">(pfn<<PAGE_SHIFT)+size.</font></div>
22129 <br>
22130 <font class="fixd">size</font><br>
22131 <div class="bq">
22132 The dimension, in bytes, of the area being remapped.</div>
22133 <br>
22134 <font class="fixd">prot</font><br>
22135 <div class="bq">
22136 The "protection" requested for the new VMA. The driver can (and should) use
22137 the value found in <font class="fixd">vma->vm_page_prot.</font></div>
22138 <br>
22139 The arguments to <i>remap_pfn_range </i>are fairly straightforward, and most of them are
22140 already provided to you in the VMA when your <i>mmap </i>method is called. You may be
22141 wondering why there are two functions, however. The first (<i>remap_pfn_range</i>) is
22142 intended for situations where pfn refers to actual system RAM, while <i>io_remap_
22143 <font class="fixd">page_range</font> </i>should be used when <font class="fixd">phys_addr</font> points to I/O memory. In practice, the
22144 two functions are identical on every architecture except the SPARC, and you see
22145 <i>remap_pfn_range </i>used in most situations. In the interest of writing portable drivers,
22146 however, you should use the variant of <i>remap_pfn_range </i>that is suited to your particular
22147 situation.<br>
22148 <br>
22149 One other complication has to do with caching: usually, references to device memory
22150 should not be cached by the processor. Often the system BIOS sets things up
22151 properly, but it is also possible to disable caching of specific VMAs via the protection
22152 field. Unfortunately, disabling caching at this level is highly processor dependent.
22153 The curious reader may wish to look at the <i>pgprot_noncached </i>function from
22154 <i>drivers/char/mem.c</i> to see what's involved. We won't discuss the topic further here.<br>
22155 <br>
22156 <a name="ASimpleImplementation"></a><font color="red"><b>A Simple Implementation</b></font><br>
22157 <br>
22158 If your driver needs to do a simple, linear mapping of device memory into a user address
22159 space, <i>remap_pfn_range </i>is almost all you really need to do the job. The following code is<br>
22160 <br>
22161 <A name="426"></a><font color="blue">PAGE 426</font><br>
22162 <br>
22163 derived from <i>drivers/char/mem.c </i>and shows how this task is performed in a typical module
22164 called <i>simple</i> (Simple Implementation Mapping Pages with Little Enthusiasm):<br>
22165 <pre>
22166 static int simple_remap_mmap(struct file *filp, struct vm_area_struct *vma)
22167 {
22168 if (remap_pfn_range(vma, vma->vm_start, vm->vm_pgoff,
22169 vma->vm_end - vma->vm_start,
22170 vma->vm_page_prot))
22171 return -EAGAIN;
22173 vma->vm_ops = &simple_remap_vm_ops;
22174 simple_vma_open(vma);
22175 return 0;
22176 }
22177 </pre>
22178 As you can see, remapping memory just a matter of calling <i>remap_pfn_range </i>to create
22179 the necessary page tables.<br>
22180 <br>
22181 <a name="AddingVMAOperations"></a><font color="red"><b>Adding VMA Operations</b></font><br>
22182 <br>
22183 As we have seen, the <font class="fixd">vm_area_struct</font> structure contains a set of operations that may
22184 be applied to the VMA. Now we look at providing those operations in a simple way.
22185 In particular, we provide <i>open </i>and <i>close </i>operations for our VMA. These operations
22186 are called whenever a process opens or closes the VMA; in particular, the <i>open
22187 </i>method is invoked anytime a process forks and creates a new reference to the VMA.
22188 The <i>open </i>and <i>close </i>VMA methods are called in addition to the processing performed
22189 by the kernel, so they need not reimplement any of the work done there. They exist
22190 as a way for drivers to do any additional processing that they may require.<br>
22191 <br>
22192 As it turns out, a simple driver such as <i>simple </i>need not do any extra processing in
22193 particular. So we have created <i>open </i>and <i>close </i>methods, which print a message to the
22194 system log informing the world that they have been called. Not particularly useful,
22195 but it does allow us to show how these methods can be provided, and see when they
22196 are invoked.<br>
22197 <br>
22198 To this end, we override the default <font class="fixd">vma->vm_ops</font> with operations that call <i>printk</i>:<br>
22199 <pre>
22200 void simple_vma_open(struct vm_area_struct *vma)
22201 {
22202 printk(KERN_NOTICE "Simple VMA open, virt %lx, phys %lx\n",
22203 vma->vm_start, vma->vm_pgoff << PAGE_SHIFT);
22204 }
22206 void simple_vma_close(struct vm_area_struct *vma)
22207 {
22208 printk(KERN_NOTICE "Simple VMA close.\n");
22209 }
22211 static struct vm_operations_struct simple_remap_vm_ops = {
22212 .open = simple_vma_open,
22213 .close = simple_vma_close,
22214 };
22215 </pre>
22216 <A name="427"></a><font color="blue">PAGE 427</font><br>
22217 <br>
22218 To make these operations active for a specific mapping, it is necessary to store a
22219 pointer to <font class="fixd">simple_remap_vm_ops</font> in the <font class="fixd">vm_ops</font> field of the relevant VMA. This is usually
22220 done in the <i>mmap </i>method. If you turn back to the <i>simple_remap_mmap </i>example,
22221 you see these lines of code:<br>
22222 <pre>
22223 vma->vm_ops = &simple_remap_vm_ops;
22224 simple_vma_open(vma);
22225 </pre>
22226 Note the explicit call to <i>simple_vma_open</i>. Since the <i>open </i>method is not invoked on
22227 the initial <i>mmap</i>, we must call it explicitly if we want it to run.<br>
22228 <br>
22229 <a name="MappingMemoryWithNopage"></a><font color="red"><b>Mapping Memory with nopage</b></font><br>
22230 <br>
22231 Although <i>remap_pfn_range </i>works well for many, if not most, driver <i>mmap </i>implementations,
22232 sometimes it is necessary to be a little more flexible. In such situations,
22233 an implementation using the <i>nopage</i> VMA method may be called for.<br>
22234 <br>
22235 One situation in which the <i>nopage </i>approach is useful can be brought about by the
22236 <i>mremap </i>system call, which is used by applications to change the bounding addresses
22237 of a mapped region. As it happens, the kernel does not notify drivers directly when a
22238 mapped VMA is changed by <i>mremap</i>. If the VMA is reduced in size, the kernel can
22239 quietly flush out the unwanted pages without telling the driver. If, instead, the VMA
22240 is expanded, the driver eventually finds out by way of calls to <i>nopage </i>when mappings
22241 must be set up for the new pages, so there is no need to perform a separate
22242 notification. The <i>nopage </i>method, therefore, must be implemented if you want to
22243 support the <i>mremap </i>system call. Here, we show a simple implementation of <i>nopage
22244 </i>for the <i>simple</i> device.<br>
22245 <br>
22246 The <i>nopage</i> method, remember, has the following prototype:<br>
22247 <pre>
22248 struct page *(*nopage)(struct vm_area_struct *vma,
22249 unsigned long address, int *type);
22250 </pre>
22251 When a user process attempts to access a page in a VMA that is not present in memory,
22252 the associated <i>nopage </i>function is called. The <font class="fixd">address</font> parameter contains the virtual
22253 address that caused the fault, rounded down to the beginning of the page. The
22254 <i>nopage </i>function must locate and return the <font class="fixd">struct page</font> pointer that refers to the
22255 page the user wanted. This function must also take care to increment the usage
22256 count for the page it returns by calling the <i>get_page</i> macro:<br>
22257 <pre>
22258 get_page(struct page *pageptr);
22259 </pre>
22260 This step is necessary to keep the reference counts correct on the mapped pages. The
22261 kernel maintains this count for every page; when the count goes to 0, the kernel
22262 knows that the page may be placed on the free list. When a VMA is unmapped, the
22263 kernel decrements the usage count for every page in the area. If your driver does not
22264 increment the count when adding a page to the area, the usage count becomes 0 prematurely,
22265 and the integrity of the system is compromised.<br>
22266 <br>
22267 <A name="428"></a><font color="blue">PAGE 428</font><br>
22268 <br>
22269 The <i>nopage </i>method should also store the type of fault in the location pointed to by
22270 the <font class="fixd">type</font> argument--but only if that argument is not <font class="fixd">NULL</font>. In device drivers, the
22271 proper value for type will invariably be <font class="fixd">VM_FAULT_MINOR</font>.<br>
22272 <br>
22273 If you are using <i>nopage</i>, there is usually very little work to be done when <i>mmap </i>is
22274 called; our version looks like this:<br>
22275 <pre>
22276 static int simple_nopage_mmap(struct file *filp, struct vm_area_struct *vma)
22277 {
22278 unsigned long offset = vma->vm_pgoff << PAGE_SHIFT;
22280 if (offset >= __pa(high_memory) || (filp->f_flags & O_SYNC))
22281 vma->vm_flags |= VM_IO;
22282 vma->vm_flags |= VM_RESERVED;
22284 vma->vm_ops = &simple_nopage_vm_ops;
22285 simple_vma_open(vma);
22286 return 0;
22287 }
22288 </pre>
22289 The main thing <i>mmap </i>has to do is to replace the default (<font class="fixd">NULL</font>) <font class="fixd">vm_ops</font> pointer with
22290 our own operations. The <i>nopage </i>method then takes care of "remapping" one page at
22291 a time and returning the address of its <font class="fixd">struct page</font> structure. Because we are just
22292 implementing a window onto physical memory here, the remapping step is simple:
22293 we only need to locate and return a pointer to the <font class="fixd">struct page</font> for the desired
22294 address. Our <i>nopage</i> method looks like the following:<br>
22295 <pre>
22296 struct page *simple_vma_nopage(struct vm_area_struct *vma,
22297 unsigned long address, int *type)
22298 {
22299 struct page *pageptr;
22300 unsigned long offset = vma->vm_pgoff << PAGE_SHIFT;
22301 unsigned long physaddr = address - vma->vm_start + offset;
22302 unsigned long pageframe = physaddr >> PAGE_SHIFT;
22304 if (!pfn_valid(pageframe))
22305 return NOPAGE_SIGBUS;
22306 pageptr = pfn_to_page(pageframe);
22307 get_page(pageptr);
22308 if (type)
22309 *type = VM_FAULT_MINOR;
22310 return pageptr;
22311 }
22312 </pre>
22313 Since, once again, we are simply mapping main memory here, the <i>nopage </i>function
22314 need only find the correct <font class="fixd">struct page</font> for the faulting address and increment its reference
22315 count. Therefore, the required sequence of events is to calculate the desired physical
22316 address, and turn it into a page frame number by right-shifting it <font class="fixd">PAGE_SHIFT</font> bits.
22317 Since user space can give us any address it likes, we must ensure that we have a valid
22318 page frame; the <i>pfn_valid </i>function does that for us. If the address is out of range, we
22319 return <font class="fixd">NOPAGE_SIGBUS,</font> which causes a bus signal to be delivered to the calling process.<br>
22320 <br>
22321 <A name="429"></a><font color="blue">PAGE 429</font><br>
22322 <br>
22323 Otherwise, <i>pfn_to_page </i>gets the necessary <font class="fixd">struct page</font> pointer; we can increment its
22324 reference count (with a call to <i>get_page</i>) and return it.<br>
22325 <br>
22326 The <i>nopage </i>method normally returns a pointer to a <font class="fixd">struct page</font>. If, for some reason,
22327 a normal page cannot be returned (e.g., the requested address is beyond the device's
22328 memory region), <font class="fixd">NOPAGE_SIGBUS</font> can be returned to signal the error; that is what the
22329 <i>simple </i>code above does. <i>nopage </i>can also return <font class="fixd">NOPAGE_OOM</font> to indicate failures caused
22330 by resource limitations.<br>
22331 <br>
22332 Note that this implementation works for ISA memory regions but not for those on
22333 the PCI bus. PCI memory is mapped above the highest system memory, and there are
22334 no entries in the system memory map for those addresses. Because there is no <font class="fixd">struct
22335 page</font> to return a pointer to, <i>nopage </i>cannot be used in these situations; you must use
22336 <i>remap_pfn_range</i> instead.<br>
22337 <br>
22338 If the <i>nopage </i>method is left <font class="fixd">NULL</font>, kernel code that handles page faults maps the zero
22339 page to the faulting virtual address. The <i>zero page </i>is a copy-on-write page that reads
22340 as 0 and that is used, for example, to map the BSS segment. Any process referencing
22341 the zero page sees exactly that: a page filled with zeroes. If the process writes to the
22342 page, it ends up modifying a private copy. Therefore, if a process extends a mapped
22343 region by calling <i>mremap</i>, and the driver hasn't implemented <i>nopage</i>, the process
22344 ends up with zero-filled memory instead of a segmentation fault.<br>
22345 <br>
22346 <a name="RemappingSpecificIORegions"></a><font color="red"><b>Remapping Specific I/O Regions</b></font><br>
22347 <br>
22348 All the examples we've seen so far are reimplementations of <i>/dev/mem</i>; they remap
22349 physical addresses into user space. The typical driver, however, wants to map only
22350 the small address range that applies to its peripheral device, not all memory. In order
22351 to map to user space only a subset of the whole memory range, the driver needs only
22352 to play with the offsets. The following does the trick for a driver mapping a region of
22353 <font class="fixd">simple_region_size</font> bytes, beginning at physical address <font class="fixd">simple_region_start</font> (which
22354 should be page-aligned):<br>
22355 <pre>
22356 unsigned long off = vma->vm_pgoff << PAGE_SHIFT;
22357 unsigned long physical = <font class="fixd">simple_region_start</font> + off;
22358 unsigned long vsize = vma->vm_end - vma->vm_start;
22359 unsigned long psize = <font class="fixd">simple_region_size</font> - off;
22361 if (vsize > psize)
22362 return -EINVAL; /* spans too high */
22363 remap_pfn_range(vma, vma_>vm_start, physical, vsize, vma->vm_page_prot);
22364 </pre>
22365 In addition to calculating the offsets, this code introduces a check that reports an
22366 error when the program tries to map more memory than is available in the I/O region
22367 of the target device. In this code, <font class="fixd">psize</font> is the physical I/O size that is left after the offset
22368 has been specified, and <font class="fixd">vsize</font> is the requested size of virtual memory; the function
22369 refuses to map addresses that extend beyond the allowed memory range.<br>
22370 <br>
22371 <A name="430"></a><font color="blue">PAGE 430</font><br>
22372 <br>
22373 Note that the user process can always use <i>mremap </i>to extend its mapping, possibly
22374 past the end of the physical device area. If your driver fails to define a <i>nopage
22375 </i>method, it is never notified of this extension, and the additional area maps to the
22376 zero page. As a driver writer, you may well want to prevent this sort of behavior;
22377 mapping the zero page onto the end of your region is not an explicitly bad thing to
22378 do, but it is highly unlikely that the programmer wanted that to happen.<br>
22379 <br>
22380 The simplest way to prevent extension of the mapping is to implement a simple
22381 <i>nopage </i>method that always causes a bus signal to be sent to the faulting process.
22382 Such a method would look like this:<br>
22383 <pre>
22384 struct page *simple_nopage(struct vm_area_struct *vma,
22385 unsigned long address, int *type);
22386 { return NOPAGE_SIGBUS; /* send a SIGBUS */}
22387 </pre>
22388 As we have seen, the <i>nopage </i>method is called only when the process dereferences an
22389 address that is within a known VMA but for which there is currently no valid page
22390 table entry. If we have used <i>remap_pfn_range </i>to map the entire device region, the
22391 <i>nopage </i>method shown here is called only for references outside of that region. Thus,
22392 it can safely return <font class="fixd">NOPAGE_SIGBUS</font> to signal an error. Of course, a more thorough
22393 implementation of <i>nopage </i>could check to see whether the faulting address is within
22394 the device area, and perform the remapping if that is the case. Once again, however,
22395 <i>nopage </i>does not work with PCI memory areas, so extension of PCI mappings is not
22396 possible.<br>
22397 <br>
22398 <a name="RemappingRAM"></a><font color="red"><b>Remapping RAM</b></font><br>
22399 <br>
22400 An interesting limitation of <i>remap_pfn_range </i>is that it gives access only to reserved
22401 pages and physical addresses above the top of physical memory. In Linux, a page of
22402 physical addresses is marked as "reserved" in the memory map to indicate that it is
22403 not available for memory management. On the PC, for example, the range between
22404 640 KB and 1 MB is marked as reserved, as are the pages that host the kernel code
22405 itself. Reserved pages are locked in memory and are the only ones that can be safely
22406 mapped to user space; this limitation is a basic requirement for system stability.<br>
22407 <br>
22408 Therefore, <i>remap_pfn_range </i>won't allow you to remap conventional addresses,
22409 which include the ones you obtain by calling <i>get_free_page</i>. Instead, it maps in the
22410 zero page. Everything appears to work, with the exception that the process sees private,
22411 zero-filled pages rather than the remapped RAM that it was hoping for. Nonetheless,
22412 the function does everything that most hardware drivers need it to do,
22413 because it can remap high PCI buffers and ISA memory.<br>
22414 <br>
22415 The limitations of <i>remap_pfn_range </i>can be seen by running <i>mapper</i>, one of the sample
22416 programs in <i>misc-progs </i>in the files provided on O'Reilly's FTP site. <i>mapper </i>is a
22417 simple tool that can be used to quickly test the <i>mmap </i>system call; it maps read-only
22418 parts of a file specified by command-line options and dumps the mapped region to
22419 standard output. The following session, for instance, shows that <i>/dev/mem </i>doesn't<br>
22420 <br>
22421 <A name="431"></a><font color="blue">PAGE 431</font><br>
22422 <br>
22423 map the physical page located at address 64 KB--instead, we see a page full of zeros
22424 (the host computer in this example is a PC, but the result would be the same on
22425 other platforms):<br>
22426 <pre>
22427 morgana.root# ./mapper /dev/mem 0x10000 0x1000 | od -Ax -t x1
22428 mapped "/dev/mem" from 65536 to 69632
22429 000000 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
22430 *
22431 001000
22432 </pre>
22433 The inability of <i>remap_pfn_range </i>to deal with RAM suggests that memory-based
22434 devices like <i>scull </i>can't easily implement <i>mmap</i>, because its device memory is conventional
22435 RAM, not I/O memory. Fortunately, a relatively easy work-around is available
22436 to any driver that needs to map RAM into user space; it uses the <i>nopage </i>method that
22437 we have seen earlier.<br>
22438 <br>
22439 <a name="RemappingRAMWithTheNopageMethod"></a><font color="red"><b>Remapping RAM with the nopage method</b></font><br>
22440 <br>
22441 The way to map real RAM to user space is to use <font class="fixd">vm_ops->nopage</font> to deal with page
22442 faults one at a time. A sample implementation is part of the <i>scullp </i>module, introduced
22443 in Chapter 8.<br>
22444 <br>
22445 <i>scullp </i>is a page-oriented char device. Because it is page oriented, it can implement
22446 <i>mmap </i>on its memory. The code implementing memory mapping uses some of the
22447 concepts introduced in the section "Memory Management in Linux."<br>
22448 <br>
22449 Before examining the code, let's look at the design choices that affect the <i>mmap
22450 </i>implementation in <i>scullp</i>:<br>
22451 <ul>
22452 <li> <i>scullp </i>doesn't release device memory as long as the device is mapped. This is a
22453 matter of policy rather than a requirement, and it is different from the behavior
22454 of <i>scull </i>and similar devices, which are truncated to a length of 0 when opened for
22455 writing. Refusing to free a mapped <i>scullp </i>device allows a process to overwrite
22456 regions actively mapped by another process, so you can test and see how processes
22457 and device memory interact. To avoid releasing a mapped device, the
22458 driver must keep a count of active mappings; the <font class="fixd">vmas</font> field in the device structure
22459 is used for this purpose.
22460 <li> Memory mapping is performed only when the <i>scullp </i><font class="fixd">order</font> parameter (set at module load time) is 0. The parameter controls how <i>__get_free_pages </i>is invoked (see
22461 the section "get_free_page and Friends" in Chapter 8). The zero-order limitation
22462 (which forces pages to be allocated one at a time, rather than in larger groups) is
22463 dictated by the internals of <i>__get_free_pages</i>, the allocation function used by
22464 <i>scullp</i>. To maximize allocation performance, the Linux kernel maintains a list of
22465 free pages for each allocation order, and only the reference count of the first page
22466 in a cluster is incremented by <i>get_free_pages </i>and decremented by <i>free_pages</i>. The
22467 <i>mmap </i>method is disabled for a <i>scullp </i>device if the allocation order is greater than
22468 zero, because <i>nopage </i>deals with single pages rather than clusters of pages. <i>scullp</i>
22469 </ul>
22470 <A name="432"></a><font color="blue">PAGE 432</font><br>
22471 <ul>
22472 simply does not know how to properly manage reference counts for pages that
22473 are part of higher-order allocations. (Return to the section "A scull Using Whole
22474 Pages: scullp" in Chapter 8 if you need a refresher on <i>scullp </i>and the memory allocation
22475 order value.)
22476 </ul>
22477 The zero-order limitation is mostly intended to keep the code simple. It <i>is </i>possible to
22478 correctly implement <i>mmap </i>for multipage allocations by playing with the usage count
22479 of the pages, but it would only add to the complexity of the example without introducing
22480 any interesting information.<br>
22481 <br>
22482 Code that is intended to map RAM according to the rules just outlined needs to
22483 implement the <i>open</i>, <i>close</i>, and <i>nopage </i>VMA methods; it also needs to access the
22484 memory map to adjust the page usage counts.<br>
22485 <br>
22486 This implementation of <i>scullp_mmap </i>is very short, because it relies on the <i>nopage
22487 </i>function to do all the interesting work:<br>
22488 <pre>
22489 int scullp_mmap(struct file *filp, struct vm_area_struct *vma)
22490 {
22491 struct inode *inode = filp->f_dentry->d_inode;
22493 /* refuse to map if order is not 0 */
22494 if (scullp_devices[iminor(inode)].order)
22495 return -ENODEV;
22497 /* don't do anything here: "nopage" will fill the holes */
22498 vma->vm_ops = &scullp_vm_ops;
22499 vma->vm_flags |= VM_RESERVED;
22500 vma->vm_private_data = filp->private_data;
22501 scullp_vma_open(vma);
22502 return 0;
22503 }
22504 </pre>
22505 The purpose of the if statement is to avoid mapping devices whose allocation order
22506 is not 0. <i>scullp</i>'s operations are stored in the <font class="fixd">vm_ops</font> field, and a pointer to the device
22507 structure is stashed in the <font class="fixd">vm_private_data</font> field. At the end, <font class="fixd">vm_ops->open</font> is called to
22508 update the count of active mappings for the device.<br>
22509 <br>
22510 <i>open</i> and <i>close</i> simply keep track of the mapping count and are defined as follows:<br>
22511 <pre>
22512 void scullp_vma_open(struct vm_area_struct *vma)
22513 {
22514 struct scullp_dev *dev = vma->vm_private_data;
22516 dev->vmas++;
22517 }
22519 void scullp_vma_close(struct vm_area_struct *vma)
22520 {
22521 struct scullp_dev *dev = vma->vm_private_data;
22523 dev->vmas--;
22524 }
22525 </pre>
22526 <A name="433"></a><font color="blue">PAGE 433</font><br>
22527 <br>
22528 Most of the work is then performed by <i>nopage</i>. In the <i>scullp </i>implementation, the
22529 address parameter to <i>nopage </i>is used to calculate an offset into the device; the offset is
22530 then used to look up the correct page in the <i>scullp</i> memory tree:<br>
22531 <pre>
22532 struct page *scullp_vma_nopage(struct vm_area_struct *vma,
22533 unsigned long address, int *type)
22534 {
22535 unsigned long offset;
22536 struct scullp_dev *ptr, *dev = vma->vm_private_data;
22537 struct page *page = NOPAGE_SIGBUS;
22538 void *pageptr = NULL; /* default to "missing" */
22540 down(&dev->sem);
22541 offset = (address - vma->vm_start) + (vma->vm_pgoff << PAGE_SHIFT);
22542 if (offset >= dev->size) goto out; /* out of range */
22544 /*
22545 * Now retrieve the scullp device from the list, then the page.
22546 * If the device has holes, the process receives a SIGBUS when
22547 * accessing the hole.
22548 */
22549 offset >>= PAGE_SHIFT; /* offset is a number of pages */
22550 for (ptr = dev; ptr && offset >= dev->qset;) {
22551 ptr = ptr->next;
22552 offset -= dev->qset;
22553 }
22554 if (ptr && ptr->data) pageptr = ptr->data[offset];
22555 if (!pageptr) goto out; /* hole or end-of-file */
22556 page = virt_to_page(pageptr);
22558 /* got it, now increment the count */
22559 get_page(page);
22560 if (type)
22561 *type = VM_FAULT_MINOR;
22562 out:
22563 up(&dev->sem);
22564 return page;
22565 }
22566 </pre>
22567 <i>scullp </i>uses memory obtained with <i>get_free_pages</i>. That memory is addressed using
22568 logical addresses, so all <i>scullp_nopage </i>has to do to get a <font class="fixd">struct page</font> pointer is to call
22569 <i>virt_to_page</i>.<br>
22570 <br>
22571 The <i>scullp </i>device now works as expected, as you can see in this sample output from
22572 the <i>mapper </i>utility. Here, we send a directory listing of <i>/dev </i>(which is long) to the
22573 <i>scullp </i>device and then use the <i>mapper </i>utility to look at pieces of that listing with
22574 <i>mmap</i>:<br>
22575 <pre>
22576 morgana% <b>ls -l /dev > /dev/scullp
22577 </b>morgana% <b>./mapper /dev/scullp 0 140
22578 </b>mapped "/dev/scullp" from 0 (0x00000000) to 140 (0x0000008c)
22579 total 232
22580 crw------- 1 root root 10, 10 Sep 15 07:40 adbmouse
22581 </pre>
22582 <A name="434"></a><font color="blue">PAGE 434</font><br>
22583 <pre>
22584 crw-r--r-- 1 root root 10, 175 Sep 15 07:40 agpgart
22585 morgana% <b>./mapper /dev/scullp 8192 200
22586 </b>mapped "/dev/scullp" from 8192 (0x00002000) to 8392 (0x000020c8)
22587 d0h1494
22588 brw-rw---- 1 root floppy 2, 92 Sep 15 07:40 fd0h1660
22589 brw-rw---- 1 root floppy 2, 20 Sep 15 07:40 fd0h360
22590 brw-rw---- 1 root floppy 2, 12 Sep 15 07:40 fd0H360
22591 </pre>
22592 <a name="RemappingKernelVirtualAddresses"></a><font color="red"><b>Remapping Kernel Virtual Addresses</b></font><br>
22593 <br>
22594 Although it's rarely necessary, it's interesting to see how a driver can map a kernel
22595 virtual address to user space using <i>mmap</i>. A true kernel virtual address, remember, is
22596 an address returned by a function such as <i>vmalloc</i>--that is, a virtual address mapped
22597 in the kernel page tables. The code in this section is taken from <i>scullv</i>, which is the
22598 module that works like <i>scullp</i> but allocates its storage through <i>vmalloc</i>.<br>
22599 <br>
22600 Most of the <i>scullv </i>implementation is like the one we've just seen for <i>scullp</i>, except
22601 that there is no need to check the order parameter that controls memory allocation.
22602 The reason for this is that <i>vmalloc </i>allocates its pages one at a time, because singlepage
22603 allocations are far more likely to succeed than multipage allocations. Therefore,
22604 the allocation order problem doesn't apply to <i>vmalloc</i>ed space.<br>
22605 <br>
22606 Beyond that, there is only one difference between the <i>nopage </i>implementations used by
22607 <i>scullp </i>and <i>scullv</i>. Remember that <i>scullp</i>, once it found the page of interest, would obtain
22608 the corresponding <font class="fixd">struct page</font> pointer with <i>virt_to_page</i>. That function does not work
22609 with kernel virtual addresses, however. Instead, you must use <i>vmalloc_to_page</i>. So the
22610 final part of the <i>scullv</i> version of <i>nopage</i> looks like:<br>
22611 <pre>
22612 /*
22613 * After scullv lookup, "page" is now the address of the page
22614 * needed by the current process. Since it's a vmalloc address,
22615 * turn it into a struct page.
22616 */
22617 page = vmalloc_to_page(pageptr);
22619 /* got it, now increment the count */
22620 get_page(page);
22621 if (type)
22622 *type = VM_FAULT_MINOR;
22623 out:
22624 up(&dev->sem);
22625 return page;
22626 </pre>
22627 Based on this discussion, you might also want to map addresses returned by <i>ioremap
22628 </i>to user space. That would be a mistake, however; addresses from <i>ioremap </i>are special
22629 and cannot be treated like normal kernel virtual addresses. Instead, you should use
22630 <i>remap_pfn_range</i> to remap I/O memory areas into user space.<br>
22631 <br>
22632 <A name="435"></a><font color="blue">PAGE 435</font><br>
22633 <br>
22634 <a name="PerformingDirectIO"></a><font color="red"><b>Performing Direct I/O</b></font><br>
22635 <br>
22636 Most I/O operations are buffered through the kernel. The use of a kernel-space
22637 buffer allows a degree of separation between user space and the actual device; this
22638 separation can make programming easier and can also yield performance benefits in
22639 many situations. There are cases, however, where it can be beneficial to perform I/O
22640 directly to or from a user-space buffer. If the amount of data being transferred is
22641 large, transferring data directly without an extra copy through kernel space can
22642 speed things up.<br>
22643 <br>
22644 One example of direct I/O use in the 2.6 kernel is the SCSI tape driver. Streaming
22645 tapes can pass a lot of data through the system, and tape transfers are usually record oriented,
22646 so there is little benefit to buffering data in the kernel. So, when the conditions
22647 are right (the user-space buffer is page-aligned, for example), the SCSI tape
22648 driver performs its I/O without copying the data.<br>
22649 <br>
22650 That said, it is important to recognize that direct I/O does not always provide the
22651 performance boost that one might expect. The overhead of setting up direct I/O
22652 (which involves faulting in and pinning down the relevant user pages) can be significant,
22653 and the benefits of buffered I/O are lost. For example, the use of direct I/O
22654 requires that the <i>write </i>system call operate synchronously; otherwise the application
22655 does not know when it can reuse its I/O buffer. Stopping the application until each
22656 write completes can slow things down, which is why applications that use direct I/O
22657 often use asynchronous I/O operations as well.<br>
22658 <br>
22659 The real moral of the story, in any case, is that implementing direct I/O in a char
22660 driver is usually unnecessary and can be hurtful. You should take that step only if
22661 you are sure that the overhead of buffered I/O is truly slowing things down. Note
22662 also that block and network drivers need not worry about implementing direct I/O at
22663 all; in both cases, higher-level code in the kernel sets up and makes use of direct I/O
22664 when it is indicated, and driver-level code need not even know that direct I/O is
22665 being performed.<br>
22666 <br>
22667 The key to implementing direct I/O in the 2.6 kernel is a function called <i>get_user_pages</i>,
22668 which is declared in <i><linux/mm.h></i> with the following prototype:<br>
22669 <pre>
22670 int get_user_pages(struct task_struct *tsk,
22671 struct mm_struct *mm,
22672 unsigned long start,
22673 int len,
22674 int write,
22675 int force,
22676 struct page **pages,
22677 struct vm_area_struct **vmas);
22678 </pre>
22679 <A name="436"></a><font color="blue">PAGE 436</font><br>
22680 <br>
22681 This function has several arguments:<br>
22682 <br>
22683 <font class="fixd">tsk</font><br>
22684 <div class="bq">
22685 A pointer to the task performing the I/O; its main purpose is to tell the kernel
22686 who should be charged for any page faults incurred while setting up the buffer.
22687 This argument is almost always passed as <font class="fixd">current.</font></div>
22688 <br>
22689 <font class="fixd">mm</font><br>
22690 <div class="bq">
22691 A pointer to the memory management structure describing the address space to
22692 be mapped. The <font class="fixd">mm_struct</font> structure is the piece that ties together all of the parts
22693 (VMAs) of a process's virtual address space. For driver use, this argument should
22694 always be <font class="fixd">current->mm.</font></div>
22695 <br>
22696 <font class="fixd">start<br>
22697 len</font><br>
22698 <div class="bq">
22699 start is the (page-aligned) address of the user-space buffer, and <font class="fixd">len</font> is the length
22700 of the buffer in pages.</div>
22701 <br>
22702 <font class="fixd">write<br>
22703 force</font><br>
22704 <div class="bq">
22705 If write is nonzero, the pages are mapped for write access (implying, of course,
22706 that user space is performing a read operation). The <font class="fixd">force</font> flag tells <i>get_user_pages
22707 </i>to override the protections on the given pages to provide the requested access;
22708 drivers should always pass 0 here.</div>
22709 <br>
22710 <font class="fixd">pages<br>
22711 vmas</font><br>
22712 <div class="bq">
22713 Output parameters. Upon successful completion, <font class="fixd">pages</font> contain a list of pointers
22714 to the <font class="fixd">struct page</font> structures describing the user-space buffer, and <font class="fixd">vmas</font> contains
22715 pointers to the associated VMAs. The parameters should, obviously, point to
22716 arrays capable of holding at least len pointers. Either parameter can be <font class="fixd">NULL</font>, but
22717 you need, at least, the <font class="fixd">struct page</font> pointers to actually operate on the buffer.</div>
22718 <br>
22719 <i>get_user_pages </i>is a low-level memory management function, with a suitably complex
22720 interface. It also requires that the mmap reader/writer semaphore for the address
22721 space be obtained in read mode before the call. As a result, calls to <i>get_user_pages
22722 </i>usually look something like:<br>
22723 <pre>
22724 down_read(&current->mm->mmap_sem);
22725 result = get_user_pages(current, current->mm, ...);
22726 up_read(&current->mm->mmap_sem);
22727 </pre>
22728 The return value is the number of pages actually mapped, which could be fewer than
22729 the number requested (but greater than zero).<br>
22730 <br>
22731 Upon successful completion, the caller has a <font class="fixd">pages</font> array pointing to the user-space
22732 buffer, which is locked into memory. To operate on the buffer directly, the kernelspace
22733 code must turn each <font class="fixd">struct page</font> pointer into a kernel virtual address with
22734 <i>kmap </i>or <i>kmap_atomic</i>. Usually, however, devices for which direct I/O is justified are
22735 using DMA operations, so your driver will probably want to create a scatter/gather<br>
22736 <br>
22737 <A name="437"></a><font color="blue">PAGE 437</font><br>
22738 <br>
22739 list from the array of <font class="fixd">struct page</font> pointers. We discuss how to do this in the section,
22740 "Scatter/gather mappings."<br>
22741 <br>
22742 Once your direct I/O operation is complete, you must release the user pages. Before
22743 doing so, however, you must inform the kernel if you changed the contents of those
22744 pages. Otherwise, the kernel may think that the pages are "clean," meaning that they
22745 match a copy found on the swap device, and free them without writing them out to
22746 backing store. So, if you have changed the pages (in response to a user-space read
22747 request), you must mark each affected page dirty with a call to:<br>
22748 <pre>
22749 void SetPageDirty(struct page *page);
22750 </pre>
22751 (This macro is defined in <i><linux/page-flags.h></i>). Most code that performs this operation
22752 checks first to ensure that the page is not in the reserved part of the memory
22753 map, which is never swapped out. Therefore, the code usually looks like:<br>
22754 <pre>
22755 if (! PageReserved(page))
22756 SetPageDirty(page);
22757 </pre>
22758 Since user-space memory is not normally marked reserved, this check should not
22759 strictly be necessary, but when you are getting your hands dirty deep within the
22760 memory management subsystem, it is best to be thorough and careful.<br>
22761 <br>
22762 Regardless of whether the pages have been changed, they must be freed from the
22763 page cache, or they stay there forever. The call to use is:<br>
22764 <pre>
22765 void page_cache_release(struct page *page);
22766 </pre>
22767 This call should, of course, be made <i>after</i> the page has been marked dirty, if need be.<br>
22768 <br>
22769 <a name="AsynchronousIO"></a><font color="red"><b>Asynchronous I/O</b></font><br>
22770 <br>
22771 One of the new features added to the 2.6 kernel was the <i>asynchronous I/O </i>capability.
22772 Asynchronous I/O allows user space to initiate operations without waiting for
22773 their completion; thus, an application can do other processing while its I/O is in
22774 flight. A complex, high-performance application can also use asynchronous I/O to
22775 have multiple operations going at the same time.<br>
22776 <br>
22777 The implementation of asynchronous I/O is optional, and very few driver authors
22778 bother; most devices do not benefit from this capability. As we will see in the coming
22779 chapters, block and network drivers are fully asynchronous at all times, so only
22780 char drivers are candidates for explicit asynchronous I/O support. A char device can
22781 benefit from this support if there are good reasons for having more than one I/O
22782 operation outstanding at any given time. One good example is streaming tape drives,
22783 where the drive can stall and slow down significantly if I/O operations do not arrive
22784 quickly enough. An application trying to get the best performance out of a streaming
22785 drive could use asynchronous I/O to have multiple operations ready to go at any
22786 given time.<br>
22787 <br>
22788 <A name="438"></a><font color="blue">PAGE 438</font><br>
22789 <br>
22790 For the rare driver author who needs to implement asynchronous I/O, we present a
22791 quick overview of how it works. We cover asynchronous I/O in this chapter, because
22792 its implementation almost always involves direct I/O operations as well (if you are
22793 buffering data in the kernel, you can usually implement asynchronous behavior without
22794 imposing the added complexity on user space).<br>
22795 <br>
22796 Drivers supporting asynchronous I/O should include <i><linux/aio.h></i>. There are three
22797 <i>file_operations</i> methods for the implementation of asynchronous I/O:<br>
22798 <pre>
22799 ssize_t (*aio_read) (struct kiocb *iocb, char *buffer,
22800 size_t count, loff_t offset);
22801 ssize_t (*aio_write) (struct kiocb *iocb, const char *buffer,
22802 size_t count, loff_t offset);
22803 int (*aio_fsync) (struct kiocb *iocb, int datasync);
22804 </pre>
22805 The <i>aio_fsync </i>operation is only of interest to filesystem code, so we do not discuss it
22806 further here. The other two, <i>aio_read </i>and <i>aio_write</i>, look very much like the regular
22807 <i>read </i>and <i>write </i>methods but with a couple of exceptions. One is that the <font class="fixd">offset</font>
22808 parameter is passed by value; asynchronous operations never change the file position,
22809 so there is no reason to pass a pointer to it. These methods also take the <font class="fixd">iocb</font>
22810 ("I/O control block") parameter, which we get to in a moment.<br>
22811 <br>
22812 The purpose of the <i>aio_read </i>and <i>aio_write </i>methods is to initiate a read or write operation
22813 that may or may not be complete by the time they return. If it <i>is </i>possible to
22814 complete the operation immediately, the method should do so and return the usual
22815 status: the number of bytes transferred or a negative error code. Thus, if your driver
22816 has a <i>read </i>method called <i>my_read</i>, the following <i>aio_read </i>method is entirely correct
22817 (though rather pointless):<br>
22818 <pre>
22819 static ssize_t my_aio_read(struct kiocb *iocb, char *buffer,
22820 ssize_t count, loff_t offset)
22821 {
22822 return my_read(iocb->ki_filp, buffer, count, &offset);
22823 }
22824 </pre>
22825 Note that the <font class="fixd">struct file</font> pointer is found in the <font class="fixd">ki_filp</font> field of the <font class="fixd">kiocb</font> structure.<br>
22826 <br>
22827 If you support asynchronous I/O, you must be aware of the fact that the kernel can,
22828 on occasion, create "synchronous IOCBs." These are, essentially, asynchronous
22829 operations that must actually be executed synchronously. One may well wonder why
22830 things are done this way, but it's best to just do what the kernel asks. Synchronous
22831 operations are marked in the IOCB; your driver should query that status with:<br>
22832 <pre>
22833 int is_sync_kiocb(struct kiocb *iocb);
22834 </pre>
22835 If this function returns a nonzero value, your driver must execute the operation
22836 synchronously.<br>
22837 <br>
22838 In the end, however, the point of all this structure is to enable asynchronous operations.
22839 If your driver is able to initiate the operation (or, simply, to queue it until some
22840 future time when it can be executed), it must do two things: remember everything it<br>
22841 <br>
22842 <A name="439"></a><font color="blue">PAGE 439</font><br>
22843 <br>
22844 needs to know about the operation, and return <font class="fixd">-EIOCBQUEUED</font> to the caller. Remembering
22845 the operation information includes arranging access to the user-space buffer;
22846 once you return, you will not again have the opportunity to access that buffer while
22847 running in the context of the calling process. In general, that means you will likely
22848 have to set up a direct kernel mapping (with <i>get_user_pages</i>) or a DMA mapping.
22849 The <font class="fixd">-EIOCBQUEUED</font> error code indicates that the operation is not yet complete, and its
22850 final status will be posted later.<br>
22851 <br>
22852 When "later" comes, your driver must inform the kernel that the operation has completed.
22853 That is done with a call to <i>aio_complete</i>:<br>
22854 <pre>
22855 int aio_complete(struct kiocb *iocb, long res, long res2);
22856 </pre>
22857 Here, <font class="fixd">iocb</font> is the same IOCB that was initially passed to you, and <font class="fixd">res</font> is the usual
22858 result status for the operation. <font class="fixd">res2</font> is a second result code that will be returned to
22859 user space; most asynchronous I/O implementations pass <font class="fixd">res2</font> as <font class="fixd">0.</font> Once you call
22860 <i>aio_complete</i>, you should not touch the IOCB or user buffer again.<br>
22861 <br>
22862 <a name="AnAsynchronousIOExample"></a><font color="red"><b>An asynchronous I/O example</b></font><br>
22863 <br>
22864 The page-oriented <i>scullp </i>driver in the example source implements asynchronous I/O.
22865 The implementation is simple, but it is enough to show how asynchronous operations
22866 should be structured.<br>
22867 <br>
22868 The <i>aio_read</i> and <i>aio_write</i> methods don't actually do much:<br>
22869 <pre>
22870 static ssize_t scullp_aio_read(struct kiocb *iocb, char *buf, size_t count,
22871 loff_t pos)
22872 {
22873 return scullp_defer_op(0, iocb, buf, count, pos);
22874 }
22876 static ssize_t scullp_aio_write(struct kiocb *iocb, const char *buf,
22877 size_t count, loff_t pos)
22878 {
22879 return scullp_defer_op(1, iocb, (char *) buf, count, pos);
22880 }
22881 </pre>
22882 These methods simply call a common function:<br>
22883 <pre>
22884 struct async_work {
22885 struct kiocb *iocb;
22886 int result;
22887 struct work_struct work;
22888 };
22890 static int scullp_defer_op(int write, struct kiocb *iocb, char *buf,
22891 size_t count, loff_t pos)
22892 {
22893 struct async_work *stuff;
22894 int result;
22895 </pre>
22896 <A name="440"></a><font color="blue">PAGE 440</font><br>
22897 <pre>
22898 /* Copy now while we can access the buffer */
22899 if (write)
22900 result = scullp_write(iocb->ki_filp, buf, count, &pos);
22901 else
22902 result = scullp_read(iocb->ki_filp, buf, count, &pos);
22904 /* If this is a synchronous IOCB, we return our status now. */
22905 if (is_sync_kiocb(iocb))
22906 return result;
22908 /* Otherwise defer the completion for a few milliseconds. */
22909 stuff = kmalloc (sizeof (*stuff), GFP_KERNEL);
22910 if (stuff = = NULL)
22911 return result; /* No memory, just complete now */
22912 stuff->iocb = iocb;
22913 stuff->result = result;
22914 INIT_WORK(&stuff->work, scullp_do_deferred_op, stuff);
22915 schedule_delayed_work(&stuff->work, HZ/100);
22916 return -EIOCBQUEUED;
22917 }
22918 </pre>
22919 A more complete implementation would use <i>get_user_pages </i>to map the user buffer
22920 into kernel space. We chose to keep life simple by just copying over the data at the
22921 outset. Then a call is made to <i>is_sync_kiocb </i>to see if this operation must be completed
22922 synchronously; if so, the result status is returned, and we are done. Otherwise
22923 we remember the relevant information in a little structure, arrange for "completion"
22924 via a workqueue, and return <font class="fixd">-EIOCBQUEUED</font>. At this point, control returns to user
22925 space.<br>
22926 <br>
22927 Later on, the workqueue executes our completion function:<br>
22928 <pre>
22929 static void scullp_do_deferred_op(void *p)
22930 {
22931 struct async_work *stuff = (struct async_work *) p;
22932 aio_complete(stuff->iocb, stuff->result, 0);
22933 kfree(stuff);
22934 }
22935 </pre>
22936 Here, it is simply a matter of calling <i>aio_complete </i>with our saved information. A real
22937 driver's asynchronous I/O implementation is somewhat more complicated, of
22938 course, but it follows this sort of structure.<br>
22939 <br>
22940 <a name="DirectMemoryAccess"></a><font color="red"><b>Direct Memory Access</b></font><br>
22941 <br>
22942 Direct memory access, or DMA, is the advanced topic that completes our overview
22943 of memory issues. DMA is the hardware mechanism that allows peripheral components
22944 to transfer their I/O data directly to and from main memory without the need
22945 to involve the system processor. Use of this mechanism can greatly increase throughput
22946 to and from a device, because a great deal of computational overhead is eliminated.<br>
22947 <br>
22948 <A name="441"></a><font color="blue">PAGE 441</font><br>
22949 <br>
22950 <a name="OverviewOfADMADataTransfer"></a><font color="red"><b>Overview of a DMA Data Transfer</b></font><br>
22951 <br>
22952 Before introducing the programming details, let's review how a DMA transfer takes
22953 place, considering only input transfers to simplify the discussion.<br>
22954 <br>
22955 Data transfer can be triggered in two ways: either the software asks for data (via a
22956 function such as <i>read</i>) or the hardware asynchronously pushes data to the system.<br>
22957 <br>
22958 In the first case, the steps involved can be summarized as follows:<br>
22959 <ol>
22960 <li>When a process calls <i>read</i>, the driver method allocates a DMA buffer and
22961 instructs the hardware to transfer its data into that buffer. The process is put to sleep.
22962 <li>The hardware writes data to the DMA buffer and raises an interrupt when it's done.
22963 <li>The interrupt handler gets the input data, acknowledges the interrupt, and
22964 awakens the process, which is now able to read data.
22965 </ol>
22966 The second case comes about when DMA is used asynchronously. This happens, for
22967 example, with data acquisition devices that go on pushing data even if nobody is
22968 reading them. In this case, the driver should maintain a buffer so that a subsequent
22969 <i>read </i>call will return all the accumulated data to user space. The steps involved in this
22970 kind of transfer are slightly different:<br>
22971 <ol>
22972 <li>The hardware raises an interrupt to announce that new data has arrived.
22973 <li>The interrupt handler allocates a buffer and tells the hardware where to transfer its data.
22974 <li>The peripheral device writes the data to the buffer and raises another interrupt when it's done.
22975 <li>The handler dispatches the new data, wakes any relevant process, and takes care of housekeeping.
22976 </ol>
22977 A variant of the asynchronous approach is often seen with network cards. These
22978 cards often expect to see a circular buffer (often called a <i>DMA ring buffer</i>) established
22979 in memory shared with the processor; each incoming packet is placed in the
22980 next available buffer in the ring, and an interrupt is signaled. The driver then passes
22981 the network packets to the rest of the kernel and places a new DMA buffer in the
22982 ring.<br>
22983 <br>
22984 The processing steps in all of these cases emphasize that efficient DMA handling
22985 relies on interrupt reporting. While it is possible to implement DMA with a polling
22986 driver, it wouldn't make sense, because a polling driver would waste the performance
22987 benefits that DMA offers over the easier processor-driven I/O.*<br>
22988 <br>
22989 * There are, of course, exceptions to everything; see the section "Receive Interrupt Mitigation" in
22990 Chapter 17 for a demonstration of how high-performance network drivers are best implemented using polling.<br>
22991 <br>
22992 <A name="442"></a><font color="blue">PAGE 442</font><br>
22993 <br>
22994 Another relevant item introduced here is the DMA buffer. DMA requires device drivers
22995 to allocate one or more special buffers suited to DMA. Note that many drivers
22996 allocate their buffers at initialization time and use them until shutdown--the word
22997 <i>allocate </i>in the previous lists, therefore, means "get hold of a previously allocated
22998 buffer."<br>
22999 <br>
23000 <a name="AllocatingTheDMABuffer"></a><font color="red"><b>Allocating the DMA Buffer</b></font><br>
23001 <br>
23002 This section covers the allocation of DMA buffers at a low level; we introduce a
23003 higher-level interface shortly, but it is still a good idea to understand the material
23004 presented here.<br>
23005 <br>
23006 The main issue that arrises with DMA buffers is that, when they are bigger than one
23007 page, they must occupy contiguous pages in physical memory because the device
23008 transfers data using the ISA or PCI system bus, both of which carry physical
23009 addresses. It's interesting to note that this constraint doesn't apply to the SBus (see
23010 the section "SBus" in Chapter 12), which uses virtual addresses on the peripheral
23011 bus. Some architectures <i>can </i>also use virtual addresses on the PCI bus, but a portable
23012 driver cannot count on that capability.<br>
23013 <br>
23014 Although DMA buffers can be allocated either at system boot or at runtime, modules
23015 can allocate their buffers only at runtime. (Chapter 8 introduced these techniques;
23016 the section "Obtaining Large Buffers" covered allocation at system boot,
23017 while "The Real Story of kmalloc" and "get_free_page and Friends" described allocation
23018 at runtime.) Driver writers must take care to allocate the right kind of memory
23019 when it is used for DMA operations; not all memory zones are suitable. In particular,
23020 high memory may not work for DMA on some systems and with some devices-the
23021 peripherals simply cannot work with addresses that high.<br>
23022 <br>
23023 Most devices on modern buses can handle 32-bit addresses, meaning that normal
23024 memory allocations work just fine for them. Some PCI devices, however, fail to
23025 implement the full PCI standard and cannot work with 32-bit addresses. And ISA
23026 devices, of course, are limited to 24-bit addresses only.<br>
23027 <br>
23028 For devices with this kind of limitation, memory should be allocated from the DMA
23029 zone by adding the <font class="fixd">GFP_DMA</font> flag to the <i>kmalloc </i>or <i>get_free_pages </i>call. When this flag
23030 is present, only memory that can be addressed with 24 bits is allocated. Alternatively,
23031 you can use the generic DMA layer (which we discuss shortly) to allocate buffers
23032 that work around your device's limitations.<br>
23033 <br>
23034 <a name="DoityourselfAllocation"></a><font color="red"><b>Do-it-yourself allocation</b></font><br>
23035 <br>
23036 We have seen how <i>get_free_pages </i>can allocate up to a few megabytes (as order can
23037 range up to <font class="fixd">MAX_ORDER,</font> currently 11), but high-order requests are prone to fail even<br>
23038 <br>
23039 <A name="443"></a><font color="blue">PAGE 443</font><br>
23040 <br>
23041 when the requested buffer is far less than 128 KB, because system memory becomes
23042 fragmented over time.*<br>
23043 <br>
23044 When the kernel cannot return the requested amount of memory or when you need
23045 more than 128 KB (a common requirement for PCI frame grabbers, for example), an
23046 alternative to returning <font class="fixd">-ENOMEM</font> is to allocate memory at boot time or reserve the top
23047 of physical RAM for your buffer. We described allocation at boot time in the section
23048 "Obtaining Large Buffers" in Chapter 8, but it is not available to modules. Reserving
23049 the top of RAM is accomplished by passing a <font class="fixd">mem=</font> argument to the kernel at boot
23050 time. For example, if you have 256 MB, the argument <font class="fixd">mem=255M</font> keeps the kernel from
23051 using the top megabyte. Your module could later use the following code to gain
23052 access to such memory:<br>
23053 <pre>
23054 dmabuf = ioremap (0xFF00000 /* 255M */, 0x100000 /* 1M */);
23055 </pre>
23056 The <i>allocator</i>, part of the sample code accompanying the book, offers a simple API to
23057 probe and manage such reserved RAM and has been used successfully on several
23058 architectures. However, this trick doesn't work when you have an high-memory system
23059 (i.e., one with more physical memory than could fit in the CPU address space).<br>
23060 <br>
23061 Another option, of course, is to allocate your buffer with the <font class="fixd">GFP_NOFAIL</font> allocation
23062 flag. This approach does, however, severely stress the memory management subsystem,
23063 and it runs the risk of locking up the system altogether; it is best avoided
23064 unless there is truly no other way.<br>
23065 <br>
23066 If you are going to such lengths to allocate a large DMA buffer, however, it is worth
23067 putting some thought into alternatives. If your device can do scatter/gather I/O, you
23068 can allocate your buffer in smaller pieces and let the device do the rest. Scatter/gather
23069 I/O can also be used when performing direct I/O into user space, which may well be
23070 the best solution when a truly huge buffer is required.<br>
23071 <br>
23072 <a name="BusAddresses"></a><font color="red"><b>Bus Addresses</b></font><br>
23073 <br>
23074 A device driver using DMA has to talk to hardware connected to the interface bus,
23075 which uses physical addresses, whereas program code uses virtual addresses.<br>
23076 <br>
23077 As a matter of fact, the situation is slightly more complicated than that. DMA-based
23078 hardware uses <i>bus</i>, rather than <i>physical</i>, addresses. Although ISA and PCI bus
23079 addresses are simply physical addresses on the PC, this is not true for every platform.
23080 Sometimes the interface bus is connected through bridge circuitry that maps I/O
23081 addresses to different physical addresses. Some systems even have a page-mapping
23082 scheme that can make arbitrary pages appear contiguous to the peripheral bus.<br>
23083 <br>
23084 * The word <i>fragmentation </i>is usually applied to disks to express the idea that files are not
23085 stored consecutively on the magnetic medium. The same concept applies to memory, where each virtual
23086 address space gets scattered throughout physical RAM, and it becomes difficult to retrieve
23087 consecutive free pages when a DMA buffer is requested.<br>
23088 <br>
23089 <A name="444"></a><font color="blue">PAGE 444</font><br>
23090 <br>
23091 At the lowest level (again, we'll look at a higher-level solution shortly), the Linux kernel
23092 provides a portable solution by exporting the following functions, defined in
23093 <i><asm/io.h></i>. The use of these functions is strongly discouraged, because they work
23094 properly only on systems with a very simple I/O architecture; nonetheless, you may
23095 encounter them when working with kernel code.<br>
23096 <pre>
23097 unsigned long virt_to_bus(volatile void *address);
23098 void *bus_to_virt(unsigned long address);
23099 </pre>
23100 These functions perform a simple conversion between kernel logical addresses and
23101 bus addresses. They do not work in any situation where an I/O memory management
23102 unit must be programmed or where bounce buffers must be used. The right
23103 way of performing this conversion is with the generic DMA layer, so we now move
23104 on to that topic.<br>
23105 <br>
23106 <a name="TheGenericDMALayer"></a><font color="red"><b>The Generic DMA Layer</b></font><br>
23107 <br>
23108 DMA operations, in the end, come down to allocating a buffer and passing bus
23109 addresses to your device. However, the task of writing portable drivers that perform
23110 DMA safely and correctly on all architectures is harder than one might think. Different
23111 systems have different ideas of how cache coherency should work; if you do not
23112 handle this issue correctly, your driver may corrupt memory. Some systems have
23113 complicated bus hardware that can make the DMA task easier--or harder. And not
23114 all systems can perform DMA out of all parts of memory. Fortunately, the kernel
23115 provides a bus- and architecture-independent DMA layer that hides most of these
23116 issues from the driver author. We strongly encourage you to use this layer for DMA
23117 operations in any driver you write.<br>
23118 <br>
23119 Many of the functions below require a pointer to a <font class="fixd">struct device</font>. This structure is
23120 the low-level representation of a device within the Linux device model. It is not
23121 something that drivers often have to work with directly, but you do need it when
23122 using the generic DMA layer. Usually, you can find this structure buried inside the
23123 bus specific that describes your device. For example, it can be found as the <font class="fixd">dev</font> field
23124 in <font class="fixd">struct pci_device</font> or <font class="fixd">struct usb_device</font>. The device structure is covered in detail
23125 in Chapter 14.<br>
23126 <br>
23127 Drivers that use the following functions should include <i><linux/dma-mapping.h></i>.<br>
23128 <br>
23129 <a name="DealingWithDifficultHardware"></a><font color="red"><b>Dealing with difficult hardware</b></font><br>
23130 <br>
23131 The first question that must be answered before attempting DMA is whether the
23132 given device is capable of such an operation on the current host. Many devices are
23133 limited in the range of memory they can address, for a number of reasons. By default,
23134 the kernel assumes that your device can perform DMA to any 32-bit address. If this is
23135 not the case, you should inform the kernel of that fact with a call to:<br>
23136 <pre>
23137 int dma_set_mask(struct device *dev, u64 mask);
23138 </pre>
23139 <A name="445"></a><font color="blue">PAGE 445</font><br>
23140 <br>
23141 The <font class="fixd">mask</font> should show the bits that your device can address; if it is limited to 24 bits,
23142 for example, you would pass <font class="fixd">mask</font> as <font class="fixd">0x0FFFFFF.</font> The return value is nonzero if DMA
23143 is possible with the given <font class="fixd">mask;</font> if <i>dma_set_mask </i>returns 0, you are not able to use
23144 DMA operations with this device. Thus, the initialization code in a driver for a device
23145 limited to 24-bit DMA operations might look like:<br>
23146 <pre>
23147 if (dma_set_mask (dev, 0xffffff))
23148 card->use_dma = 1;
23149 else {
23150 card->use_dma = 0; /* We'll have to live without DMA */
23151 printk (KERN_WARN, "mydev: DMA not supported\n");
23152 }
23153 </pre>
23154 Again, if your device supports normal, 32-bit DMA operations, there is no need to
23155 call <i>dma_set_mask</i>.<br>
23156 <br>
23157 <a name="DMAMappings"></a><font color="red"><b>DMA mappings</b></font><br>
23158 <br>
23159 A <i>DMA mapping </i>is a combination of allocating a DMA buffer and generating an
23160 address for that buffer that is accessible by the device. It is tempting to get that
23161 address with a simple call to <i>virt_to_bus</i>, but there are strong reasons for avoiding
23162 that approach. The first of those is that reasonable hardware comes with an IOMMU
23163 that provides a set of <i>mapping registers </i>for the bus. The IOMMU can arrange for any
23164 physical memory to appear within the address range accessible by the device, and it
23165 can cause physically scattered buffers to look contiguous to the device. Making use
23166 of the IOMMU requires using the generic DMA layer; <i>virt_to_bus </i>is not up to the
23167 task.<br>
23168 <br>
23169 Note that not all architectures have an IOMMU; in particular, the popular x86 platform
23170 has no IOMMU support. A properly written driver need not be aware of the I/O
23171 support hardware it is running over, however.<br>
23172 <br>
23173 Setting up a useful address for the device may also, in some cases, require the establishment
23174 of a <i>bounce buffer</i>. Bounce buffers are created when a driver attempts to
23175 perform DMA on an address that is not reachable by the peripheral device--a high memory
23176 address, for example. Data is then copied to and from the bounce buffer as
23177 needed. Needless to say, use of bounce buffers can slow things down, but sometimes
23178 there is no alternative.<br>
23179 <br>
23180 DMA mappings must also address the issue of cache coherency. Remember that modern
23181 processors keep copies of recently accessed memory areas in a fast, local cache;
23182 without this cache, reasonable performance is not possible. If your device changes an
23183 area of main memory, it is imperative that any processor caches covering that area be
23184 invalidated; otherwise the processor may work with an incorrect image of main memory,
23185 and data corruption results. Similarly, when your device uses DMA to read data
23186 from main memory, any changes to that memory residing in processor caches must be
23187 flushed out first. These <i>cache coherency </i>issues can create no end of obscure and difficult-to-find
23188 bugs if the programmer is not careful. Some architectures manage cache<br>
23189 <br>
23190 <A name="446"></a><font color="blue">PAGE 446</font><br>
23191 <br>
23192 coherency in the hardware, but others require software support. The generic DMA
23193 layer goes to great lengths to ensure that things work correctly on all architectures,
23194 but, as we will see, proper behavior requires adherence to a small set of rules.<br>
23195 <br>
23196 The DMA mapping sets up a new type, <font class="fixd">dma_addr_t,</font> to represent bus addresses. Variables
23197 of type <font class="fixd">dma_addr_t</font> should be treated as opaque by the driver; the only allowable
23198 operations are to pass them to the DMA support routines and to the device
23199 itself. As a bus address, <font class="fixd">dma_addr_t</font> may lead to unexpected problems if used directly
23200 by the CPU.<br>
23201 <br>
23202 The PCI code distinguishes between two types of DMA mappings, depending on
23203 how long the DMA buffer is expected to stay around:<br>
23204 <br>
23205 <i>Coherent DMA mappings</i><br>
23206 <div class="bq">
23207 These mappings usually exist for the life of the driver. A coherent buffer must be
23208 simultaneously available to both the CPU and the peripheral (other types of
23209 mappings, as we will see later, can be available only to one or the other at any
23210 given time). As a result, coherent mappings must live in cache-coherent memory.
23211 Coherent mappings can be expensive to set up and use.</div>
23212 <br>
23213 <i>Streaming DMA mappings</i><br>
23214 <div class="bq">
23215 Streaming mappings are usually set up for a single operation. Some architectures
23216 allow for significant optimizations when streaming mappings are used, as
23217 we see, but these mappings also are subject to a stricter set of rules in how they
23218 may be accessed. The kernel developers recommend the use of streaming mappings
23219 over coherent mappings whenever possible. There are two reasons for this
23220 recommendation. The first is that, on systems that support mapping registers,
23221 each DMA mapping uses one or more of them on the bus. Coherent mappings,
23222 which have a long lifetime, can monopolize these registers for a long time, even
23223 when they are not being used. The other reason is that, on some hardware,
23224 streaming mappings can be optimized in ways that are not available to coherent
23225 mappings.</div>
23226 <br>
23227 The two mapping types must be manipulated in different ways; it's time to look at
23228 the details.<br>
23229 <br>
23230 <a name="SettingUpCoherentDMAMappings"></a><font color="red"><b>Setting up coherent DMA mappings</b></font><br>
23231 <br>
23232 A driver can set up a coherent mapping with a call to <i>dma_alloc_coherent</i>:<br>
23233 <pre>
23234 void *dma_alloc_coherent(struct device *dev, size_t size,
23235 dma_addr_t *dma_handle, int flag);
23236 </pre>
23237 This function handles both the allocation and the mapping of the buffer. The first two
23238 arguments are the device structure and the size of the buffer needed. The function
23239 returns the result of the DMA mapping in two places. The return value from the function
23240 is a kernel virtual address for the buffer, which may be used by the driver; the
23241 associated bus address, meanwhile, is returned in <font class="fixd">dma_handle</font>. Allocation is handled in<br>
23242 <br>
23243 <A name="447"></a><font color="blue">PAGE 447</font><br>
23244 <br>
23245 this function so that the buffer is placed in a location that works with DMA; usually
23246 the memory is just allocated with <i>get_free_pages </i>(but note that the size is in bytes,
23247 rather than an order value). The <font class="fixd">flag</font> argument is the usual <font class="fixd">GFP_</font> value describing how
23248 the memory is to be allocated; it should usually be <font class="fixd">GFP_KERNEL</font> (usually) or <font class="fixd">GFP_ATOMIC</font>
23249 (when running in atomic context).<br>
23250 <br>
23251 When the buffer is no longer needed (usually at module unload time), it should be
23252 returned to the system with <i>dma_free_coherent</i>:<br>
23253 <pre>
23254 void dma_free_coherent(struct device *dev, size_t size,
23255 void *vaddr, dma_addr_t dma_handle);
23256 </pre>
23257 Note that this function, like many of the generic DMA functions, requires that all of
23258 the size, CPU address, and bus address arguments be provided.<br>
23259 <br>
23260 <a name="DMAPools"></a><font color="red"><b>DMA pools</b></font><br>
23261 <br>
23262 A <i>DMA pool </i>is an allocation mechanism for small, coherent DMA mappings. Mappings
23263 obtained from <i>dma_alloc_coherent </i>may have a minimum size of one page. If
23264 your device needs smaller DMA areas than that, you should probably be using a
23265 DMA pool. DMA pools are also useful in situations where you may be tempted to
23266 perform DMA to small areas embedded within a larger structure. Some very obscure
23267 driver bugs have been traced down to cache coherency problems with structure fields
23268 adjacent to small DMA areas. To avoid this problem, you should always allocate
23269 areas for DMA operations explicitly, away from other, non-DMA data structures.<br>
23270 <br>
23271 The DMA pool functions are defined in <i><linux/dmapool.h></i>.<br>
23272 <br>
23273 A DMA pool must be created before use with a call to:<br>
23274 <pre>
23275 struct dma_pool *dma_pool_create(const char *name, struct device *dev,
23276 size_t size, size_t align,
23277 size_t allocation);
23278 </pre>
23279 Here, <font class="fixd">name</font> is a name for the pool, <font class="fixd">dev</font> is your device structure, <font class="fixd">size</font> is the size of the
23280 buffers to be allocated from this pool, <font class="fixd">align</font> is the required hardware alignment for
23281 allocations from the pool (expressed in bytes), and <font class="fixd">allocation</font> is, if nonzero, a memory
23282 boundary that allocations should not exceed. If <font class="fixd">allocation</font> is passed as 4096, for
23283 example, the buffers allocated from this pool do not cross 4-KB boundaries.<br>
23284 <br>
23285 When you are done with a pool, it can be freed with:<br>
23286 <pre>
23287 void dma_pool_destroy(struct dma_pool *pool);
23288 </pre>
23289 You should return all allocations to the pool before destroying it.<br>
23290 <br>
23291 Allocations are handled with <i>dma_pool_alloc</i>:<br>
23292 <pre>
23293 void *dma_pool_alloc(struct dma_pool *pool, int mem_flags,
23294 dma_addr_t *handle);
23295 </pre>
23296 For this call, <font class="fixd">mem_flags</font> is the usual set of <font class="fixd">GFP_</font> allocation flags. If all goes well, a
23297 region of memory (of the size specified when the pool was created) is allocated and<br>
23298 <br>
23299 <A name="448"></a><font color="blue">PAGE 448</font><br>
23300 <br>
23301 returned. As with <i>dma_alloc_coherent</i>, the address of the resulting DMA buffer is
23302 returned as a kernel virtual address and stored in <font class="fixd">handle</font> as a bus address.<br>
23303 <br>
23304 Unneeded buffers should be returned to the pool with:<br>
23305 <pre>
23306 void dma_pool_free(struct dma_pool *pool, void *vaddr, dma_addr_t addr);
23307 </pre>
23308 <a name="SettingUpStreamingDMAMappings"></a><font color="red"><b>Setting up streaming DMA mappings</b></font><br>
23309 <br>
23310 Streaming mappings have a more complicated interface than the coherent variety, for
23311 a number of reasons. These mappings expect to work with a buffer that has already
23312 been allocated by the driver and, therefore, have to deal with addresses that they did
23313 not choose. On some architectures, streaming mappings can also have multiple, discontiguous
23314 pages and multipart "scatter/gather" buffers. For all of these reasons,
23315 streaming mappings have their own set of mapping functions.<br>
23316 <br>
23317 When setting up a streaming mapping, you must tell the kernel in which direction
23318 the data is moving. Some symbols (of type <font class="fixd">enum dma_data_direction</font>) have been
23319 defined for this purpose:<br>
23320 <br>
23321 <font class="fixd">DMA_TO_DEVICE<br>
23322 DMA_FROM_DEVICE</font><br>
23323 <div class="bq">
23324 These two symbols should be reasonably self-explanatory. If data is being sent to
23325 the device (in response, perhaps, to a <i>write </i>system call), <font class="fixd">DMA_TO_DEVICE</font> should be
23326 used; data going to the CPU, instead, is marked with <font class="fixd">DMA_FROM_DEVICE</font>.</div>
23327 <br>
23328 <font class="fixd">DMA_BIDIRECTIONAL</font><br>
23329 <div class="bq">
23330 If data can move in either direction, use <font class="fixd">DMA_BIDIRECTIONAL</font>.</div>
23331 <br>
23332 <font class="fixd">DMA_NONE</font><br>
23333 <div class="bq">
23334 This symbol is provided only as a debugging aid. Attempts to use buffers with
23335 this "direction" cause a kernel panic.</div>
23336 <br>
23337 It may be tempting to just pick <font class="fixd">DMA_BIDIRECTIONAL</font> at all times, but driver authors
23338 should resist that temptation. On some architectures, there is a performance penalty
23339 to pay for that choice.<br>
23340 <br>
23341 When you have a single buffer to transfer, map it with <i>dma_map_single</i>:<br>
23342 <pre>
23343 dma_addr_t dma_map_single(struct device *dev, void *buffer, size_t size,
23344 enum dma_data_direction direction);
23345 </pre>
23346 The return value is the bus address that you can pass to the device or <font class="fixd">NULL</font> if something
23347 goes wrong.<br>
23348 <br>
23349 Once the transfer is complete, the mapping should be deleted with <i>dma_unmap_single</i>:<br>
23350 <pre>
23351 void dma_unmap_single(struct device *dev, dma_addr_t dma_addr, size_t size,
23352 enum dma_data_direction direction);
23353 </pre>
23354 Here, the <font class="fixd">size</font> and <font class="fixd">direction</font> arguments must match those used to map the buffer.<br>
23355 <br>
23356 <A name="449"></a><font color="blue">PAGE 449</font><br>
23357 <br>
23358 Some important rules apply to streaming DMA mappings:<br>
23359 <ul>
23360 <li> The buffer must be used only for a transfer that matches the direction value given when it was mapped.
23361 <li> Once a buffer has been mapped, it belongs to the device, not the processor. Until
23362 the buffer has been unmapped, the driver should not touch its contents in any
23363 way. Only after <i>dma_unmap_single </i>has been called is it safe for the driver to
23364 access the contents of the buffer (with one exception that we see shortly).
23365 Among other things, this rule implies that a buffer being written to a device cannot
23366 be mapped until it contains all the data to write.
23367 <li> The buffer must not be unmapped while DMA is still active, or serious system instability is guaranteed.
23368 </ul>
23369 You may be wondering why the driver can no longer work with a buffer once it has
23370 been mapped. There are actually two reasons why this rule makes sense. First, when
23371 a buffer is mapped for DMA, the kernel must ensure that all of the data in that buffer
23372 has actually been written to memory. It is likely that some data is in the processor's
23373 cache when <i>dma_unmap_single </i>is issued, and must be explicitly flushed. Data written
23374 to the buffer by the processor after the flush may not be visible to the device.<br>
23375 <br>
23376 Second, consider what happens if the buffer to be mapped is in a region of memory
23377 that is not accessible to the device. Some architectures simply fail in this case, but
23378 others create a bounce buffer. The bounce buffer is just a separate region of memory
23379 that <i>is </i>accessible to the device. If a buffer is mapped with a direction of <font class="fixd">DMA_TO_DEVICE,</font>
23380 and a bounce buffer is required, the contents of the original buffer are copied
23381 as part of the mapping operation. Clearly, changes to the original buffer after the
23382 copy are not seen by the device. Similarly, <font class="fixd">DMA_FROM_DEVICE</font> bounce buffers are copied
23383 back to the original buffer by <i>dma_unmap_single</i>; the data from the device is not
23384 present until that copy has been done.<br>
23385 <br>
23386 Incidentally, bounce buffers are one reason why it is important to get the direction
23387 right. <font class="fixd">DMA_BIDIRECTIONAL</font> bounce buffers are copied both before and after the operation,
23388 which is often an unnecessary waste of CPU cycles.<br>
23389 <br>
23390 Occasionally a driver needs to access the contents of a streaming DMA buffer without
23391 unmapping it. A call has been provided to make this possible:<br>
23392 <pre>
23393 void dma_sync_single_for_cpu(struct device *dev, dma_handle_t bus_addr,
23394 size_t size, enum dma_data_direction direction);
23395 </pre>
23396 This function should be called before the processor accesses a streaming DMA
23397 buffer. Once the call has been made, the CPU "owns" the DMA buffer and can work
23398 with it as needed. Before the device accesses the buffer, however, ownership should
23399 be transferred back to it with:<br>
23400 <pre>
23401 void dma_sync_single_for_device(struct device *dev, dma_handle_t bus_addr,
23402 size_t size, enum dma_data_direction direction);
23403 </pre>
23404 <A name="450"></a><font color="blue">PAGE 450</font><br>
23405 <br>
23406 The processor, once again, should not access the DMA buffer after this call has been
23407 made.<br>
23408 <br>
23409 <a name="SinglepageStreamingMappings"></a><font color="red"><b>Single-page streaming mappings</b></font><br>
23410 <br>
23411 Occasionally, you may want to set up a mapping on a buffer for which you have a
23412 <font class="fixd">struct page</font> pointer; this can happen, for example, with user-space buffers mapped
23413 with <i>get_user_pages</i>. To set up and tear down streaming mappings using <font class="fixd">struct page</font>
23414 pointers, use the following:<br>
23415 <pre>
23416 dma_addr_t dma_map_page(struct device *dev, struct page *page,
23417 unsigned long offset, size_t size,
23418 enum dma_data_direction direction);
23420 void dma_unmap_page(struct device *dev, dma_addr_t dma_address,
23421 size_t size, enum dma_data_direction direction);
23422 </pre>
23423 The <font class="fixd">offset</font> and <font class="fixd">size</font> arguments can be used to map part of a page. It is recommended,
23424 however, that partial-page mappings be avoided unless you are really sure
23425 of what you are doing. Mapping part of a page can lead to cache coherency problems
23426 if the allocation covers only part of a cache line; that, in turn, can lead to memory
23427 corruption and extremely difficult-to-debug bugs.<br>
23428 <br>
23429 <a name="ScattergatherMappings"></a><font color="red"><b>Scatter/gather mappings</b></font><br>
23430 <br>
23431 Scatter/gather mappings are a special type of streaming DMA mapping. Suppose you
23432 have several buffers, all of which need to be transferred to or from the device. This
23433 situation can come about in several ways, including from a <i>readv </i>or <i>writev </i>system
23434 call, a clustered disk I/O request, or a list of pages in a mapped kernel I/O buffer.
23435 You could simply map each buffer, in turn, and perform the required operation, but
23436 there are advantages to mapping the whole list at once.<br>
23437 <br>
23438 Many devices can accept a <i>scatterlist </i>of array pointers and lengths, and transfer them
23439 all in one DMA operation; for example, "zero-copy" networking is easier if packets
23440 can be built in multiple pieces. Another reason to map scatterlists as a whole is to
23441 take advantage of systems that have mapping registers in the bus hardware. On such
23442 systems, physically discontiguous pages can be assembled into a single, contiguous
23443 array from the device's point of view. This technique works only when the entries in
23444 the scatterlist are equal to the page size in length (except the first and last), but when
23445 it does work, it can turn multiple operations into a single DMA, and speed things up
23446 accordingly.<br>
23447 <br>
23448 Finally, if a bounce buffer must be used, it makes sense to coalesce the entire list into
23449 a single buffer (since it is being copied anyway).<br>
23450 <br>
23451 So now you're convinced that mapping of scatterlists is worthwhile in some situations.
23452 The first step in mapping a scatterlist is to create and fill in an array of <font class="fixd">struct scatterlist</font>
23453 describing the buffers to be transferred. This structure is architecture<br>
23454 <br>
23455 <A name="451"></a><font color="blue">PAGE 451</font><br>
23456 <br>
23457 dependent, and is described in <i><asm/scatterlist.h></i>. However, it always contains three
23458 fields:<br>
23459 <br>
23460 <font class="fixd">struct page *page;</font><br>
23461 <div class="bq">
23462 The <font class="fixd">struct page</font> pointer corresponding to the buffer to be used in the scatter/gather
23463 operation.</div>
23464 <br>
23465 <font class="fixd">unsigned int length;<br>
23466 unsigned int offset;</font><br>
23467 <div class="bq">
23468 The length of that buffer and its offset within the page</div>
23469 <br>
23470 To map a scatter/gather DMA operation, your driver should set the <font class="fixd">page, offset,</font> and
23471 <font class="fixd">length</font> fields in a <font class="fixd">struct scatterlist</font> entry for each buffer to be transferred. Then
23472 call:<br>
23473 <pre>
23474 int dma_map_sg(struct device *dev, struct scatterlist *sg, int nents,
23475 enum dma_data_direction direction)
23476 </pre>
23477 where <font class="fixd">nents</font> is the number of scatterlist entries passed in. The return value is the
23478 number of DMA buffers to transfer; it may be less than <font class="fixd">nents.</font><br>
23479 <br>
23480 For each buffer in the input scatterlist, <i>dma_map_sg </i>determines the proper bus
23481 address to give to the device. As part of that task, it also coalesces buffers that are
23482 adjacent to each other in memory. If the system your driver is running on has an I/O
23483 memory management unit, <i>dma_map_sg </i>also programs that unit's mapping registers,
23484 with the possible result that, from your device's point of view, you are able to
23485 transfer a single, contiguous buffer. You will never know what the resulting transfer
23486 will look like, however, until after the call.<br>
23487 <br>
23488 Your driver should transfer each buffer returned by <i>pci_map_sg</i>. The bus address and
23489 length of each buffer are stored in the <font class="fixd">struct scatterlist</font> entries, but their location
23490 in the structure varies from one architecture to the next. Two macros have been
23491 defined to make it possible to write portable code:<br>
23492 <br>
23493 <font class="fixd">dma_addr_t sg_dma_address(struct scatterlist *sg);</font><br>
23494 <div class="bq">
23495 Returns the bus (DMA) address from this scatterlist entry.</div>
23496 <br>
23497 <font class="fixd">unsigned int sg_dma_len(struct scatterlist *sg);</font><br>
23498 <div class="bq">
23499 Returns the length of this buffer.</div>
23500 <br>
23501 Again, remember that the address and length of the buffers to transfer may be different
23502 from what was passed in to <i>dma_map_sg</i>.<br>
23503 <br>
23504 Once the transfer is complete, a scatter/gather mapping is unmapped with a call to
23505 <i>dma_unmap_sg</i>:<br>
23506 <pre>
23507 void dma_unmap_sg(struct device *dev, struct scatterlist *list,
23508 int nents, enum dma_data_direction direction);
23509 </pre>
23510 Note that <font class="fixd">nents</font> must be the number of entries that you originally passed to <i>dma_map_sg
23511 </i>and not the number of DMA buffers the function returned to you.<br>
23512 <br>
23513 <A name="452"></a><font color="blue">PAGE 452</font><br>
23514 <br>
23515 Scatter/gather mappings are streaming DMA mappings, and the same access rules
23516 apply to them as to the single variety. If you must access a mapped scatter/gather list,
23517 you must synchronize it first:<br>
23518 <pre>
23519 void dma_sync_sg_for_cpu(struct device *dev, struct scatterlist *sg,
23520 int nents, enum dma_data_direction direction);
23521 void dma_sync_sg_for_device(struct device *dev, struct scatterlist *sg,
23522 int nents, enum dma_data_direction direction);
23523 </pre>
23524 <a name="PCIDoubleaddressCycleMappings"></a><font color="red"><b>PCI double-address cycle mappings</b></font><br>
23525 <br>
23526 Normally, the DMA support layer works with 32-bit bus addresses, possibly
23527 restricted by a specific device's DMA mask. The PCI bus, however, also supports a
23528 64-bit addressing mode, the <i>double-address cycle </i>(DAC). The generic DMA layer
23529 does not support this mode for a couple of reasons, the first of which being that it is
23530 a PCI-specific feature. Also, many implementations of DAC are buggy at best, and,
23531 because DAC is slower than a regular, 32-bit DMA, there can be a performance cost.
23532 Even so, there are applications where using DAC can be the right thing to do; if you
23533 have a device that is likely to be working with very large buffers placed in high memory,
23534 you may want to consider implementing DAC support. This support is available
23535 only for the PCI bus, so PCI-specific routines must be used.<br>
23536 <br>
23537 To use DAC, your driver must include <i><linux/pci.h></i>. You must set a separate DMA
23538 mask:<br>
23539 <pre>
23540 int pci_dac_set_dma_mask(struct pci_dev *pdev, u64 mask);
23541 </pre>
23542 You can use DAC addressing only if this call returns 0.<br>
23543 <br>
23544 A special type (dma64_addr_t) is used for DAC mappings. To establish one of these
23545 mappings, call <i>pci_dac_page_to_dma</i>:<br>
23546 <pre>
23547 dma64_addr_t pci_dac_page_to_dma(struct pci_dev *pdev, struct page *page,
23548 unsigned long offset, int direction);
23549 </pre>
23550 DAC mappings, you will notice, can be made only from <font class="fixd">struct page</font> pointers (they
23551 should live in high memory, after all, or there is no point in using them); they
23552 must be created a single page at a time. The <font class="fixd">direction</font> argument is the PCI equivalent
23553 of the <font class="fixd">enum dma_data_direction</font> used in the generic DMA layer; it should be
23554 <font class="fixd">PCI_DMA_TODEVICE, PCI_DMA_FROMDEVICE,</font> or <font class="fixd">PCI_DMA_BIDIRECTIONAL</font>.<br>
23555 <br>
23556 DAC mappings require no external resources, so there is no need to explicitly release
23557 them after use. It is necessary, however, to treat DAC mappings like other streaming
23558 mappings, and observe the rules regarding buffer ownership. There is a set of functions
23559 for synchronizing DMA buffers that is analogous to the generic variety:<br>
23560 <pre>
23561 void pci_dac_dma_sync_single_for_cpu(struct pci_dev *pdev,
23562 dma64_addr_t dma_addr,
23563 size_t len,
23564 int direction);
23565 </pre>
23566 <A name="453"></a><font color="blue">PAGE 453</font><br>
23567 <pre>
23568 void pci_dac_dma_sync_single_for_device(struct pci_dev *pdev,
23569 dma64_addr_t dma_addr,
23570 size_t len,
23571 int direction);
23572 </pre>
23573 <a name="ASimplePCIDMAExample"></a><font color="red"><b>A simple PCI DMA example</b></font><br>
23574 <br>
23575 As an example of how the DMA mappings might be used, we present a simple example
23576 of DMA coding for a PCI device. The actual form of DMA operations on the PCI
23577 bus is very dependent on the device being driven. Thus, this example does not apply
23578 to any real device; instead, it is part of a hypothetical driver called <i>dad </i>(DMA Acquisition
23579 Device). A driver for this device might define a transfer function like this:<br>
23580 <pre>
23581 int dad_transfer(struct dad_dev *dev, int write, void *buffer,
23582 size_t count)
23583 {
23584 dma_addr_t bus_addr;
23586 /* Map the buffer for DMA */
23587 dev->dma_dir = (write ? DMA_TO_DEVICE : DMA_FROM_DEVICE);
23588 dev->dma_size = count;
23589 bus_addr = dma_map_single(&dev->pci_dev->dev, buffer, count,
23590 dev->dma_dir);
23591 dev->dma_addr = bus_addr;
23593 /* Set up the device */
23595 writeb(dev->registers.command, DAD_CMD_DISABLEDMA);
23596 writeb(dev->registers.command, write ? <font class="fixd">DAD_CMD_WR</font> : DAD_CMD_RD);
23597 writel(dev->registers.addr, cpu_to_le32(bus_addr));
23598 writel(dev->registers.len, cpu_to_le32(count));
23600 /* Start the operation */
23601 writeb(dev->registers.command, DAD_CMD_ENABLEDMA);
23602 return 0;
23603 }
23604 </pre>
23605 This function maps the buffer to be transferred and starts the device operation. The
23606 other half of the job must be done in the interrupt service routine, which looks something
23607 like this:<br>
23608 <pre>
23609 void dad_interrupt(int irq, void *dev_id, struct pt_regs *regs)
23610 {
23611 struct dad_dev *dev = (struct dad_dev *) dev_id;
23613 /* Make sure it's really our device interrupting */
23615 /* Unmap the DMA buffer */
23616 dma_unmap_single(dev->pci_dev->dev, dev->dma_addr,
23617 dev->dma_size, dev->dma_dir);
23619 /* Only now is it safe to access the buffer, copy to user, etc. */
23620 ...
23621 }
23622 </pre>
23623 <A name="454"></a><font color="blue">PAGE 454</font><br>
23624 <br>
23625 Obviously, a great deal of detail has been left out of this example, including whatever
23626 steps may be required to prevent attempts to start multiple, simultaneous DMA
23627 operations.<br>
23628 <br>
23629 <a name="DMAForISADevices"></a><font color="red"><b>DMA for ISA Devices</b></font><br>
23630 <br>
23631 The ISA bus allows for two kinds of DMA transfers: native DMA and ISA bus master
23632 DMA. Native DMA uses standard DMA-controller circuitry on the motherboard
23633 to drive the signal lines on the ISA bus. ISA bus master DMA, on the other hand, is
23634 handled entirely by the peripheral device. The latter type of DMA is rarely used and
23635 doesn't require discussion here, because it is similar to DMA for PCI devices, at least
23636 from the driver's point of view. An example of an ISA bus master is the 1542 SCSI
23637 controller, whose driver is <i>drivers/scsi/aha1542.c</i> in the kernel sources.<br>
23638 <br>
23639 As far as native DMA is concerned, there are three entities involved in a DMA data
23640 transfer on the ISA bus:<br>
23641 <br>
23642 <i>The 8237 DMA controller (DMAC)</i><br>
23643 <div class="bq">
23644 The controller holds information about the DMA transfer, such as the direction,
23645 the memory address, and the size of the transfer. It also contains a counter that
23646 tracks the status of ongoing transfers. When the controller receives a DMA
23647 request signal, it gains control of the bus and drives the signal lines so that the
23648 device can read or write its data.</div>
23649 <br>
23650 <i>The peripheral device</i><br>
23651 <div class="bq">
23652 The device must activate the DMA request signal when it's ready to transfer
23653 data. The actual transfer is managed by the DMAC; the hardware device sequentially
23654 reads or writes data onto the bus when the controller strobes the device.
23655 The device usually raises an interrupt when the transfer is over.</div>
23656 <br>
23657 <i>The device driver</i><br>
23658 <div class="bq">
23659 The driver has little to do; it provides the DMA controller with the direction, bus
23660 address, and size of the transfer. It also talks to its peripheral to prepare it for
23661 transferring the data and responds to the interrupt when the DMA is over.</div>
23662 <br>
23663 The original DMA controller used in the PC could manage four "channels," each
23664 associated with one set of DMA registers. Four devices could store their DMA information
23665 in the controller at the same time. Newer PCs contain the equivalent of two
23666 DMAC devices:* the second controller (master) is connected to the system processor,
23667 and the first (slave) is connected to channel 0 of the second controller.†<br>
23668 <br>
23669 * These circuits are now part of the motherboard's chipset, but a few years ago they were two separate 8237 chips.<br>
23670 <br>
23671 † The original PCs had only one controller; the second was added in 286-based platforms. However,
23672 the second controller is connected as the master because it handles 16-bit transfers; the first transfers
23673 only eight bits at a time and is there for backward compatibility.<br>
23674 <br>
23675 <A name="455"></a><font color="blue">PAGE 455</font><br>
23676 <br>
23677 The channels are numbered from 0-7: channel 4 is not available to ISA peripherals,
23678 because it is used internally to cascade the slave controller onto the master. The
23679 available channels are, thus, 0-3 on the slave (the 8-bit channels) and 5-7 on the
23680 master (the 16-bit channels). The size of any DMA transfer, as stored in the controller,
23681 is a 16-bit number representing the number of bus cycles. The maximum transfer
23682 size is, therefore, 64 KB for the slave controller (because it transfers eight bits in
23683 one cycle) and 128 KB for the master (which does 16-bit transfers).<br>
23684 <br>
23685 Because the DMA controller is a system-wide resource, the kernel helps deal with it.
23686 It uses a DMA registry to provide a request-and-free mechanism for the DMA channels
23687 and a set of functions to configure channel information in the DMA controller.<br>
23688 <br>
23689 <a name="RegisteringDMAUsage"></a><font color="red"><b>Registering DMA usage</b></font><br>
23690 <br>
23691 You should be used to kernel registries--we've already seen them for I/O ports and
23692 interrupt lines. The DMA channel registry is similar to the others. After <i><asm/dma.h>
23693 </i>has been included, the following functions can be used to obtain and release ownership
23694 of a DMA channel:<br>
23695 <pre>
23696 int request_dma(unsigned int channel, const char *name);
23697 void free_dma(unsigned int channel);
23698 </pre>
23699 The <font class="fixd">channel</font> argument is a number between 0 and 7 or, more precisely, a positive
23700 number less than <font class="fixd">MAX_DMA_CHANNELS</font>. On the PC, <font class="fixd">MAX_DMA_CHANNELS</font> is defined as 8 to
23701 match the hardware. The <font class="fixd">name</font> argument is a string identifying the device. The specified
23702 name appears in the file <i>/proc/dma</i>, which can be read by user programs.<br>
23703 <br>
23704 The return value from <i>request_dma </i>is 0 for success and <font class="fixd">-EINVAL</font> or <font class="fixd">-EBUSY</font> if there was
23705 an error. The former means that the requested channel is out of range, and the latter
23706 means that another device is holding the channel.<br>
23707 <br>
23708 We recommend that you take the same care with DMA channels as with I/O ports
23709 and interrupt lines; requesting the channel at <i>open </i>time is much better than requesting
23710 it from the module initialization function. Delaying the request allows some sharing
23711 between drivers; for example, your sound card and your analog I/O interface can
23712 share the DMA channel as long as they are not used at the same time.<br>
23713 <br>
23714 We also suggest that you request the DMA channel <i>after </i>you've requested the interrupt
23715 line and that you release it <i>before </i>the interrupt. This is the conventional order
23716 for requesting the two resources; following the convention avoids possible deadlocks.
23717 Note that every device using DMA needs an IRQ line as well; otherwise, it
23718 couldn't signal the completion of data transfer.<br>
23719 <br>
23720 In a typical case, the code for <i>open </i>looks like the following, which refers to our hypothetical
23721 <i>dad </i>module. The <i>dad </i>device as shown uses a fast interrupt handler without
23722 support for shared IRQ lines.<br>
23723 <pre>
23724 int dad_open (struct inode *inode, struct file *filp)
23725 {
23726 struct dad_device *my_device;
23727 </pre>
23728 <A name="456"></a><font color="blue">PAGE 456</font><br>
23729 <pre>
23730 /* ... */
23731 if ( (error = request_irq(my_device.irq, dad_interrupt,
23732 SA_INTERRUPT, "dad", NULL)) )
23733 return error; /* or implement blocking open */
23735 if ( (error = request_dma(my_device.dma, "dad")) ) {
23736 free_irq(my_device.irq, NULL);
23737 return error; /* or implement blocking open */
23738 }
23739 /* ... */
23740 return 0;
23741 }
23742 </pre>
23743 The <i>close</i> implementation that matches the <i>open</i> just shown looks like this:<br>
23744 <pre>
23745 void dad_close (struct inode *inode, struct file *filp)
23746 {
23747 struct dad_device *my_device;
23749 /* ... */
23750 free_dma(my_device.dma);
23751 free_irq(my_device.irq, NULL);
23752 /* ... */
23753 }
23754 </pre>
23755 Here's how the <i>/proc/dma</i> file looks on a system with the sound card installed:<br>
23756 <pre>
23757 merlino% <b>cat /proc/dma
23758 </b> 1: Sound Blaster8
23759 4: cascade
23760 </pre>
23761 It's interesting to note that the default sound driver gets the DMA channel at system
23762 boot and never releases it. The <font class="fixd">cascade</font> entry is a placeholder, indicating that channel
23763 4 is not available to drivers, as explained earlier.<br>
23764 <br>
23765 <a name="TalkingToTheDMAController"></a><font color="red"><b>Talking to the DMA controller</b></font><br>
23766 <br>
23767 After registration, the main part of the driver's job consists of configuring the DMA
23768 controller for proper operation. This task is not trivial, but fortunately, the kernel
23769 exports all the functions needed by the typical driver.<br>
23770 <br>
23771 The driver needs to configure the DMA controller either when <i>read </i>or <i>write </i>is called,
23772 or when preparing for asynchronous transfers. This latter task is performed either at
23773 <i>open </i>time or in response to an <i>ioctl </i>command, depending on the driver and the policy
23774 it implements. The code shown here is the code that is typically called by the <i>read
23775 </i>or <i>write</i> device methods.<br>
23776 <br>
23777 This subsection provides a quick overview of the internals of the DMA controller so
23778 you understand the code introduced here. If you want to learn more, we'd urge you
23779 to read <i><asm/dma.h> </i>and some hardware manuals describing the PC architecture. In<br>
23780 <br>
23781 <A name="457"></a><font color="blue">PAGE 457</font><br>
23782 <br>
23783 particular, we don't deal with the issue of 8-bit versus 16-bit data transfers. If you are
23784 writing device drivers for ISA device boards, you should find the relevant information
23785 in the hardware manuals for the devices.<br>
23786 <br>
23787 The DMA controller is a shared resource, and confusion could arise if more than one
23788 processor attempts to program it simultaneously. For that reason, the controller is
23789 protected by a spinlock, called <font class="fixd">dma_spin_lock</font>. Drivers should not manipulate the
23790 lock directly; however, two functions have been provided to do that for you:<br>
23791 <br>
23792 <font class="fixd">unsigned long claim_dma_lock( );</font><br>
23793 <div class="bq">
23794 Acquires the DMA spinlock. This function also blocks interrupts on the local
23795 processor; therefore, the return value is a set of flags describing the previous
23796 interrupt state; it must be passed to the following function to restore the interrupt
23797 state when you are done with the lock.</div>
23798 <br>
23799 <font class="fixd">void release_dma_lock(unsigned long flags);</font><br>
23800 <div class="bq">
23801 Returns the DMA spinlock and restores the previous interrupt status.</div>
23802 <br>
23803 The spinlock should be held when using the functions described next. It should <i>not
23804 </i>be held during the actual I/O, however. A driver should never sleep when holding a
23805 spinlock.<br>
23806 <br>
23807 The information that must be loaded into the controller consists of three items: the
23808 RAM address, the number of atomic items that must be transferred (in bytes or
23809 words), and the direction of the transfer. To this end, the following functions are
23810 exported by <i><asm/dma.h></i>:<br>
23811 <br>
23812 <font class="fixd">void set_dma_mode(unsigned int channel, char mode);</font><br>
23813 <div class="bq">
23814 Indicates whether the channel must read from the device (<font class="fixd">DMA_MODE_READ</font>) or
23815 write to it (<font class="fixd">DMA_MODE_WRITE</font>). A third mode exists, <font class="fixd">DMA_MODE_CASCADE,</font> which is
23816 used to release control of the bus. Cascading is the way the first controller is connected
23817 to the top of the second, but it can also be used by true ISA bus-master
23818 devices. We won't discuss bus mastering here.</div>
23819 <br>
23820 <font class="fixd">void set_dma_addr(unsigned int channel, unsigned int addr);</font><br>
23821 <div class="bq">
23822 Assigns the address of the DMA buffer. The function stores the 24 least significant
23823 bits of addr in the controller. The <font class="fixd">addr</font> argument must be a <i>bus </i>address (see
23824 the section "Bus Addresses" earlier in this chapter).</div>
23825 <br>
23826 <font class="fixd">void set_dma_count(unsigned int channel, unsigned int count);</font><br>
23827 <div class="bq">
23828 Assigns the number of bytes to transfer. The <font class="fixd">count</font> argument represents bytes for
23829 16-bit channels as well; in this case, the number <i>must</i> be even.</div>
23830 <br>
23831 <A name="458"></a><font color="blue">PAGE 458</font><br>
23832 <br>
23833 In addition to these functions, there are a number of housekeeping facilities that
23834 must be used when dealing with DMA devices:<br>
23835 <br>
23836 <font class="fixd">void disable_dma(unsigned int channel);</font><br>
23837 <div class="bq">
23838 A DMA channel can be disabled within the controller. The channel should be
23839 disabled before the controller is configured to prevent improper operation. (Otherwise,
23840 corruption can occur because the controller is programmed via 8-bit data
23841 transfers and, therefore, none of the previous functions is executed atomically).</div>
23842 <br>
23843 <font class="fixd">void enable_dma(unsigned int channel);</font><br>
23844 <div class="bq">
23845 This function tells the controller that the DMA channel contains valid data.</div>
23846 <br>
23847 <font class="fixd">int get_dma_residue(unsigned int channel);</font><br>
23848 <div class="bq">
23849 The driver sometimes needs to know whether a DMA transfer has been completed.
23850 This function returns the number of bytes that are still to be transferred.
23851 The return value is 0 after a successful transfer and is unpredictable (but not 0)
23852 while the controller is working. The unpredictability springs from the need to
23853 obtain the 16-bit residue through two 8-bit input operations.</div>
23854 <br>
23855 <font class="fixd">void clear_dma_ff(unsigned int channel)</font><br>
23856 <div class="bq">
23857 This function clears the DMA flip-flop. The flip-flop is used to control access to
23858 16-bit registers. The registers are accessed by two consecutive 8-bit operations,
23859 and the flip-flop is used to select the least significant byte (when it is clear) or the
23860 most significant byte (when it is set). The flip-flop automatically toggles when
23861 eight bits have been transferred; the programmer must clear the flip-flop (to set
23862 it to a known state) before accessing the DMA registers.</div>
23863 <br>
23864 Using these functions, a driver can implement a function like the following to prepare
23865 for a DMA transfer:<br>
23866 <pre>
23867 int dad_dma_prepare(int channel, int mode, unsigned int buf,
23868 unsigned int count)
23869 {
23870 unsigned long flags;
23872 flags = claim_dma_lock( );
23873 disable_dma(channel);
23874 clear_dma_ff(channel);
23875 set_dma_mode(channel, mode);
23876 set_dma_addr(channel, virt_to_bus(buf));
23877 set_dma_count(channel, count);
23878 enable_dma(channel);
23879 release_dma_lock(flags);
23881 return 0;
23882 }
23883 </pre>
23884 Then, a function like the next one is used to check for successful completion of
23885 DMA:<br>
23886 <pre>
23887 int dad_dma_isdone(int channel)
23888 {
23889 </pre>
23890 <A name="459"></a><font color="blue">PAGE 459</font><br>
23891 <pre>
23892 int residue;
23893 unsigned long flags = claim_dma_lock ( );
23894 residue = get_dma_residue(channel);
23895 release_dma_lock(flags);
23896 return (residue = = 0);
23897 }
23898 </pre>
23899 The only thing that remains to be done is to configure the device board. This device-specific
23900 task usually consists of reading or writing a few I/O ports. Devices differ in
23901 significant ways. For example, some devices expect the programmer to tell the hardware
23902 how big the DMA buffer is, and sometimes the driver has to read a value that is
23903 hardwired into the device. For configuring the board, the hardware manual is your
23904 only friend.<br>
23905 <br>
23906 <a name="QuickReference15"></a><font color="red"><b>Quick Reference</b></font><br>
23907 <br>
23908 This chapter introduced the following symbols related to memory handling.<br>
23909 <br>
23910 <a name="IntroductoryMaterial"></a><font color="red"><b>Introductory Material</b></font><br>
23911 <br>
23912 <font class="fixd">#include <linux/mm.h><br>
23913 #include <asm/page.h></font><br>
23914 <div class="bq">
23915 Most of the functions and structures related to memory management are prototyped
23916 and defined in these header files.</div>
23917 <br>
23918 <font class="fixd">void *__va(unsigned long physaddr);<br>
23919 unsigned long __pa(void *kaddr);</font><br>
23920 <div class="bq">
23921 Macros that convert between kernel logical addresses and physical addresses.</div>
23922 <br>
23923 <font class="fixd">PAGE_SIZE<br>
23924 PAGE_SHIFT</font><br>
23925 <div class="bq">
23926 Constants that give the size (in bytes) of a page on the underlying hardware and
23927 the number of bits that a page frame number must be shifted to turn it into a
23928 physical address.</div>
23929 <br>
23930 <font class="fixd">struct page</font><br>
23931 <div class="bq">
23932 Structure that represents a hardware page in the system memory map.</div>
23933 <br>
23934 <font class="fixd">struct page *virt_to_page(void *kaddr);<br>
23935 void *page_address(struct page *page);<br>
23936 struct page *pfn_to_page(int pfn);</font><br>
23937 <div class="bq">
23938 Macros that convert between kernel logical addresses and their associated memory
23939 map entries. <i>page_address </i>works only for low-memory pages or high-memory
23940 pages that have been explicitly mapped. <i>pfn_to_page </i>converts a page frame number
23941 to its associated <font class="fixd">struct page</font> pointer.</div>
23942 <br>
23943 <A name="460"></a><font color="blue">PAGE 460</font><br>
23944 <br>
23945 <font class="fixd">unsigned long kmap(struct page *page);<br>
23946 void kunmap(struct page *page);</font><br>
23947 <div class="bq">
23948 <i>kmap </i>returns a kernel virtual address that is mapped to the given page, creating
23949 the mapping if need be. <i>kunmap</i> deletes the mapping for the given page.</div>
23950 <br>
23951 <font class="fixd">#include <linux/highmem.h><br>
23952 #include <asm/kmap_types.h><br>
23953 void *kmap_atomic(struct page *page, enum km_type type);<br>
23954 void kunmap_atomic(void *addr, enum km_type type);</font><br>
23955 <div class="bq">
23956 The high-performance version of <i>kmap</i>; the resulting mappings can be held only by
23957 atomic code. For drivers, type should be <font class="fixd">KM_USER0, KM_USER1, KM_IRQ0,</font> or <font class="fixd">KM_IRQ1.</font></div>
23958 <br>
23959 <font class="fixd">struct vm_area_struct;</font><br>
23960 <div class="bq">
23961 Structure describing a VMA.</div>
23962 <br>
23963 <a name="ImplementingMmap"></a><font color="red"><b>Implementing mmap</b></font><br>
23964 <br>
23965 <font class="fixd">int remap_pfn_range(struct vm_area_struct *vma, unsigned long virt_add, unsigned long pfn, unsigned long size, pgprot_t prot);<br>
23966 int io_remap_page_range(struct vm_area_struct *vma, unsigned long virt_add, unsigned long phys_add, unsigned long size, pgprot_t prot);</font><br>
23967 <div class="bq">
23968 Functions that sit at the heart of <i>mmap</i>. They map <font class="fixd">size</font> bytes of physical
23969 addresses, starting at the page number indicated by <font class="fixd">pfn</font> to the virtual address
23970 <font class="fixd">virt_add</font>. The protection bits associated with the virtual space are specified in
23971 prot. <i>io_remap_page_range </i>should be used when the target address is in I/O
23972 memory space.</div>
23973 <br>
23974 <font class="fixd">struct page *vmalloc_to_page(void *vmaddr);</font><br>
23975 <div class="bq">
23976 Converts a kernel virtual address obtained from <i>vmalloc </i>to its corresponding
23977 <font class="fixd">struct page</font> pointer.</div>
23978 <br>
23979 <a name="ImplementingDirectIO"></a><font color="red"><b>Implementing Direct I/O</b></font><br>
23980 <br>
23981 <font class="fixd">int get_user_pages(struct task_struct *tsk, struct mm_struct *mm, unsigned long start, int len, int write, int force, struct page **pages, struct vm_area_struct **vmas);</font><br>
23982 <div class="bq">
23983 Function that locks a user-space buffer into memory and returns the corresponding
23984 <font class="fixd">struct page</font> pointers. The caller must hold <font class="fixd">mm->mmap_sem.</font></div>
23985 <br>
23986 <font class="fixd">SetPageDirty(struct page *page);</font><br>
23987 <div class="bq">
23988 Macro that marks the given page as "dirty" (modified) and in need of writing to
23989 its backing store before it can be freed.</div>
23990 <br>
23991 <font class="fixd">void page_cache_release(struct page *page);</font><br>
23992 <div class="bq">
23993 Frees the given page from the page cache.</div>
23994 <br>
23995 <A name="461"></a><font color="blue">PAGE 461</font><br>
23996 <br>
23997 <font class="fixd">int is_sync_kiocb(struct kiocb *iocb);</font><br>
23998 <div class="bq">
23999 Macro that returns nonzero if the given IOCB requires synchronous execution.</div>
24000 <br>
24001 <font class="fixd">int aio_complete(struct kiocb *iocb, long res, long res2);</font><br>
24002 <div class="bq">
24003 Function that indicates completion of an asynchronous I/O operation.</div>
24004 <br>
24005 <a name="DirectMemoryAccess2"></a><font color="red"><b>Direct Memory Access</b></font><br>
24006 <br>
24007 <font class="fixd">#include <asm/io.h><br>
24008 unsigned long virt_to_bus(volatile void * address);<br>
24009 void * bus_to_virt(unsigned long address);</font><br>
24010 <div class="bq">
24011 Obsolete and deprecated functions that convert between kernel, virtual, and bus
24012 addresses. Bus addresses must be used to talk to peripheral devices.</div>
24013 <br>
24014 <font class="fixd">#include <linux/dma-mapping.h></font><br>
24015 <div class="bq">
24016 Header file required to define the generic DMA functions.</div>
24017 <br>
24018 <font class="fixd">int dma_set_mask(struct device *dev, u64 mask);</font><br>
24019 <div class="bq">
24020 For peripherals that cannot address the full 32-bit range, this function informs
24021 the kernel of the addressable range and returns nonzero if DMA is possible.</div>
24022 <br>
24023 <font class="fixd">void *dma_alloc_coherent(struct device *dev, size_t size, dma_addr_t *bus_addr, int flag)<br>
24024 void dma_free_coherent(struct device *dev, size_t size, void *cpuaddr, dma_handle_t bus_addr);</font><br>
24025 <div class="bq">
24026 Allocate and free coherent DMA mappings for a buffer that will last the lifetime
24027 of the driver.</div>
24028 <br>
24029 <font class="fixd">#include <linux/dmapool.h><br>
24030 struct dma_pool *dma_pool_create(const char *name, struct device *dev, size_t size, size_t align, size_t allocation);<br>
24031 void dma_pool_destroy(struct dma_pool *pool);<br>
24032 void *dma_pool_alloc(struct dma_pool *pool, int mem_flags, dma_addr_t *handle);<br>
24033 void dma_pool_free(struct dma_pool *pool, void *vaddr, dma_addr_t handle);</font><br>
24034 <div class="bq">
24035 Functions that create, destroy, and use DMA pools to manage small DMA areas.</div>
24036 <br>
24037 <font class="fixd">enum dma_data_direction;<br>
24038 DMA_TO_DEVICE<br>
24039 DMA_FROM_DEVICE<br>
24040 DMA_BIDIRECTIONAL<br>
24041 DMA_NONE</font><br>
24042 <div class="bq">
24043 Symbols used to tell the streaming mapping functions the direction in which
24044 data is moving to or from the buffer.</div>
24045 <br>
24046 <A name="462"></a><font color="blue">PAGE 462</font><br>
24047 <br>
24048 <font class="fixd">dma_addr_t dma_map_single(struct device *dev, void *buffer, size_t size, enum dma_data_direction direction);<br>
24049 void dma_unmap_single(struct device *dev, dma_addr_t bus_addr, size_t size, enum dma_data_direction direction);</font><br>
24050 <div class="bq">
24051 Create and destroy a single-use, streaming DMA mapping.</div>
24052 <br>
24053 <font class="fixd">void dma_sync_single_for_cpu(struct device *dev, dma_handle_t bus_addr, size_t size, enum dma_data_direction direction);<br>
24054 void dma_sync_single_for_device(struct device *dev, dma_handle_t bus_addr, size_t size, enum dma_data_direction direction);</font><br>
24055 <div class="bq">
24056 Synchronizes a buffer that has a streaming mapping. These functions must be
24057 used if the processor must access a buffer while the streaming mapping is in
24058 place (i.e., while the device owns the buffer).</div>
24059 <br>
24060 <font class="fixd">#include <asm/scatterlist.h><br>
24061 struct scatterlist { /* ... */ };<br>
24062 dma_addr_t sg_dma_address(struct scatterlist *sg);<br>
24063 unsigned int sg_dma_len(struct scatterlist *sg);</font><br>
24064 <div class="bq">
24065 The <font class="fixd">scatterlist</font> structure describes an I/O operation that involves more than
24066 one buffer. The macros <i>sg_dma_address </i>and <i>sg_dma_len </i>may be used to extract
24067 bus addresses and buffer lengths to pass to the device when implementing scatter/gather
24068 operations.</div>
24069 <br>
24070 <font class="fixd">dma_map_sg(struct device *dev, struct scatterlist *list, int nents, enum dma_data_direction direction);<br>
24071 dma_unmap_sg(struct device *dev, struct scatterlist *list, int nents, enum dma_data_direction direction);<br>
24072 void dma_sync_sg_for_cpu(struct device *dev, struct scatterlist *sg, int nents, enum dma_data_direction direction);<br>
24073 void dma_sync_sg_for_device(struct device *dev, struct scatterlist *sg, int nents, enum dma_data_direction direction);</font><br>
24074 <div class="bq">
24075 <i>dma_map_sg </i>maps a scatter/gather operation, and <i>dma_unmap_sg </i>undoes
24076 that mapping. If the buffers must be accessed while the mapping is active,
24077 <i>dma_sync_sg_*</i> may be used to synchronize things.</div>
24078 <br>
24079 <font class="fixd">/proc/dma</font><br>
24080 <div class="bq">
24081 File that contains a textual snapshot of the allocated channels in the DMA controllers.
24082 PCI-based DMA is not shown because each board works independently,
24083 without the need to allocate a channel in the DMA controller.</div>
24084 <br>
24085 <font class="fixd">#include <asm/dma.h></font><br>
24086 <div class="bq">
24087 Header that defines or prototypes all the functions and macros related to DMA.
24088 It must be included to use any of the following symbols.</div>
24089 <br>
24090 <A name="463"></a><font color="blue">PAGE 463</font><br>
24091 <br>
24092 <font class="fixd">int request_dma(unsigned int channel, const char *name);<br>
24093 void free_dma(unsigned int channel);</font><br>
24094 <div class="bq">
24095 Access the DMA registry. Registration must be performed before using ISA DMA
24096 channels.</div>
24097 <br>
24098 <font class="fixd">unsigned long claim_dma_lock( );<br>
24099 void release_dma_lock(unsigned long flags);</font><br>
24100 <div class="bq">
24101 Acquire and release the DMA spinlock, which must be held prior to calling the
24102 other ISA DMA functions described later in this list. They also disable and reenable
24103 interrupts on the local processor.</div>
24104 <br>
24105 <font class="fixd">void set_dma_mode(unsigned int channel, char mode);<br>
24106 void set_dma_addr(unsigned int channel, unsigned int addr);<br>
24107 void set_dma_count(unsigned int channel, unsigned int count);</font><br>
24108 <div class="bq">
24109 Program DMA information in the DMA controller. addr is a bus address.</div>
24110 <br>
24111 <font class="fixd">void disable_dma(unsigned int channel);<br>
24112 void enable_dma(unsigned int channel);</font><br>
24113 <div class="bq">
24114 A DMA channel must be disabled during configuration. These functions change
24115 the status of the DMA channel.</div>
24116 <br>
24117 <font class="fixd">int get_dma_residue(unsigned int channel);</font><br>
24118 <div class="bq">
24119 If the driver needs to know how a DMA transfer is proceeding, it can call this
24120 function, which returns the number of data transfers that are yet to be completed.
24121 After successful completion of DMA, the function returns 0; the value is
24122 unpredictable while data is being transferred.</div>
24123 <br>
24124 <font class="fixd">void clear_dma_ff(unsigned int channel)</font><br>
24125 <div class="bq">
24126 The DMA flip-flop is used by the controller to transfer 16-bit values by means of
24127 two 8-bit operations. It must be cleared before sending any data to the controller.</div>
24128 <br>
24129 <A name="464"></a><font color="blue">PAGE 464</font><br>
24130 <br>
24131 <a name="CHAPTER16"></a><font color="red"><b>CHAPTER 16</b></font><br>
24132 <br>
24133 <a name="BlockDrivers"></a><font color="#7519FF" size="+1"><b>Block Drivers</b></font><br>
24134 <br>
24135 So far, our discussion has been limited to char drivers. There are other types of drivers
24136 in Linux systems, however, and the time has come for us to widen our focus
24137 somewhat. Accordingly, this chapter discusses block drivers.<br>
24138 <br>
24139 A block driver provides access to devices that transfer randomly accessible data in
24140 fixed-size blocks--disk drives, primarily. The Linux kernel sees block devices as
24141 being fundamentally different from char devices; as a result, block drivers have a distinct
24142 interface and their own particular challenges.<br>
24143 <br>
24144 Efficient block drivers are critical for performance--and not just for explicit reads
24145 and writes in user applications. Modern systems with virtual memory work by shifting
24146 (hopefully) unneeded data to secondary storage, which is usually a disk drive.
24147 Block drivers are the conduit between core memory and secondary storage; therefore,
24148 they can be seen as making up part of the virtual memory subsystem. While it is
24149 possible to write a block driver without knowing about <font class="fixd">struct page</font> and other important
24150 memory concepts, anybody needing to write a high-performance driver has to
24151 draw upon the material covered in Chapter 15.<br>
24152 <br>
24153 Much of the design of the block layer is centered on performance. Many char devices
24154 can run below their maximum speed, and the performance of the system as a whole
24155 is not affected. The system cannot run well, however, if its block I/O subsystem is
24156 not well-tuned. The Linux block driver interface allows you to get the most out of a
24157 block device but imposes, necessarily, a degree of complexity that you must deal
24158 with. Happily, the 2.6 block interface is much improved over what was found in
24159 older kernels.<br>
24160 <br>
24161 The discussion in this chapter is, as one would expect, centered on an example driver
24162 that implements a block-oriented, memory-based device. It is, essentially, a ramdisk.
24163 The kernel already contains a far superior ramdisk implementation, but our driver
24164 (called <i>sbull</i>) lets us demonstrate the creation of a block driver while minimizing
24165 unrelated complexity.<br>
24166 <br>
24167 <A name="465"></a><font color="blue">PAGE 465</font><br>
24168 <br>
24169 Before getting into the details, let's define a couple of terms precisely. A <i>block </i>is a
24170 fixed-size chunk of data, the size being determined by the kernel. Blocks are often
24171 4096 bytes, but that value can vary depending on the architecture and the exact filesystem
24172 being used. A <i>sector</i>, in contrast, is a small block whose size is usually determined
24173 by the underlying hardware. The kernel expects to be dealing with devices
24174 that implement 512-byte sectors. If your device uses a different size, the kernel
24175 adapts and avoids generating I/O requests that the hardware cannot handle. It is
24176 worth keeping in mind, however, that any time the kernel presents you with a sector
24177 number, it is working in a world of 512-byte sectors. If you are using a different
24178 hardware sector size, you have to scale the kernel's sector numbers accordingly. We
24179 see how that is done in the <i>sbull</i> driver.<br>
24180 <br>
24181 <a name="Registration"></a><font color="red"><b>Registration</b></font><br>
24182 <br>
24183 Block drivers, like char drivers, must use a set of registration interfaces to make their
24184 devices available to the kernel. The concepts are similar, but the details of block
24185 device registration are all different. You have a whole new set of data structures and
24186 device operations to learn.<br>
24187 <br>
24188 <a name="BlockDriverRegistration"></a><font color="red"><b>Block Driver Registration</b></font><br>
24189 <br>
24190 The first step taken by most block drivers is to register themselves with the kernel.
24191 The function for this task is <i>register_blkdev</i> (which is declared in <i><linux/fs.h></i>):<br>
24192 <pre>
24193 int register_blkdev(unsigned int major, const char *name);
24194 </pre>
24195 The arguments are the major number that your device will be using and the associated
24196 name (which the kernel will display in <i>/proc/devices</i>). If <font class="fixd">major</font> is passed as 0, the
24197 kernel allocates a new major number and returns it to the caller. As always, a negative
24198 return value from <i>register_blkdev</i> indicates that an error has occurred.<br>
24199 <br>
24200 The corresponding function for canceling a block driver registration is:<br>
24201 <pre>
24202 int unregister_blkdev(unsigned int major, const char *name);
24203 </pre>
24204 Here, the arguments must match those passed to <i>register_blkdev</i>, or the function
24205 returns <font class="fixd">-EINVAL</font> and not unregister anything.<br>
24206 <br>
24207 In the 2.6 kernel, the call to <i>register_blkdev </i>is entirely optional. The functions performed
24208 by <i>register_blkdev </i>have been decreasing over time; the only tasks performed
24209 by this call at this point are (1) allocating a dynamic major number if requested, and
24210 (2) creating an entry in <i>/proc/devices</i>. In future kernels, <i>register_blkdev </i>may be
24211 removed altogether. Meanwhile, however, most drivers still call it; it's traditional.<br>
24212 <br>
24213 <A name="466"></a><font color="blue">PAGE 466</font><br>
24214 <br>
24215 <a name="DiskRegistration"></a><font color="red"><b>Disk Registration</b></font><br>
24216 <br>
24217 While <i>register_blkdev </i>can be used to obtain a major number, it does not make any
24218 disk drives available to the system. There is a separate registration interface that you
24219 must use to manage individual drives. Using this interface requires familiarity with a
24220 pair of new structures, so that is where we start.<br>
24221 <br>
24222 <a name="BlockDeviceOperations"></a><font color="red"><b>Block device operations</b></font><br>
24223 <br>
24224 Char devices make their operations available to the system by way of the <font class="fixd">file_operations</font>
24225 structure. A similar structure is used with block devices; it is <font class="fixd">struct block_device_operations,</font>
24226 which is declared in <i><linux/fs.h></i>. The following is a brief
24227 overview of the fields found in this structure; we revisit them in more detail when we
24228 get into the details of the <i>sbull</i> driver:<br>
24229 <br>
24230 <font class="fixd">int (*open)(struct inode *inode, struct file *filp);<br>
24231 int (*release)(struct inode *inode, struct file *filp);</font><br>
24232 <div class="bq">
24233 Functions that work just like their char driver equivalents; they are called whenever
24234 the device is opened and closed. A block driver might respond to an open
24235 call by spinning up the device, locking the door (for removable media), etc. If
24236 you lock media into the device, you should certainly unlock it in the <i>release
24237 </i>method.</div>
24238 <br>
24239 <font class="fixd">int (*ioctl)(struct inode *inode, struct file *filp, unsigned int cmd, unsigned long arg);</font><br>
24240 <div class="bq">
24241 Method that implements the <i>ioctl </i>system call. The block layer first intercepts a
24242 large number of standard requests, however; so most block driver <i>ioctl </i>methods
24243 are fairly short.</div>
24244 <br>
24245 <font class="fixd">int (*media_changed) (struct gendisk *gd);</font><br>
24246 <div class="bq">
24247 Method called by the kernel to check whether the user has changed the media in
24248 the drive, returning a nonzero value if so. Obviously, this method is only applicable
24249 to drives that support removable media (and that are smart enough to
24250 make a "media changed" flag available to the driver); it can be omitted in other
24251 cases.<br>
24252 <br>
24253 The <font class="fixd">struct gendisk</font> argument is how the kernel represents a single disk; we will
24254 be looking at that structure in the next section.</div>
24255 <br>
24256 <font class="fixd">int (*revalidate_disk) (struct gendisk *gd);</font><br>
24257 <div class="bq">
24258 The <i>revalidate_disk </i>method is called in response to a media change; it gives the
24259 driver a chance to perform whatever work is required to make the new media
24260 ready for use. The function returns an <font class="fixd">int</font> value, but that value is ignored by the
24261 kernel.</div>
24262 <br>
24263 <font class="fixd">struct module *owner;</font><br>
24264 <div class="bq">
24265 A pointer to the module that owns this structure; it should usually be initialized
24266 to <font class="fixd">THIS_MODULE</font>.</div>
24267 <br>
24268 <A name="467"></a><font color="blue">PAGE 467</font><br>
24269 <br>
24270 Attentive readers may have noticed an interesting omission from this list: there are
24271 no functions that actually read or write data. In the block I/O subsystem, these operations
24272 are handled by the <i>request </i>function, which deserves a large section of its own
24273 and is discussed later in the chapter. Before we can talk about servicing requests, we
24274 must complete our discussion of disk registration.<br>
24275 <br>
24276 <a name="TheGendiskStructure"></a><font color="red"><b>The gendisk structure</b></font><br>
24277 <br>
24278 <font class="fixd">struct gendisk</font> (declared in <i><linux/genhd.h></i>) is the kernel's representation of an individual
24279 disk device. In fact, the kernel also uses <font class="fixd">gendisk</font> structures to represent partitions,
24280 but driver authors need not be aware of that. There are several fields in struct
24281 gendisk that must be initialized by a block driver:<br>
24282 <br>
24283 <font class="fixd">int major;<br>
24284 int first_minor;<br>
24285 int minors;</font><br>
24286 <div class="bq">
24287 Fields that describe the device number(s) used by the disk. At a minimum, a
24288 drive must use at least one minor number. If your drive is to be partitionable,
24289 however (and most should be), you want to allocate one minor number for each
24290 possible partition as well. A common value for <font class="fixd">minors</font> is 16, which allows for the
24291 "full disk" device and 15 partitions. Some disk drivers use 64 minor numbers for
24292 each device.</div>
24293 <br>
24294 <font class="fixd">char disk_name[32];</font><br>
24295 <div class="bq">
24296 Field that should be set to the name of the disk device. It shows up in <i>/proc/
24297 partitions</i> and sysfs.</div>
24298 <br>
24299 <font class="fixd">struct block_device_operations *fops;</font><br>
24300 <div class="bq">
24301 Set of device operations from the previous section.</div>
24302 <br>
24303 <font class="fixd">struct request_queue *queue;</font><br>
24304 <div class="bq">
24305 Structure used by the kernel to manage I/O requests for this device; we examine
24306 it in the section "Request Processing."</div>
24307 <br>
24308 <font class="fixd">int flags;</font><br>
24309 <div class="bq">
24310 A (little-used) set of flags describing the state of the drive. If your device has
24311 removable media, you should set <font class="fixd">GENHD_FL_REMOVABLE</font>. CD-ROM drives can set
24312 <font class="fixd">GENHD_FL_CD</font>. If, for some reason, you do not want partition information to
24313 show up in <i>/proc/partitions</i>, set <font class="fixd">GENHD_FL_SUPPRESS_PARTITION_INFO</font>.</div>
24314 <br>
24315 <font class="fixd">sector_t capacity;</font><br>
24316 <div class="bq">
24317 The capacity of this drive, in 512-byte sectors. The <font class="fixd">sector_t</font> type can be 64 bits
24318 wide. Drivers should not set this field directly; instead, pass the number of sectors
24319 to <i>set_capacity</i>.</div>
24320 <br>
24321 <font class="fixd">void *private_data;</font><br>
24322 <div class="bq">
24323 Block drivers may use this field for a pointer to their own internal data.</div>
24324 <br>
24325 <A name="468"></a><font color="blue">PAGE 468</font><br>
24326 <br>
24327 The kernel provides a small set of functions for working with <font class="fixd">gendisk</font> structures. We
24328 introduce them here, then see how <i>sbull </i>uses them to make its disk devices available
24329 to the system.<br>
24330 <br>
24331 <font class="fixd">struct gendisk</font> is a dynamically allocated structure that requires special kernel
24332 manipulation to be initialized; drivers cannot allocate the structure on their own.
24333 Instead, you must call:<br>
24334 <pre>
24335 struct gendisk *alloc_disk(int minors);
24336 </pre>
24337 The <font class="fixd">minors</font> argument should be the number of minor numbers this disk uses; note
24338 that you cannot change the <font class="fixd">minors</font> field later and expect things to work properly.<br>
24339 <br>
24340 When a disk is no longer needed, it should be freed with:<br>
24341 <pre>
24342 void del_gendisk(struct gendisk *gd);
24343 </pre>
24344 A <font class="fixd">gendisk</font> is a reference-counted structure (it contains a kobject). There are <i>get_disk
24345 </i>and <i>put_disk </i>functions available to manipulate the reference count, but drivers
24346 should never need to do that. Normally, the call to <i>del_gendisk </i>removes the final reference
24347 to a gendisk, but there are no guarantees of that. Thus, it is possible that the
24348 structure could continue to exist (and your methods could be called) after a call to
24349 <i>del_gendisk</i>. If you delete the structure when there are no users (that is, after the final
24350 <i>release </i>or in your module <i>cleanup </i>function), however, you can be sure that you will
24351 not hear from it again.<br>
24352 <br>
24353 Allocating a <font class="fixd">gendisk</font> structure does not make the disk available to the system. To do
24354 that, you must initialize the structure and call <i>add_disk</i>:<br>
24355 <pre>
24356 void add_disk(struct gendisk *gd);
24357 </pre>
24358 Keep one important thing in mind here: as soon as you call <i>add_disk</i>, the disk is
24359 "live" and its methods can be called at any time. In fact, the first such calls will probably
24360 happen even before <i>add_disk </i>returns; the kernel will read the first few blocks in
24361 an attempt to find a partition table. So you should not call <i>add_disk </i>until your driver
24362 is completely initialized and ready to respond to requests on that disk.<br>
24363 <br>
24364 <a name="InitializationInSbull"></a><font color="red"><b>Initialization in sbull</b></font><br>
24365 <br>
24366 It is time to get down to some examples. The <i>sbull </i>driver (available from O'Reilly's
24367 FTP site with the rest of the example source) implements a set of in-memory virtual
24368 disk drives. For each drive, <i>sbull </i>allocates (with <i>vmalloc</i>, for simplicity) an array of
24369 memory; it then makes that array available via block operations. The <i>sbull </i>driver can
24370 be tested by partitioning the virtual device, building filesystems on it, and mounting
24371 it in the system hierarchy.<br>
24372 <br>
24373 Like our other example drivers, <i>sbull </i>allows a major number to be specified at compile
24374 or module load time. If no number is specified, one is allocated dynamically.
24375 Since a call to <i>register_blkdev</i> is required for dynamic allocation, <i>sbull</i> does so:<br>
24376 <pre>
24377 sbull_major = register_blkdev(sbull_major, "sbull");
24378 if (sbull_major <= 0) {
24379 </pre>
24380 <A name="469"></a><font color="blue">PAGE 469</font>
24381 <pre>
24382 printk(KERN_WARNING "sbull: unable to get major number\n");
24383 return -EBUSY;
24384 }
24385 </pre>
24386 Also, like the other virtual devices we have presented in this book, the <i>sbull </i>device is
24387 described by an internal structure:<br>
24388 <pre>
24389 struct sbull_dev {
24390 int size; /* Device size in sectors */
24391 u8 *data; /* The data array */
24392 short users; /* How many users */
24393 short media_change; /* Flag a media change? */
24394 spinlock_t lock; /* For mutual exclusion */
24395 struct request_queue *queue; /* The device request queue */
24396 struct gendisk *gd; /* The gendisk structure */
24397 struct timer_list timer; /* For simulated media changes */
24398 };
24399 </pre>
24400 Several steps are required to initialize this structure and make the associated device
24401 available to the system. We start with basic initialization and allocation of the underlying
24402 memory:<br>
24403 <pre>
24404 memset (dev, 0, sizeof (struct sbull_dev));
24405 dev->size = nsectors*hardsect_size;
24406 dev->data = vmalloc(dev->size);
24407 if (dev->data = = NULL) {
24408 printk (KERN_NOTICE "vmalloc failure.\n");
24409 return;
24410 }
24411 spin_lock_init(&dev->lock);
24412 </pre>
24413 It's important to allocate and initialize a spinlock before the next step, which is the
24414 allocation of the request queue. We look at this process in more detail when we get
24415 to request processing; for now, suffice it to say that the necessary call is:<br>
24416 <pre>
24417 dev->queue = blk_init_queue(sbull_request, &dev->lock);
24418 </pre>
24419 Here, <i>sbull_request </i>is our <i>request </i>function--the function that actually performs
24420 block read and write requests. When we allocate a request queue, we must provide a
24421 spinlock that controls access to that queue. The lock is provided by the driver rather
24422 than the general parts of the kernel because, often, the request queue and other
24423 driver data structures fall within the same critical section; they tend to be accessed
24424 together. As with any function that allocates memory, <i>blk_init_queue </i>can fail, so you
24425 must check the return value before continuing.<br>
24426 <br>
24427 Once we have our device memory and request queue in place, we can allocate, initialize,
24428 and install the corresponding <font class="fixd">gendisk</font> structure. The code that does this work is:<br>
24429 <pre>
24430 dev->gd = alloc_disk(SBULL_MINORS);
24431 if (! dev->gd) {
24432 printk (KERN_NOTICE "alloc_disk failure\n");
24433 goto out_vfree;
24434 }
24435 dev->gd->major = sbull_major;
24436 </pre>
24437 <A name="470"></a><font color="blue">PAGE 470</font><br>
24438 <pre>
24439 dev->gd->first_minor = which*SBULL_MINORS;
24440 dev->gd->fops = &sbull_ops;
24441 dev->gd->queue = dev->queue;
24442 dev->gd->private_data = dev;
24443 snprintf (dev->gd->disk_name, 32, "sbull%c", which + 'a');
24444 set_capacity(dev->gd, nsectors*(hardsect_size/KERNEL_SECTOR_SIZE));
24445 add_disk(dev->gd);
24446 </pre>
24447 Here, <font class="fixd">SBULL_MINORS</font> is the number of minor numbers each <i>sbull </i>device supports.
24448 When we set the first minor number for each device, we must take into account all of
24449 the numbers taken by prior devices. The name of the disk is set such that the first
24450 one is <i>sbulla</i>, the second <i>sbullb</i>, and so on. User space can then add partition numbers
24451 so that the third partition on the second device might be <i>/dev/sbullb3</i>.<br>
24452 <br>
24453 Once everything is set up, we finish with a call to <i>add_disk</i>. Chances are that several
24454 of our methods will have been called for that disk by the time <i>add_disk </i>returns, so we
24455 take care to make that call the very last step in the initialization of our device.<br>
24456 <br>
24457 <a name="ANoteOnSectorSizes"></a><font color="red"><b>A Note on Sector Sizes</b></font><br>
24458 <br>
24459 As we have mentioned before, the kernel treats every disk as a linear array of 512byte
24460 sectors. Not all hardware uses that sector size, however. Getting a device with a
24461 different sector size to work is not particularly hard; it is just a matter of taking care
24462 of a few details. The <i>sbull </i>device exports a <font class="fixd">hardsect_size</font> parameter that can be used
24463 to change the "hardware" sector size of the device; by looking at its implementation,
24464 you can see how to add this sort of support to your own drivers.<br>
24465 <br>
24466 The first of those details is to inform the kernel of the sector size your device supports.
24467 The hardware sector size is a parameter in the request queue, rather than in
24468 the <font class="fixd">gendisk</font> structure. This size is set with a call to <i>blk_queue_hardsect_size </i>immediately
24469 after the queue is allocated:<br>
24470 <pre>
24471 blk_queue_hardsect_size(dev->queue, hardsect_size);
24472 </pre>
24473 Once that is done, the kernel adheres to your device's hardware sector size. All I/O
24474 requests are properly aligned at the beginning of a hardware sector, and the length of
24475 each request is an integral number of sectors. You must remember, however, that the
24476 kernel always expresses itself in 512-byte sectors; thus, it is necessary to translate all
24477 sector numbers accordingly. So, for example, when <i>sbull </i>sets the capacity of the
24478 device in its <font class="fixd">gendisk</font> structure, the call looks like:<br>
24479 <pre>
24480 set_capacity(dev->gd, nsectors*(hardsect_size/KERNEL_SECTOR_SIZE));
24481 </pre>
24482 <font class="fixd">KERNEL_SECTOR_SIZE</font> is a locally-defined constant that we use to scale between the kernel's
24483 512-byte sectors and whatever size we have been told to use. This sort of calculation
24484 pops up frequently as we look at the <i>sbull</i> request processing logic.<br>
24485 <br>
24486 <A name="471"></a><font color="blue">PAGE 471</font><br>
24487 <br>
24488 <a name="TheBlockDeviceOperations"></a><font color="red"><b>The Block Device Operations</b></font><br>
24489 <br>
24490 We had a brief introduction to the <font class="fixd">block_device_operations</font> structure in the previous
24491 section. Now we take some time to look at these operations in a bit more detail
24492 before getting into request processing. To that end, it is time to mention one other
24493 feature of the <i>sbull </i>driver: it pretends to be a removable device. Whenever the last
24494 user closes the device, a 30-second timer is set; if the device is not opened during that
24495 time, the contents of the device are cleared, and the kernel will be told that the media
24496 has been changed. The 30-second delay gives the user time to, for example, mount
24497 an <i>sbull</i> device after creating a filesystem on it.<br>
24498 <br>
24499 <a name="TheOpenAndReleaseMethods"></a><font color="red"><b>The open and release Methods</b></font><br>
24500 <br>
24501 To implement the simulated media removal, <i>sbull </i>must know when the last user has
24502 closed the device. A count of users is maintained by the driver. It is the job of the
24503 <i>open</i> and <i>close</i> methods to keep that count current.<br>
24504 <br>
24505 The <i>open </i>method looks very similar to its char-driver equivalent; it takes the relevant
24506 <font class="fixd">inode</font> and <font class="fixd">file</font> structure pointers as arguments. When an inode refers to a block
24507 device, the field <font class="fixd">i_bdev->bd_disk</font> contains a pointer to the associated <font class="fixd">gendisk</font> structure;
24508 this pointer can be used to get to a driver's internal data structures for the
24509 device. That is, in fact, the first thing that the <i>sbull open</i> method does:<br>
24510 <pre>
24511 static int sbull_open(struct inode *inode, struct file *filp)
24512 {
24513 struct sbull_dev *dev = inode->i_bdev->bd_disk->private_data;
24515 del_timer_sync(&dev->timer);
24516 filp->private_data = dev;
24517 spin_lock(&dev->lock);
24518 if (! dev->users)
24519 check_disk_change(inode->i_bdev);
24520 dev->users++;
24521 spin_unlock(&dev->lock);
24522 return 0;
24523 }
24524 </pre>
24525 Once <i>sbull_open </i>has its device structure pointer, it calls <i>del_timer_sync </i>to remove the
24526 "media removal" timer, if any is active. Note that we do not lock the device spinlock
24527 until after the timer has been deleted; doing otherwise invites deadlock if the timer
24528 function runs before we can delete it. With the device locked, we call a kernel function
24529 called <i>check_disk_change </i>to check whether a media change has happened. One
24530 might argue that the kernel should make that call, but the standard pattern is for
24531 drivers to handle it at <i>open</i> time.<br>
24532 <br>
24533 The last step is to increment the user count and return.<br>
24534 <br>
24535 <A name="472"></a><font color="blue">PAGE 472</font><br>
24536 <br>
24537 The task of the <i>release </i>method is, in contrast, to decrement the user count and, if
24538 indicated, start the media removal timer:<br>
24539 <pre>
24540 static int sbull_release(struct inode *inode, struct file *filp)
24541 {
24542 struct sbull_dev *dev = inode->i_bdev->bd_disk->private_data;
24544 spin_lock(&dev->lock);
24545 dev->users--;
24547 if (!dev->users) {
24548 dev->timer.expires = jiffies + INVALIDATE_DELAY;
24549 add_timer(&dev->timer);
24550 }
24551 spin_unlock(&dev->lock);
24553 return 0;
24554 }
24555 </pre>
24556 In a driver that handles a real, hardware device, the <i>open </i>and <i>release </i>methods would
24557 set the state of the driver and hardware accordingly. This work could involve spinning
24558 the disk up or down, locking the door of a removable device, allocating DMA
24559 buffers, etc.<br>
24560 <br>
24561 You may be wondering who actually opens a block device. There are some operations
24562 that cause a block device to be opened directly from user space; these include
24563 partitioning a disk, building a filesystem on a partition, or running a filesystem
24564 checker. A block driver also sees an <i>open </i>call when a partition is mounted. In this
24565 case, there is no user-space process holding an open file descriptor for the device; the
24566 open file is, instead, held by the kernel itself. A block driver cannot tell the difference
24567 between a <i>mount </i>operation (which opens the device from kernel space) and the
24568 invocation of a utility such as <i>mkfs</i> (which opens it from user space).<br>
24569 <br>
24570 <a name="SupportingRemovableMedia"></a><font color="red"><b>Supporting Removable Media</b></font><br>
24571 <br>
24572 The <font class="fixd">block_device_operations</font> structure includes two methods for supporting removable
24573 media. If you are writing a driver for a nonremovable device, you can safely omit
24574 these methods. Their implementation is relatively straightforward.<br>
24575 <br>
24576 The <i>media_changed </i>method is called (from <i>check_disk_change</i>) to see whether the
24577 media has been changed; it should return a nonzero value if this has happened. The
24578 <i>sbull </i>implementation is simple; it queries a flag that has been set if the media
24579 removal timer has expired:<br>
24580 <pre>
24581 int sbull_media_changed(struct gendisk *gd)
24582 {
24583 struct sbull_dev *dev = gd->private_data;
24585 return dev->media_change;
24586 }
24587 </pre>
24588 <A name="473"></a><font color="blue">PAGE 473</font><br>
24589 <br>
24590 The <i>revalidate </i>method is called after a media change; its job is to do whatever is
24591 required to prepare the driver for operations on the new media, if any. After the call
24592 to <i>revalidate</i>, the kernel attempts to reread the partition table and start over with the
24593 device. The <i>sbull </i>implementation simply resets the <font class="fixd">media_change</font> flag and zeroes out
24594 the device memory to simulate the insertion of a blank disk.<br>
24595 <pre>
24596 int sbull_revalidate(struct gendisk *gd)
24597 {
24598 struct sbull_dev *dev = gd->private_data;
24600 if (dev->media_change) {
24601 dev->media_change = 0;
24602 memset (dev->data, 0, dev->size);
24603 }
24604 return 0;
24605 }
24606 </pre>
24607 <a name="TheIoctlMethod2"></a><font color="red"><b>The ioctl Method</b></font><br>
24608 <br>
24609 Block devices can provide an <i>ioctl </i>method to perform device control functions. The
24610 higher-level block subsystem code intercepts a number of <i>ioctl </i>commands before
24611 your driver ever gets to see them, however (see <i>drivers/block/ioctl.c </i>in the kernel
24612 source for the full set). In fact, a modern block driver may not have to implement
24613 very many <i>ioctl</i> commands at all.<br>
24614 <br>
24615 The <i>sbull ioctl </i>method handles only one command--a request for the device's
24616 geometry:<br>
24617 <pre>
24618 int sbull_ioctl (struct inode *inode, struct file *filp,
24619 unsigned int cmd, unsigned long arg)
24620 {
24621 long size;
24622 struct hd_geometry geo;
24623 struct sbull_dev *dev = filp->private_data;
24625 switch(cmd) {
24626 case HDIO_GETGEO:
24627 /*
24628 * Get geometry: since we are a virtual device, we have to make
24629 * up something plausible. So we claim 16 sectors, four heads,
24630 * and calculate the corresponding number of cylinders. We set the
24631 * start of data at sector four.
24632 */
24633 size = dev->size*(hardsect_size/KERNEL_SECTOR_SIZE);
24634 geo.cylinders = (size & ~0x3f) >> 6;
24635 geo.heads = 4;
24636 geo.sectors = 16;
24637 geo.start = 4;
24638 if (copy_to_user((void __user *) arg, &geo, sizeof(geo)))
24639 return -EFAULT;
24640 </pre>
24641 <A name="474"></a><font color="blue">PAGE 474</font><br>
24642 <pre>
24643 return 0;
24644 }
24646 return -ENOTTY; /* unknown command */
24647 }
24648 </pre>
24649 Providing geometry information may seem like a curious task, since our device is
24650 purely virtual and has nothing to do with tracks and cylinders. Even most real-block
24651 hardware has been furnished with much more complicated structures for many
24652 years. The kernel is not concerned with a block device's geometry; it sees it simply as
24653 a linear array of sectors. There are certain user-space utilities that still expect to be
24654 able to query a disk's geometry, however. In particular, the <i>fdisk </i>tool, which edits
24655 partition tables, depends on cylinder information and does not function properly if
24656 that information is not available.<br>
24657 <br>
24658 We would like the <i>sbull </i>device to be partitionable, even with older, simple-minded
24659 tools. So, we have provided an <i>ioctl </i>method that comes up with a credible fiction for
24660 a geometry that could match the capacity of our device. Most disk drivers do something
24661 similar. Note that, as usual, the sector count is translated, if need be, to match
24662 the 512-byte convention used by the kernel.<br>
24663 <br>
24664 <a name="RequestProcessing"></a><font color="red"><b>Request Processing</b></font><br>
24665 <br>
24666 The core of every block driver is its <i>request </i>function. This function is where the real
24667 work gets done--or at least started; all the rest is overhead. Consequently, we spend
24668 a fair amount of time looking at request processing in block drivers.<br>
24669 <br>
24670 A disk driver's performance can be a critical part of the performance of the system as
24671 a whole. Therefore, the kernel's block subsystem has been written with performance
24672 very much in mind; it does everything possible to enable your driver to get the most
24673 out of the devices it controls. This is a good thing, in that it enables blindingly fast I/O.
24674 On the other hand, the block subsystem unnecessarily exposes a great deal of complexity
24675 in the driver API. It is possible to write a very simple <i>request </i>function (we will
24676 see one shortly), but if your driver must perform at a high level on complex hardware,
24677 it will be anything but simple.<br>
24678 <br>
24679 <a name="IntroductionToTheRequestMethod"></a><font color="red"><b>Introduction to the request Method</b></font><br>
24680 <br>
24681 The block driver <i>request</i> method has the following prototype:<br>
24682 <pre>
24683 void request(request_queue_t *queue);
24684 </pre>
24685 This function is called whenever the kernel believes it is time for your driver to process
24686 some reads, writes, or other operations on the device. The <i>request </i>function does
24687 not need to actually complete all of the requests on the queue before it returns;
24688 indeed, it probably does not complete any of them for most real devices. It must,<br>
24689 <br>
24690 <A name="475"></a><font color="blue">PAGE 475</font><br>
24691 <br>
24692 however, make a start on those requests and ensure that they are all, eventually, processed
24693 by the driver.<br>
24694 <br>
24695 Every device has a request queue. This is because actual transfers to and from a disk
24696 can take place far away from the time the kernel requests them, and because the kernel
24697 needs the flexibility to schedule each transfer at the most propitious moment
24698 (grouping together, for instance, requests that affect sectors close together on the
24699 disk). And the <i>request </i>function, you may remember, is associated with a request
24700 queue when that queue is created. Let us look back at how <i>sbull</i> makes its queue:<br>
24701 <pre>
24702 dev->queue = blk_init_queue(sbull_request, &dev->lock);
24703 </pre>
24704 Thus, when the queue is created, the <i>request </i>function is associated with it. We also
24705 provided a spinlock as part of the queue creation process. Whenever our <i>request
24706 </i>function is called, that lock is held by the kernel. As a result, the <i>request </i>function is
24707 running in an atomic context; it must follow all of the usual rules for atomic code
24708 discussed in Chapter 5.<br>
24709 <br>
24710 The queue lock also prevents the kernel from queuing any other requests for your
24711 device while your <i>request </i>function holds the lock. Under some conditions, you may
24712 want to consider dropping that lock while the <i>request </i>function runs. If you do so,
24713 however, you must be sure not to access the request queue, or any other data structure
24714 protected by the lock, while the lock is not held. You must also reacquire the
24715 lock before the <i>request</i> function returns.<br>
24716 <br>
24717 Finally, the invocation of the <i>request </i>function is (usually) entirely asynchronous with
24718 respect to the actions of any user-space process. You cannot assume that the kernel is
24719 running in the context of the process that initiated the current request. You do not
24720 know if the I/O buffer provided by the request is in kernel or user space. So any sort
24721 of operation that explicitly accesses user space is in error and will certainly lead to
24722 trouble. As you will see, everything your driver needs to know about the request is
24723 contained within the structures passed to you via the request queue.<br>
24724 <br>
24725 <a name="ASimpleRequestMethod"></a><font color="red"><b>A Simple request Method</b></font><br>
24726 <br>
24727 The <i>sbull </i>example driver provides a few different methods for request processing. By
24728 default, <i>sbull </i>uses a method called <i>sbull_request</i>, which is meant to be an example of
24729 the simplest possible <i>request</i> method. Without further ado, here it is:<br>
24730 <pre>
24731 static void sbull_request(request_queue_t *q)
24732 {
24733 struct request *req;
24735 while ((req = elv_next_request(q)) != NULL) {
24736 struct sbull_dev *dev = req->rq_disk->private_data;
24737 if (! blk_fs_request(req)) {
24738 </pre>
24739 <A name="476"></a><font color="blue">PAGE 476</font><br>
24740 <pre>
24741 printk (KERN_NOTICE "Skip non-fs request\n");
24742 end_request(req, 0);
24743 continue;
24744 }
24745 sbull_transfer(dev, req->sector, req->current_nr_sectors,
24746 req->buffer, rq_data_dir(req));
24747 end_request(req, 1);
24748 }
24749 }
24750 </pre>
24751 This function introduces the <font class="fixd">struct request</font> structure. We will
24752 examine <font class="fixd">struct request</font> in great detail later on; for now, suffice
24753 it to say that it represents a block I/O request for us to execute.<br>
24754 <br>
24755 The kernel provides the function <i>elv_next_request </i>to obtain the first incomplete
24756 request on the queue; that function returns <font class="fixd">NULL</font> when there are no requests to be
24757 processed. Note that <i>elv_next_request </i>does not remove the request from the queue. If
24758 you call it twice with no intervening operations, it returns the same request structure
24759 both times. In this simple mode of operation, requests are taken off the queue
24760 only when they are complete.<br>
24761 <br>
24762 A block request queue can contain requests that do not actually move blocks to and
24763 from a disk. Such requests can include vendor-specific, low-level diagnostics operations
24764 or instructions relating to specialized device modes, such as the packet writing mode for
24765 recordable media. Most block drivers do not know how to handle such requests and
24766 simply fail them; <i>sbull </i>works in this way as well. The call to <i>block_fs_request </i>tells us
24767 whether we are looking at a filesystem request--one that moves blocks of data. If a
24768 request is not a filesystem request, we pass it to <i>end_request</i>:<br>
24769 <pre>
24770 void end_request(struct request *req, int succeeded);
24771 </pre>
24772 When we dispose of nonfilesystem requests, we pass <font class="fixd">succeeded</font> as <font class="fixd">0</font> to indicate that
24773 we did not successfully complete the request. Otherwise, we call <i>sbull_transfer </i>to
24774 actually move the data, using a set of fields provided in the <font class="fixd">request</font> structure:<br>
24775 <br>
24776 <font class="fixd">sector_t sector;</font><br>
24777 <div class="bq">
24778 The index of the beginning sector on our device. Remember that this sector
24779 number, like all such numbers passed between the kernel and the driver, is
24780 expressed in 512-byte sectors. If your hardware uses a different sector size, you
24781 need to scale <font class="fixd">sector</font> accordingly. For example, if the hardware uses 2048-byte
24782 sectors, you need to divide the beginning sector number by four before putting it
24783 into a request for the hardware.</div>
24784 <br>
24785 <font class="fixd">unsigned long nr_sectors;</font><br>
24786 <div class="bq">
24787 The number of (512-byte) sectors to be transferred.</div>
24788 <br>
24789 <A name="477"></a><font color="blue">PAGE 477</font><br>
24790 <br>
24791 <font class="fixd">char *buffer;</font><br>
24792 <div class="bq">
24793 A pointer to the buffer to or from which the data should be transferred. This
24794 pointer is a kernel virtual address and can be dereferenced directly by the driver
24795 if need be.</div>
24796 <br>
24797 <font class="fixd">rq_data_dir(struct request *req);</font><br>
24798 <div class="bq">
24799 This macro extracts the direction of the transfer from the request; a zero return
24800 value denotes a read from the device, and a nonzero return value denotes a write
24801 to the device.</div>
24802 <br>
24803 Given this information, the <i>sbull </i>driver can implement the actual data transfer with a
24804 simple <i>memcpy </i>call--our data is already in memory, after all. The function that performs
24805 this copy operation (<i>sbull_transfer</i>) also handles the scaling of sector sizes and
24806 ensures that we do not try to copy beyond the end of our virtual device:<br>
24807 <pre>
24808 static void sbull_transfer(struct sbull_dev *dev, unsigned long sector,
24809 unsigned long nsect, char *buffer, int write)
24810 {
24811 unsigned long offset = sector*KERNEL_SECTOR_SIZE;
24812 unsigned long nbytes = nsect*KERNEL_SECTOR_SIZE;
24814 if ((offset + nbytes) > dev->size) {
24815 printk (KERN_NOTICE "Beyond-end write (%ld %ld)\n", offset, nbytes);
24816 return;
24817 }
24818 if (write)
24819 memcpy(dev->data + offset, buffer, nbytes);
24820 else
24821 memcpy(buffer, dev->data + offset, nbytes);
24822 }
24823 </pre>
24824 With the code, <i>sbull </i>implements a complete, simple RAM-based disk device. It is
24825 not, however, a realistic driver for many types of devices, for a couple of reasons.<br>
24826 <br>
24827 The first of those reasons is that <i>sbull </i>executes requests synchronously, one at a time.
24828 High-performance disk devices are capable of having numerous requests outstanding
24829 at the same time; the disk's onboard controller can then choose to execute them
24830 in the optimal order (one hopes). As long as we process only the first request in the
24831 queue, we can never have multiple requests being fulfilled at a given time. Being able
24832 to work with more than one request requires a deeper understanding of request
24833 queues and the <font class="fixd">request</font> structure; the next few sections help build that understanding.<br>
24834 <br>
24835 There is another issue to consider, however. The best performance is obtained from
24836 disk devices when the system performs large transfers involving multiple sectors that
24837 are located together on the disk. The highest cost in a disk operation is always the
24838 positioning of the read and write heads; once that is done, the time required to actually
24839 read or write the data is almost insignificant. The developers who design and
24840 implement filesystems and virtual memory subsystems understand this, so they do
24841 their best to locate related data contiguously on the disk and to transfer as many sectors
24842 as possible in a single request. The block subsystem also helps in this regard;<br>
24843 <br>
24844 <A name="478"></a><font color="blue">PAGE 478</font><br>
24845 <br>
24846 request queues contain a great deal of logic aimed at finding adjacent requests and
24847 coalescing them into larger operations.<br>
24848 <br>
24849 The <i>sbull </i>driver, however, takes all that work and simply ignores it. Only one buffer
24850 is transferred at a time, meaning that the largest single transfer is almost never going
24851 to exceed the size of a single page. A block driver can do much better than that, but
24852 it requires a deeper understanding of <font class="fixd">request</font> structures and the <font class="fixd">bio</font> structures from
24853 which requests are built.<br>
24854 <br>
24855 The next few sections delve more deeply into how the block layer does its job and
24856 the data structures that result from that work.<br>
24857 <br>
24858 <a name="RequestQueues"></a><font color="red"><b>Request Queues</b></font><br>
24859 <br>
24860 In the simplest sense, a block request queue is exactly that: a queue of block I/O
24861 requests. If you look under the hood, a request queue turns out to be a surprisingly
24862 complex data structure. Fortunately, drivers need not worry about most of that
24863 complexity.<br>
24864 <br>
24865 Request queues keep track of outstanding block I/O requests. But they also play a
24866 crucial role in the creation of those requests. The request queue stores parameters
24867 that describe what kinds of requests the device is able to service: their maximum size,
24868 how many separate segments may go into a request, the hardware sector size, alignment
24869 requirements, etc. If your request queue is properly configured, it should never
24870 present you with a request that your device cannot handle.<br>
24871 <br>
24872 Request queues also implement a plug-in interface that allows the use of multiple <i>I/O
24873 schedulers </i>(or <i>elevators</i>) to be used. An I/O scheduler's job is to present I/O requests
24874 to your driver in a way that maximizes performance. To this end, most I/O schedulers
24875 accumulate a batch of requests, sort them into increasing (or decreasing) block
24876 index order, and present the requests to the driver in that order. The disk head,
24877 when given a sorted list of requests, works its way from one end of the disk to the
24878 other, much like a full elevator moves in a single direction until all of its "requests"
24879 (people waiting to get off) have been satisfied. The 2.6 kernel includes a "deadline
24880 scheduler," which makes an effort to ensure that every request is satisfied within a
24881 preset maximum time, and an "anticipatory scheduler," which actually stalls a device
24882 briefly after a read request in anticipation that another, adjacent read will arrive
24883 almost immediately. As of this writing, the default scheduler is the anticipatory
24884 scheduler, which seems to give the best interactive system performance.<br>
24885 <br>
24886 The I/O scheduler is also charged with merging adjacent requests. When a new I/O
24887 request is handed to the scheduler, it searches the queue for requests involving adjacent
24888 sectors; if one is found and if the resulting request would not be too large, the
24889 two requests are merged.<br>
24890 <br>
24891 Request queues have a type of struct <font class="fixd">request_queue</font> or <font class="fixd">request_queue_t</font>. This type,
24892 and the many functions that operate on it, are defined in <i><linux/blkdev.h></i>. If you are<br>
24893 <br>
24894 <A name="479"></a><font color="blue">PAGE 479</font><br>
24895 <br>
24896 interested in the implementation of request queues, you can find most of the code in
24897 <i>drivers/block/ll_rw_block.c</i> and <i>elevator.c</i>.<br>
24898 <br>
24899 <a name="QueueCreationAndDeletion"></a><font color="red"><b>Queue creation and deletion</b></font><br>
24900 <br>
24901 As we saw in our example code, a request queue is a dynamic data structure that
24902 must be created by the block I/O subsystem. The function to create and initialize a
24903 request queue is:<br>
24904 <pre>
24905 request_queue_t *blk_init_queue(request_fn_proc *request, spinlock_t *lock);
24906 </pre>
24907 The arguments are, of course, the <i>request </i>function for this queue and a spinlock that
24908 controls access to the queue. This function allocates memory (quite a bit of memory,
24909 actually) and can fail because of this; you should always check the return value
24910 before attempting to use the queue.<br>
24911 <br>
24912 As part of the initialization of a request queue, you can set the field <font class="fixd">queuedata</font> (which
24913 is a <font class="fixd">void *</font> pointer) to any value you like. This field is the request queue's equivalent
24914 to the <font class="fixd">private_data</font> we have seen in other structures.<br>
24915 <br>
24916 To return a request queue to the system (at module unload time, generally), call
24917 <i>blk_cleanup_queue</i>:<br>
24918 <pre>
24919 void blk_cleanup_queue(request_queue_t *);
24920 </pre>
24921 After this call, your driver sees no more requests from the given queue and should
24922 not reference it again.<br>
24923 <br>
24924 <a name="QueueingFunctions"></a><font color="red"><b>Queueing functions</b></font><br>
24925 <br>
24926 There is a very small set of functions for the manipulation of requests on queues--at
24927 least, as far as drivers are concerned. You must hold the queue lock before you call
24928 these functions.<br>
24929 <br>
24930 The function that returns the next request to process is <i>elv_next_request</i>:<br>
24931 <pre>
24932 struct request *elv_next_request(request_queue_t *queue);
24933 </pre>
24934 We have already seen this function in the simple <i>sbull </i>example. It returns a pointer
24935 to the next request to process (as determined by the I/O scheduler) or <font class="fixd">NULL</font> if no
24936 more requests remain to be processed. <i>elv_next_request </i>leaves the request on the
24937 queue but marks it as being active; this mark prevents the I/O scheduler from
24938 attempting to merge other requests with this one once you start to execute it.<br>
24939 <br>
24940 To actually remove a request from a queue, use <i>blkdev_dequeue_request</i>:<br>
24941 <pre>
24942 void blkdev_dequeue_request(struct request *req);
24943 </pre>
24944 If your driver operates on multiple requests from the same queue simultaneously, it
24945 must dequeue them in this manner.<br>
24946 <br>
24947 <A name="480"></a><font color="blue">PAGE 480</font><br>
24948 <br>
24949 Should you need to put a dequeued request back on the queue for some reason, you
24950 can call:<br>
24951 <pre>
24952 void elv_requeue_request(request_queue_t *queue, struct request *req);
24953 </pre>
24954 <a name="QueueControlFunctions"></a><font color="red"><b>Queue control functions</b></font><br>
24955 <br>
24956 The block layer exports a set of functions that can be used by a driver to control how
24957 a request queue operates. These functions include:<br>
24958 <br>
24959 <font class="fixd">void blk_stop_queue(request_queue_t *queue);<br>
24960 void blk_start_queue(request_queue_t *queue);</font><br>
24961 <div class="bq">
24962 If your device has reached a state where it can handle no more outstanding commands,
24963 you can call <i>blk_stop_queue </i>to tell the block layer. After this call, your
24964 <i>request </i>function will not be called until you call <i>blk_start_queue</i>. Needless to say,
24965 you should not forget to restart the queue when your device can handle more
24966 requests. The queue lock must be held when calling either of these functions.</div>
24967 <br>
24968 <font class="fixd">void blk_queue_bounce_limit(request_queue_t *queue, u64 dma_addr);</font><br>
24969 <div class="bq">
24970 Function that tells the kernel the highest physical address to which your device
24971 can perform DMA. If a request comes in containing a reference to memory above
24972 the limit, a bounce buffer will be used for the operation; this is, of course, an
24973 expensive way to perform block I/O and should be avoided whenever possible.
24974 You can provide any reasonable physical address in this argument, or make use
24975 of the predefined symbols <font class="fixd">BLK_BOUNCE_HIGH</font> (use bounce buffers for high-memory
24976 pages), <font class="fixd">BLK_BOUNCE_ISA</font> (the driver can DMA only into the 16-MB ISA zone),
24977 or <font class="fixd">BLK_BOUNCE_ANY</font> (the driver can perform DMA to any address). The default
24978 value is <font class="fixd">BLK_BOUNCE_HIGH</font>.</div>
24979 <br>
24980 <font class="fixd">void blk_queue_max_sectors(request_queue_t *queue, unsigned short max);<br>
24981 void blk_queue_max_phys_segments(request_queue_t *queue, unsigned short max);<br>
24982 void blk_queue_max_hw_segments(request_queue_t *queue, unsigned short max);<br>
24983 void blk_queue_max_segment_size(request_queue_t *queue, unsigned int max);</font><br>
24984 <div class="bq">
24985 Functions that set parameters describing the requests that can be satisfied by this
24986 device. <i>blk_queue_max_sectors </i>can be used to set the maximum size of any
24987 request in (512-byte) sectors; the default is 255. <i>blk_queue_max_phys_segments
24988 </i>and <i>blk_queue_max_hw_segments </i>both control how many physical segments
24989 (nonadjacent areas in system memory) may be contained within a single request.
24990 Use <i>blk_queue_max_phys_segments </i>to say how many segments your driver is
24991 prepared to cope with; this may be the size of a staticly allocated scatterlist, for
24992 example. <i>blk_queue_max_hw_segments</i>, in contrast, is the maximum number of
24993 segments that the device itself can handle. Both of these parameters default to
24994 128. Finally, <i>blk_queue_max_segment_size </i>tells the kernel how large any individual
24995 segment of a request can be in bytes; the default is 65,536 bytes.</div>
24996 <br>
24997 <A name="481"></a><font color="blue">PAGE 481</font><br>
24998 <br>
24999 <font class="fixd">blk_queue_segment_boundary(request_queue_t *queue, unsigned long mask);</font><br>
25000 <div class="bq">
25001 Some devices cannot handle requests that cross a particular size memory boundary;
25002 if your device is one of those, use this function to tell the kernel about that
25003 boundary. For example, if your device has trouble with requests that cross a 4MB
25004 boundary, pass in a mask of <font class="fixd">0x3fffff.</font> The default mask is <font class="fixd">0xffffffff</font>.</div>
25005 <br>
25006 <font class="fixd">void blk_queue_dma_alignment(request_queue_t *queue, int mask);</font><br>
25007 <div class="bq">
25008 Function that tells the kernel about the memory alignment constraints your
25009 device imposes on DMA transfers. All requests are created with the given alignment,
25010 and the length of the request also matches the alignment. The default
25011 mask is <font class="fixd">0x1ff,</font> which causes all requests to be aligned on 512-byte boundaries.</div>
25012 <br>
25013 <font class="fixd">void blk_queue_hardsect_size(request_queue_t *queue, unsigned short max);</font><br>
25014 <div class="bq">
25015 Tells the kernel about your device's hardware sector size. All requests generated
25016 by the kernel are a multiple of this size and are properly aligned. All communications
25017 between the block layer and the driver continues to be expressed in 512 byte
25018 sectors, however.</div>
25019 <br>
25020 <a name="TheAnatomyOfARequest"></a><font color="red"><b>The Anatomy of a Request</b></font><br>
25021 <br>
25022 In our simple example, we encountered the <font class="fixd">request</font> structure. However, we have
25023 barely scratched the surface of that complicated data structure. In this section, we
25024 look, in some detail, at how block I/O requests are represented in the Linux kernel.<br>
25025 <br>
25026 Each <font class="fixd">request</font> structure represents one block I/O request, although it may have been
25027 formed through a merger of several independent requests at a higher level. The sectors
25028 to be transferred for any particular request may be distributed throughout main
25029 memory, although they always correspond to a set of consecutive sectors on the
25030 block device. The request is represented as a set of segments, each of which corresponds
25031 to one in-memory buffer. The kernel may join multiple requests that involve
25032 adjacent sectors on the disk, but it never combines read and write operations within
25033 a single <font class="fixd">request</font> structure. The kernel also makes sure not to combine requests if the
25034 result would violate any of the request queue limits described in the previous section.<br>
25035 <br>
25036 A <font class="fixd">request</font> structure is implemented, essentially, as a linked list of <font class="fixd">bio</font> structures combined
25037 with some housekeeping information to enable the driver to keep track of its
25038 position as it works through the request. The <font class="fixd">bio</font> structure is a low-level description
25039 of a portion of a block I/O request; we take a look at it now.<br>
25040 <br>
25041 <a name="TheBioStructure"></a><font color="red"><b>The <font class="fixd">bio</font> structure</b></font><br>
25042 <br>
25043 When the kernel, in the form of a filesystem, the virtual memory subsystem, or a system
25044 call, decides that a set of blocks must be transferred to or from a block I/O
25045 device; it puts together a <font class="fixd">bio</font> structure to describe that operation. That structure is
25046 then handed to the block I/O code, which merges it into an existing <font class="fixd">request</font> structure
25047 or, if need be, creates a new one. The <font class="fixd">bio</font> structure contains everything that a<br>
25048 <br>
25049 <A name="482"></a><font color="blue">PAGE 482</font><br>
25050 <br>
25051 block driver needs to carry out the request without reference to the user-space process
25052 that caused that request to be initiated.<br>
25053 <br>
25054 The <font class="fixd">bio</font> structure, which is defined in <i><linux/bio.h></i>, contains a number of fields that
25055 may be of use to driver authors:<br>
25056 <br>
25057 <font class="fixd">sector_t bi_sector;</font><br>
25058 <div class="bq">
25059 The first (512-byte) sector to be transferred for this <font class="fixd">bio.</font></div>
25060 <br>
25061 <font class="fixd">unsigned int bi_size;</font><br>
25062 <div class="bq">
25063 The size of the data to be transferred, in bytes. Instead, it is often easier to use
25064 <font class="fixd">bio_sectors(bio),</font> a macro that gives the size in sectors.</div>
25065 <br>
25066 <font class="fixd">unsigned long bi_flags;</font><br>
25067 <div class="bq">
25068 A set of flags describing the <font class="fixd">bio;</font> the least significant bit is set if this is a write
25069 request (although the macro <font class="fixd">bio_data_dir(bio)</font> should be used instead of looking
25070 at the flags directly).</div>
25071 <br>
25072 <font class="fixd">unsigned short bio_phys_segments;
25073 unsigned short bio_hw_segments;</font><br>
25074 <div class="bq">
25075 The number of physical segments contained within this BIO and the number of
25076 segments seen by the hardware after DMA mapping is done, respectively.</div>
25077 <br>
25078 The core of a bio, however, is an array called <font class="fixd">bi_io_vec,</font> which is made up of the following
25079 structure:<br>
25080 <pre>
25081 struct bio_vec {
25082 struct page *bv_page;
25083 unsigned int bv_len;
25084 unsigned int bv_offset;
25085 };
25086 </pre>
25087 Figure 16-1 shows how these structures all tie together. As you can see, by the time a
25088 block I/O request is turned into a <font class="fixd">bio</font> structure, it has been broken down into individual
25089 pages of physical memory. All a driver needs to do is to step through this array
25090 of structures (there are <font class="fixd">bi_vcnt</font> of them), and transfer data within each page (but
25091 only len bytes starting at <font class="fixd">offset</font>).<br>
25092 <br><br>
25093 <center>
25094 <img src="fig16-1.gif">
25095 </center>
25096 <br>
25097 <i>Figure 16-1. The bio structure</i><br>
25098 <br>
25099 <A name="483"></a><font color="blue">PAGE 483</font><br>
25100 <br>
25101 Working directly with the <font class="fixd">bi_io_vec</font> array is discouraged in the interest of kernel
25102 developers being able to change the <font class="fixd">bio</font> structure in the future without breaking
25103 things. To that end, a set of macros has been provided to ease the process of working
25104 with the <font class="fixd">bio</font> structure. The place to start is with <font class="fixd">bio_for_each_segment,</font> which
25105 simply loops through every unprocessed entry in the <font class="fixd">bi_io_vec</font> array. This macro
25106 should be used as follows:<br>
25107 <pre>
25108 int segno;
25109 struct bio_vec *bvec;
25111 bio_for_each_segment(bvec, bio, segno) {
25112 /* Do something with this segment
25113 }<br>
25114 </pre>
25115 Within this loop, <font class="fixd">bvec</font> points to the current <font class="fixd">bio_vec</font> entry, and <font class="fixd">segno</font> is the current
25116 segment number. These values can be used to set up DMA transfers (an alternative
25117 way using <i>blk_rq_map_sg </i>is described in the section "Block requests and DMA"). If
25118 you need to access the pages directly, you should first ensure that a proper kernel virtual
25119 address exists; to that end, you can use:<br>
25120 <pre>
25121 char *__bio_kmap_atomic(struct bio *bio, int i, enum km_type type);
25122 void __bio_kunmap_atomic(char *buffer, enum km_type type);
25123 </pre>
25124 This low-level function allows you to directly map the buffer found in a given <font class="fixd">bio_vec,</font>
25125 as indicated by the index <font class="fixd">i.</font> An atomic kmap is created; the caller must provide the
25126 appropriate slot to use (as described in the section "The Memory Map and Struct
25127 Page" in Chapter 15).<br>
25128 <br>
25129 The block layer also maintains a set of pointers within the <font class="fixd">bio</font> structure to keep track
25130 of the current state of request processing. Several macros exist to provide access to
25131 that state:<br>
25132 <br>
25133 <font class="fixd">struct page *bio_page(struct bio *bio);</font><br>
25134 <div class="bq">
25135 Returns a pointer to the page structure representing the page to be transferred next.</div>
25136 <br>
25137 <font class="fixd">int bio_offset(struct bio *bio);</font><br>
25138 <div class="bq">
25139 Returns the offset within the page for the data to be transferred.</div>
25140 <br>
25141 <font class="fixd">int bio_cur_sectors(struct bio *bio);</font><br>
25142 <div class="bq">
25143 Returns the number of sectors to be transferred out of the current page.</div>
25144 <br>
25145 <font class="fixd">char *bio_data(struct bio *bio);</font><br>
25146 <div class="bq">
25147 Returns a kernel logical address pointing to the data to be transferred. Note that
25148 this address is available only if the page in question is not located in high memory;
25149 calling it in other situations is a bug. By default, the block subsystem does
25150 not pass high-memory buffers to your driver, but if you have changed that setting
25151 with <i>blk_queue_bounce_limit</i>, you probably should not be using <font class="fixd">bio_data</font>.</div>
25152 <br>
25153 <A name="484"></a><font color="blue">PAGE 484</font><br>
25154 <br>
25155 <font class="fixd">char *bio_kmap_irq(struct bio *bio, unsigned long *flags);<br>
25156 void bio_kunmap_irq(char *buffer, unsigned long *flags);</font><br>
25157 <div class="bq">
25158 <i>bio_kmap_irq </i>returns a kernel virtual address for any buffer, regardless of
25159 whether it resides in high or low memory. An atomic kmap is used, so your
25160 driver cannot sleep while this mapping is active. Use <i>bio_kunmap_irq </i>to unmap
25161 the buffer. Note that the <font class="fixd">flags</font> argument is passed by pointer here. Note also
25162 that since an atomic kmap is used, you cannot map more than one segment at a
25163 time.</div>
25164 <br>
25165 All of the functions just described access the "current" buffer--the first buffer that,
25166 as far as the kernel knows, has not been transferred. Drivers often want to work
25167 through several buffers in the <font class="fixd">bio</font> before signaling completion on any of them (with
25168 <i>end_that_request_first</i>, to be described shortly), so these functions are often not useful.
25169 Several other macros exist for working with the internals of the <font class="fixd">bio</font> structure (see
25170 <i><linux/bio.h></i> for details).<br>
25171 <br>
25172 <a name="RequestStructureFields"></a><font color="red"><b><font class="fixd">request</font> structure fields</b></font><br>
25173 <br>
25174 Now that we have an idea of how the <font class="fixd">bio</font> structure works, we can get deep into
25175 <font class="fixd">struct request</font> and see how request processing works. The fields of this structure
25176 include:<br>
25177 <br>
25178 <font class="fixd">sector_t hard_sector;<br>
25179 unsigned long hard_nr_sectors;<br>
25180 unsigned int hard_cur_sectors;</font><br>
25181 <div class="bq">
25182 Fields that track the sectors that the driver has yet to complete. The first sector
25183 that has <i>not </i>been transferred is stored in <font class="fixd">hard_sector,</font> the total number of sectors
25184 yet to transfer is in <font class="fixd">hard_nr_sectors,</font> and the number of sectors remaining in
25185 the current bio is <font class="fixd">hard_cur_sectors</font>. These fields are intended for use only within
25186 the block subsystem; drivers should not make use of them.</div>
25187 <br>
25188 <font class="fixd">struct bio *bio;</font><br>
25189 <div class="bq">
25190 bio is the linked list of <font class="fixd">bio</font> structures for this request. You should not access this
25191 field directly; use <i>rq_for_each_bio</i> (described later) instead.</div>
25192 <br>
25193 <font class="fixd">char *buffer;</font><br>
25194 <div class="bq">
25195 The simple driver example earlier in this chapter used this field to find the buffer
25196 for the transfer. With our deeper understanding, we can now see that this field is
25197 simply the result of calling <i>bio_data</i> on the current <font class="fixd">bio.</font></div>
25198 <br>
25199 <font class="fixd">unsigned short nr_phys_segments;</font><br>
25200 <div class="bq">
25201 The number of distinct segments occupied by this request in physical memory
25202 after adjacent pages have been merged.</div>
25203 <br>
25204 <font class="fixd">struct list_head queuelist;</font><br>
25205 <div class="bq">
25206 The linked-list structure (as described in the section "Linked Lists" in
25207 Chapter 11) that links the request into the request queue. If (and only if) you</div>
25208 <br>
25209 <A name="485"></a><font color="blue">PAGE 485</font><br>
25210 <br>
25211 <div class="bq">remove the request from the queue with <i>blkdev_dequeue_request</i>, you may use
25212 this list head to track the request in an internal list maintained by your driver.</div>
25213 <br>
25214 Figure 16-2 shows how the <font class="fixd">request</font> structure and its component <font class="fixd">bio</font> structures fit
25215 together. In the figure, the request has been partially satisfied; the <font class="fixd">cbio</font> and <font class="fixd">buffer</font>
25216 fields point to the first <font class="fixd">bio</font> that has not yet been transferred.<br>
25217 <br><br>
25218 <center>
25219 <img src="fig16-2.gif">
25220 </center>
25221 <br>
25222 <i>Figure 16-2. A request queue with a partially processed request</i><br>
25223 <br>
25224 There are many other fields inside the <font class="fixd">request</font> structure, but the list in this section
25225 should be enough for most driver writers.<br>
25226 <br>
25227 <a name="BarrierRequests"></a><font color="red"><b>Barrier requests</b></font><br>
25228 <br>
25229 The block layer reorders requests before your driver sees them to improve I/O performance.
25230 Your driver, too, can reorder requests if there is a reason to do so. Often, this
25231 reordering happens by passing multiple requests to the drive and letting the hardware
25232 figure out the optimal ordering. There is a problem with unrestricted reordering
25233 of requests, however: some applications require guarantees that certain
25234 operations will complete before others are started. Relational database managers, for
25235 example, must be absolutely sure that their journaling information has been flushed
25236 to the drive before executing a transaction on the database contents. Journaling filesystems,
25237 which are now in use on most Linux systems, have very similar ordering
25238 constraints. If the wrong operations are reordered, the result can be severe, undetected
25239 data corruption.<br>
25240 <br>
25241 The 2.6 block layer addresses this problem with the concept of a <i>barrier request</i>. If a
25242 request is marked with the <font class="fixd">REQ_HARDBARRER</font> flag, it must be written to the drive before
25243 any following request is initiated. By "written to the drive," we mean that the data
25244 must actually reside and be persistent on the physical media. Many drives perform
25245 caching of write requests; this caching improves performance, but it can defeat the purpose
25246 of barrier requests. If a power failure occurs when the critical data is still sitting in<br>
25247 <br>
25248 <A name="486"></a><font color="blue">PAGE 486</font><br>
25249 <br>
25250 the drive's cache, that data is still lost even if the drive has reported completion. So a
25251 driver that implements barrier requests must take steps to force the drive to actually
25252 write the data to the media.<br>
25253 <br>
25254 If your driver honors barrier requests, the first step is to inform the block layer of this
25255 fact. Barrier handling is another of the request queues; it is set with:<br>
25256 <pre>
25257 void blk_queue_ordered(request_queue_t *queue, int flag);
25258 </pre>
25259 To indicate that your driver implements barrier requests, set the <font class="fixd">flag</font> parameter to a
25260 nonzero value.<br>
25261 <br>
25262 The actual implementation of barrier requests is simply a matter of testing for the
25263 associated flag in the <font class="fixd">request</font> structure. A macro has been provided to perform this
25264 test:
25265 <pre>
25266 int blk_barrier_rq(struct request *req);
25267 </pre>
25268 If this macro returns a nonzero value, the request is a barrier request. Depending on
25269 how your hardware works, you may have to stop taking requests from the queue
25270 until the barrier request has been completed. Other drives can understand barrier
25271 requests themselves; in this case, all your driver has to do is to issue the proper operations
25272 for those drives.<br>
25273 <br>
25274 <a name="NonretryableRequests"></a><font color="red"><b>Nonretryable requests</b></font><br>
25275 <br>
25276 Block drivers often attempt to retry requests that fail the first time. This behavior can
25277 lead to a more reliable system and help to avoid data loss. The kernel, however,
25278 sometimes marks requests as not being retryable. Such requests should simply fail as
25279 quickly as possible if they cannot be executed on the first try.<br>
25280 <br>
25281 If your driver is considering retrying a failed request, it should first make a call to:<br>
25282 <pre>
25283 int blk_noretry_request(struct request *req);
25284 </pre>
25285 If this macro returns a nonzero value, your driver should simply abort the request
25286 with an error code instead of retrying it.<br>
25287 <br>
25288 <a name="RequestCompletionFunctions"></a><font color="red"><b>Request Completion Functions</b></font><br>
25289 <br>
25290 There are, as we will see, several different ways of working through a <font class="fixd">request</font> structure.
25291 All of them make use of a couple of common functions, however, which handle
25292 the completion of an I/O request or parts of a request. Both of these functions are
25293 atomic and can be safely called from an atomic context.<br>
25294 <br>
25295 When your device has completed transferring some or all of the sectors in an I/O
25296 request, it must inform the block subsystem with:<br>
25297 <pre>
25298 int end_that_request_first(struct request *req, int success, int count);
25299 </pre>
25300 This function tells the block code that your driver has finished with the transfer of
25301 <font class="fixd">count</font> sectors starting where you last left off. If the I/O was successful, pass <font class="fixd">success</font><br>
25302 <br>
25303 <A name="487"></a><font color="blue">PAGE 487</font><br>
25304 <br>
25305 as 1; otherwise pass 0. Note that you must signal completion in order from the first
25306 sector to the last; if your driver and device somehow conspire to complete requests
25307 out of order, you have to store the out-of-order completion status until the intervening
25308 sectors have been transferred.<br>
25309 <br>
25310 The return value from <i>end_that_request_first </i>is an indication of whether all sectors in
25311 this request have been transferred or not. A return value of 0 means that all sectors
25312 have been transferred and that the request is complete. At that point, you must
25313 dequeue the request with <i>blkdev_dequeue_request </i>(if you have not already done so)
25314 and pass it to:<br>
25315 <pre>
25316 void end_that_request_last(struct request *req);
25317 </pre>
25318 <i>end_that_request_last </i>informs whoever is waiting for the request that it has completed
25319 and recycles the <font class="fixd">request</font> structure; it must be called with the queue lock held.<br>
25320 <br>
25321 In our simple <i>sbull </i>example, we didn't use any of the above functions. That example,
25322 instead, is called <i>end_request</i>. To show the effects of this call, here is the entire
25323 <i>end_request</i> function as seen in the 2.6.10 kernel:<br>
25324 <pre>
25325 void end_request(struct request *req, int uptodate)
25326 {
25327 if (!end_that_request_first(req, uptodate, req->hard_cur_sectors)) {
25328 add_disk_randomness(req->rq_disk);
25329 blkdev_dequeue_request(req);
25330 end_that_request_last(req);
25331 }
25332 }
25333 </pre>
25334 The function <i>add_disk_randomness </i>uses the timing of block I/O requests to contribute
25335 entropy to the system's random number pool; it should be called only if the disk's
25336 timing is truly random. That is true for most mechanical devices, but it is not true for
25337 a memory-based virtual device, such as <i>sbull</i>. For this reason, the more complicated
25338 version of <i>sbull</i> shown in the next section does not call <i>add_disk_randomness</i>.<br>
25339 <br>
25340 <a name="WorkingWithBios"></a><font color="red"><b>Working with bios</b></font><br>
25341 <br>
25342 You now know enough to write a block driver that works directly with the <font class="fixd">bio</font> structures
25343 that make up a request. An example might help, however. If the <i>sbull </i>driver is
25344 loaded with the <font class="fixd">request_mode</font> parameter set to <font class="fixd">1,</font> it registers a <font class="fixd">bio-aware</font> <i>request </i>function
25345 instead of the simple function we saw above. That function looks like this:<br>
25346 <pre>
25347 static void sbull_full_request(request_queue_t *q)
25348 {
25349 struct request *req;
25350 int sectors_xferred;
25351 struct sbull_dev *dev = q->queuedata;
25353 while ((req = elv_next_request(q)) != NULL) {
25354 if (! blk_fs_request(req)) {
25355 printk (KERN_NOTICE "Skip non-fs request\n");
25356 </pre>
25357 <A name="488"></a><font color="blue">PAGE 488</font><br>
25358 <pre>
25359 end_request(req, 0);
25360 continue;
25361 }
25362 sectors_xferred = sbull_xfer_request(dev, req);
25363 if (! end_that_request_first(req, 1, sectors_xferred)) {
25364 blkdev_dequeue_request(req);
25365 end_that_request_last(req);
25366 }
25367 }
25368 }
25369 </pre>
25370 This function simply takes each request, passes it to <i>sbull_xfer_request</i>, then completes
25371 it with <i>end_that_request_first </i>and, if necessary, <i>end_that_request_last</i>. Thus,
25372 this function is handling the high-level queue and request management parts of the
25373 problem. The job of actually executing a request, however, falls to <i>sbull_xfer_request</i>:<br>
25374 <pre>
25375 static int sbull_xfer_request(struct sbull_dev *dev, struct request *req)
25376 {
25377 struct bio *bio;
25378 int nsect = 0;
25380 rq_for_each_bio(bio, req) {
25381 sbull_xfer_bio(dev, bio);
25382 nsect += bio->bi_size/KERNEL_SECTOR_SIZE;
25383 }
25384 return nsect;
25385 }
25386 </pre>
25387 Here we introduce another macro: <i>rq_for_each_bio</i>. As you might expect, this macro
25388 simply steps through each <font class="fixd">bio</font> structure in the request, giving us a pointer that we
25389 can pass to <i>sbull_xfer_bio</i> for the transfer. That function looks like:<br>
25390 <pre>
25391 static int sbull_xfer_bio(struct sbull_dev *dev, struct bio *bio)
25392 {
25393 int i;
25394 struct bio_vec *bvec;
25395 sector_t sector = bio->bi_sector;
25397 /* Do each segment independently. */
25398 bio_for_each_segment(bvec, bio, i) {
25399 char *buffer = __bio_kmap_atomic(bio, i, KM_USER0);
25400 sbull_transfer(dev, sector, bio_cur_sectors(bio),
25401 buffer, bio_data_dir(bio) = = WRITE);
25402 sector += bio_cur_sectors(bio);
25403 __bio_kunmap_atomic(bio, KM_USER0);
25404 }
25405 return 0; /* Always "succeed" */
25406 }
25407 </pre>
25408 This function simply steps through each segment in the <font class="fixd">bio</font> structure, gets a kernel
25409 virtual address to access the buffer, then calls the same <i>sbull_transfer </i>function we
25410 saw earlier to copy the data over.<br>
25411 <br>
25412 <A name="489"></a><font color="blue">PAGE 489</font><br>
25413 <br>
25414 Each device has its own needs, but, as a general rule, the code just shown should
25415 serve as a model for many situations where digging through the <font class="fixd">bio</font> structures is
25416 needed.<br>
25417 <br>
25418 <a name="BlockRequestsAndDMA"></a><font color="red"><b>Block requests and DMA</b></font><br>
25419 <br>
25420 If you are working on a high-performance block driver, chances are you will be using
25421 DMA for the actual data transfers. A block driver can certainly step through the <font class="fixd">bio</font> structures,
25422 as described above, create a DMA mapping for each one, and pass the result
25423 to the device. There is an easier way, however, if your device can do scatter/gather I/O.
25424 The function:<br>
25425 <pre>
25426 int blk_rq_map_sg(request_queue_t *queue, struct request *req,
25427 struct scatterlist *list);
25428 </pre>
25429 fills in the given <font class="fixd">list</font> with the full set of segments from the given request. Segments
25430 that are adjacent in memory are coalesced prior to insertion into the scatterlist, so
25431 you need not try to detect them yourself. The return value is the number of entries in
25432 the list. The function also passes back, in its third argument, a scatterlist suitable for
25433 passing to <i>dma_map_sg</i>. (See the section "Scatter-gather mappings" in Chapter 15
25434 for more information on <i>dma_map_sg</i>.)<br>
25435 <br>
25436 Your driver must allocate the storage for the scatterlist before calling <i>blk_rq_map_sg</i>.
25437 The list must be able to hold at least as many entries as the request has physical segments;
25438 the <font class="fixd">struct request</font> field <font class="fixd">nr_phys_segments</font> holds that count, which will not
25439 exceed the maximum number of physical segments specified with <i>blk_queue_max_
25440 phys_segments</i>.<br>
25441 <br>
25442 If you do not want <i>blk_rq_map_sg </i>to coalesce adjacent segments, you can change the
25443 default behavior with a call such as:<br>
25444 <pre>
25445 clear_bit(QUEUE_FLAG_CLUSTER, &queue->queue_flags);
25446 </pre>
25447 Some SCSI disk drivers mark their request queue in this way, since they do not benefit
25448 from the coalescing of requests.<br>
25449 <br>
25450 <a name="DoingWithoutARequestQueue"></a><font color="red"><b>Doing without a request queue</b></font><br>
25451 <br>
25452 Previously, we have discussed the work the kernel does to optimize the order of
25453 requests in the queue; this work involves sorting requests and, perhaps, even stalling
25454 the queue to allow an anticipated request to arrive. These techniques help the system's
25455 performance when dealing with a real, spinning disk drive. They are completely
25456 wasted, however, with a device like <i>sbull</i>. Many block-oriented devices, such
25457 as flash memory arrays, readers for media cards used in digital cameras, and RAM
25458 disks have truly random-access performance and do not benefit from advanced request
25459 queueing logic. Other devices, such as software RAID arrays or virtual disks
25460 created by logical volume managers, do not have the performance characteristics for
25461 which the block layer's request queues are optimized. For this kind of device, it<br>
25462 <br>
25463 <A name="490"></a><font color="blue">PAGE 490</font><br>
25464 <br>
25465 would be better to accept requests directly from the block layer and not bother with
25466 the request queue at all.<br>
25467 <br>
25468 For these situations, the block layer supports a "no queue" mode of operation. To
25469 make use of this mode, your driver must provide a "make request" function, rather
25470 than a <i>request</i> function. The <i>make_request</i> function has this prototype:<br>
25471 <pre>
25472 typedef int (make_request_fn) (request_queue_t *q, struct bio *bio);
25473 </pre>
25474 Note that a request queue is still present, even though it will never actually hold any
25475 requests. The <i>make_request </i>function takes as its main parameter a <font class="fixd">bio</font> structure,
25476 which represents one or more buffers to be transferred. The <i>make_request </i>function
25477 can do one of two things: it can either perform the transfer directly, or it can redirect
25478 the request to another device.<br>
25479 <br>
25480 Performing the transfer directly is just a matter of working through the <font class="fixd">bio</font> with the
25481 accessor methods we described earlier. Since there is no <font class="fixd">request</font> structure to work
25482 with, however, your function should signal completion directly to the creator of the
25483 <font class="fixd">bio</font> structure with a call to <i>bio_endio</i>:<br>
25484 <pre>
25485 void bio_endio(struct bio *bio, unsigned int bytes, int error);
25486 </pre>
25487 Here, <font class="fixd">bytes</font> is the number of bytes you have transferred so far. It can be less than the
25488 number of bytes represented by the <font class="fixd">bio</font> as a whole; in this way, you can signal partial
25489 completion, and update the internal "current buffer" pointers within the <font class="fixd">bio.</font>
25490 You should either call <i>bio_endio </i>again as your device makes further process, or signal
25491 an error if you are unable to complete the request. Errors are indicated by providing
25492 a nonzero value for the <font class="fixd">error</font> parameter; this value is normally an error code such
25493 as <font class="fixd">-EIO.</font> The <i>make_request</i> should return 0, regardless of whether the I/O is successful.<br>
25494 <br>
25495 If <i>sbull </i>is loaded with <font class="fixd">request_mode=2,</font> it operates with a <i>make_request </i>function.
25496 Since <i>sbull </i>already has a function that can transfer a single <font class="fixd">bio,</font> the <i>make_request
25497 </i>function is simple:<br>
25498 <pre>
25499 static int sbull_make_request(request_queue_t *q, struct bio *bio)
25500 {
25501 struct sbull_dev *dev = q->queuedata;
25502 int status;
25504 status = sbull_xfer_bio(dev, bio);
25505 bio_endio(bio, bio->bi_size, status);
25506 return 0;
25507 }
25508 </pre>
25509 Please note that you should never call <i>bio_endio </i>from a regular <i>request </i>function; that
25510 job is handled by <i>end_that_request_first</i> instead.<br>
25511 <br>
25512 Some block drivers, such as those implementing volume managers and software
25513 RAID arrays, really need to redirect the request to another device that handles the
25514 actual I/O. Writing such a driver is beyond the scope of this book. We note, however,
25515 that if the <i>make_request </i>function returns a nonzero value, the <font class="fixd">bio</font> is submitted<br>
25516 <br>
25517 <A name="491"></a><font color="blue">PAGE 491</font><br>
25518 <br>
25519 again. A "stacking" driver can, therefore, modify the <font class="fixd">bi_bdev</font> field to point to a different
25520 device, change the starting sector value, then return; the block system then
25521 passes the <font class="fixd">bio</font> to the new device. There is also a <i>bio_split </i>call that can be used to split
25522 a <font class="fixd">bio</font> into multiple chunks for submission to more than one device. Although if the
25523 queue parameters are set up correctly, splitting a <font class="fixd">bio</font> in this way should almost never
25524 be necessary.<br>
25525 <br>
25526 Either way, you must tell the block subsystem that your driver is using a custom
25527 <i>make_request</i> function. To do so, you must allocate a request queue with:<br>
25528 <pre>
25529 request_queue_t *blk_alloc_queue(int flags);
25530 </pre>
25531 This function differs from <i>blk_init_queue </i>in that it does not actually set up the queue
25532 to hold requests. The <font class="fixd">flags</font> argument is a set of allocation flags to be used in allocating
25533 memory for the queue; usually the right value is <font class="fixd">GFP_KERNEL</font>. Once you have a
25534 queue, pass it and your <i>make_request</i> function to <i>blk_queue_make_request</i>:<br>
25535 <pre>
25536 void blk_queue_make_request(request_queue_t *queue, make_request_fn *func);
25537 </pre>
25538 The <i>sbull</i> code to set up the <i>make_request</i> function looks like:<br>
25539 <pre>
25540 dev->queue = blk_alloc_queue(GFP_KERNEL);
25541 if (dev->queue = = NULL)
25542 goto out_vfree;
25543 blk_queue_make_request(dev->queue, sbull_make_request);
25544 </pre>
25545 For the curious, some time spent digging through <i>drivers/block/ll_rw_block.c </i>shows
25546 that all queues have a <i>make_request </i>function. The default version, <i>generic_make_request</i>,
25547 handles the incorporation of the <font class="fixd">bio</font> into a <font class="fixd">request</font> structure. By providing a
25548 <i>make_request </i>function of its own, a driver is really just overriding a specific <i>request
25549 queue</i> method and sorting out much of the work.<br>
25550 <br>
25551 <a name="SomeOtherDetails"></a><font color="red"><b>Some Other Details</b></font><br>
25552 <br>
25553 This section covers a few other aspects of the block layer that may be of interest for
25554 advanced drivers. None of the following facilities need to be used to write a correct
25555 driver, but they may be helpful in some situations.<br>
25556 <br>
25557 <a name="CommandPrePreparation"></a><font color="red"><b>Command Pre-Preparation</b></font><br>
25558 <br>
25559 The block layer provides a mechanism for drivers to examine and preprocess
25560 requests before they are returned from <i>elv_next_request</i>. This mechanism allows
25561 drivers to set up the actual drive commands ahead of time, decide whether the
25562 request can be handled at all, or perform other sorts of housekeeping.<br>
25563 <br>
25564 If you want to use this feature, create a command preparation function that fits this
25565 prototype:<br>
25566 <pre>
25567 typedef int (prep_rq_fn) (request_queue_t *queue, struct request *req);
25568 </pre>
25569 <A name="492"></a><font color="blue">PAGE 492</font><br>
25570 <br>
25571 The <font class="fixd">request</font> structure includes a field called <font class="fixd">cmd</font>, which is an array of <font class="fixd">BLK_MAX_CDB</font>
25572 bytes; this array may be used by the preparation function to store the actual hardware
25573 command (or any other useful information). This function should return one of
25574 the following values:<br>
25575 <br>
25576 <font class="fixd">BLKPREP_OK</font><br>
25577 <div class="bq">
25578 Command preparation went normally, and the request can be handed to your
25579 driver's <i>request</i> function.</div>
25580 <br>
25581 <font class="fixd">BLKPREP_KILL</font><br>
25582 <div class="bq">
25583 This request cannot be completed; it is failed with an error code.</div>
25584 <br>
25585 <font class="fixd">BLKPREP_DEFER</font><br>
25586 <div class="bq">
25587 This request cannot be completed at this time. It stays at the front of the queue
25588 but is not handed to the <i>request</i> function.</div>
25589 <br>
25590 The preparation function is called by <i>elv_next_request </i>immediately before the
25591 request is returned to your driver. If this function returns <font class="fixd">BLKPREP_DEFER,</font> the return
25592 value from <i>elv_next_request </i>to your driver is <font class="fixd">NULL</font>. This mode of operation can be
25593 useful if, for example, your device has reached the maximum number of requests it
25594 can have outstanding.<br>
25595 <br>
25596 To have the block layer call your preparation function, pass it to:<br>
25597 <pre>
25598 void blk_queue_prep_rq(request_queue_t *queue, prep_rq_fn *func);
25599 </pre>
25600 By default, request queues have no preparation function.<br>
25601 <br>
25602 <a name="TaggedCommandQueueing"></a><font color="red"><b>Tagged Command Queueing</b></font><br>
25603 <br>
25604 Hardware that can have multiple requests active at once usually supports some form
25605 of <i>tagged command queueing </i>(TCQ). TCQ is simply the technique of attaching an
25606 integer "tag" to each request so that when the drive completes one of those requests,
25607 it can tell the driver which one. In previous versions of the kernel, block drivers that
25608 implemented TCQ had to do all of the work themselves; in 2.6, a TCQ support
25609 infrastructure has been added to the block layer for all drivers to use.<br>
25610 <br>
25611 If your drive performs tagged command queueing, you should inform the kernel of
25612 that fact at initialization time with a call to:<br>
25613 <pre>
25614 int blk_queue_init_tags(request_queue_t *queue, int depth,
25615 struct blk_queue_tag *tags);
25616 </pre>
25617 Here, <font class="fixd">queue</font> is your request queue, and <font class="fixd">depth</font> is the number of tagged requests your
25618 device can have outstanding at any given time. <font class="fixd">tags</font> is an optional pointer to an array of
25619 <font class="fixd">struct blk_queue_tag</font> structures; there must be <font class="fixd">depth</font> of them. Normally, <font class="fixd">tags</font> can be
25620 passed as <font class="fixd">NULL</font>, and <i>blk_queue_init_tags </i>allocates the array. If, however, you need to
25621 share the same tags between multiple devices, you can pass the tags array pointer
25622 (stored in the <font class="fixd">queue_tags</font> field) from another request queue. You should never actually<br>
25623 <br>
25624 <A name="493"></a><font color="blue">PAGE 493</font><br>
25625 <br>
25626 allocate the <font class="fixd">tags</font> array yourself; the block layer needs to initialize the array and does
25627 not export the initialization function to modules.<br>
25628 <br>
25629 Since <i>blk_queue_init_tags </i>allocates memory, it can fail; it returns a negative error
25630 code to the caller in that case.<br>
25631 <br>
25632 If the number of tags your device can handle changes, you can inform the kernel
25633 with:<br>
25634 <pre>
25635 int blk_queue_resize_tags(request_queue_t *queue, int new_depth);
25636 </pre>
25637 The queue lock must be held during the call. This call can fail, returning a negative
25638 error code in that case.<br>
25639 <br>
25640 The association of a tag with a <font class="fixd">request</font> structure is done with <i>blk_queue_start_tag</i>,
25641 which must be called with the queue lock held:<br>
25642 <pre>
25643 int blk_queue_start_tag(request_queue_t *queue, struct request *req);
25644 </pre>
25645 If a tag is available, this function allocates it for this request, stores the tag number in
25646 <font class="fixd">req->tag,</font> and returns <font class="fixd">0.</font> It also dequeues the request from the queue and links it into
25647 its own tag-tracking structure, so your driver should take care not to dequeue the
25648 request itself if it's using tags. If no more tags are available, <i>blk_queue_start_tag
25649 </i>leaves the request on the queue and returns a nonzero value.<br>
25650 <br>
25651 When all transfers for a given request have been completed, your driver should
25652 return the tag with:<br>
25653 <pre>
25654 void blk_queue_end_tag(request_queue_t *queue, struct request *req);
25655 </pre>
25656 Once again, you must hold the queue lock before calling this function. The call
25657 should be made after <i>end_that_request_first </i>returns 0 (meaning that the request is
25658 complete) but before calling <i>end_that_request_last</i>. Remember that the request is
25659 already dequeued, so it would be a mistake for your driver to do so at this point.<br>
25660 <br>
25661 If you need to find the request associated with a given tag (when the drive reports
25662 completion, for example), use <i>blk_queue_find_tag</i>:<br>
25663 <pre>
25664 struct request *blk_queue_find_tag(request_queue_t *qeue, int tag);
25665 </pre>
25666 The return value is the associated <font class="fixd">request</font> structure, unless something has gone truly
25667 wrong.<br>
25668 <br>
25669 If things really do go wrong, your driver may find itself having to reset or perform
25670 some other act of violence against one of its devices. In that case, any outstanding
25671 tagged commands will not be completed. The block layer provides a function that
25672 can help with the recovery effort in such situations:<br>
25673 <pre>
25674 void blk_queue_invalidate_tags(request_queue_t *queue);
25675 </pre>
25676 This function returns all outstanding tags to the pool and puts the associated
25677 requests back into the request queue. The queue lock must be held when you call
25678 this function.<br>
25679 <br>
25680 <A name="494"></a><font color="blue">PAGE 494</font><br>
25681 <br>
25682 <a name="QuickReference16"></a><font color="red"><b>Quick Reference</b></font><br>
25683 <br>
25684 <font class="fixd">#include <linux/fs.h><br>
25685 int register_blkdev(unsigned int major, const char *name);<br>
25686 int unregister_blkdev(unsigned int major, const char *name);</font><br>
25687 <div class="bq">
25688 <i>register_blkdev </i>registers a block driver with the kernel and, optionally, obtains a
25689 major number. A driver can be unregistered with <i>unregister_blkdev</i>.</div>
25690 <br>
25691 <font class="fixd">struct block_device_operations</font><br>
25692 <div class="bq">
25693 Structure that holds most of the methods for block drivers.</div>
25694 <br>
25695 <font class="fixd">#include <linux/genhd.h><br>
25696 struct gendisk;</font><br>
25697 <div class="bq">
25698 Structure that describes a single block device within the kernel.</div>
25699 <br>
25700 <font class="fixd">struct gendisk *alloc_disk(int minors);<br>
25701 void add_disk(struct gendisk *gd);</font><br>
25702 <div class="bq">
25703 Functions that allocate <font class="fixd">gendisk</font> structures and return them to the system.</div>
25704 <br>
25705 <font class="fixd">void set_capacity(struct gendisk *gd, sector_t sectors);</font><br>
25706 <div class="bq">
25707 Stores the capacity of the device (in 512-byte sectors) within the <font class="fixd">gendisk</font> structure.</div>
25708 <br>
25709 <font class="fixd">void add_disk(struct gendisk *gd);</font><br>
25710 <div class="bq">
25711 Adds a disk to the kernel. As soon as this function is called, your disk's methods
25712 can be invoked by the kernel.</div>
25713 <br>
25714 <font class="fixd">int check_disk_change(struct block_device *bdev);</font><br>
25715 <div class="bq">
25716 A kernel function that checks for a media change in the given disk drive and
25717 takes the required cleanup action when such a change is detected.</div>
25718 <br>
25719 <font class="fixd">#include <linux/blkdev.h><br>
25720 request_queue_t blk_init_queue(request_fn_proc *request, spinlock_t *lock);<br>
25721 void blk_cleanup_queue(request_queue_t *);</font><br>
25722 <div class="bq">
25723 Functions that handle the creation and deletion of block request queues.</div>
25724 <br>
25725 <font class="fixd">struct request *elv_next_request(request_queue_t *queue);<br>
25726 void end_request(struct request *req, int success);</font><br>
25727 <div class="bq">
25728 <i>elv_next_request </i>obtains the next request from a request queue; <i>end_request </i>may
25729 be used in very simple drivers to mark the completion of (or part of) a request.</div>
25730 <br>
25731 <font class="fixd">void blkdev_dequeue_request(struct request *req);<br>
25732 void elv_requeue_request(request_queue_t *queue, struct request *req);</font><br>
25733 <div class="bq">
25734 Functions that remove a request from a queue and put it back on if necessary.</div>
25735 <br>
25736 <font class="fixd">void blk_stop_queue(request_queue_t *queue);<br>
25737 void blk_start_queue(request_queue_t *queue);</font><br>
25738 <div class="bq">
25739 If you need to prevent further calls to your <i>request </i>method, a call to <i>blk_stop_queue
25740 </i>does the trick. A call to <i>blk_start_queue </i>is necessary to cause your <i>request </i>method
25741 to be invoked again.</div>
25742 <br>
25743 <A name="495"></a><font color="blue">PAGE 495</font><br>
25744 <br>
25745 <font class="fixd">void blk_queue_bounce_limit(request_queue_t *queue, u64 dma_addr);<br>
25746 void blk_queue_max_sectors(request_queue_t *queue, unsigned short max);<br>
25747 void blk_queue_max_phys_segments(request_queue_t *queue, unsigned short max);<br>
25748 void blk_queue_max_hw_segments(request_queue_t *queue, unsigned short max);<br>
25749 void blk_queue_max_segment_size(request_queue_t *queue, unsigned int max);<br>
25750 blk_queue_segment_boundary(request_queue_t *queue, unsigned long mask);<br>
25751 void blk_queue_dma_alignment(request_queue_t *queue, int mask);<br>
25752 void blk_queue_hardsect_size(request_queue_t *queue, unsigned short max);</font><br>
25753 <div class="bq">
25754 Functions that set various queue parameters that control how requests are created
25755 for a particular device; the parameters are described in the section "Queue
25756 control functions."</div>
25757 <br>
25758 <font class="fixd">#include <linux/bio.h><br>
25759 struct bio;</font><br>
25760 <div class="bq">
25761 Low-level structure representing a portion of a block I/O request.</div>
25762 <br>
25763 <font class="fixd">bio_sectors(struct bio *bio);<br>
25764 bio_data_dir(struct bio *bio);</font><br>
25765 <div class="bq">
25766 Two macros that yield the size and direction of a transfer described by a <font class="fixd">bio</font> structure.</div>
25767 <br>
25768 <font class="fixd">bio_for_each_segment(bvec, bio, segno);</font><br>
25769 <div class="bq">
25770 A pseudo-control structure used to loop through the segments that make up a <font class="fixd">bio</font> structure.</div>
25771 <br>
25772 <font class="fixd">char *__bio_kmap_atomic(struct bio *bio, int i, enum km_type type);<br>
25773 void __bio_kunmap_atomic(char *buffer, enum km_type type);</font><br>
25774 <div class="bq">
25775 <i>__bio_kmap_atomic </i>may be used to create a kernel virtual address for a given
25776 segment within a <font class="fixd">bio</font> structure. The mapping must be
25777 undone with <i>__bio_kunmap_atomic</i>.</div>
25778 <br>
25779 <font class="fixd">struct page *bio_page(struct bio *bio);<br>
25780 int bio_offset(struct bio *bio);<br>
25781 int bio_cur_sectors(struct bio *bio);<br>
25782 char *bio_data(struct bio *bio);<br>
25783 char *bio_kmap_irq(struct bio *bio, unsigned long *flags);<br>
25784 void bio_kunmap_irq(char *buffer, unsigned long *flags);</font><br>
25785 <div class="bq">
25786 A set of accessor macros that provide access to the "current" segment within a
25787 <font class="fixd">bio</font> structure.</div>
25788 <br>
25789 <font class="fixd">void blk_queue_ordered(request_queue_t *queue, int flag);<br>
25790 int blk_barrier_rq(struct request *req);</font><br>
25791 <div class="bq">
25792 Call <i>blk_queue_ordered </i>if your driver implements barrier requests--as it should.
25793 The macro <i>blk_barrier_rq </i>returns a nonzero value if the current request is a barrier
25794 request.</div>
25795 <br>
25796 <A name="496"></a><font color="blue">PAGE 496</font><br>
25797 <br>
25798 <font class="fixd">int blk_noretry_request(struct request *req);</font><br>
25799 <div class="bq">
25800 This macro returns a nonzero value if the given request should not be retried on
25801 errors.</div>
25802 <br>
25803 <font class="fixd">int end_that_request_first(struct request *req, int success, int count);<br>
25804 void end_that_request_last(struct request *req);</font><br>
25805 <div class="bq">
25806 Use <i>end_that_request_first </i>to indicate completion of a portion of a block I/O
25807 request. When that function returns 0, the request is complete and should be
25808 passed to <i>end_that_request_last</i>.</div>
25809 <br>
25810 <font class="fixd">rq_for_each_bio(bio, request)</font><br>
25811 <div class="bq">
25812 Another macro-implemented control structure; it steps through each <font class="fixd">bio</font> that
25813 makes up a request.</div>
25814 <br>
25815 <font class="fixd">int blk_rq_map_sg(request_queue_t *queue, struct request *req, struct scatterlist *list);</font><br>
25816 <div class="bq">
25817 Fills the given scatterlist with the information needed to map the buffers in the
25818 given request for a DMA transfer.</div>
25819 <br>
25820 <font class="fixd">typedef int (make_request_fn) (request_queue_t *q, struct bio *bio);</font><br>
25821 <div class="bq">
25822 The prototype for the <i>make_request</i> function.</div>
25823 <br>
25824 <font class="fixd">void bio_endio(struct bio *bio, unsigned int bytes, int error);</font><br>
25825 <div class="bq">
25826 Signal completion for a given <font class="fixd">bio</font>. This function should be used only if your
25827 driver obtained the <font class="fixd">bio</font> directly from the block layer via the <i>make_request</i> function.</div>
25828 <br>
25829 <font class="fixd">request_queue_t *blk_alloc_queue(int flags);<br>
25830 void blk_queue_make_request(request_queue_t *queue, make_request_fn *func);</font><br>
25831 <div class="bq">
25832 Use <i>blk_alloc_queue </i>to allocate a request queue that is used with a custom
25833 <i>make_request </i>function. That function should be set with <i>blk_queue_make_request</i>.</div>
25834 <br>
25835 <font class="fixd">typedef int (prep_rq_fn) (request_queue_t *queue, struct request *req);<br>
25836 void blk_queue_prep_rq(request_queue_t *queue, prep_rq_fn *func);</font><br>
25837 <div class="bq">
25838 The prototype and setup functions for a command preparation function, which
25839 can be used to prepare the necessary hardware command before the request is
25840 passed to your <i>request</i> function.</div>
25841 <br>
25842 <font class="fixd">int blk_queue_init_tags(request_queue_t *queue, int depth, struct blk_queue_tag *tags);<br>
25843 int blk_queue_resize_tags(request_queue_t *queue, int new_depth);<br>
25844 int blk_queue_start_tag(request_queue_t *queue, struct request *req);<br>
25845 void blk_queue_end_tag(request_queue_t *queue, struct request *req);<br>
25846 struct request *blk_queue_find_tag(request_queue_t *qeue, int tag);<br>
25847 void blk_queue_invalidate_tags(request_queue_t *queue);</font><br>
25848 <div class="bq">
25849 Support functions for drivers using tagged command queueing.</div>
25850 <br>
25851 <A name="497"></a><font color="blue">PAGE 497</font><br>
25852 <br>
25853 <a name="CHAPTER17"></a><font color="red"><b>CHAPTER 17</b></font><br>
25854 <br>
25855 <a name="NetworkDrivers"></a><font color="#7519FF" size="+1"><b>Network Drivers</b></font><br>
25856 <br>
25857 Having discussed char and block drivers, we are now ready to move on to the world
25858 of networking. Network interfaces are the third standard class of Linux devices, and
25859 this chapter describes how they interact with the rest of the kernel.<br>
25860 <br>
25861 The role of a network interface within the system is similar to that of a mounted
25862 block device. A block device registers its disks and methods with the kernel, and
25863 then "transmits" and "receives" blocks on request, by means of its <i>request </i>function.
25864 Similarly, a network interface must register itself within specific kernel data structures
25865 in order to be invoked when packets are exchanged with the outside world.<br>
25866 <br>
25867 There are a few important differences between mounted disks and packet-delivery
25868 interfaces. To begin with, a disk exists as a special file in the <i>/dev </i>directory, whereas a
25869 network interface has no such entry point. The normal file operations (read, write,
25870 and so on) do not make sense when applied to network interfaces, so it is not possible
25871 to apply the Unix "everything is a file" approach to them. Thus, network interfaces
25872 exist in their own namespace and export a different set of operations.<br>
25873 <br>
25874 Although you may object that applications use the <i>read </i>and <i>write </i>system calls when
25875 using sockets, those calls act on a software object that is distinct from the interface.
25876 Several hundred sockets can be multiplexed on the same physical interface.<br>
25877 <br>
25878 But the most important difference between the two is that block drivers operate only
25879 in response to requests from the kernel, whereas network drivers receive packets
25880 asynchronously from the outside. Thus, while a block driver is <i>asked </i>to send a buffer
25881 toward the kernel, the network device <i>asks </i>to push incoming packets toward the kernel.
25882 The kernel interface for network drivers is designed for this different mode of
25883 operation.<br>
25884 <br>
25885 Network drivers also have to be prepared to support a number of administrative
25886 tasks, such as setting addresses, modifying transmission parameters, and maintaining
25887 traffic and error statistics. The API for network drivers reflects this need and,
25888 therefore, looks somewhat different from the interfaces we have seen so far.<br>
25889 <br>
25890 <A name="498"></a><font color="blue">PAGE 498</font><br>
25891 <br>
25892 The network subsystem of the Linux kernel is designed to be completely protocol independent.
25893 This applies to both networking protocols (Internet protocol [IP] versus
25894 IPX or other protocols) and hardware protocols (Ethernet versus token ring, etc.).
25895 Interaction between a network driver and the kernel properly deals with one network
25896 packet at a time; this allows protocol issues to be hidden neatly from the driver and
25897 the physical transmission to be hidden from the protocol.<br>
25898 <br>
25899 This chapter describes how the network interfaces fit in with the rest of the Linux
25900 kernel and provides examples in the form of a memory-based modularized network
25901 interface, which is called (you guessed it) <i>snull</i>. To simplify the discussion, the interface
25902 uses the Ethernet hardware protocol and transmits IP packets. The knowledge
25903 you acquire from examining <i>snull </i>can be readily applied to protocols other than IP,
25904 and writing a non-Ethernet driver is different only in tiny details related to the actual
25905 network protocol.<br>
25906 <br>
25907 This chapter doesn't talk about IP numbering schemes, network protocols, or other
25908 general networking concepts. Such topics are not (usually) of concern to the driver
25909 writer, and it's impossible to offer a satisfactory overview of networking technology
25910 in less than a few hundred pages. The interested reader is urged to refer to other
25911 books describing networking issues.<br>
25912 <br>
25913 One note on terminology is called for before getting into network devices. The networking
25914 world uses the term <i>octet </i>to refer to a group of eight bits, which is generally
25915 the smallest unit understood by networking devices and protocols. The term byte is
25916 almost never encountered in this context. In keeping with standard usage, we will
25917 use octet when talking about networking devices.<br>
25918 <br>
25919 The term "header" also merits a quick mention. A header is a set of bytes (err, octets)
25920 prepended to a packet as it is passed through the various layers of the networking
25921 subsystem. When an application sends a block of data through a TCP socket, the
25922 networking subsystem breaks that data up into packets and puts a TCP header,
25923 describing where each packet fits within the stream, at the beginning. The lower levels
25924 then put an IP header, used to route the packet to its destination, in front of the
25925 TCP header. If the packet moves over an Ethernet-like medium, an Ethernet header,
25926 interpreted by the hardware, goes in front of the rest. Network drivers need not concern
25927 themselves with higher-level headers (usually), but they often must be involved
25928 in the creation of the hardware-level header.<br>
25929 <br>
25930 <a name="HowSnullIsDesigned"></a><font color="red"><b>How snull Is Designed</b></font><br>
25931 <br>
25932 This section discusses the design concepts that led to the <i>snull </i>network interface.
25933 Although this information might appear to be of marginal use, failing to understand
25934 it might lead to problems when you play with the sample code.<br>
25935 <br>
25936 The first, and most important, design decision was that the sample interfaces should
25937 remain independent of real hardware, just like most of the sample code used in this<br>
25938 <br>
25939 <A name="499"></a><font color="blue">PAGE 499</font><br>
25940 <br>
25941 book. This constraint led to something that resembles the loopback interface. <i>snull </i>is
25942 not a loopback interface; however, it simulates conversations with real remote hosts
25943 in order to better demonstrate the task of writing a network driver. The Linux loopback
25944 driver is actually quite simple; it can be found in <i>drivers/net/loopback.c</i>.<br>
25945 <br>
25946 Another feature of <i>snull </i>is that it supports only IP traffic. This is a consequence of the
25947 internal workings of the interface--<i>snull </i>has to look inside and interpret the packets
25948 to properly emulate a pair of hardware interfaces. Real interfaces don't depend on
25949 the protocol being transmitted, and this limitation of <i>snull </i>doesn't affect the fragments
25950 of code shown in this chapter.<br>
25951 <br>
25952 <a name="AssigningIPNumbers"></a><font color="red"><b>Assigning IP Numbers</b></font><br>
25953 <br>
25954 The <i>snull </i>module creates two interfaces. These interfaces are different from a simple
25955 loopback, in that whatever you transmit through one of the interfaces loops back to
25956 the other one, not to itself. It looks like you have two external links, but actually
25957 your computer is replying to itself.<br>
25958 <br>
25959 Unfortunately, this effect can't be accomplished through IP number assignments
25960 alone, because the kernel wouldn't send out a packet through interface A that was
25961 directed to its own interface B. Instead, it would use the loopback channel without
25962 passing through <i>snull</i>. To be able to establish a communication through the <i>snull
25963 </i>interfaces, the source and destination addresses need to be modified during data
25964 transmission. In other words, packets sent through one of the interfaces should be
25965 received by the other, but the receiver of the outgoing packet shouldn't be recognized
25966 as the local host. The same applies to the source address of received packets.<br>
25967 <br>
25968 To achieve this kind of "hidden loopback," the <i>snull </i>interface toggles the least significant
25969 bit of the third octet of both the source and destination addresses; that is, it
25970 changes both the network number and the host number of class C IP numbers. The
25971 net effect is that packets sent to network A (connected to <font class="fixd">sn0,</font> the first interface)
25972 appear on the <font class="fixd">sn1</font> interface as packets belonging to network B.<br>
25973 <br>
25974 To avoid dealing with too many numbers, let's assign symbolic names to the IP numbers
25975 involved:<br>
25976 <ul>
25977 <li><font class="fixd">snullnet0</font> is the network that is connected to the <font class="fixd">sn0</font> interface. Similarly,
25978 <font class="fixd">snullnet1</font> is the network connected to <font class="fixd">sn1.</font> The addresses of these networks
25979 should differ only in the least significant bit of the third octet. These networks
25980 must have 24-bit netmasks.
25981 <li><font class="fixd">local0</font> is the IP address assigned to the <font class="fixd">sn0</font> interface; it belongs to <font class="fixd">snullnet0.</font>
25982 The address associated with <font class="fixd">sn1</font> is <font class="fixd">local1. local0</font> and <font class="fixd">local1</font> must differ in the
25983 least significant bit of their third octet and in the fourth octet.
25984 <li><font class="fixd">remote0</font> is a host in <font class="fixd">snullnet0,</font> and its fourth octet is the same as that of <font class="fixd">local1.</font>
25985 Any packet sent to <font class="fixd">remote0</font> reaches <font class="fixd">local1</font> after its network address has been
25986 </ul>
25987 <A name="500"></a><font color="blue">PAGE 500</font>
25988 <ul>
25989 modified by the interface code. The host <font class="fixd">remote1</font> belongs to <font class="fixd">snullnet1,</font> and its
25990 fourth octet is the same as that of <font class="fixd">local0.</font>
25991 </ul>
25992 The operation of the <i>snull </i>interfaces is depicted in Figure 17-1, in which the hostname
25993 associated with each interface is printed near the interface name.<br>
25994 <br><br>
25995 <center>
25996 <img src="fig17-1.gif">
25997 </center>
25998 <br>
25999 <i>Figure 17-1. How a host sees its interfaces</i><br>
26000 <br>
26001 Here are possible values for the network numbers. Once you put these lines in <i>/etc/
26002 networks</i>, you can call your networks by name. The values were chosen from the
26003 range of numbers reserved for private use.<br>
26004 <pre>
26005 snullnet0 192.168.0.0
26006 snullnet1 192.168.1.0
26007 </pre>
26008 The following are possible host numbers to put into <i>/etc/hosts</i>:<br>
26009 <pre>
26010 192.168.0.1 local0
26011 192.168.0.2 remote0
26012 192.168.1.2 local1
26013 192.168.1.1 remote1
26014 </pre>
26015 The important feature of these numbers is that the host portion of <font class="fixd">local0</font> is the same
26016 as that of <font class="fixd">remote1</font>, and the host portion of <font class="fixd">local1</font> is the same as that of <font class="fixd">remote0</font>. You
26017 can use completely different numbers as long as this relationship applies.<br>
26018 <br>
26019 Be careful, however, if your computer is already connected to a network. The numbers
26020 you choose might be real Internet or intranet numbers, and assigning them to
26021 your interfaces prevents communication with the real hosts. For example, although<br>
26022 <br>
26023 <A name="501"></a><font color="blue">PAGE 501</font><br>
26024 <br>
26025 the numbers just shown are not routable Internet numbers, they could already be
26026 used by your private network.<br>
26027 <br>
26028 Whatever numbers you choose, you can correctly set up the interfaces for operation
26029 by issuing the following commands:<br>
26030 <pre>
26031 ifconfig sn0 local0
26032 ifconfig sn1 local1
26033 </pre>
26034 You may need to add the netmask 255.255.255.0 parameter if the address range chosen
26035 is not a class C range.<br>
26036 <br>
26037 At this point, the "remote" end of the interface can be reached. The following screendump
26038 shows how a host reaches <font class="fixd">remote0</font> and <font class="fixd">remote1</font> through the <i>snull</i> interface:<br>
26039 <pre>
26040 morgana% <b>ping -c 2 remote0
26041 </b>64 bytes from 192.168.0.99: icmp_seq=0 ttl=64 time=1.6 ms
26042 64 bytes from 192.168.0.99: icmp_seq=1 ttl=64 time=0.9 ms
26043 2 packets transmitted, 2 packets received, 0% packet loss
26045 morgana% <b>ping -c 2 remote1
26046 </b>64 bytes from 192.168.1.88: icmp_seq=0 ttl=64 time=1.8 ms
26047 64 bytes from 192.168.1.88: icmp_seq=1 ttl=64 time=0.9 ms
26048 2 packets transmitted, 2 packets received, 0% packet loss
26049 </pre>
26050 Note that you won't be able to reach any other "host" belonging to the two networks,
26051 because the packets are discarded by your computer after the address has
26052 been modified and the packet has been received. For example, a packet aimed at
26053 192.168.0.32 will leave through <font class="fixd">sn0</font> and reappear at <font class="fixd">sn1</font> with a destination address of
26054 192.168.1.32, which is not a local address for the host computer.<br>
26055 <br>
26056 <a name="ThePhysicalTransportOfPackets"></a><font color="red"><b>The Physical Transport of Packets</b></font><br>
26057 <br>
26058 As far as data transport is concerned, the <i>snull</i> interfaces belong to the Ethernet class.<br>
26059 <br>
26060 <i>snull </i>emulates Ethernet because the vast majority of existing networks--at least the
26061 segments that a workstation connects to--are based on Ethernet technology, be it
26062 10base-T, 100base-T, or Gigabit. Additionally, the kernel offers some generalized
26063 support for Ethernet devices, and there's no reason not to use it. The advantage of
26064 being an Ethernet device is so strong that even the <i>plip </i>interface (the interface that
26065 uses the printer ports) declares itself as an Ethernet device.<br>
26066 <br>
26067 The last advantage of using the Ethernet setup for <i>snull </i>is that you can run <i>tcpdump
26068 </i>on the interface to see the packets go by. Watching the interfaces with <i>tcpdump </i>can
26069 be a useful way to see how the two interfaces work.<br>
26070 <br>
26071 As was mentioned previously, <i>snull </i>works only with IP packets. This limitation is a
26072 result of the fact that <i>snull </i>snoops in the packets and even modifies them, in order for
26073 the code to work. The code modifies the source, destination, and checksum in the IP
26074 header of each packet without checking whether it actually conveys IP information.<br>
26075 <br>
26076 <A name="502"></a><font color="blue">PAGE 502</font><br>
26077 <br>
26078 This quick-and-dirty data modification destroys non-IP packets. If you want to deliver
26079 other protocols through <i>snull</i>, you must modify the module's source code.<br>
26080 <br>
26081 <a name="ConnectingToTheKernel"></a><font color="red"><b>Connecting to the Kernel</b></font><br>
26082 <br>
26083 We start looking at the structure of network drivers by dissecting the <i>snull </i>source.
26084 Keeping the source code for several drivers handy might help you follow the discussion
26085 and to see how real-world Linux network drivers operate. As a place to start, we
26086 suggest <i>loopback.c</i>, <i>plip.c</i>, and <i>e100.c</i>, in order of increasing complexity. All these
26087 files live in <i>drivers/net</i>, within the kernel source tree.<br>
26088 <br>
26089 <a name="DeviceRegistration17"></a><font color="red"><b>Device Registration</b></font><br>
26090 <br>
26091 When a driver module is loaded into a running kernel, it requests resources and
26092 offers facilities; there's nothing new in that. And there's also nothing new in the way
26093 resources are requested. The driver should probe for its device and its hardware location
26094 (I/O ports and IRQ line)--but not register them--as described in "Installing an
26095 Interrupt Handler" in Chapter 10. The way a network driver is registered by its module
26096 initialization function is different from char and block drivers. Since there is no
26097 equivalent of major and minor numbers for network interfaces, a network driver
26098 does not request such a number. Instead, the driver inserts a data structure for each
26099 newly detected interface into a global list of network devices.<br>
26100 <br>
26101 Each interface is described by a <font class="fixd">struct net_device</font> item, which is defined in <i><linux/
26102 netdevice.h></i>. The <i>snull </i>driver keeps pointers to two of these structures (for <font class="fixd">sn0</font> and
26103 <font class="fixd">sn1</font>) in a simple array:<br>
26104 <pre>
26105 struct net_device *snull_devs[2];
26106 </pre>
26107 The <font class="fixd">net_device</font> structure, like many other kernel structures, contains a kobject and
26108 is, therefore, reference-counted and exported via sysfs. As with other such structures,
26109 it must be allocated dynamically. The kernel function provided to perform this
26110 allocation is <i>alloc_netdev</i>, which has the following prototype:<br>
26111 <pre>
26112 struct net_device *alloc_netdev(int sizeof_priv,
26113 const char *name,
26114 void (*setup)(struct net_device *));
26115 </pre>
26116 Here, <font class="fixd">sizeof_priv</font> is the size of the driver's "private data" area; with network devices,
26117 that area is allocated along with the <font class="fixd">net_device</font> structure. In fact, the two are allocated
26118 together in one large chunk of memory, but driver authors should pretend that
26119 they don't know that. <font class="fixd">name</font> is the name of this interface, as is seen by user space; this
26120 name can have a <i>printf</i>-style <font class="fixd">%d</font> in it. The kernel replaces the <font class="fixd">%d</font> with the next available
26121 interface number. Finally, <font class="fixd">setup</font> is a pointer to an initialization function that is called
26122 to set up the rest of the <font class="fixd">net_device</font> structure. We get to the initialization function<br>
26123 <br>
26124 <A name="503"></a><font color="blue">PAGE 503</font><br>
26125 <br>
26126 shortly, but, for now, suffice it to say that <i>snull </i>allocates its two device structures in
26127 this way:<br>
26128 <pre>
26129 snull_devs[0] = alloc_netdev(sizeof(struct snull_priv), "sn%d",
26130 snull_init);
26131 snull_devs[1] = alloc_netdev(sizeof(struct snull_priv), "sn%d",
26132 snull_init);
26133 if (snull_devs[0] = = NULL || snull_devs[1] = = NULL)
26134 goto out;
26135 </pre>
26136 As always, we must check the return value to ensure that the allocation succeeded.<br>
26137 <br>
26138 The networking subsystem provides a number of helper functions wrapped around
26139 <i>alloc_netdev </i>for various types of interfaces. The most common is <i>alloc_etherdev</i>,
26140 which is defined in <i><linux/etherdevice.h></i>:<br>
26141 <pre>
26142 struct net_device *alloc_etherdev(int sizeof_priv);
26143 </pre>
26144 This function allocates a network device using <font class="fixd">eth%d</font> for the name argument. It provides
26145 its own initialization function (<i>ether_setup</i>) that sets several <font class="fixd">net_device</font> fields
26146 with appropriate values for Ethernet devices. Thus, there is no driver-supplied initialization
26147 function for <i>alloc_etherdev</i>; the driver should simply do its required initialization
26148 directly after a successful allocation. Writers of drivers for other types of devices
26149 may want to take advantage of one of the other helper functions, such as <i>alloc_fcdev
26150 </i>(defined in <i><linux/fcdevice.h></i>) for fiber-channel devices, <i>alloc_fddidev </i>(<i><linux/
26151 fddidevice.h></i>) for FDDI devices, or <i>alloc_trdev </i>(<i><linux/trdevice.h></i>) for token ring
26152 devices.<br>
26153 <br>
26154 <i>snull </i>could use <i>alloc_etherdev </i>without trouble; we chose to use <i>alloc_netdev </i>instead,
26155 as a way of demonstrating the lower-level interface and to give us control over the
26156 name assigned to the interface.<br>
26157 <br>
26158 Once the <font class="fixd">net_device</font> structure has been initialized, completing the process is just a
26159 matter of passing the structure to <i>register_netdev</i>. In <i>snull</i>, the call looks as follows:<br>
26160 <pre>
26161 for (i = 0; i < 2; i++)
26162 if ((result = register_netdev(snull_devs[i])))
26163 printk("snull: error %i registering device \"%s\"\n",
26164 result, snull_devs[i]->name);
26165 </pre>
26166 The usual cautions apply here: as soon as you call <i>register_netdev</i>, your driver may be
26167 called to operate on the device. Thus, you should not register the device until everything
26168 has been completely initialized.<br>
26169 <br>
26170 <a name="InitializingEachDevice"></a><font color="red"><b>Initializing Each Device</b></font><br>
26171 <br>
26172 We have looked at the allocation and registration of <font class="fixd">net_device</font> structures, but we
26173 passed over the intermediate step of completely initializing that structure. Note that
26174 <font class="fixd">struct net_device</font> is always put together at runtime; it cannot be set up at compile
26175 time in the same manner as a <font class="fixd">file_operations</font> or <font class="fixd">block_device_operations</font> structure.
26176 This initialization must be complete before calling <i>register_netdev</i>. The <font class="fixd">net_device</font><br>
26177 <br>
26178 <A name="504"></a><font color="blue">PAGE 504</font><br>
26179 <br>
26180 structure is large and complicated; fortunately, the kernel takes care of some Ethernet wide
26181 defaults through the <i>ether_setup</i> function (which is called by <i>alloc_etherdev</i>).<br>
26182 <br>
26183 Since <i>snull </i>uses <i>alloc_netdev</i>, it has a separate initialization function. The core of this
26184 function (<i>snull_init</i>) is as follows:<br>
26185 <pre>
26186 ether_setup(dev); /* assign some of the fields */
26188 dev->open = snull_open;
26189 dev->stop = snull_release;
26190 dev->set_config = snull_config;
26191 dev->hard_start_xmit = snull_tx;
26192 dev->do_ioctl = snull_ioctl;
26193 dev->get_stats = snull_stats;
26194 dev->rebuild_header = snull_rebuild_header;
26195 dev->hard_header = snull_header;
26196 dev->tx_timeout = snull_tx_timeout;
26197 dev->watchdog_timeo = timeout;
26198 /* keep the default flags, just add NOARP */
26199 dev->flags |= IFF_NOARP;
26200 dev->features |= NETIF_F_NO_CSUM;
26201 dev->hard_header_cache = NULL; /* Disable caching */
26202 </pre>
26203 The above code is a fairly routine initialization of the <font class="fixd">net_device</font> structure; it is
26204 mostly a matter of storing pointers to our various driver functions. The single
26205 unusual feature of the code is setting <font class="fixd">IFF_NOARP</font> in the flags. This specifies that the
26206 interface cannot use the Address Resolution Protocol (ARP). ARP is a low-level
26207 Ethernet protocol; its job is to turn IP addresses into Ethernet medium access control
26208 (MAC) addresses. Since the "remote" systems simulated by <i>snull </i>do not really
26209 exist, there is nobody available to answer ARP requests for them. Rather than complicate
26210 <i>snull </i>with the addition of an ARP implementation, we chose to mark the
26211 interface as being unable to handle that protocol. The assignment to <font class="fixd">hard_header_cache </font>
26212 is there for a similar reason: it disables the caching of the (nonexistent) ARP
26213 replies on this interface. This topic is discussed in detail in the section "MAC
26214 Address Resolution" later in this chapter.<br>
26215 <br>
26216 The initialization code also sets a couple of fields (<font class="fixd">tx_timeout</font> and <font class="fixd">watchdog_timeo</font>)
26217 that relate to the handling of transmission timeouts. We cover this topic thoroughly
26218 in the section "Transmission Timeouts."<br>
26219 <br>
26220 We look now at one more <font class="fixd">struct net_device</font> field, <font class="fixd">priv.</font> Its role is similar to that of
26221 the <font class="fixd">private_data</font> pointer that we used for char drivers. Unlike <font class="fixd">fops->private_data,</font>
26222 this <font class="fixd">priv</font> pointer is allocated along with the <font class="fixd">net_device</font> structure. Direct access to the
26223 <font class="fixd">priv</font> field is also discouraged, for performance and flexibility reasons. When a driver
26224 needs to get access to the private data pointer, it should use the <i>netdev_priv </i>function.
26225 Thus, the <i>snull</i> driver is full of declarations such as:<br>
26226 <pre>
26227 struct snull_priv *priv = netdev_priv(dev);
26228 </pre>
26229 <A name="505"></a><font color="blue">PAGE 505</font><br>
26230 <br>
26231 The <i>snull</i> module declares a <font class="fixd">snull_priv</font> data structure to be used for <font class="fixd">priv:</font><br>
26232 <pre>
26233 struct snull_priv {
26234 struct net_device_stats stats;
26235 int status;
26236 struct snull_packet *ppool;
26237 struct snull_packet *rx_queue; /* List of incoming packets */
26238 int rx_int_enabled;
26239 int tx_packetlen;
26240 u8 *tx_packetdata;
26241 struct sk_buff *skb;
26242 spinlock_t lock;
26243 };
26244 </pre>
26245 The structure includes, among other things, an instance of <font class="fixd">struct net_device_stats,</font>
26246 which is the standard place to hold interface statistics. The following lines in <i>snull_init
26247 </i>allocate and initialize <font class="fixd">dev->priv:</font><br>
26248 <pre>
26249 priv = netdev_priv(dev);
26250 memset(priv, 0, sizeof(struct snull_priv));
26251 spin_lock_init(&priv->lock);
26252 snull_rx_ints(dev, 1); /* enable receive interrupts */
26253 </pre>
26254 <a name="ModuleUnloading"></a><font color="red"><b>Module Unloading</b></font><br>
26255 <br>
26256 Nothing special happens when the module is unloaded. The module cleanup function
26257 simply unregisters the interfaces, performs whatever internal cleanup is
26258 required, and releases the <font class="fixd">net_device</font> structure back to the system:<br>
26259 <pre>
26260 void snull_cleanup(void)
26261 {
26262 int i;
26264 for (i = 0; i < 2; i++) {
26265 if (snull_devs[i]) {
26266 unregister_netdev(snull_devs[i]);
26267 snull_teardown_pool(snull_devs[i]);
26268 free_netdev(snull_devs[i]);
26269 }
26270 }
26271 return;
26272 }
26273 </pre>
26274 The call to <i>unregister_netdev </i>removes the interface from the system; <i>free_netdev
26275 </i>returns the <font class="fixd">net_device</font> structure to the kernel. If a reference to that structure exists
26276 somewhere, it may continue to exist, but your driver need not care about that. Once
26277 you have unregistered the interface, the kernel no longer calls its methods.<br>
26278 <br>
26279 Note that our internal cleanup (done in <i>snull_teardown_pool</i>) cannot happen until the
26280 device has been unregistered. It must, however, happen before we return the <font class="fixd">net_device</font>
26281 structure to the system; once we have called <i>free_netdev</i>, we cannot make any further
26282 references to the device or our private area.<br>
26283 <br>
26284 <A name="506"></a><font color="blue">PAGE 506</font><br>
26285 <br>
26286 <a name="TheNetdeviceStructureInDetail"></a><font color="red"><b>The <font class="fixd">net_device</font> Structure in Detail</b></font><br>
26287 <br>
26288 The <font class="fixd">net_device</font> structure is at the very core of the network driver layer and deserves a
26289 complete description. This list describes all the fields, but more to provide a reference
26290 than to be memorized. The rest of this chapter briefly describes each field as
26291 soon as it is used in the sample code, so you don't need to keep referring back to this
26292 section.<br>
26293 <br>
26294 <a name="GlobalInformation"></a><font color="red"><b>Global Information</b></font><br>
26295 <br>
26296 The first part of <font class="fixd">struct net_device</font> is composed of the following fields:<br>
26297 <br>
26298 <font class="fixd">char name[IFNAMSIZ];</font><br>
26299 <div class="bq">
26300 The name of the device. If the name set by the driver contains a <font class="fixd">%d</font> format string,
26301 <i>register_netdev </i>replaces it with a number to make a unique name; assigned numbers
26302 start at 0.</div>
26303 <br>
26304 <font class="fixd">unsigned long state;</font><br>
26305 <div class="bq">
26306 Device state. The field includes several flags. Drivers do not normally manipulate
26307 these flags directly; instead, a set of utility functions has been provided.
26308 These functions are discussed shortly when we get into driver operations.</div>
26309 <br>
26310 <font class="fixd">struct net_device *next;</font><br>
26311 <div class="bq">
26312 Pointer to the next device in the global linked list. This field shouldn't be
26313 touched by the driver.</div>
26314 <br>
26315 <font class="fixd">int (*init)(struct net_device *dev);</font><br>
26316 <div class="bq">
26317 An initialization function. If this pointer is set, the function is called by <i>register_netdev
26318 </i>to complete the initialization of the <font class="fixd">net_device</font> structure. Most modern network
26319 drivers do not use this function any longer; instead, initialization is performed
26320 before registering the interface.</div>
26321 <br>
26322 <a name="HardwareInformation"></a><font color="red"><b>Hardware Information</b></font><br>
26323 <br>
26324 The following fields contain low-level hardware information for relatively simple
26325 devices. They are a holdover from the earlier days of Linux networking; most modern
26326 drivers do make use of them (with the possible exception of <font class="fixd">if_port</font>). We list
26327 them here for completeness.<br>
26328 <br>
26329 <font class="fixd">unsigned long rmem_end;<br>
26330 unsigned long rmem_start;<br>
26331 unsigned long mem_end;<br>
26332 unsigned long mem_start;</font><br>
26333 <div class="bq">
26334 Device memory information. These fields hold the beginning and ending
26335 addresses of the shared memory used by the device. If the device has different
26336 receive and transmit memories, the <font class="fixd">mem</font> fields are used for transmit memory and
26337 the <font class="fixd">rmem</font> fields for receive memory. The <font class="fixd">rmem</font> fields are never referenced outside</div>
26338 <br>
26339 <A name="507"></a><font color="blue">PAGE 507</font><br>
26340 <br>
26341 <div class="bq">of the driver itself. By convention, the <font class="fixd">end</font> fields are set so that <font class="fixd">end - start</font> is the
26342 amount of available onboard memory.</div>
26343 <br>
26344 <font class="fixd">unsigned long base_addr;</font><br>
26345 <div class="bq">
26346 The I/O base address of the network interface. This field, like the previous ones,
26347 is assigned by the driver during the device probe. The <i>ifconfig </i>command can be
26348 used to display or modify the current value. The <font class="fixd">base_addr</font> can be explicitly
26349 assigned on the kernel command line at system boot (via the <font class="fixd">netdev=</font> parameter)
26350 or at module load time. The field, like the memory fields described above, is not
26351 used by the kernel.</div>
26352 <br>
26353 <font class="fixd">unsigned char irq;</font><br>
26354 <div class="bq">
26355 The assigned interrupt number. The value of <font class="fixd">dev->irq</font> is printed by <i>ifconfig </i>when
26356 interfaces are listed. This value can usually be set at boot or load time and modified
26357 later using <i>ifconfig</i>.</div>
26358 <br>
26359 <font class="fixd">unsigned char if_port;</font><br>
26360 <div class="bq">
26361 The port in use on multiport devices. This field is used, for example, with devices
26362 that support both coaxial (<font class="fixd">IF_PORT_10BASE2</font>) and twisted-pair (<font class="fixd">IF_PORT_100BASET</font>)
26363 Ethernet connections. The full set of known port types is defined in <i><linux/netdevice.h></i>.</div>
26364 <br>
26365 <font class="fixd">unsigned char dma;</font><br>
26366 <div class="bq">
26367 The DMA channel allocated by the device. The field makes sense only with some
26368 peripheral buses, such as ISA. It is not used outside of the device driver itself but
26369 for informational purposes (in <i>ifconfig</i>).</div>
26370 <br>
26371 <a name="InterfaceInformation"></a><font color="red"><b>Interface Information</b></font><br>
26372 <br>
26373 Most of the information about the interface is correctly set up by the <i>ether_setup
26374 </i>function (or whatever other setup function is appropriate for the given hardware
26375 type). Ethernet cards can rely on this general-purpose function for most of these
26376 fields, but the <font class="fixd">flags</font> and <font class="fixd">dev_addr</font> fields are device specific and must be explicitly
26377 assigned at initialization time.<br>
26378 <br>
26379 Some non-Ethernet interfaces can use helper functions similar to <i>ether_setup</i>. <i>drivers/
26380 net/net_init.c</i> exports a number of such functions, including the following:<br>
26381 <br>
26382 <font class="fixd">void ltalk_setup(struct net_device *dev);</font><br>
26383 <div class="bq">
26384 Sets up the fields for a LocalTalk device</div>
26385 <br>
26386 <font class="fixd">void fc_setup(struct net_device *dev);</font><br>
26387 <div class="bq">
26388 Initializes fields for fiber-channel devices</div>
26389 <br>
26390 <font class="fixd">void fddi_setup(struct net_device *dev);</font><br>
26391 <div class="bq">
26392 Configures an interface for a Fiber Distributed Data Interface (FDDI) network</div>
26393 <br>
26394 <A name="508"></a><font color="blue">PAGE 508</font><br>
26395 <br>
26396 <font class="fixd">void hippi_setup(struct net_device *dev);</font><br>
26397 <div class="bq">
26398 Prepares fields for a High-Performance Parallel Interface (HIPPI) high-speed
26399 interconnect driver</div>
26400 <br>
26401 <font class="fixd">void tr_setup(struct net_device *dev);</font><br>
26402 <div class="bq">
26403 Handles setup for token ring network interfaces</div>
26404 <br>
26405 Most devices are covered by one of these classes. If yours is something radically new
26406 and different, however, you need to assign the following fields by hand:<br>
26407 <br>
26408 <font class="fixd">unsigned short hard_header_len;</font><br>
26409 <div class="bq">
26410 The hardware header length, that is, the number of octets that lead the transmitted
26411 packet before the IP header, or other protocol information. The value of
26412 <font class="fixd">hard_header_len</font> is <font class="fixd">14 (ETH_HLEN)</font> for Ethernet interfaces.</div>
26413 <br>
26414 <font class="fixd">unsigned mtu;</font><br>
26415 <div class="bq">
26416 The maximum transfer unit (MTU). This field is used by the network layer to
26417 drive packet transmission. Ethernet has an MTU of 1500 octets (<font class="fixd">ETH_DATA_LEN</font>).
26418 This value can be changed with <i>ifconfig</i>.</div>
26419 <br>
26420 <font class="fixd">unsigned long tx_queue_len;</font><br>
26421 <div class="bq">
26422 The maximum number of frames that can be queued on the device's transmission
26423 queue. This value is set to 1000 by <i>ether_setup</i>, but you can change it. For
26424 example, <i>plip </i>uses 10 to avoid wasting system memory (<i>plip </i>has a lower
26425 throughput than a real Ethernet interface).</div>
26426 <br>
26427 <font class="fixd">unsigned short type;</font><br>
26428 <div class="bq">
26429 The hardware type of the interface. The <font class="fixd">type</font> field is used by ARP to determine
26430 what kind of hardware address the interface supports. The proper value for
26431 Ethernet interfaces is <font class="fixd">ARPHRD_ETHER,</font> and that is the value set by <i>ether_setup</i>. The
26432 recognized types are defined in <i><linux/if_arp.h></i>.</div>
26433 <br>
26434 <font class="fixd">unsigned char addr_len;<br>
26435 unsigned char broadcast[MAX_ADDR_LEN];<br>
26436 unsigned char dev_addr[MAX_ADDR_LEN];</font><br>
26437 <div class="bq">
26438 Hardware (MAC) address length and device hardware addresses. The Ethernet
26439 address length is six octets (we are referring to the hardware ID of the interface
26440 board), and the broadcast address is made up of six <font class="fixd">0xff</font> octets; <i>ether_setup
26441 </i>arranges for these values to be correct. The device address, on the other hand,
26442 must be read from the interface board in a device-specific way, and the driver
26443 should copy it to <font class="fixd">dev_addr</font>. The hardware address is used to generate correct
26444 Ethernet headers before the packet is handed over to the driver for transmission.
26445 The <i>snull </i>device doesn't use a physical interface, and it invents its own hardware
26446 address.</div>
26447 <br>
26448 <font class="fixd">unsigned short flags;<br>
26449 int features;</font><br>
26450 <div class="bq">
26451 Interface flags (detailed next).</div>
26452 <br>
26453 <A name="509"></a><font color="blue">PAGE 509</font><br>
26454 <br>
26455 The <font class="fixd">flags</font> field is a bit mask including the following bit values. The <font class="fixd">IFF_prefix</font>
26456 stands for "interface flags." Some flags are managed by the kernel, and some are set
26457 by the interface at initialization time to assert various capabilities and other features
26458 of the interface. The valid flags, which are defined in <i><linux/if.h></i>, are:<br>
26459 <br>
26460 <font class="fixd">IFF_UP</font><br>
26461 <div class="bq">
26462 This flag is read-only for the driver. The kernel turns it on when the interface is
26463 active and ready to transfer packets.</div>
26464 <br>
26465 <font class="fixd">IFF_BROADCAST</font><br>
26466 <div class="bq">
26467 This flag (maintained by the networking code) states that the interface allows
26468 broadcasting. Ethernet boards do.</div>
26469 <br>
26470 <font class="fixd">IFF_DEBUG</font><br>
26471 <div class="bq">
26472 This marks debug mode. The flag can be used to control the verbosity of your
26473 <i>printk </i>calls or for other debugging purposes. Although no in-tree driver currently
26474 uses this flag, it can be set and reset by user programs via <i>ioctl</i>, and your
26475 driver can use it. The <i>misc-progs/netifdebug </i>program can be used to turn the flag
26476 on and off.</div>
26477 <br>
26478 <font class="fixd">IFF_LOOPBACK</font><br>
26479 <div class="bq">
26480 This flag should be set only in the loopback interface. The kernel checks for
26481 <font class="fixd">IFF_LOOPBACK</font> instead of hard-wiring the lo name as a special interface.</div>
26482 <br>
26483 <font class="fixd">IFF_POINTOPOINT</font><br>
26484 <div class="bq">
26485 This flag signals that the interface is connected to a point-to-point link. It is set
26486 by the driver or, sometimes, by <i>ifconfig</i>. For example, <i>plip </i>and the PPP driver
26487 have it set.</div>
26488 <br>
26489 <font class="fixd">IFF_NOARP</font><br>
26490 <div class="bq">
26491 This means that the interface can't perform ARP. For example, point-to-point
26492 interfaces don't need to run ARP, which would only impose additional traffic
26493 without retrieving useful information. <i>snull </i>runs without ARP capabilities, so it
26494 sets the flag.</div>
26495 <br>
26496 <font class="fixd">IFF_PROMISC</font><br>
26497 <div class="bq">
26498 This flag is set (by the networking code) to activate promiscuous operation. By
26499 default, Ethernet interfaces use a hardware filter to ensure that they receive
26500 broadcast packets and packets directed to that interface's hardware address
26501 only. Packet sniffers such as <i>tcpdump </i>set promiscuous mode on the interface in
26502 order to retrieve all packets that travel on the interface's transmission medium.</div>
26503 <br>
26504 <font class="fixd">IFF_MULTICAST</font><br>
26505 <div class="bq">
26506 This flag is set by drivers to mark interfaces that are capable of multicast transmission.
26507 <i>ether_setup </i>sets <font class="fixd">IFF_MULTICAST</font> by default, so if your driver does not
26508 support multicast, it must clear the flag at initialization time.</div>
26509 <br>
26510 <font class="fixd">IFF_ALLMULTI</font><br>
26511 <div class="bq">
26512 This flag tells the interface to receive all multicast packets. The kernel sets it when
26513 the host performs multicast routing, only if <font class="fixd">IFF_MULTICAST</font> is set. <font class="fixd">IFF_ALLMULTI</font> is</div>
26514 <br>
26515 <A name="510"></a><font color="blue">PAGE 510</font><br>
26516 <br>
26517 <div class="bq">read-only for the driver. Multicast flags are used in the section "Multicast," later
26518 in this chapter.</div>
26519 <br>
26520 <font class="fixd">IFF_MASTER<br>
26521 IFF_SLAVE</font><br>
26522 <div class="bq">
26523 These flags are used by the load equalization code. The interface driver doesn't
26524 need to know about them.</div>
26525 <br>
26526 <font class="fixd">IFF_PORTSEL<br>
26527 IFF_AUTOMEDIA</font><br>
26528 <div class="bq">
26529 These flags signal that the device is capable of switching between multiple media
26530 types; for example, unshielded twisted pair (UTP) versus coaxial Ethernet cables.
26531 If <font class="fixd">IFF_AUTOMEDIA</font> is set, the device selects the proper medium automatically. In
26532 practice, the kernel makes no use of either flag.</div>
26533 <br>
26534 <font class="fixd">IFF_DYNAMIC</font><br>
26535 <div class="bq">
26536 This flag, set by the driver, indicates that the address of this interface can
26537 change. It is not currently used by the kernel.</div>
26538 <br>
26539 <font class="fixd">IFF_RUNNING</font><br>
26540 <div class="bq">
26541 This flag indicates that the interface is up and running. It is mostly present for
26542 BSD compatibility; the kernel makes little use of it. Most network drivers need
26543 not worry about <font class="fixd">IFF_RUNNING</font>.</div>
26544 <br>
26545 <font class="fixd">IFF_NOTRAILERS</font><br>
26546 <div class="bq">
26547 This flag is unused in Linux, but it exists for BSD compatibility.</div>
26548 <br>
26549 When a program changes <font class="fixd">IFF_UP,</font> the <i>open </i>or <i>stop </i>device method is called. Furthermore,
26550 when <font class="fixd">IFF_UP</font> or any other flag is modified, the <i>set_multicast_list </i>method is
26551 invoked. If the driver needs to perform some action in response to a modification of
26552 the flags, it must take that action in <i>set_multicast_list</i>. For example, when <font class="fixd">IFF_PROMISC</font>
26553 is set or reset, <i>set_multicast_list </i>must notify the onboard hardware filter. The responsibilities
26554 of this device method are outlined in the section "Multicast."<br>
26555 <br>
26556 The features field of the <font class="fixd">net_device</font> structure is set by the driver to tell the kernel
26557 about any special hardware capabilities that this interface has. We will discuss some
26558 of these features; others are beyond the scope of this book. The full set is:<br>
26559 <br>
26560 <font class="fixd">NETIF_F_SG<br>
26561 NETIF_F_FRAGLIST</font><br>
26562 <div class="bq">
26563 Both of these flags control the use of scatter/gather I/O. If your interface can transmit
26564 a packet that has been split into several distinct memory segments, you should
26565 set <font class="fixd">NETIF_F_SG</font>. Of course, you have to actually implement the scatter/gather I/O (we
26566 describe how that is done in the section "Scatter/Gather I/O"). <font class="fixd">NETIF_F_FRAGLIST</font>
26567 states that your interface can cope with packets that have been fragmented; only the
26568 loopback driver does this in 2.6.<br>
26569 <br>
26570 Note that the kernel does not perform scatter/gather I/O to your device if it does
26571 not also provide some form of checksumming as well. The reason is that, if the</div>
26572 <br>
26573 <A name="511"></a><font color="blue">PAGE 511</font><br>
26574 <br>
26575 <div class="bq">kernel has to make a pass over a fragmented ("nonlinear") packet to calculate
26576 the checksum, it might as well copy the data and coalesce the packet at the same
26577 time.</div>
26578 <br>
26579 <font class="fixd">NETIF_F_IP_CSUM<br>
26580 NETIF_F_NO_CSUM<br>
26581 NETIF_F_HW_CSUM</font><br>
26582 <div class="bq">
26583 These flags are all ways of telling the kernel that it need not apply checksums to
26584 some or all packets leaving the system by this interface. Set <font class="fixd">NETIF_F_IP_CSUM</font> if
26585 your interface can checksum IP packets but not others. If no checksums are ever
26586 required for this interface, set <font class="fixd">NETIF_F_NO_CSUM</font>. The loopback driver sets this
26587 flag, and <i>snull </i>does, too; since packets are only transferred through system memory,
26588 there is (one hopes!) no opportunity for them to be corrupted, and no need
26589 to check them. If your hardware does checksumming itself, set <font class="fixd">NETIF_F_HW_CSUM</font>.</div>
26590 <br>
26591 <font class="fixd">NETIF_F_HIGHDMA</font><br>
26592 <div class="bq">
26593 Set this flag if your device can perform DMA to high memory. In the absence of
26594 this flag, all packet buffers provided to your driver are allocated in low memory.</div>
26595 <br>
26596 <font class="fixd">NETIF_F_HW_VLAN_TX<br>
26597 NETIF_F_HW_VLAN_RX<br>
26598 NETIF_F_HW_VLAN_FILTER<br>
26599 NETIF_F_VLAN_CHALLENGED</font><br>
26600 <div class="bq">
26601 These options describe your hardware's support for 802.1q VLAN packets. VLAN
26602 support is beyond what we can cover in this chapter. If VLAN packets confuse
26603 your device (which they really shouldn't), set the <font class="fixd">NETIF_F_VLAN_CHALLENGED</font> flag.</div>
26604 <br>
26605 <font class="fixd">NETIF_F_TSO</font><br>
26606 <div class="bq">
26607 Set this flag if your device can perform TCP segmentation offloading. TSO is an
26608 advanced feature that we cannot cover here.</div>
26609 <br>
26610 <a name="TheDeviceMethods"></a><font color="red"><b>The Device Methods</b></font><br>
26611 <br>
26612 As happens with the char and block drivers, each network device declares the functions
26613 that act on it. Operations that can be performed on network interfaces are
26614 listed in this section. Some of the operations can be left <font class="fixd">NULL</font>, and others are usually
26615 untouched because <i>ether_setup</i> assigns suitable methods to them.<br>
26616 <br>
26617 Device methods for a network interface can be divided into two groups: fundamental
26618 and optional. Fundamental methods include those that are needed to be able to
26619 use the interface; optional methods implement more advanced functionalities that
26620 are not strictly required. The following are the fundamental methods:<br>
26621 <br>
26622 <font class="fixd">int (*open)(struct net_device *dev);</font><br>
26623 <div class="bq">
26624 Opens the interface. The interface is opened whenever <i>ifconfig </i>activates it. The
26625 <i>open </i>method should register any system resource it needs (I/O ports, IRQ,</div>
26626 <br>
26627 <A name="512"></a><font color="blue">PAGE 512</font><br>
26628 <br>
26629 <div class="bq">DMA, etc.), turn on the hardware, and perform any other setup your device
26630 requires.</div>
26631 <br>
26632 <font class="fixd">int (*stop)(struct net_device *dev);</font><br>
26633 <div class="bq">
26634 Stops the interface. The interface is stopped when it is brought down. This function
26635 should reverse operations performed at open time.</div>
26636 <br>
26637 <font class="fixd">int (*hard_start_xmit) (struct sk_buff *skb, struct net_device *dev);</font><br>
26638 <div class="bq">
26639 Method that initiates the transmission of a packet. The full packet (protocol
26640 headers and all) is contained in a socket buffer (<font class="fixd">sk_buff</font>) structure. Socket buffers
26641 are introduced later in this chapter.</div>
26642 <br>
26643 <font class="fixd">int (*hard_header) (struct sk_buff *skb, struct net_device *dev, unsigned short type, void *daddr, void *saddr, unsigned len);</font><br>
26644 <div class="bq">
26645 Function (called before <i>hard_start_xmit</i>) that builds the hardware header from
26646 the source and destination hardware addresses that were previously retrieved; its
26647 job is to organize the information passed to it as arguments into an appropriate,
26648 device-specific hardware header. <i>eth_header </i>is the default function for Ethernet like
26649 interfaces, and <i>ether_setup</i> assigns this field accordingly.</div>
26650 <br>
26651 <font class="fixd">int (*rebuild_header)(struct sk_buff *skb);</font><br>
26652 <div class="bq">
26653 Function used to rebuild the hardware header after ARP resolution completes
26654 but before a packet is transmitted. The default function used by Ethernet devices
26655 uses the ARP support code to fill the packet with missing information.</div>
26656 <br>
26657 <font class="fixd">void (*tx_timeout)(struct net_device *dev);</font><br>
26658 <div class="bq">
26659 Method called by the networking code when a packet transmission fails to complete
26660 within a reasonable period, on the assumption that an interrupt has been
26661 missed or the interface has locked up. It should handle the problem and resume
26662 packet transmission.</div>
26663 <br>
26664 <font class="fixd">struct net_device_stats *(*get_stats)(struct net_device *dev);</font><br>
26665 <div class="bq">
26666 Whenever an application needs to get statistics for the interface, this method is
26667 called. This happens, for example, when <i>ifconfig </i>or <i>netstat -i </i>is run. A sample
26668 implementation for <i>snull</i> is introduced in the section "Statistical Information."</div>
26669 <br>
26670 <font class="fixd">int (*set_config)(struct net_device *dev, struct ifmap *map);</font><br>
26671 <div class="bq">
26672 Changes the interface configuration. This method is the entry point for configuring
26673 the driver. The I/O address for the device and its interrupt number can be
26674 changed at runtime using <i>set_config</i>. This capability can be used by the system
26675 administrator if the interface cannot be probed for. Drivers for modern hardware
26676 normally do not need to implement this method.</div>
26677 <br>
26678 <A name="513"></a><font color="blue">PAGE 513</font><br>
26679 <br>
26680 The remaining device operations are optional:<br>
26681 <br>
26682 <font class="fixd">int weight;<br>
26683 int (*poll)(struct net_device *dev; int *quota);</font><br>
26684 <div class="bq">
26685 Method provided by NAPI-compliant drivers to operate the interface in a polled
26686 mode, with interrupts disabled. NAPI (and the <font class="fixd">weight</font> field) are covered in the
26687 section "Receive Interrupt Mitigation."</div>
26688 <br>
26689 <font class="fixd">void (*poll_controller)(struct net_device *dev);</font><br>
26690 <div class="bq">
26691 Function that asks the driver to check for events on the interface in situations
26692 where interrupts are disabled. It is used for specific in-kernel networking tasks,
26693 such as remote consoles and kernel debugging over the network.</div>
26694 <br>
26695 <font class="fixd">int (*do_ioctl)(struct net_device *dev, struct ifreq *ifr, int cmd);</font><br>
26696 <div class="bq">
26697 Performs interface-specific <i>ioctl </i>commands. (Implementation of those commands
26698 is described in the section "Custom ioctl Commands.") The corresponding
26699 field in <font class="fixd">struct net_device</font> can be left as <font class="fixd">NULL</font> if the interface doesn't need any
26700 interface-specific commands.</div>
26701 <br>
26702 <font class="fixd">void (*set_multicast_list)(struct net_device *dev);</font><br>
26703 <div class="bq">
26704 Method called when the multicast list for the device changes and when the
26705 flags change. See the section "Multicast" for further details and a sample
26706 implementation.</div>
26707 <br>
26708 <font class="fixd">int (*set_mac_address)(struct net_device *dev, void *addr);</font><br>
26709 <div class="bq">
26710 Function that can be implemented if the interface supports the ability to change its
26711 hardware address. Many interfaces don't support this ability at all. Others use the
26712 default <i>eth_mac_addr </i>implementation (from <i>drivers/net/net_init.c</i>). <i>eth_mac_addr
26713 </i>only copies the new address into <font class="fixd">dev->dev_addr,</font> and it does so only if the interface
26714 is not running. Drivers that use <i>eth_mac_addr </i>should set the hardware MAC
26715 address from <font class="fixd">dev->dev_addr</font> in their <i>open</i> method.</div>
26716 <br>
26717 <font class="fixd">int (*change_mtu)(struct net_device *dev, int new_mtu);</font><br>
26718 <div class="bq">
26719 Function that takes action if there is a change in the maximum transfer unit (MTU)
26720 for the interface. If the driver needs to do anything particular when the MTU is
26721 changed by the user, it should declare its own function; otherwise, the default does
26722 the right thing. <i>snull</i> has a template for the function if you are interested.</div>
26723 <br>
26724 <font class="fixd">int (*header_cache) (struct neighbour *neigh, struct hh_cache *hh);</font><br>
26725 <div class="bq">
26726 <i>header_cache </i>is called to fill in the <font class="fixd">hh_cache</font> structure with the results of an ARP
26727 query. Almost all Ethernet-like drivers can use the default <i>eth_header_cache
26728 </i>implementation.</div>
26729 <br>
26730 <A name="514"></a><font color="blue">PAGE 514</font><br>
26731 <br>
26732 <font class="fixd">int (*header_cache_update) (struct hh_cache *hh, struct net_device *dev, unsigned char *haddr);</font><br>
26733 <div class="bq">
26734 Method that updates the destination address in the <font class="fixd">hh_cache</font> structure in
26735 response to a change. Ethernet devices use <i>eth_header_cache_update</i>.</div>
26736 <br>
26737 <font class="fixd">int (*hard_header_parse) (struct sk_buff *skb, unsigned char *haddr);</font><br>
26738 <div class="bq">
26739 The <i>hard_header_parse </i>method extracts the source address from the packet contained
26740 in <font class="fixd">skb,</font> copying it into the buffer at <font class="fixd">haddr.</font> The return value from the function
26741 is the length of that address. Ethernet devices normally use <i>eth_header_parse</i>.</div>
26742 <br>
26743 <a name="UtilityFields"></a><font color="red"><b>Utility Fields</b></font><br>
26744 <br>
26745 The remaining <font class="fixd">struct net_device</font> data fields are used by the interface to hold useful
26746 status information. Some of the fields are used by <i>ifconfig </i>and <i>netstat </i>to provide the
26747 user with information about the current configuration. Therefore, an interface
26748 should assign values to these fields:<br>
26749 <br>
26750 <font class="fixd">unsigned long trans_start;<br>
26751 unsigned long last_rx;</font><br>
26752 <div class="bq">
26753 Fields that hold a jiffies value. The driver is responsible for updating these values
26754 when transmission begins and when a packet is received, respectively. The
26755 <font class="fixd">trans_start</font> value is used by the networking subsystem to detect transmitter
26756 lockups. <font class="fixd">last_rx</font> is currently unused, but the driver should maintain this field
26757 anyway to be prepared for future use.</div>
26758 <br>
26759 <font class="fixd">int watchdog_timeo;</font><br>
26760 <div class="bq">
26761 The minimum time (in jiffies) that should pass before the networking layer
26762 decides that a transmission timeout has occurred and calls the driver's <i>tx_timeout</i>
26763 function.</div>
26764 <br>
26765 <font class="fixd">void *priv;</font><br>
26766 <div class="bq">
26767 The equivalent of <font class="fixd">filp->private_data.</font> In modern drivers, this field is set by
26768 <i>alloc_netdev</i> and should not be accessed directly; use <i>netdev_priv</i> instead.</div>
26769 <br>
26770 <font class="fixd">struct dev_mc_list *mc_list;<br>
26771 int mc_count;</font><br>
26772 <div class="bq">
26773 Fields that handle multicast transmission. <font class="fixd">mc_count</font> is the count of items in <font class="fixd">mc_list</font>.
26774 See the section "Multicast" for further details.</div>
26775 <br>
26776 <font class="fixd">spinlock_t xmit_lock;<br>
26777 int xmit_lock_owner;</font><br>
26778 <div class="bq">
26779 The <font class="fixd">xmit_lock</font> is used to avoid multiple simultaneous calls to the driver's
26780 <i>hard_start_xmit </i>function. <font class="fixd">xmit_lock_owner</font> is the number of the CPU that has
26781 obtained <font class="fixd">xmit_lock</font>. The driver should make no changes to these fields.</div>
26782 <br>
26783 There are other fields in <font class="fixd">struct net_device,</font> but they are not used by network drivers.<br>
26784 <br>
26785 <A name="515"></a><font color="blue">PAGE 515</font><br>
26786 <br>
26787 <a name="OpeningAndClosing"></a><font color="red"><b>Opening and Closing</b></font><br>
26788 <br>
26789 Our driver can probe for the interface at module load time or at kernel boot. Before the
26790 interface can carry packets, however, the kernel must open it and assign an address to
26791 it. The kernel opens or closes an interface in response to the <i>ifconfig</i> command.<br>
26792 <br>
26793 When <i>ifconfig </i>is used to assign an address to the interface, it performs two tasks.
26794 First, it assigns the address by means of <font class="fixd">ioctl(SIOCSIFADDR)</font> (Socket I/O Control Set
26795 Interface Address). Then it sets the <font class="fixd">IFF_UP</font> bit in <font class="fixd">dev->flag</font> by means of
26796 <font class="fixd">ioctl(SIOCSIFFLAGS)</font> (Socket I/O Control Set Interface Flags) to turn the interface on.<br>
26797 <br>
26798 As far as the device is concerned, <font class="fixd">ioctl(SIOCSIFADDR)</font> does nothing. No driver function
26799 is invoked--the task is device independent, and the kernel performs it. The latter
26800 command (<font class="fixd">ioctl(SIOCSIFFLAGS)</font>), however, calls the <i>open</i> method for the device.<br>
26801 <br>
26802 Similarly, when the interface is shut down, <i>ifconfig </i>uses <font class="fixd">ioctl(SIOCSIFFLAGS)</font> to clear
26803 <font class="fixd">IFF_UP,</font> and the <i>stop</i> method is called.<br>
26804 <br>
26805 Both device methods return 0</font> in case of success and the usual negative value in case of error.<br>
26806 <br>
26807 As far as the actual code is concerned, the driver has to perform many of the same
26808 tasks as the char and block drivers do. <i>open </i>requests any system resources it needs
26809 and tells the interface to come up; <i>stop </i>shuts down the interface and releases system
26810 resources. Network drivers must perform some additional steps at <i>open</i> time, however.<br>
26811 <br>
26812 First, the hardware (MAC) address needs to be copied from the hardware device to
26813 <font class="fixd">dev->dev_addr</font> before the interface can communicate with the outside world. The
26814 hardware address can then be copied to the device at open time. The <i>snull </i>software
26815 interface assigns it from within <i>open</i>; it just fakes a hardware number using an ASCII
26816 string of length <font class="fixd">ETH_ALEN,</font> the length of Ethernet hardware addresses.<br>
26817 <br>
26818 The <i>open </i>method should also start the interface's transmit queue (allowing it to
26819 accept packets for transmission) once it is ready to start sending data. The kernel
26820 provides a function to start the queue:<br>
26821 <pre>
26822 void netif_start_queue(struct net_device *dev);
26823 </pre>
26824 The <i>open</i> code for <i>snull</i> looks like the following:<br>
26825 <pre>
26826 int snull_open(struct net_device *dev)
26827 {
26828 /* request_region( ), request_irq( ), .... (like fops->open) */
26830 /*
26831 * Assign the hardware address of the board: use "\0SNULx", where
26832 * x is 0 or 1. The first byte is '\0' to avoid being a multicast
26833 * address (the first byte of multicast addrs is odd).
26834 */
26835 memcpy(dev->dev_addr, "\0SNUL0", ETH_ALEN);
26836 if (dev = = snull_devs[1])
26837 </pre>
26838 <A name="516"></a><font color="blue">PAGE 516</font><br>
26839 <pre>
26840 dev->dev_addr[ETH_ALEN-1]++; /* \0SNUL1 */
26841 netif_start_queue(dev);
26842 return 0;
26843 }
26844 </pre>
26845 As you can see, in the absence of real hardware, there is little to do in the <i>open
26846 </i>method. The same is true of the <i>stop </i>method; it just reverses the operations of <i>open</i>.
26847 For this reason, the function implementing <i>stop</i> is often called <i>close</i> or <i>release</i>.<br>
26848 <pre>
26849 int snull_release(struct net_device *dev)
26850 {
26851 /* release ports, irq and such -- like fops->close */
26853 netif_stop_queue(dev); /* can't transmit any more */
26854 return 0;
26855 }
26856 </pre>
26857 The function:<br>
26858 <pre>
26859 void netif_stop_queue(struct net_device *dev);
26860 </pre>
26861 is the opposite of <i>netif_start_queue</i>; it marks the device as being unable to transmit
26862 any more packets. The function must be called when the interface is closed (in the
26863 <i>stop </i>method) but can also be used to temporarily stop transmission, as explained in
26864 the next section.<br>
26865 <br>
26866 <a name="PacketTransmission"></a><font color="red"><b>Packet Transmission</b></font><br>
26867 <br>
26868 The most important tasks performed by network interfaces are data transmission
26869 and reception. We start with transmission because it is slightly easier to understand.<br>
26870 <br>
26871 <i>Transmission </i>refers to the act of sending a packet over a network link. Whenever the
26872 kernel needs to transmit a data packet, it calls the driver's <i>hard_start_transmit
26873 </i>method to put the data on an outgoing queue. Each packet handled by the kernel is
26874 contained in a socket buffer structure (<font class="fixd">struct sk_buff</font>), whose definition is found in
26875 <i><linux/skbuff.h></i>. The structure gets its name from the Unix abstraction used to represent
26876 a network connection, the <i>socket</i>. Even if the interface has nothing to do with
26877 sockets, each network packet belongs to a socket in the higher network layers, and
26878 the input/output buffers of any socket are lists of <font class="fixd">struct sk_buff</font> structures. The
26879 same <font class="fixd">sk_buff</font> structure is used to host network data throughout all the Linux
26880 network subsystems, but a socket buffer is just a packet as far as the interface is
26881 concerned.<br>
26882 <br>
26883 A pointer to <font class="fixd">sk_buff</font> is usually called <font class="fixd">skb,</font> and we follow this practice both in the
26884 sample code and in the text.<br>
26885 <br>
26886 The socket buffer is a complex structure, and the kernel offers a number of functions
26887 to act on it. The functions are described later in the section "The Socket Buffers";
26888 for now, a few basic facts about <font class="fixd">sk_buff</font> are enough for us to write a working
26889 driver.<br>
26890 <br>
26891 <A name="517"></a><font color="blue">PAGE 517</font><br>
26892 <br>
26893 The socket buffer passed to <i>hard_start_xmit </i>contains the physical packet as it should
26894 appear on the media, complete with the transmission-level headers. The interface
26895 doesn't need to modify the data being transmitted. <font class="fixd">skb->data</font> points to the packet
26896 being transmitted, and <font class="fixd">skb->len</font> is its length in octets. This situation gets a little more
26897 complicated if your driver can handle scatter/gather I/O; we get to that in the section
26898 "Scatter/Gather I/O."<br>
26899 <br>
26900 The <i>snull </i>packet transmission code follows; the physical transmission machinery has
26901 been isolated in another function, because every interface driver must implement it
26902 according to the specific hardware being driven:<br>
26903 <pre>
26904 int snull_tx(struct sk_buff *skb, struct net_device *dev)
26905 {
26906 int len;
26907 char *data, shortpkt[ETH_ZLEN];
26908 struct snull_priv *priv = netdev_priv(dev);
26910 data = skb->data;
26911 len = skb->len;
26912 if (len < ETH_ZLEN) {
26913 memset(shortpkt, 0, ETH_ZLEN);
26914 memcpy(shortpkt, skb->data, skb->len);
26915 len = ETH_ZLEN;
26916 data = shortpkt;
26917 }
26918 dev->trans_start = jiffies; /* save the timestamp */
26920 /* Remember the skb, so we can free it at interrupt time */
26921 priv->skb = skb;
26923 /* actual deliver of data is device-specific, and not shown here */
26924 snull_hw_tx(data, len, dev);
26926 return 0; /* Our simple device can not fail */
26927 }
26928 </pre>
26929 The transmission function, thus, just performs some sanity checks on the packet and
26930 transmits the data through the hardware-related function. Do note, however, the
26931 care that is taken when the packet to be transmitted is shorter than the minimum
26932 length supported by the underlying media (which, for <i>snull</i>, is our virtual "Ethernet").
26933 Many Linux network drivers (and those for other operating systems as well)
26934 have been found to leak data in such situations. Rather than create that sort of security
26935 vulnerability, we copy short packets into a separate array that we can explicitly
26936 zero-pad out to the full length required by the media. (We can safely put that data on
26937 the stack, since the minimum length--60 bytes--is quite small).<br>
26938 <br>
26939 The return value from <i>hard_start_xmit </i>should be 0 on success; at that point, your
26940 driver has taken responsibility for the packet, should make its best effort to ensure
26941 that transmission succeeds, and must free the skb at the end. A nonzero return value
26942 indicates that the packet could not be transmitted at this time; the kernel will retry<br>
26943 <br>
26944 <A name="518"></a><font color="blue">PAGE 518</font><br>
26945 <br>
26946 later. In this situation, your driver should stop the queue until whatever situation
26947 caused the failure has been resolved.<br>
26948 <br>
26949 The "hardware-related" transmission function (<i>snull_hw_tx</i>) is omitted here since it
26950 is entirely occupied with implementing the trickery of the <i>snull </i>device, including
26951 manipulating the source and destination addresses, and has little of interest to
26952 authors of real network drivers. It is present, of course, in the sample source for
26953 those who want to go in and see how it works.<br>
26954 <br>
26955 <a name="ControllingTransmissionConcurrency"></a><font color="red"><b>Controlling Transmission Concurrency</b></font><br>
26956 <br>
26957 The <i>hard_start_xmit </i>function is protected from concurrent calls by a spinlock
26958 (<font class="fixd">xmit_lock</font>) in the <font class="fixd">net_device</font> structure. As soon as the function returns, however, it
26959 may be called again. The function returns when the software is done instructing the
26960 hardware about packet transmission, but hardware transmission will likely not have
26961 been completed. This is not an issue with <i>snull</i>, which does all of its work using the
26962 CPU, so packet transmission is complete before the transmission function returns.<br>
26963 <br>
26964 Real hardware interfaces, on the other hand, transmit packets asynchronously and
26965 have a limited amount of memory available to store outgoing packets. When that
26966 memory is exhausted (which, for some hardware, happens with a single outstanding
26967 packet to transmit), the driver needs to tell the networking system not to start any
26968 more transmissions until the hardware is ready to accept new data.<br>
26969 <br>
26970 This notification is accomplished by calling <i>netif_stop_queue</i>, the function introduced
26971 earlier to stop the queue. Once your driver has stopped its queue, it <i>must
26972 </i>arrange to restart the queue at some point in the future, when it is again able to
26973 accept packets for transmission. To do so, it should call:<br>
26974 <pre>
26975 void netif_wake_queue(struct net_device *dev);
26976 </pre>
26977 This function is just like <i>netif_start_queue</i>, except that it also pokes the networking
26978 system to make it start transmitting packets again.<br>
26979 <br>
26980 Most modern network hardware maintains an internal queue with multiple packets
26981 to transmit; in this way it can get the best performance from the network. Network
26982 drivers for these devices must support having multiple transmisions outstanding at
26983 any given time, but device memory can fill up whether or not the hardware supports
26984 multiple outstanding transmissions. Whenever device memory fills to the point that
26985 there is no room for the largest possible packet, the driver should stop the queue
26986 until space becomes available again.<br>
26987 <br>
26988 If you must disable packet transmission from anywhere other than your <i>hard_start_xmit
26989 </i>function (in response to a reconfiguration request, perhaps), the function you want to
26990 use is:<br>
26991 <pre>
26992 void netif_tx_disable(struct net_device *dev);
26993 </pre>
26994 <A name="519"></a><font color="blue">PAGE 519</font><br>
26995 <br>
26996 This function behaves much like <i>netif_stop_queue</i>, but it also ensures that, when it
26997 returns, your <i>hard_start_xmit </i>method is not running on another CPU. The queue
26998 can be restarted with <i>netif_wake_queue</i>, as usual.<br>
26999 <br>
27000 <a name="TransmissionTimeouts"></a><font color="red"><b>Transmission Timeouts</b></font><br>
27001 <br>
27002 Most drivers that deal with real hardware have to be prepared for that hardware to
27003 fail to respond occasionally. Interfaces can forget what they are doing, or the system
27004 can lose an interrupt. This sort of problem is common with some devices designed to
27005 run on personal computers.<br>
27006 <br>
27007 Many drivers handle this problem by setting timers; if the operation has not completed
27008 by the time the timer expires, something is wrong. The network system, as it
27009 happens, is essentially a complicated assembly of state machines controlled by a
27010 mass of timers. As such, the networking code is in a good position to detect transmission
27011 timeouts as part of its regular operation.<br>
27012 <br>
27013 Thus, network drivers need not worry about detecting such problems themselves.
27014 Instead, they need only set a timeout period, which goes in the <font class="fixd">watchdog_timeo</font> field
27015 of the <font class="fixd">net_device</font> structure. This period, which is in jiffies, should be long enough to
27016 account for normal transmission delays (such as collisions caused by congestion on
27017 the network media).<br>
27018 <br>
27019 If the current system time exceeds the device's <font class="fixd">trans_start time</font> by at least the timeout
27020 period, the networking layer eventually calls the driver's <i>tx_timeout </i>method.
27021 That method's job is to do whatever is needed to clear up the problem and to ensure
27022 the proper completion of any transmissions that were already in progress. It is
27023 important, in particular, that the driver not lose track of any socket buffers that have
27024 been entrusted to it by the networking code.<br>
27025 <br>
27026 <i>snull </i>has the ability to simulate transmitter lockups, which is controlled by two loadtime
27027 parameters:<br>
27028 <pre>
27029 static int lockup = 0;
27030 module_param(lockup, int, 0);
27032 static int timeout = SNULL_TIMEOUT;
27033 module_param(timeout, int, 0);
27034 </pre>
27035 If the driver is loaded with the parameter <font class="fixd">lockup=n,</font> a lockup is simulated once every
27036 n packets transmitted, and the <font class="fixd">watchdog_timeo</font> field is set to the given <font class="fixd">timeout</font> value.
27037 When simulating lockups, <i>snull </i>also calls <i>netif_stop_queue </i>to prevent other transmission
27038 attempts from occurring.<br>
27039 <br>
27040 The <i>snull</i> transmission timeout handler looks like this:<br>
27041 <pre>
27042 void snull_tx_timeout (struct net_device *dev)
27043 {
27044 struct snull_priv *priv = netdev_priv(dev);
27045 </pre>
27046 <A name="520"></a><font color="blue">PAGE 520</font><br>
27047 <pre>
27048 PDEBUG("Transmit timeout at %ld, latency %ld\n", jiffies,
27049 jiffies - dev->trans_start);
27050 /* Simulate a transmission interrupt to get things moving */
27051 priv->status = SNULL_TX_INTR;
27052 snull_interrupt(0, dev, NULL);
27053 priv->stats.tx_errors++;
27054 netif_wake_queue(dev);
27055 return;
27056 }
27057 </pre>
27058 When a transmission timeout happens, the driver must mark the error in the interface
27059 statistics and arrange for the device to be reset to a sane state so that new packets can
27060 be transmitted. When a timeout happens in <i>snull</i>, the driver calls <i>snull_interrupt </i>to fill
27061 in the "missing" interrupt and restarts the transmit queue with <i>netif_wake_queue</i>.<br>
27062 <br>
27063 <a name="ScatterGatherIO"></a><font color="red"><b>Scatter/Gather I/O</b></font><br>
27064 <br>
27065 The process of creating a packet for transmission on the network involves assembling
27066 multiple pieces. Packet data must often be copied in from user space, and the
27067 headers used by various levels of the network stack must be added as well. This
27068 assembly can require a fair amount of data copying. If, however, the network interface
27069 that is destined to transmit the packet can perform scatter/gather I/O, the
27070 packet need not be assembled into a single chunk, and much of that copying can be
27071 avoided. Scatter/gather I/O also enables "zero-copy" transmission of network data
27072 directly from user-space buffers.<br>
27073 <br>
27074 The kernel does not pass scattered packets to your <i>hard_start_xmit </i>method unless
27075 the <font class="fixd">NETIF_F_SG</font> bit has been set in the <font class="fixd">features</font> field of your device structure. If you
27076 have set that flag, you need to look at a special "shared info" field within the skb to
27077 see whether the packet is made up of a single fragment or many and to find the scattered
27078 fragments if need be. A special macro exists to access this information; it is
27079 called <i>skb_shinfo</i>. The first step when transmitting potentially fragmented packets
27080 usually looks something like this:<br>
27081 <pre>
27082 if (skb_shinfo(skb)->nr_frags = = 0) {
27083 /* Just use skb->data and skb->len as usual */
27084 }
27085 </pre>
27086 The <font class="fixd">nr_frags</font> field tells how many fragments have been used to build the packet. If it
27087 is <font class="fixd">0,</font> the packet exists in a single piece and can be accessed via the <font class="fixd">data</font> field as usual.
27088 If, however, it is nonzero, your driver must pass through and arrange to transfer each
27089 individual fragment. The data field of the <font class="fixd">skb</font> structure points conveniently to the first
27090 fragment (as compared to the full packet, as in the unfragmented case). The length of
27091 the fragment must be calculated by subtracting <font class="fixd">skb->data_len</font> from <font class="fixd">skb->len</font> (which
27092 still contains the length of the full packet). The remaining fragments are to be found
27093 in an array called <font class="fixd">frags</font> in the shared information structure; each entry in <font class="fixd">frags</font> is an
27094 <font class="fixd">skb_frag_struct</font> structure:<br>
27095 <pre>
27096 struct skb_frag_struct {
27097 struct page *page;
27098 </pre>
27099 <A name="521"></a><font color="blue">PAGE 521</font><br>
27100 <pre>
27101 __u16 page_offset;
27102 __u16 size;
27103 };
27104 </pre>
27105 As you can see, we are once again dealing with <font class="fixd">page</font> structures, rather than kernel virtual
27106 addresses. Your driver should loop through the fragments, mapping each for a
27107 DMA transfer and not forgetting the first fragment, which is pointed to by the skb
27108 directly. Your hardware, of course, must assemble the fragments and transmit them
27109 as a single packet. Note that, if you have set the <font class="fixd">NETIF_F_HIGHDMA</font> feature flag, some
27110 or all of the fragments may be located in high memory.<br>
27111 <br>
27112 <a name="PacketReception"></a><font color="red"><b>Packet Reception</b></font><br>
27113 <br>
27114 Receiving data from the network is trickier than transmitting it, because an <font class="fixd">sk_buff</font>
27115 must be allocated and handed off to the upper layers from within an atomic context.
27116 There are two modes of packet reception that may be implemented by network drivers:
27117 interrupt driven and polled. Most drivers implement the interrupt-driven technique,
27118 and that is the one we cover first. Some drivers for high-bandwidth adapters
27119 may also implement the polled technique; we look at this approach in the section
27120 "Receive Interrupt Mitigation."<br>
27121 <br>
27122 The implementation of <i>snull </i>separates the "hardware" details from the device-independent
27123 housekeeping. Therefore, the function <i>snull_rx </i>is called from the <i>snull
27124 </i>"interrupt" handler after the hardware has received the packet, and it is already in
27125 the computer's memory. <i>snull_rx </i>receives a pointer to the data and the length of the
27126 packet; its sole responsibility is to send the packet and some additional information
27127 to the upper layers of networking code. This code is independent of the way the data
27128 pointer and length are obtained.<br>
27129 <pre>
27130 void snull_rx(struct net_device *dev, struct snull_packet *pkt)
27131 {
27132 struct sk_buff *skb;
27133 struct snull_priv *priv = netdev_priv(dev);
27135 /*
27136 * The packet has been retrieved from the transmission
27137 * medium. Build an skb around it, so upper layers can handle it
27138 */
27139 skb = dev_alloc_skb(pkt->datalen + 2);
27140 if (!skb) {
27141 if (printk_ratelimit( ))
27142 printk(KERN_NOTICE "snull rx: low on mem - packet dropped\n");
27143 priv->stats.rx_dropped++;
27144 goto out;
27145 }
27146 memcpy(skb_put(skb, pkt->datalen), pkt->data, pkt->datalen);
27148 /* Write metadata, and then pass to the receive level */
27149 skb->dev = dev;
27150 </pre>
27151 <A name="522"></a><font color="blue">PAGE 522</font><br>
27152 <pre>
27153 skb->protocol = eth_type_trans(skb, dev);
27154 skb->ip_summed = CHECKSUM_UNNECESSARY; /* don't check it */
27155 priv->stats.rx_packets++;
27156 priv->stats.rx_bytes += pkt->datalen;
27157 netif_rx(skb);
27158 out:
27159 return;
27160 }
27161 </pre>
27162 The function is sufficiently general to act as a template for any network driver, but
27163 some explanation is necessary before you can reuse this code fragment with confidence.<br>
27164 <br>
27165 The first step is to allocate a buffer to hold the packet. Note that the buffer allocation
27166 function (<i>dev_alloc_skb</i>) needs to know the data length. The information is used
27167 by the function to allocate space for the buffer. <i>dev_alloc_skb </i>calls <i>kmalloc </i>with
27168 atomic priority, so it can be used safely at interrupt time. The kernel offers other
27169 interfaces to socket-buffer allocation, but they are not worth introducing here; socket
27170 buffers are explained in detail in the section "The Socket Buffers."<br>
27171 <br>
27172 Of course, the return value from <i>dev_alloc_skb </i>must be checked, and <i>snull </i>does so.
27173 We call <i>printk_ratelimit </i>before complaining about failures, however. Generating
27174 hundreds or thousands of console messages per second is a good way to bog down
27175 the system entirely and hide the real source of problems; <i>printk_ratelimit </i>helps prevent
27176 that problem by returning <font class="fixd">0</font> when too much output has gone to the console, and
27177 things need to be slowed down a bit.<br>
27178 <br>
27179 Once there is a valid <font class="fixd">skb</font> pointer, the packet data is copied into the buffer by calling
27180 <i>memcpy</i>; the <i>skb_put </i>function updates the end-of-data pointer in the buffer and
27181 returns a pointer to the newly created space.<br>
27182 <br>
27183 If you are writing a high-performance driver for an interface that can do full bus-mastering
27184 I/O, there is a possible optimization that is worth considering here. Some drivers
27185 allocate socket buffers for incoming packets prior to their reception, then instruct
27186 the interface to place the packet data directly into the socket buffer's space. The networking
27187 layer cooperates with this strategy by allocating all socket buffers in DMA capable
27188 space (which may be in high memory if your device has the <font class="fixd">NETIF_F_HIGHDMA</font>
27189 feature flag set). Doing things this way avoids the need for a separate copy operation
27190 to fill the socket buffer, but requires being careful with buffer sizes because you
27191 won't know in advance how big the incoming packet is. The implementation of a
27192 <i>change_mtu </i>method is also important in this situation, since it allows the driver to
27193 respond to a change in the maximum packet size.<br>
27194 <br>
27195 The network layer needs to have some information spelled out before it can make
27196 sense of the packet. To this end, the <font class="fixd">dev</font> and <font class="fixd">protocol</font> fields must be assigned before
27197 the buffer is passed upstairs. The Ethernet support code exports a helper function
27198 (<i>eth_type_trans</i>), which finds an appropriate value to put into <font class="fixd">protocol.</font> Then we
27199 need to specify how checksumming is to be performed or has been performed on the<br>
27200 <br>
27201 <A name="523"></a><font color="blue">PAGE 523</font><br>
27202 <br>
27203 packet (<i>snull </i>does not need to perform any checksums). The possible policies for
27204 <font class="fixd">skb->ip_summed</font> are:<br>
27205 <br>
27206 <font class="fixd">CHECKSUM_HW</font><br>
27207 <div class="bq">
27208 The device has already performed checksums in hardware. An example of a
27209 hardware checksum is the SPARC HME interface.</div>
27210 <br>
27211 <font class="fixd">CHECKSUM_NONE</font><br>
27212 <div class="bq">
27213 Checksums have not yet been verified, and the task must be accomplished by
27214 system software. This is the default in newly allocated buffers.</div>
27215 <br>
27216 <font class="fixd">CHECKSUM_UNNECESSARY</font><br>
27217 <div class="bq">
27218 Don't do any checksums. This is the policy in <i>snull</i> and in the loopback interface.</div>
27219 <br>
27220 You may be wondering why the checksum status must be specified here when we
27221 have already set a flag in the features field of our <font class="fixd">net_device</font> structure. The answer is
27222 that the features flag tells the kernel about how our device treats outgoing packets.
27223 It is not used for incoming packets, which must, instead, be marked individually.<br>
27224 <br>
27225 Finally, the driver updates its statistics counter to record that a packet has been
27226 received. The statistics structure is made up of several fields; the most important are
27227 <font class="fixd">rx_packets, rx_bytes, tx_packets,</font> and <font class="fixd">tx_bytes,</font> which contain the number of packets
27228 received and transmitted and the total number of octets transferred. All the fields
27229 are thoroughly described in the section "Statistical Information."<br>
27230 <br>
27231 The last step in packet reception is performed by <i>netif_rx</i>, which hands off the socket
27232 buffer to the upper layers. <i>netif_rx </i>actually returns an integer value; <font class="fixd">NET_RX_SUCCESS</font>
27233 (0) means that the packet was successfully received; any other value indicates trouble.
27234 There are three return values (<font class="fixd">NET_RX_CN_LOW, NET_RX_CN_MOD,</font> and <font class="fixd">NET_RX_CN_HIGH</font>) that
27235 indicate increasing levels of congestion in the networking subsystem; <font class="fixd">NET_RX_DROP</font>
27236 means the packet was dropped. A driver could use these values to stop feeding packets
27237 into the kernel when congestion gets high, but, in practice, most drivers ignore the
27238 return value from <i>netif_rx</i>. If you are writing a driver for a high-bandwidth device and
27239 wish to do the right thing in response to congestion, the best approach is to implement
27240 NAPI, which we get to after a quick discussion of interrupt handlers.<br>
27241 <br>
27242 <a name="TheInterruptHandler"></a><font color="red"><b>The Interrupt Handler</b></font><br>
27243 <br>
27244 Most hardware interfaces are controlled by means of an interrupt handler. The hardware
27245 interrupts the processor to signal one of two possible events: a new packet has
27246 arrived or transmission of an outgoing packet is complete. Network interfaces can
27247 also generate interrupts to signal errors, link status changes, and so on.<br>
27248 <br>
27249 The usual interrupt routine can tell the difference between a new-packet-arrived interrupt
27250 and a done-transmitting notification by checking a status register found on the
27251 physical device. The <i>snull </i>interface works similarly, but its status word is implemented<br>
27252 <br>
27253 <A name="524"></a><font color="blue">PAGE 524</font><br>
27254 <br>
27255 in software and lives in <font class="fixd">dev->priv.</font> The interrupt handler for a network interface looks
27256 like this:<br>
27257 <pre>
27258 static void snull_regular_interrupt(int irq, void *dev_id, struct pt_regs *regs)
27259 {
27260 int statusword;
27261 struct snull_priv *priv;
27262 struct snull_packet *pkt = NULL;
27263 /*
27264 * As usual, check the "device" pointer to be sure it is
27265 * really interrupting.
27266 * Then assign "struct device *dev"
27267 */
27268 struct net_device *dev = (struct net_device *)dev_id;
27269 /* ... and check with hw if it's really ours */
27271 /* paranoid */
27272 if (!dev)
27273 return;
27275 /* Lock the device */
27276 priv = netdev_priv(dev);
27277 spin_lock(&priv->lock);
27279 /* retrieve statusword: real netdevices use I/O instructions */
27280 statusword = priv->status;
27281 priv->status = 0;
27282 if (statusword & SNULL_RX_INTR) {
27283 /* send it to snull_rx for handling */
27284 pkt = priv->rx_queue;
27285 if (pkt) {
27286 priv->rx_queue = pkt->next;
27287 snull_rx(dev, pkt);
27288 }
27289 }
27290 if (statusword & SNULL_TX_INTR) {
27291 /* a transmission is over: free the skb */
27292 priv->stats.tx_packets++;
27293 priv->stats.tx_bytes += priv->tx_packetlen;
27294 dev_kfree_skb(priv->skb);
27295 }
27297 /* Unlock the device and we are done */
27298 spin_unlock(&priv->lock);
27299 if (pkt) snull_release_buffer(pkt); /* Do this outside the lock! */
27300 return;
27301 }
27302 </pre>
27303 The handler's first task is to retrieve a pointer to the correct <font class="fixd">struct net_device</font>. This
27304 pointer usually comes from the <font class="fixd">dev_id</font> pointer received as an argument.<br>
27305 <br>
27306 The interesting part of this handler deals with the "transmission done" situation. In
27307 this case, the statistics are updated, and <i>dev_kfree_skb </i>is called to return the (no<br>
27308 <br>
27309 <A name="525"></a><font color="blue">PAGE 525</font><br>
27310 <br>
27311 longer needed) socket buffer to the system. There are, actually, three variants of this
27312 function that may be called:<br>
27313 <br>
27314 <font class="fixd">dev_kfree_skb(struct sk_buff *skb);</font><br>
27315 <div class="bq">
27316 This version should be called when you know that your code will not be running
27317 in interrupt context. Since <i>snull </i>has no actual hardware interrupts, this is
27318 the version we use.</div>
27319 <br>
27320 <font class="fixd">dev_kfree_skb_irq(struct sk_buff *skb);</font><br>
27321 <div class="bq">
27322 If you know that you will be freeing the buffer in an interrupt handler, use this
27323 version, which is optimized for that case.</div>
27324 <br>
27325 <font class="fixd">dev_kfree_skb_any(struct sk_buff *skb);</font><br>
27326 <div class="bq">
27327 This is the version to use if the relevant code could be running in either interrupt
27328 or noninterrupt context.</div>
27329 <br>
27330 Finally, if your driver has temporarily stopped the transmission queue, this is usually
27331 the place to restart it with <i>netif_wake_queue</i>.<br>
27332 <br>
27333 Packet reception, in contrast to transmission, doesn't need any special interrupt handling.
27334 Calling <i>snull_rx</i> (which we have already seen) is all that's required.<br>
27335 <br>
27336 <a name="ReceiveInterruptMitigation"></a><font color="red"><b>Receive Interrupt Mitigation</b></font><br>
27337 <br>
27338 When a network driver is written as we have described above, the processor is interrupted
27339 for every packet received by your interface. In many cases, that is the desired
27340 mode of operation, and it is not a problem. High-bandwidth interfaces, however, can
27341 receive thousands of packets per second. With that sort of interrupt load, the overall
27342 performance of the system can suffer.<br>
27343 <br>
27344 As a way of improving the performance of Linux on high-end systems, the networking
27345 subsystem developers have created an alternative interface (called NAPI)* based
27346 on polling. "Polling" can be a dirty word among driver developers, who often see
27347 polling techniques as inelegant and inefficient. Polling is inefficient, however, only if
27348 the interface is polled when there is no work to do. When the system has a high speed
27349 interface handling heavy traffic, there is <i>always </i>more packets to process. There
27350 is no need to interrupt the processor in such situations; it is enough that the new
27351 packets be collected from the interface every so often.<br>
27352 <br>
27353 Stopping receive interrupts can take a substantial amount of load off the processor.
27354 NAPI-compliant drivers can also be told not to feed packets into the kernel if those
27355 packets are just dropped in the networking code due to congestion, which can also
27356 help performance when that help is needed most. For various reasons, NAPI drivers
27357 are also less likely to reorder packets.<br>
27358 <br>
27359 * NAPI stands for "new API"; the networking hackers are better at creating interfaces than naming them.<br>
27360 <br>
27361 <A name="526"></a><font color="blue">PAGE 526</font><br>
27362 <br>
27363 Not all devices can operate in the NAPI mode, however. A NAPI-capable interface
27364 must be able to store several packets (either on the card itself, or in an in-memory
27365 DMA ring). The interface should be capable of disabling interrupts for received packets,
27366 while continuing to interrupt for successful transmissions and other events.
27367 There are other subtle issues that can make writing a NAPI-compliant driver harder;
27368 see <i>Documentation/networking/NAPI_HOWTO.txt </i>in the kernel source tree for the
27369 details.<br>
27370 <br>
27371 Relatively few drivers implement the NAPI interface. If you are writing a driver for an
27372 interface that may generate a huge number of interrupts, however, taking the time to
27373 implement NAPI may well prove worthwhile.<br>
27374 <br>
27375 The <i>snull </i>driver, when loaded with the <font class="fixd">use_napi</font> parameter set to a nonzero value,
27376 operates in the NAPI mode. At initialization time, we have to set up a couple of extra
27377 <font class="fixd">struct net_device</font> fields:<br>
27378 <pre>
27379 if (use_napi) {
27380 dev->poll = snull_poll;
27381 dev->weight = 2;
27382 }
27383 </pre>
27384 The <font class="fixd">poll</font> field must be set to your driver's polling function; we look at <i>snull_poll
27385 </i>shortly. The <font class="fixd">weight</font> field describes the relative importance of the interface: how much
27386 traffic should be accepted from the interface when resources are tight. There are no
27387 strict rules for how the <font class="fixd">weight</font> parameter should be set; by convention, 10 MBps
27388 Ethernet interfaces <font class="fixd">set weight</font> to <font class="fixd">16,</font> while faster interfaces use <font class="fixd">64.</font> You should not set
27389 <font class="fixd">weight</font> to a value greater than the number of packets your interface can store. In
27390 <i>snull</i>, we set the <font class="fixd">weight</font> to two as a way of demonstrating deferred packet reception.<br>
27391 <br>
27392 The next step in the creation of a NAPI-compliant driver is to change the interrupt
27393 handler. When your interface (which should start with receive interrupts enabled)
27394 signals that a packet has arrived, the interrupt handler should <i>not </i>process that
27395 packet. Instead, it should disable further receive interrupts and tell the kernel that it
27396 is time to start polling the interface. In the <i>snull </i>"interrupt" handler, the code that
27397 responds to packet reception interrupts has been changed to the following:<br>
27398 <pre>
27399 if (statusword & SNULL_RX_INTR) {
27400 snull_rx_ints(dev, 0); /* Disable further interrupts */
27401 netif_rx_schedule(dev);
27402 }
27403 </pre>
27404 When the interface tells us that a packet is available, the interrupt handler leaves it in
27405 the interface; all that needs to happen at this point is a call to <i>netif_rx_schedule</i>,
27406 which causes our <i>poll</i> method to be called at some future point.<br>
27407 <br>
27408 The <i>poll</i> method has this prototype:<br>
27409 <pre>
27410 int (*poll)(struct net_device *dev, int *budget);
27411 </pre>
27412 <A name="527"></a><font color="blue">PAGE 527</font><br>
27413 <br>
27414 The <i>snull</i> implementation of the <i>poll</i> method looks like this:<br>
27415 <pre>
27416 static int snull_poll(struct net_device *dev, int *budget)
27417 {
27418 int npackets = 0, quota = min(dev->quota, *budget);
27419 struct sk_buff *skb;
27420 struct snull_priv *priv = netdev_priv(dev);
27421 struct snull_packet *pkt;
27423 while (npackets < quota && priv->rx_queue) {
27424 pkt = snull_dequeue_buf(dev);
27425 skb = dev_alloc_skb(pkt->datalen + 2);
27426 if (! skb) {
27427 if (printk_ratelimit( ))
27428 printk(KERN_NOTICE "snull: packet dropped\n");
27429 priv->stats.rx_dropped++;
27430 snull_release_buffer(pkt);
27431 continue;
27432 }
27433 memcpy(skb_put(skb, pkt->datalen), pkt->data, pkt->datalen);
27434 skb->dev = dev;
27435 skb->protocol = eth_type_trans(skb, dev);
27436 skb->ip_summed = CHECKSUM_UNNECESSARY; /* don't check it */
27437 netif_receive_skb(skb);
27439 /* Maintain stats */
27440 npackets++;
27441 priv->stats.rx_packets++;
27442 priv->stats.rx_bytes += pkt->datalen;
27443 snull_release_buffer(pkt);
27444 }
27445 /* If we processed all packets, we're done; tell the kernel and reenable ints */
27446 *budget -= npackets;
27447 dev->quota -= npackets;
27448 if (! priv->rx_queue) {
27449 netif_rx_complete(dev);
27450 snull_rx_ints(dev, 1);
27451 return 0;
27452 }
27453 /* We couldn't process everything. */
27454 return 1;
27455 }
27456 </pre>
27457 The central part of the function is concerned with the creation of an skb holding the
27458 packet; this code is the same as what we saw in <i>snull_rx </i>before. A number of things
27459 are different, however:<br>
27460 <ul>
27461 <li> The <font class="fixd">budget</font> parameter provides a maximum number of packets that we are
27462 allowed to pass into the kernel. Within the device structure, the <font class="fixd">quota</font> field gives
27463 another maximum; the <i>poll </i>method must respect the lower of the two limits. It
27464 should also decrement both <font class="fixd">dev->quota</font> and <font class="fixd">*budget</font> by the number of packets
27465 actually received. The <font class="fixd">budget</font> value is a maximum number of packets that the
27466 current CPU can receive from all interfaces, while <font class="fixd">quota</font> is a per-interface value
27467 </ul>
27468 <A name="528"></a><font color="blue">PAGE 528</font>
27469 <ul>
27470 that usually starts out as the <font class="fixd">weight</font> assigned to the interface at initialization time.
27471 <li> Packets should be fed to the kernel with <i>netif_receive_skb</i>, rather than <i>netif_rx</i>.
27472 <li> If the <i>poll </i>method is able to process all of the available packets within the limits
27473 given to it, it should re-enable receive interrupts, call <i>netif_rx_complete </i>to turn
27474 off polling, and return <font class="fixd">0.</font> A return value of <font class="fixd">1</font> indicates that there are packets
27475 remaining to be processed.
27476 </ul>
27477 The networking subsystem guarantees that any given device's <i>poll </i>method will not
27478 be called concurrently on more than one processor. Calls to <i>poll </i>can still happen
27479 concurrently with calls to your other device methods, however.<br>
27480 <br>
27481 <a name="ChangesInLinkState"></a><font color="red"><b>Changes in Link State</b></font><br>
27482 <br>
27483 Network connections, by definition, deal with the world outside the local system.
27484 Therefore, they are often affected by outside events, and they can be transient things.
27485 The networking subsystem needs to know when network links go up or down, and it
27486 provides a few functions that the driver may use to convey that information.<br>
27487 <br>
27488 Most networking technologies involving an actual, physical connection provide a
27489 <i>carrier </i>state; the presence of the carrier means that the hardware is present and ready
27490 to function. Ethernet adapters, for example, sense the carrier signal on the wire;
27491 when a user trips over the cable, that carrier vanishes, and the link goes down. By
27492 default, network devices are assumed to have a carrier signal present. The driver can
27493 change that state explicitly, however, with these functions:<br>
27494 <pre>
27495 void netif_carrier_off(struct net_device *dev);
27496 void netif_carrier_on(struct net_device *dev);
27497 </pre>
27498 If your driver detects a lack of carrier on one of its devices, it should call <i>netif_carrier_off
27499 </i>to inform the kernel of this change. When the carrier returns, <i>netif_carrier_on </i>should be
27500 called. Some drivers also call <i>netif_carrier_off </i>when making major configuration
27501 changes (such as media type); once the adapter has finished resetting itself, the new carrier
27502 is detected and traffic can resume.<br>
27503 <br>
27504 An integer function also exists:<br>
27505 <pre>
27506 int netif_carrier_ok(struct net_device *dev);
27507 </pre>
27508 This can be used to test the current carrier state (as reflected in the device structure).<br>
27509 <br>
27510 <a name="TheSocketBuffers"></a><font color="red"><b>The Socket Buffers</b></font><br>
27511 <br>
27512 We've now covered most of the issues related to network interfaces. What's still
27513 missing is some more detailed discussion of the <font class="fixd">sk_buff</font> structure. The structure is at
27514 the core of the network subsystem of the Linux kernel, and we now introduce both
27515 the main fields of the structure and the functions used to act on it.<br>
27516 <br>
27517 <A name="529"></a><font color="blue">PAGE 529</font><br>
27518 <br>
27519 Although there is no strict need to understand the internals of <font class="fixd">sk_buff,</font> the ability to
27520 look at its contents can be helpful when you are tracking down problems and when
27521 you are trying to optimize your code. For example, if you look in <i>loopback.c</i>, you'll
27522 find an optimization based on knowledge of the <font class="fixd">sk_buff</font> internals. The usual warning
27523 applies here: if you write code that takes advantage of knowledge of the <font class="fixd">sk_buff</font>
27524 structure, you should be prepared to see it break with future kernel releases. Still,
27525 sometimes the performance advantages justify the additional maintenance cost.<br>
27526 <br>
27527 We are not going to describe the whole structure here, just the fields that might be
27528 used from within a driver. If you want to see more, you can look at <i><linux/skbuff.h></i>,
27529 where the structure is defined and the functions are prototyped. Additional details
27530 about how the fields and functions are used can be easily retrieved by grepping in the
27531 kernel sources.<br>
27532 <br>
27533 <a name="TheImportantFields"></a><font color="red"><b>The Important Fields</b></font><br>
27534 <br>
27535 The fields introduced here are the ones a driver might need to access. They are listed
27536 in no particular order.<br>
27537 <br>
27538 <font class="fixd">struct net_device *dev;</font><br>
27539 <div class="bq">
27540 The device receiving or sending this buffer.</div>
27541 <br>
27542 <font class="fixd">union { /* ... */ } h;<br>
27543 union { /* ... */ } nh;<br>
27544 union { /*... */} mac;</font><br>
27545 <div class="bq">
27546 Pointers to the various levels of headers contained within the packet. Each field
27547 of the union is a pointer to a different type of data structure. <font class="fixd">h</font> hosts pointers to
27548 transport layer headers (for example, <font class="fixd">struct tcphdr *th</font>); <font class="fixd">nh</font> includes network
27549 layer headers (such as <font class="fixd">struct iphdr *iph</font>); and <font class="fixd">mac</font> collects pointers to link-layer
27550 headers (such as <font class="fixd">struct ethdr *ethernet</font>).<br>
27551 <br>
27552 If your driver needs to look at the source and destination addresses of a TCP
27553 packet, it can find them in <font class="fixd">skb->h.th.</font> See the header file for the full set of header
27554 types that can be accessed in this way.<br>
27555 <br>
27556 Note that network drivers are responsible for setting the <font class="fixd">mac</font> pointer for incoming
27557 packets. This task is normally handled by <i>eth_type_trans</i>, but non-Ethernet
27558 drivers have to set <font class="fixd">skb->mac.raw</font> directly, as shown in the section "Non-Ethernet
27559 Headers."</div>
27560 <br>
27561 <font class="fixd">unsigned char *head;<br>
27562 unsigned char *data;<br>
27563 unsigned char *tail;<br>
27564 unsigned char *end;</font><br>
27565 <div class="bq">
27566 Pointers used to address the data in the packet. <font class="fixd">head</font> points to the beginning of
27567 the allocated space, <font class="fixd">data</font> is the beginning of the valid octets (and is usually
27568 slightly greater than <font class="fixd">head</font>), <font class="fixd">tail</font> is the end of the valid octets, and <font class="fixd">end</font> points to</div>
27569 <br>
27570 <A name="530"></a><font color="blue">PAGE 530</font><br>
27571 <br>
27572 <div class="bq">the maximum address<font class="fixd"> tail</font> can reach. Another way to look at it is that the <i>available
27573 </i>buffer space is <font class="fixd">skb->end - skb->head,</font> and the <i>currently used </i>data space is
27574 <font class="fixd">skb->tail - skb->data.</font></div>
27575 <br>
27576 <font class="fixd">unsigned int len;<br>
27577 unsigned int data_len;</font><br>
27578 <div class="bq">
27579 len is the full length of the data in the packet, while <font class="fixd">data_len</font> is the length of the
27580 portion of the packet stored in separate fragments. The <font class="fixd">data_len</font> field is <font class="fixd">0</font> unless
27581 scatter/gather I/O is being used.</div>
27582 <br>
27583 <font class="fixd">unsigned char ip_summed;</font><br>
27584 <div class="bq">
27585 The checksum policy for this packet. The field is set by the driver on incoming
27586 packets, as described in the section "Packet Reception."</div>
27587 <br>
27588 <font class="fixd">unsigned char pkt_type;</font><br>
27589 <div class="bq">
27590 Packet classification used in its delivery. The driver is responsible for setting it to
27591 <font class="fixd">PACKET_HOST</font> (this packet is for me), <font class="fixd">PACKET_OTHERHOST</font> (no, this packet is not for
27592 me), <font class="fixd">PACKET_BROADCAST</font>, or <font class="fixd">PACKET_MULTICAST</font>. Ethernet drivers don't
27593 modify <font class="fixd">pkt_type</font> explicitly because <i>eth_type_trans</i> does it for them.</div>
27594 <br>
27595 <font class="fixd">shinfo(struct sk_buff *skb);<br>
27596 unsigned int shinfo(skb)->nr_frags;<br>
27597 skb_frag_t shinfo(skb)->frags;</font><br>
27598 <div class="bq">
27599 For performance reasons, some skb information is stored in a separate structure
27600 that appears immediately after the skb in memory. This "shared info" (so called
27601 because it can be shared among copies of the skb within the networking code)
27602 must be accessed via the <i>shinfo </i>macro. There are several fields in this structure,
27603 but most of them are beyond the scope of this book. We saw <font class="fixd">nr_frags</font> and <font class="fixd">frags</font>
27604 in the section "Scatter/Gather I/O."</div>
27605 <br>
27606 The remaining fields in the structure are not particularly interesting. They are used to
27607 maintain lists of buffers, to account for memory belonging to the socket that owns
27608 the buffer, and so on.<br>
27609 <br>
27610 <a name="FunctionsActingOnSocketBuffers"></a><font color="red"><b>Functions Acting on Socket Buffers</b></font><br>
27611 <br>
27612 Network devices that use an <font class="fixd">sk_buff</font> structure act on it by means of the official interface
27613 functions. Many functions operate on socket buffers; here are the most interesting
27614 ones:<br>
27615 <br>
27616 <font class="fixd">struct sk_buff *alloc_skb(unsigned int len, int priority);<br>
27617 struct sk_buff *dev_alloc_skb(unsigned int len);</font><br>
27618 <div class="bq">
27619 Allocate a buffer. The <i>alloc_skb </i>function allocates a buffer and initializes both
27620 <font class="fixd">skb->data</font> and <font class="fixd">skb->tail</font> to <font class="fixd">skb->head.</font> The <i>dev_alloc_skb </i>function is a shortcut
27621 that calls <i>alloc_skb </i>with <font class="fixd">GFP_ATOMIC</font> priority and reserves some space between
27622 <font class="fixd">skb->head</font> and <font class="fixd">skb->data.</font> This data space is used for optimizations within the
27623 network layer and should not be touched by the driver.</div>
27624 <br>
27625 <A name="531"></a><font color="blue">PAGE 531</font><br>
27626 <br>
27627 <font class="fixd">void kfree_skb(struct sk_buff *skb);<br>
27628 void dev_kfree_skb(struct sk_buff *skb);<br>
27629 void dev_kfree_skb_irq(struct sk_buff *skb);<br>
27630 void dev_kfree_skb_any(struct sk_buff *skb);</font><br>
27631 <div class="bq">
27632 Free a buffer. The <i>kfree_skb </i>call is used internally by the kernel. A driver should
27633 use one of the forms of <i>dev_kfree_skb </i>instead: <i>dev_kfree_skb </i>for noninterrupt
27634 context, <i>dev_kfree_skb_irq </i>for interrupt context, or <i>dev_kfree_skb_any </i>for code
27635 that can run in either context.</div>
27636 <br>
27637 <font class="fixd">unsigned char *skb_put(struct sk_buff *skb, int len);<br>
27638 unsigned char *__skb_put(struct sk_buff *skb, int len);</font><br>
27639 <div class="bq">
27640 Update the <font class="fixd">tail</font> and <font class="fixd">len</font> fields of the <font class="fixd">sk_buff</font> structure; they are used to add data
27641 to the end of the buffer. Each function's return value is the previous value of
27642 <font class="fixd">skb->tail</font> (in other words, it points to the data space just created). Drivers can
27643 use the return value to copy data by invoking <font class="fixd">memcpy(skb_put(...), data, len)</font>
27644 or an equivalent. The difference between the two functions is that <i>skb_put
27645 </i>checks to be sure that the data fits in the buffer, whereas <i>__skb_put </i>omits the
27646 check.</div>
27647 <br>
27648 <font class="fixd">unsigned char *skb_push(struct sk_buff *skb, int len);<br>
27649 unsigned char *__skb_push(struct sk_buff *skb, int len);</font><br>
27650 <div class="bq">
27651 Functions to decrement <font class="fixd">skb->data</font> and increment <font class="fixd">skb->len.</font> They are similar to
27652 <i>skb_put</i>, except that data is added to the beginning of the packet instead of the
27653 end. The return value points to the data space just created. The functions are used
27654 to add a hardware header before transmitting a packet. Once again, <i>__skb_push
27655 </i>differs in that it does not check for adequate available space.</div>
27656 <br>
27657 <font class="fixd">int skb_tailroom(struct sk_buff *skb);</font><br>
27658 <div class="bq">
27659 Returns the amount of space available for putting data in the buffer. If a driver
27660 puts more data into the buffer than it can hold, the system panics. Although you
27661 might object that a <i>printk </i>would be sufficient to tag the error, memory corruption
27662 is so harmful to the system that the developers decided to take definitive
27663 action. In practice, you shouldn't need to check the available space if the buffer
27664 has been correctly allocated. Since drivers usually get the packet size before allocating
27665 a buffer, only a severely broken driver puts too much data in the buffer,
27666 and a panic might be seen as due punishment.</div>
27667 <br>
27668 <font class="fixd">int skb_headroom(struct sk_buff *skb);</font><br>
27669 <div class="bq">
27670 Returns the amount of space available in front of data, that is, how many octets
27671 one can "push" to the buffer.</div>
27672 <br>
27673 <font class="fixd">void skb_reserve(struct sk_buff *skb, int len);</font><br>
27674 <div class="bq">
27675 Increments both <font class="fixd">data</font> and <font class="fixd">tail.</font> The function can be used to reserve headroom
27676 before filling the buffer. Most Ethernet interfaces reserve two bytes in front of
27677 the packet; thus, the IP header is aligned on a 16-byte boundary, after a 14-byte
27678 Ethernet header. <i>snull </i>does this as well, although the instruction was not shown
27679 in "Packet Reception" to avoid introducing extra concepts at that point.</div>
27680 <br>
27681 <A name="532"></a><font color="blue">PAGE 532</font><br>
27682 <br>
27683 <font class="fixd">unsigned char *skb_pull(struct sk_buff *skb, int len);</font><br>
27684 <div class="bq">
27685 Removes data from the head of the packet. The driver won't need to use this
27686 function, but it is included here for completeness. It decrements <font class="fixd">skb->len</font> and
27687 increments <font class="fixd">skb->data;</font> this is how the hardware header (Ethernet or equivalent)
27688 is stripped from the beginning of incoming packets.</div>
27689 <br>
27690 <font class="fixd">int skb_is_nonlinear(struct sk_buff *skb);</font><br>
27691 <div class="bq">
27692 Returns a true value if this skb is separated into multiple fragments for scatter/gather
27693 I/O.</div>
27694 <br>
27695 <font class="fixd">int skb_headlen(struct sk_buff *skb);</font><br>
27696 <div class="bq">
27697 Returns the length of the first segment of the skb (that part pointed to by <font class="fixd">skb->data</font>).</div>
27698 <br>
27699 <font class="fixd">void *kmap_skb_frag(skb_frag_t *frag);<br>
27700 void kunmap_skb_frag(void *vaddr);</font><br>
27701 <div class="bq">
27702 If you must directly access fragments in a nonlinear skb from within the kernel,
27703 these functions map and unmap them for you. An atomic kmap is used, so you
27704 cannot have more than one fragment mapped at a time.</div>
27705 <br>
27706 The kernel defines several other functions that act on socket buffers, but they are
27707 meant to be used in higher layers of networking code, and the driver doesn't need them.<br>
27708 <br>
27709 <a name="MACAddressResolution"></a><font color="red"><b>MAC Address Resolution</b></font><br>
27710 <br>
27711 An interesting issue with Ethernet communication is how to associate the MAC
27712 addresses (the interface's unique hardware ID) with the IP number. Most protocols
27713 have a similar problem, but we concentrate on the Ethernet-like case here. We try to
27714 offer a complete description of the issue, so we show three situations: ARP, Ethernet
27715 headers without ARP (such as <i>plip</i>), and non-Ethernet headers.<br>
27716 <br>
27717 <a name="UsingARPWithEthernet"></a><font color="red"><b>Using ARP with Ethernet</b></font><br>
27718 <br>
27719 The usual way to deal with address resolution is by using the Address Resolution
27720 Protocol (ARP). Fortunately, ARP is managed by the kernel, and an Ethernet interface
27721 doesn't need to do anything special to support ARP. As long as <font class="fixd">dev->addr</font> and
27722 <font class="fixd">dev->addr_len</font> are correctly assigned at open time, the driver doesn't need to worry
27723 about resolving IP numbers to MAC addresses; <i>ether_setup </i>assigns the correct device
27724 methods to <font class="fixd">dev->hard_header</font> and <font class="fixd">dev->rebuild_header.</font><br>
27725 <br>
27726 Although the kernel normally handles the details of address resolution (and caching
27727 of the results), it calls upon the interface driver to help in the building of the packet.
27728 After all, the driver knows about the details of the physical layer header, while the
27729 authors of the networking code have tried to insulate the rest of the kernel from that
27730 knowledge. To this end, the kernel calls the driver's <i>hard_header </i>method to lay out<br>
27731 <br>
27732 <A name="533"></a><font color="blue">PAGE 533</font><br>
27733 <br>
27734 the packet with the results of the ARP query. Normally, Ethernet driver writers need
27735 not know about this process--the common Ethernet code takes care of everything.<br>
27736 <br>
27737 <a name="OverridingARP"></a><font color="red"><b>Overriding ARP</b></font><br>
27738 <br>
27739 Simple point-to-point network interfaces, such as <i>plip</i>, might benefit from using
27740 Ethernet headers, while avoiding the overhead of sending ARP packets back and
27741 forth. The sample code in <i>snull </i>also falls into this class of network devices. <i>snull </i>cannot
27742 use ARP because the driver changes IP addresses in packets being transmitted,
27743 and ARP packets exchange IP addresses as well. Although we could have implemented
27744 a simple ARP reply generator with little trouble, it is more illustrative to
27745 show how to handle physical-layer headers directly.<br>
27746 <br>
27747 If your device wants to use the usual hardware header without running ARP, you
27748 need to override the default <i>dev->hard_header </i>method. This is how <i>snull </i>implements
27749 it, as a very short function:<br>
27750 <pre>
27751 int snull_header(struct sk_buff *skb, struct net_device *dev,
27752 unsigned short type, void *daddr, void *saddr,
27753 unsigned int len)
27754 {
27755 struct ethhdr *eth = (struct ethhdr *)skb_push(skb,ETH_HLEN);
27757 eth->h_proto = htons(type);
27758 memcpy(eth->h_source, saddr ? saddr : dev->dev_addr, dev->addr_len);
27759 memcpy(eth->h_dest, daddr ? daddr : dev->dev_addr, dev->addr_len);
27760 eth->h_dest[ETH_ALEN-1] ^= 0x01; /* dest is us xor 1 */
27761 return (dev->hard_header_len);
27762 }
27763 </pre>
27764 The function simply takes the information provided by the kernel and formats it into
27765 a standard Ethernet header. It also toggles a bit in the destination Ethernet address,
27766 for reasons described later.<br>
27767 <br>
27768 When a packet is received by the interface, the hardware header is used in a couple
27769 of ways by <i>eth_type_trans</i>. We have already seen this call in <i>snull_rx</i>:<br>
27770 <pre>
27771 skb->protocol = eth_type_trans(skb, dev);
27772 </pre>
27773 The function extracts the protocol identifier (<font class="fixd">ETH_P_IP,</font> in this case) from the Ethernet
27774 header; it also assigns <font class="fixd">skb->mac.raw,</font> removes the hardware header from packet data
27775 (with <i>skb_pull</i>), and sets <font class="fixd">skb->pkt_type.</font> This last item defaults to <font class="fixd">PACKET_HOST</font> at <font class="fixd">skb</font>
27776 allocation (which indicates that the packet is directed to this host), and <i>eth_type_trans
27777 </i>changes it to reflect the Ethernet destination address: if that address does not match the
27778 address of the interface that received it, the <font class="fixd">pkt_type</font> field is set to <font class="fixd">PACKET_OTHERHOST</font>.
27779 Subsequently, unless the interface is in promiscuous mode or packet forwarding is
27780 enabled in the kernel, <i>netif_rx </i>drops any packet of type <font class="fixd">PACKET_OTHERHOST</font>. For this reason,
27781 <i>snull_header </i>is careful to make the destination hardware address match that of the
27782 "receiving" interface.<br>
27783 <br>
27784 <A name="534"></a><font color="blue">PAGE 534</font><br>
27785 <br>
27786 If your interface is a point-to-point link, you won't want to receive unexpected multicast
27787 packets. To avoid this problem, remember that a destination address whose first
27788 octet has <font class="fixd">0</font> as the least significant bit (LSB) is directed to a single host (i.e., it is either
27789 <font class="fixd">PACKET_HOST</font> or <font class="fixd">PACKET_OTHERHOST</font>). The <i>plip </i>driver uses <font class="fixd">0xfc</font> as the first octet of its
27790 hardware address, while <i>snull </i>uses <font class="fixd">0x00.</font> Both addresses result in a working Ethernet like
27791 point-to-point link.<br>
27792 <br>
27793 <a name="NonEthernetHeaders"></a><font color="red"><b>Non-Ethernet Headers</b></font><br>
27794 <br>
27795 We have just seen that the hardware header contains some information in addition to
27796 the destination address, the most important being the communication protocol. We
27797 now describe how hardware headers can be used to encapsulate relevant information.
27798 If you need to know the details, you can extract them from the kernel sources or the
27799 technical documentation for the particular transmission medium. Most driver writers
27800 are able to ignore this discussion and just use the Ethernet implementation.<br>
27801 <br>
27802 It's worth noting that not all information has to be provided by every protocol. A
27803 point-to-point link such as <i>plip </i>or <i>snull </i>could avoid transferring the whole Ethernet
27804 header without losing generality. The <i>hard_header </i>device method, shown earlier as
27805 implemented by <i>snull_header</i>, receives the delivery information--both protocol-level
27806 and hardware addresses--from the kernel. It also receives the 16-bit protocol number
27807 in the type argument; IP, for example, is identified by <font class="fixd">ETH_P_IP</font>. The driver is
27808 expected to correctly deliver both the packet data and the protocol number to the
27809 receiving host. A point-to-point link could omit addresses from its hardware header,
27810 transferring only the protocol number, because delivery is guaranteed independent of
27811 the source and destination addresses. An IP-only link could even avoid transmitting
27812 any hardware header whatsoever.<br>
27813 <br>
27814 When the packet is picked up at the other end of the link, the receiving function in the
27815 driver should correctly set the fields <font class="fixd">skb->protocol, skb->pkt_type, and skb->mac.raw.</font><br>
27816 <br>
27817 <font class="fixd">skb->mac.raw</font> is a char pointer used by the address-resolution mechanism implemented
27818 in higher layers of the networking code (for instance, <i>net/ipv4/arp.c</i>). It must
27819 point to a machine address that matches <font class="fixd">dev->type.</font> The possible values for the
27820 device type are defined in <i><linux/if_arp.h></i>; Ethernet interfaces use <font class="fixd">ARPHRD_ETHER</font>. For
27821 example, here is how <i>eth_type_trans </i>deals with the Ethernet header for received
27822 packets:<br>
27823 <pre>
27824 skb->mac.raw = skb->data;
27825 skb_pull(skb, dev->hard_header_len);
27826 </pre>
27827 In the simplest case (a point-to-point link with no headers), <font class="fixd">skb->mac.raw</font> can point
27828 to a static buffer containing the hardware address of this interface, <font class="fixd">protocol</font> can be
27829 set to <font class="fixd">ETH_P_IP,</font> and <font class="fixd">packet_type</font> can be left with its default value of <font class="fixd">PACKET_HOST</font>.<br>
27830 <br>
27831 Because every hardware type is unique, it is hard to give more specific advice than
27832 already discussed. The kernel is full of examples, however. See, for example, the<br>
27833 <br>
27834 <A name="535"></a><font color="blue">PAGE 535</font><br>
27835 <br>
27836 AppleTalk driver (<i>drivers/net/appletalk/cops.c</i>), the infrared drivers (such as <i>drivers/
27837 net/irda/smc_ircc.c</i>), or the PPP driver (<i>drivers/net/ppp_generic.c</i>).<br>
27838 <br>
27839 <a name="CustomIoctlCommands"></a><font color="red"><b>Custom ioctl Commands</b></font><br>
27840 <br>
27841 We have seen that the <i>ioctl </i>system call is implemented for sockets; <font class="fixd">SIOCSIFADDR</font> and
27842 <font class="fixd">SIOCSIFMAP</font> are examples of "socket <i>ioctls</i>." Now let's see how the third argument of
27843 the system call is used by networking code.<br>
27844 <br>
27845 When the <i>ioctl </i>system call is invoked on a socket, the command number is one of the
27846 symbols defined in <i><linux/sockios.h></i>, and the <i>sock_ioctl </i>function directly invokes a
27847 protocol-specific function (where "protocol" refers to the main network protocol
27848 being used, for example, IP or AppleTalk).<br>
27849 <br>
27850 Any <i>ioctl </i>command that is not recognized by the protocol layer is passed to the
27851 device layer. These device-related <i>ioctl </i>commands accept a third argument from user
27852 space, a <font class="fixd">struct ifreq*.</font> This structure is defined in <i><linux/if.h></i>. The <font class="fixd">SIOCSIFADDR</font>
27853 and <font class="fixd">SIOCSIFMAP</font> commands actually work on the <font class="fixd">ifreq</font> structure. The extra argument
27854 to <font class="fixd">SIOCSIFMAP</font>, although defined as <font class="fixd">ifmap,</font> is just a field of <font class="fixd">ifreq.</font><br>
27855 <br>
27856 In addition to using the standardized calls, each interface can define its own <i>ioctl
27857 </i>commands. The <i>plip </i>interface, for example, allows the interface to modify its internal
27858 timeout values via <i>ioctl</i>. The <i>ioctl </i>implementation for sockets recognizes 16 commands
27859 as private to the interface: <font class="fixd">SIOCDEVPRIVATE</font> through <font class="fixd">SIOCDEVPRIVATE+15.*</font><br>
27860 <br>
27861 When one of these commands is recognized, <font class="fixd">dev->do_ioctl</font> is called in the relevant
27862 interface driver. The function receives the same <font class="fixd">struct ifreq*</font> pointer that the
27863 general-purpose <i>ioctl</i> function uses:<br>
27864 <pre>
27865 int (*do_ioctl)(struct net_device *dev, struct ifreq *ifr, int cmd);
27866 </pre>
27867 The <font class="fixd">ifr</font> pointer points to a kernel-space address that holds a copy of the structure
27868 passed by the user. After <i>do_ioctl </i>returns, the structure is copied back to user space;
27869 Therefore, the driver can use the private commands to both receive and return data.<br>
27870 <br>
27871 The device-specific commands can choose to use the fields in </font>struct ifreq,</font> but they
27872 already convey a standardized meaning, and it's unlikely that the driver can adapt
27873 the structure to its needs. The field <font class="fixd">ifr_data</font> is a <font class="fixd">caddr_t</font> item (a pointer) that is
27874 meant to be used for device-specific needs. The driver and the program used to
27875 invoke its <i>ioctl </i>commands should agree about the use of <font class="fixd">ifr_data</font>. For example, <i>pppstats
27876 </i>uses device-specific commands to retrieve information from the <i>ppp </i>interface
27877 driver.<br>
27878 <br>
27879 * Note that, according to <i><linux/sockios.h></i>, the <font class="fixd">SIOCDEVPRIVATE</font> commands are deprecated.
27880 What should replace them is not clear, however, and numerous in-tree drivers still use them.<br>
27881 <br>
27882 <A name="536"></a><font color="blue">PAGE 536</font><br>
27883 <br>
27884 It's not worth showing an implementation of <i>do_ioctl </i>here, but with the information
27885 in this chapter and the kernel examples, you should be able to write one when you
27886 need it. Note, however, that the <i>plip </i>implementation uses <font class="fixd">ifr_data</font> incorrectly and
27887 should not be used as an example for an <i>ioctl</i> implementation.<br>
27888 <br>
27889 <a name="StatisticalInformation"></a><font color="red"><b>Statistical Information</b></font><br>
27890 <br>
27891 The last method a driver needs is <i>get_stats</i>. This method returns a pointer to the statistics
27892 for the device. Its implementation is pretty easy; the one shown works even
27893 when several interfaces are managed by the same driver, because the statistics are
27894 hosted within the device data structure.<br>
27895 <pre>
27896 struct net_device_stats *snull_stats(struct net_device *dev)
27897 {
27898 struct snull_priv *priv = netdev_priv(dev);
27899 return &priv->stats;
27900 }
27901 </pre>
27902 The real work needed to return meaningful statistics is distributed throughout the
27903 driver, where the various fields are updated. The following list shows the most interesting
27904 fields in <font class="fixd">struct net_device_stats:</font><br>
27905 <br>
27906 <font class="fixd">unsigned long rx_packets;<br>
27907 unsigned long tx_packets;</font><br>
27908 <div class="bq">
27909 The total number of incoming and outgoing packets successfully transferred by
27910 the interface.</div>
27911 <br>
27912 <font class="fixd">unsigned long rx_bytes;<br>
27913 unsigned long tx_bytes;</font><br>
27914 <div class="bq">
27915 The number of bytes received and transmitted by the interface.</div>
27916 <br>
27917 <font class="fixd">unsigned long rx_errors;<br>
27918 unsigned long tx_errors;</font><br>
27919 <div class="bq">
27920 The number of erroneous receptions and transmissions. There's no end of things
27921 that can go wrong with packet transmission, and the <font class="fixd">net_device_stats</font> structure
27922 includes six counters for specific receive errors and five for transmit errors. See
27923 <i><linux/netdevice.h> </i>for the full list. If possible, your driver should maintain
27924 detailed error statistics, because they can be most helpful to system administrators
27925 trying to track down a problem.</div>
27926 <br>
27927 <font class="fixd">unsigned long rx_dropped;<br>
27928 unsigned long tx_dropped;</font><br>
27929 <div class="bq">
27930 The number of packets dropped during reception and transmission. Packets are
27931 dropped when there's no memory available for packet data. <font class="fixd">tx_dropped</font> is rarely
27932 used.</div>
27933 <br>
27934 <A name="537"></a><font color="blue">PAGE 537</font><br>
27935 <br>
27936 <font class="fixd">unsigned long collisions;</font><br>
27937 <div class="bq">
27938 The number of collisions due to congestion on the medium.</div>
27939 <br>
27940 <font class="fixd">unsigned long multicast;</font><br>
27941 <div class="bq">
27942 The number of multicast packets received.</div>
27943 <br>
27944 It is worth repeating that the <i>get_stats </i>method can be called at any time--even when
27945 the interface is down--so the driver must retain statistical information for as long as
27946 the <font class="fixd">net_device</font> structure exists.<br>
27947 <br>
27948 <a name="Multicast"></a><font color="red"><b>Multicast</b></font><br>
27949 <br>
27950 A <i>multicast </i>packet is a network packet meant to be received by more than one host,
27951 but not by all hosts. This functionality is obtained by assigning special hardware
27952 addresses to groups of hosts. Packets directed to one of the special addresses should
27953 be received by all the hosts in that group. In the case of Ethernet, a multicast address
27954 has the least significant bit of the first address octet set in the destination address,
27955 while every device board has that bit clear in its own hardware address.<br>
27956 <br>
27957 The tricky part of dealing with host groups and hardware addresses is performed by
27958 applications and the kernel, and the interface driver doesn't need to deal with these
27959 problems.<br>
27960 <br>
27961 Transmission of multicast packets is a simple problem because they look exactly like
27962 any other packets. The interface transmits them over the communication medium
27963 without looking at the destination address. It's the kernel that has to assign a correct
27964 hardware destination address; the <i>hard_header </i>device method, if defined, doesn't
27965 need to look in the data it arranges.<br>
27966 <br>
27967 The kernel handles the job of tracking which multicast addresses are of interest at
27968 any given time. The list can change frequently, since it is a function of the applications
27969 that are running at any given time and the users' interest. It is the driver's job to
27970 accept the list of interesting multicast addresses and deliver to the kernel any packets
27971 sent to those addresses. How the driver implements the multicast list is somewhat
27972 dependent on how the underlying hardware works. Typically, hardware
27973 belongs to one of three classes, as far as multicast is concerned:<br>
27974 <ul>
27975 <li> Interfaces that cannot deal with multicast. These interfaces either receive
27976 packets directed specifically to their hardware address (plus broadcast packets) or
27977 receive every packet. They can receive multicast packets only by receiving every
27978 packet, thus, potentially overwhelming the operating system with a huge number
27979 of "uninteresting" packets. You don't usually count these interfaces as multicast
27980 capable, and the driver won't set <font class="fixd">IFF_MULTICAST</font> in <font class="fixd">dev->flags.</font><br>
27981 <br>
27982 Point-to-point interfaces are a special case because they always receive every
27983 packet without performing any hardware filtering.
27984 </ul>
27985 <A name="538"></a><font color="blue">PAGE 538</font>
27986 <ul>
27987 <li> Interfaces that can tell multicast packets from other packets (host-to-host or
27988 broadcast). These interfaces can be instructed to receive every multicast packet
27989 and let the software determine if the address is interesting for this host. The
27990 overhead introduced in this case is acceptable, because the number of multicast
27991 packets on a typical network is low.
27992 <li> Interfaces that can perform hardware detection of multicast addresses. These
27993 interfaces can be passed a list of multicast addresses for which packets are to be
27994 received, and ignore other multicast packets. This is the optimal case for the kernel,
27995 because it doesn't waste processor time dropping "uninteresting" packets
27996 received by the interface.
27997 </ul>
27998 The kernel tries to exploit the capabilities of high-level interfaces by supporting the
27999 third device class, which is the most versatile, at its best. Therefore, the kernel notifies
28000 the driver whenever the list of valid multicast addresses is changed, and it passes
28001 the new list to the driver so it can update the hardware filter according to the new
28002 information.<br>
28003 <br>
28004 <a name="KernelSupportForMulticasting"></a><font color="red"><b>Kernel Support for Multicasting</b></font><br>
28005 <br>
28006 Support for multicast packets is made up of several items: a device method, a data
28007 structure, and device flags:<br>
28008 <br>
28009 <font class="fixd">void (*dev->set_multicast_list)(struct net_device *dev);</font><br>
28010 <div class="bq">
28011 Device method called whenever the list of machine addresses associated with the
28012 device changes. It is also called when <font class="fixd">dev->flags</font> is modified, because some flags
28013 (e.g., <font class="fixd">IFF_PROMISC</font>) may also require you to reprogram the hardware filter. The
28014 method receives a pointer to <font class="fixd">struct net_device</font> as an argument and returns
28015 <font class="fixd">void.</font> A driver not interested in implementing this method can leave the field set
28016 to NULL.</div>
28017 <br>
28018 <font class="fixd">struct dev_mc_list *dev->mc_list;</font><br>
28019 <div class="bq">
28020 A linked list of all the multicast addresses associated with the device. The actual
28021 definition of the structure is introduced at the end of this section.</div>
28022 <br>
28023 <font class="fixd">int dev->mc_count;</font><br>
28024 <div class="bq">
28025 The number of items in the linked list. This information is somewhat redundant,
28026 but checking <font class="fixd">mc_count</font> against <font class="fixd">0</font> is a useful shortcut for checking the list.</div>
28027 <br>
28028 <font class="fixd">IFF_MULTICAST</font><br>
28029 <div class="bq">
28030 Unless the driver sets this flag in <font class="fixd">dev->flags,</font> the interface won't be asked to handle
28031 multicast packets. Nonetheless, the kernel calls the driver's <i>set_multicast_list
28032 </i>method when <font class="fixd">dev->flags</font> changes, because the multicast list may have changed
28033 while the interface was not active.</div>
28034 <br>
28035 <A name="539"></a><font color="blue">PAGE 539</font><br>
28036 <br>
28037 <font class="fixd">IFF_ALLMULTI</font><br>
28038 <div class="bq">
28039 Flag set in <font class="fixd">dev->flags</font> by the networking software to tell the driver to retrieve all
28040 multicast packets from the network. This happens when multicast routing is
28041 enabled. If the flag is set, <font class="fixd">dev->mc_list</font> shouldn't be used to filter multicast packets.</div>
28042 <br>
28043 <font class="fixd">IFF_PROMISC</font><br>
28044 <div class="bq">
28045 Flag set in <font class="fixd">dev->flags</font> when the interface is put into promiscuous mode. Every
28046 packet should be received by the interface, independent of <font class="fixd">dev->mc_list.</font></div>
28047 <br>
28048 The last bit of information needed by the driver developer is the definition of <font class="fixd">struct dev_mc_list, </font>
28049 which lives in <i><linux/netdevice.h></i>:<br>
28050 <pre>
28051 struct dev_mc_list {
28052 struct dev_mc_list *next; /* Next address in list */
28053 __u8 dmi_addr[MAX_ADDR_LEN]; /* Hardware address */
28054 unsigned char dmi_addrlen; /* Address length */
28055 int dmi_users; /* Number of users */
28056 int dmi_gusers; /* Number of groups */
28057 };
28058 </pre>
28059 Because multicasting and hardware addresses are independent of the actual transmission
28060 of packets, this structure is portable across network implementations, and each
28061 address is identified by a string of octets and a length, just like <font class="fixd">dev->dev_addr.</font><br>
28062 <br>
28063 <a name="ATypicalImplementation"></a><font color="red"><b>A Typical Implementation</b></font><br>
28064 <br>
28065 The best way to describe the design of <i>set_multicast_list </i>is to show you some
28066 pseudocode.<br>
28067 <br>
28068 The following function is a typical implementation of the function in a full-featured
28069 (<font class="fixd">ff</font>) driver. The driver is full featured in that the interface it controls has a complex
28070 hardware packet filter, which can hold a table of multicast addresses to be received
28071 by this host. The maximum size of the table is <font class="fixd">FF_TABLE_SIZE</font>.<br>
28072 <br>
28073 All the functions prefixed with <font class="fixd">ff_</font> are placeholders for hardware-specific operations:<br>
28074 <pre>
28075 void ff_set_multicast_list(struct net_device *dev)
28076 {
28077 struct dev_mc_list *mcptr;
28079 if (dev->flags & IFF_PROMISC) {
28080 ff_get_all_packets( );
28081 return;
28082 }
28083 /* If there's more addresses than we handle, get all multicast
28084 packets and sort them out in software. */
28085 if (dev->flags & IFF_ALLMULTI || dev->mc_count > FF_TABLE_SIZE) {
28086 ff_get_all_multicast_packets( );
28087 return;
28088 }
28089 /* No multicast? Just get our own stuff */
28090 if (dev->mc_count = = 0) {
28091 </pre>
28092 <A name="540"></a><font color="blue">PAGE 540</font><br>
28093 <pre>
28094 ff_get_only_own_packets( );
28095 return;
28096 }
28097 /* Store all of the multicast addresses in the hardware filter */
28098 ff_clear_mc_list( );
28099 for (mc_ptr = dev->mc_list; mc_ptr; mc_ptr = mc_ptr->next)
28100 ff_store_mc_address(mc_ptr->dmi_addr);
28101 ff_get_packets_in_multicast_list( );
28102 }
28103 </pre>
28104 This implementation can be simplified if the interface cannot store a multicast table
28105 in the hardware filter for incoming packets. In that case, <font class="fixd">FF_TABLE_SIZE</font> reduces to <font class="fixd">0,</font>
28106 and the last four lines of code are not needed.<br>
28107 <br>
28108 As was mentioned earlier, even interfaces that can't deal with multicast packets need
28109 to implement the <i>set_multicast_list </i>method to be notified about changes in <font class="fixd">dev->flags. </font>
28110 This approach could be called a "nonfeatured" (<font class="fixd">nf</font>) implementation. The
28111 implementation is very simple, as shown by the following code:<br>
28112 <pre>
28113 void nf_set_multicast_list(struct net_device *dev)
28114 {
28115 if (dev->flags & IFF_PROMISC)
28116 nf_get_all_packets( );
28117 else
28118 nf_get_only_own_packets( );
28119 }
28120 </pre>
28121 Implementing <font class="fixd">IFF_PROMISC</font> is important, because otherwise the user won't be able to
28122 run <i>tcpdump </i>or any other network analyzers. If the interface runs a point-to-point
28123 link, on the other hand, there's no need to implement <i>set_multicast_list </i>at all,
28124 because users receive every packet anyway.<br>
28125 <br>
28126 <a name="AFewOtherDetails17"></a><font color="red"><b>A Few Other Details</b></font><br>
28127 <br>
28128 This section covers a few other topics that may be of interest to network driver
28129 authors. In each case, we simply try to point you in the right direction. Obtaining a
28130 complete picture of the subject probably requires spending some time digging
28131 through the kernel source as well.<br>
28132 <br>
28133 <a name="MediaIndependentInterfaceSupport"></a><font color="red"><b>Media Independent Interface Support</b></font><br>
28134 <br>
28135 Media Independent Interface (or MII) is an IEEE 802.3 standard describing how
28136 Ethernet transceivers can interface with network controllers; many products on the
28137 market conform with this interface. If you are writing a driver for an MII-compliant
28138 controller, the kernel exports a generic MII support layer that may make your life
28139 easier.<br>
28140 <br>
28141 <A name="541"></a><font color="blue">PAGE 541</font><br>
28142 <br>
28143 To use the generic MII layer, you should include <i><linux/mii.h></i>. You need to fill out an
28144 <font class="fixd">mii_if_info</font> structure with information on the physical ID of the transceiver, whether
28145 full duplex is in effect, etc. Also required are two methods for the <font class="fixd">mii_if_info</font> structure:<br>
28146 <pre>
28147 int (*mdio_read) (struct net_device *dev, int phy_id, int location);
28148 void (*mdio_write) (struct net_device *dev, int phy_id, int location, int val);
28149 </pre>
28150 As you might expect, these methods should implement communications with your
28151 specific MII interface.<br>
28152 <br>
28153 The generic MII code provides a set of functions for querying and changing the operating
28154 mode of the transceiver; many of these are designed to work with the <i>ethtool
28155 </i>utility (described in the next section). Look in <i><linux/mii.h> </i>and <i>drivers/net/mii.c </i>for
28156 the details.<br>
28157 <br>
28158 <a name="EthtoolSupport"></a><font color="red"><b>Ethtool Support</b></font><br>
28159 <br>
28160 <i>Ethtool </i>is a utility designed to give system administrators a great deal of control over
28161 the operation of network interfaces. With <i>ethtool</i>, it is possible to control various
28162 interface parameters including speed, media type, duplex operation, DMA ring
28163 setup, hardware checksumming, wake-on-LAN operation, etc., but only if <i>ethtool </i>is
28164 supported by the driver. <i>Ethtool </i>may be downloaded from <a href="http://sf.net/projects/gkernel/" target="_blank"><i>http://sf.net/projects/gkernel/</i></a>.<br>
28165 <br>
28166 The relevant declarations for <i>ethtool </i>support may be found in <i><linux/ethtool.h></i>. At
28167 the core of it is a structure of type <font class="fixd">ethtool_ops,</font> which contains a full 24 different
28168 methods for <i>ethtool </i>support. Most of these methods are relatively straightforward;
28169 see <i><linux/ethtool.h> </i>for the details. If your driver is using the MII layer, you can use
28170 <i>mii_ethtool_gset </i>and <i>mii_ethtool_sset </i>to implement the <i>get_settings </i>and <i>set_settings
28171 </i>methods, respectively.<br>
28172 <br>
28173 For <i>ethtool </i>to work with your device, you must place a pointer to your <font class="fixd">ethtool_ops</font>
28174 structure in the <font class="fixd">net_device</font> structure. The macro <font class="fixd">SET_ETHTOOL_OPS</font> (defined in <i><linux/
28175 netdevice.h></i>) should be used for this purpose. Do note that your <i>ethtool </i>methods can
28176 be called even when the interface is down.<br>
28177 <br>
28178 <a name="Netpoll"></a><font color="red"><b>Netpoll</b></font><br>
28179 <br>
28180 "Netpoll" is a relatively late (2.6.5) addition to the network stack; its purpose is to
28181 enable the kernel to send and receive packets in situations where the full network
28182 and I/O subsystems may not be available. It is used for features like remote network
28183 consoles and remote kernel debugging. Supporting netpoll in your driver is not, by
28184 any means, necessary, but it may make your device more useful in some situations.
28185 Supporting netpoll is also relatively easy in most cases.<br>
28186 <br>
28187 <A name="542"></a><font color="blue">PAGE 542</font><br>
28188 <br>
28189 Drivers implementing netpoll should implement the <i>poll_controller </i>method. Its job is
28190 to keep up with anything that may be happening on the controller in the absence of
28191 device interrupts. Almost all <i>poll_controller</i> methods take the following form:<br>
28192 <pre>
28193 void my_poll_controller(struct net_device *dev)
28194 {
28195 disable_device_interrupts(dev);
28196 call_interrupt_handler(dev->irq, dev, NULL);
28197 reenable_device_interrupts(dev);
28198 }
28199 </pre>
28200 The <i>poll_controller </i>method, in essence, is simply simulating interrupts from the
28201 given device.<br>
28202 <br>
28203 <a name="QuickReference17"></a><font color="red"><b>Quick Reference</b></font><br>
28204 <br>
28205 This section provides a reference for the concepts introduced in this chapter. It also
28206 explains the role of each header file that a driver needs to include. The lists of fields
28207 in the <font class="fixd">net_device</font> and <font class="fixd">sk_buff</font> structures, however, are not repeated here.<br>
28208 <br>
28209 <font class="fixd">#include <linux/netdevice.h></font><br>
28210 <div class="bq">
28211 Header that hosts the definitions of <font class="fixd">struct net_device</font> and <font class="fixd">struct net_device_stats,</font>
28212 and includes a few other headers that are needed by network drivers.</div>
28213 <br>
28214 <font class="fixd">struct net_device *alloc_netdev(int sizeof_priv, char *name, void (*setup)(struct net_device *);<br>
28215 struct net_device *alloc_etherdev(int sizeof_priv);<br>
28216 void free_netdev(struct net_device *dev);</font><br>
28217 <div class="bq">
28218 Functions for allocating and freeing <font class="fixd">net_device</font> structures.</div>
28219 <br>
28220 <font class="fixd">int register_netdev(struct net_device *dev);<br>
28221 void unregister_netdev(struct net_device *dev);</font><br>
28222 <div class="bq">
28223 Registers and unregisters a network device.</div>
28224 <br>
28225 <font class="fixd">void *netdev_priv(struct net_device *dev);</font><br>
28226 <div class="bq">
28227 A function that retrieves the pointer to the driver-private area of a network
28228 device structure.</div>
28229 <br>
28230 <font class="fixd">struct net_device_stats;</font><br>
28231 <div class="bq">
28232 A structure that holds device statistics.</div>
28233 <br>
28234 <font class="fixd">netif_start_queue(struct net_device *dev);<br>
28235 netif_stop_queue(struct net_device *dev);<br>
28236 netif_wake_queue(struct net_device *dev);</font><br>
28237 <div class="bq">
28238 Functions that control the passing of packets to the driver for transmission. No
28239 packets are transmitted until <i>netif_start_queue </i>has been called. <i>netif_stop_queue
28240 </i>suspends transmission, and <i>netif_wake_queue </i>restarts the queue and pokes the
28241 network layer to restart transmitting packets.</div>
28242 <br>
28243 <A name="543"></a><font color="blue">PAGE 543</font><br>
28244 <br>
28245 <font class="fixd">skb_shinfo(struct sk_buff *skb);</font><br>
28246 <div class="bq">
28247 A macro that provides access to the "shared info" portion of a packet buffer.</div>
28248 <br>
28249 <font class="fixd">void netif_rx(struct sk_buff *skb);</font><br>
28250 <div class="bq">
28251 Function that can be called (including at interrupt time) to notify the kernel that
28252 a packet has been received and encapsulated into a socket buffer.</div>
28253 <br>
28254 <font class="fixd">void netif_rx_schedule(dev);</font><br>
28255 <div class="bq">
28256 Function that informs the kernel that packets are available and that polling
28257 should be started on the interface; it is used only by NAPI-compliant drivers.</div>
28258 <br>
28259 <font class="fixd">int netif_receive_skb(struct sk_buff *skb);<br>
28260 void netif_rx_complete(struct net_device *dev);</font><br>
28261 <div class="bq">
28262 Functions that should be used only by NAPI-compliant drivers. <i>netif_receive_skb
28263 </i>is the NAPI equivalent to <i>netif_rx</i>; it feeds a packet into the kernel. When a
28264 NAPI-compliant driver has exhausted the supply of received packets, it should
28265 reenable interrupts, and call <i>netif_rx_complete</i> to stop polling.</div>
28266 <br>
28267 <font class="fixd">#include <linux/if.h></font><br>
28268 <div class="bq">
28269 Included by <i>netdevice.h</i>, this file declares the interface flags (<font class="fixd">IFF_</font> macros) and
28270 <font class="fixd">struct ifmap,</font> which has a major role in the <i>ioctl </i>implementation for network
28271 drivers.</div>
28272 <br>
28273 <font class="fixd">void netif_carrier_off(struct net_device *dev);<br>
28274 void netif_carrier_on(struct net_device *dev);<br>
28275 int netif_carrier_ok(struct net_device *dev);</font><br>
28276 <div class="bq">
28277 The first two functions may be used to tell the kernel whether a carrier signal is
28278 currently present on the given interface. <i>netif_carrier_ok </i>tests the carrier state as
28279 reflected in the device structure.</div>
28280 <br>
28281 <font class="fixd">#include <linux/if_ether.h><br>
28282 ETH_ALEN<br>
28283 ETH_P_IP<br>
28284 struct ethhdr;</font><br>
28285 <div class="bq">
28286 Included by <i>netdevice.h</i>, <i>if_ether.h </i>defines all the <font class="fixd">ETH_</font> macros used to represent
28287 octet lengths (such as the address length) and network protocols (such as IP). It
28288 also defines the <font class="fixd">ethhdr</font> structure.</div>
28289 <br>
28290 <font class="fixd">#include <linux/skbuff.h></font><br>
28291 <div class="bq">
28292 The definition of <font class="fixd">struct sk_buff</font> and related structures, as well as several inline
28293 functions to act on the buffers. This header is included by <i>netdevice.h</i>.</div>
28294 <br>
28295 <A name="544"></a><font color="blue">PAGE 544</font><br>
28296 <br>
28297 <font class="fixd">struct sk_buff *alloc_skb(unsigned int len, int priority);<br>
28298 struct sk_buff *dev_alloc_skb(unsigned int len);<br>
28299 void kfree_skb(struct sk_buff *skb);<br>
28300 void dev_kfree_skb(struct sk_buff *skb);<br>
28301 void dev_kfree_skb_irq(struct sk_buff *skb);<br>
28302 void dev_kfree_skb_any(struct sk_buff *skb);</font><br>
28303 <div class="bq">
28304 Functions that handle the allocation and freeing of socket buffers. Drivers
28305 should normally use the <font class="fixd">dev_</font> variants, which are intended for that purpose.</div>
28306 <br>
28307 <font class="fixd">unsigned char *skb_put(struct sk_buff *skb, int len);<br>
28308 unsigned char *__skb_put(struct sk_buff *skb, int len);<br>
28309 unsigned char *skb_push(struct sk_buff *skb, int len);<br>
28310 unsigned char *__skb_push(struct sk_buff *skb, int len);</font><br>
28311 <div class="bq">
28312 Functions that add data to an <font class="fixd">skb;</font> <i>skb_put </i>puts the data at the end of the <font class="fixd">skb,</font>
28313 while <i>skb_push </i>puts it at the beginning. The regular versions perform checking
28314 to ensure that adequate space is available; double-underscore versions leave
28315 those tests out.</div>
28316 <br>
28317 <font class="fixd">int skb_headroom(struct sk_buff *skb);<br>
28318 int skb_tailroom(struct sk_buff *skb);<br>
28319 void skb_reserve(struct sk_buff *skb, int len);</font><br>
28320 <div class="bq">
28321 Functions that perform management of space within an <font class="fixd">skb.</font> <i>skb_headroom </i>and
28322 <i>skb_tailroom </i>tell how much space is available at the beginning and end, respectively,
28323 of an <font class="fixd">skb.</font> <i>skb_reserve </i>may be used to reserve space at the beginning of an
28324 <font class="fixd">skb,</font> which must be empty.</div>
28325 <br>
28326 <font class="fixd">unsigned char *skb_pull(struct sk_buff *skb, int len);</font><br>
28327 <div class="bq">
28328 <i>skb_pull</i> "removes" data from an <font class="fixd">skb</font> by adjusting the internal pointers.</div>
28329 <br>
28330 <font class="fixd">int skb_is_nonlinear(struct sk_buff *skb);</font><br>
28331 <div class="bq">
28332 Function that returns a true value if this skb is separated into multiple fragments
28333 for scatter/gather I/O.</div>
28334 <br>
28335 <font class="fixd">int skb_headlen(struct sk_buff *skb);</font><br>
28336 <div class="bq">
28337 Returns the length of the first segment of the skb--that part pointed to by <font class="fixd">skb->data.</font></div>
28338 <br>
28339 <font class="fixd">void *kmap_skb_frag(skb_frag_t *frag);<br>
28340 void kunmap_skb_frag(void *vaddr);</font><br>
28341 <div class="bq">
28342 Functions that provide direct access to fragments within a nonlinear skb.</div>
28343 <br>
28344 <font class="fixd">#include <linux/etherdevice.h><br>
28345 void ether_setup(struct net_device *dev);</font><br>
28346 <div class="bq">
28347 Function that sets most device methods to the general-purpose implementation
28348 for Ethernet drivers. It also sets <font class="fixd">dev->flags</font> and assigns the next available <font class="fixd">ethx</font>
28349 name to <font class="fixd">dev->name</font> if the first character in the name is a blank space or the <font class="fixd">NULL</font>
28350 character.</div>
28351 <br>
28352 <A name="545"></a><font color="blue">PAGE 545</font><br>
28353 <br>
28354 <font class="fixd">unsigned short eth_type_trans(struct sk_buff *skb, struct net_device *dev);</font><br>
28355 <div class="bq">
28356 When an Ethernet interface receives a packet, this function can be called to set
28357 <font class="fixd">skb->pkt_type.</font> The return value is a protocol number that is usually stored in
28358 <font class="fixd">skb->protocol.</font></div>
28359 <br>
28360 <font class="fixd">#include <linux/sockios.h><br>
28361 SIOCDEVPRIVATE</font><br>
28362 <div class="bq">
28363 The first of 16 <i>ioctl </i>commands that can be implemented by each driver for its
28364 own private use. All the network <i>ioctl</i> commands are defined in <i>sockios.h</i>.</div>
28365 <br>
28366 <font class="fixd">#include <linux/mii.h><br>
28367 struct mii_if_info;</font><br>
28368 <div class="bq">
28369 Declarations and a structure supporting drivers of devices that implement the
28370 MII standard.</div>
28371 <br>
28372 <font class="fixd">#include <linux/ethtool.h><br>
28373 struct ethtool_ops;</font><br>
28374 <div class="bq">
28375 Declarations and structures that let devices work with the <i>ethtool</i> utility.</div>
28376 <br>
28377 <A name="546"></a><font color="blue">PAGE 546</font><br>
28378 <br>
28379 <a name="CHAPTER18"></a><font color="red"><b>CHAPTER 18</b></font><br>
28380 <br>
28381 <a name="TTYDrivers"></a><font color="#7519FF" size="+1"><b>TTY Drivers</b></font><br>
28382 <br>
28383 A tty device gets its name from the very old abbreviation of teletypewriter and was
28384 originally associated only with the physical or virtual terminal connection to a Unix
28385 machine. Over time, the name also came to mean any serial port style device, as terminal
28386 connections could also be created over such a connection. Some examples of
28387 physical tty devices are serial ports, USB-to-serial-port converters, and some types of
28388 modems that need special processing to work properly (such as the traditional WinModem
28389 style devices). tty virtual devices support virtual consoles that are used to log
28390 into a computer, from either the keyboard, over a network connection, or through a
28391 xterm session.<br>
28392 <br>
28393 The Linux tty driver core lives right below the standard character driver level and
28394 provides a range of features focused on providing an interface for terminal style
28395 devices to use. The core is responsible for controlling both the flow of data across a
28396 tty device and the format of the data. This allows tty drivers to focus on handling the
28397 data to and from the hardware, instead of worrying about how to control the interaction
28398 with user space in a consistent way. To control the flow of data, there are a
28399 number of different line disciplines that can be virtually "plugged" into any tty
28400 device. This is done by different tty line discipline drivers.<br>
28401 <br>
28402 As Figure 18-1 shows, the tty core takes data from a user that is to be sent to a tty
28403 device. It then passes it to a tty line discipline driver, which then passes it to the tty
28404 driver. The tty driver converts the data into a format that can be sent to the hardware.
28405 Data being received from the tty hardware flows back up through the tty
28406 driver, into the tty line discipline driver, and into the tty core, where it can be
28407 retrieved by a user. Sometimes the tty driver communicates directly to the tty core,
28408 and the tty core sends data directly to the tty driver, but usually the tty line discipline
28409 has a chance to modify the data that is sent between the two.<br>
28410 <br>
28411 The tty driver never sees the tty line discipline. The driver cannot communicate
28412 directly with the line discipline, nor does it realize it is even present. The driver's job
28413 is to format data that is sent to it in a manner that the hardware can understand, and
28414 receive data from the hardware. The tty line discipline's job is to format the data<br>
28415 <br>
28416 <A name="547"></a><font color="blue">PAGE 547</font><br>
28417 <br>
28418 <center>
28419 <img src="fig18-1.gif">
28420 </center>
28421 <br>
28422 <i>Figure 18-1. tty core overview</i><br>
28423 <br>
28424 received from a user, or the hardware, in a specific manner. This formatting usually
28425 takes the form of a protocol conversion, such as PPP or Bluetooth.<br>
28426 <br>
28427 There are three different types of tty drivers: console, serial port, and pty. The console
28428 and pty drivers have already been written and probably are the only ones needed
28429 of these types of tty drivers. This leaves any new drivers using the tty core to interact
28430 with the user and the system as serial port drivers.<br>
28431 <br>
28432 To determine what kind of tty drivers are currently loaded in the kernel and what tty
28433 devices are currently present, look at the <i>/proc/tty/drivers </i>file. This file consists of a
28434 list of the different tty drivers currently present, showing the name of the driver, the
28435 default node name, the major number for the driver, the range of minors used by the
28436 driver, and the type of the tty driver. The following is an example of this file:<br>
28437 <pre>
28438 /dev/tty /dev/tty 5 0 system:/dev/tty
28439 /dev/console /dev/console 5 1 system:console
28440 /dev/ptmx /dev/ptmx 5 2 system
28441 /dev/vc/0 /dev/vc/0 4 0 system:vtmaster
28442 usbserial /dev/ttyUSB 188 0-254 serial
28443 serial /dev/ttyS 4 64-67 serial
28444 <font class="fixd">pty_slave</font> /dev/pts 136 0-255 pty:slave
28445 <font class="fixd">pty_master</font> /dev/ptm 128 0-255 pty:master
28446 <font class="fixd">pty_slave</font> /dev/ttyp 3 0-255 pty:slave
28447 <font class="fixd">pty_master</font> /dev/pty 2 0-255 pty:master
28448 unknown /dev/tty 4 1-63 console
28449 </pre>
28450 The <i>/proc/tty/driver/ </i>directory contains individual files for some of the tty drivers, if
28451 they implement that functionality. The default serial driver creates a file in this directory
28452 that shows a lot of serial-port-specific information about the hardware. Information
28453 on how to create a file in this directory is described later.<br>
28454 <br>
28455 <A name="548"></a><font color="blue">PAGE 548</font><br>
28456 <br>
28457 All of the tty devices currently registered and present in the kernel have their own
28458 subdirectory under <i>/sys/class/tty</i>. Within that subdirectory, there is a "dev" file that
28459 contains the major and minor number assigned to that tty device. If the driver tells
28460 the kernel the locations of the physical device and driver associated with the tty
28461 device, it creates symlinks back to them. An example of this tree is:<br>
28462 <pre>
28463 /sys/class/tty/
28464 |-- console
28465 | `-- dev
28466 |-- ptmx
28467 | `-- dev
28468 |-- tty
28469 | `-- dev
28470 |-- tty0
28471 | `-- dev
28472 ...
28473 |-- ttyS1
28474 | `-- dev
28475 |-- ttyS2
28476 | `-- dev
28477 |-- ttyS3
28478 | `-- dev
28479 ...
28480 |-- ttyUSB0
28481 | |-- dev
28482 | |-- device -> ../../../devices/pci0000:00/0000:00:09.0/usb3/3-1/3-1:1.0/ttyUSB0
28483 | `-- driver -> ../../../bus/usb-serial/drivers/keyspan_4
28484 |-- ttyUSB1
28485 | |-- dev
28486 | |-- device -> ../../../devices/pci0000:00/0000:00:09.0/usb3/3-1/3-1:1.0/ttyUSB1
28487 | `-- driver -> ../../../bus/usb-serial/drivers/keyspan_4
28488 |-- ttyUSB2
28489 | |-- dev
28490 | |-- device -> ../../../devices/pci0000:00/0000:00:09.0/usb3/3-1/3-1:1.0/ttyUSB2
28491 | `-- driver -> ../../../bus/usb-serial/drivers/keyspan_4
28492 `-- ttyUSB3
28493 |-- dev
28494 |-- device -> ../../../devices/pci0000:00/0000:00:09.0/usb3/3-1/3-1:1.0/ttyUSB3
28495 `-- driver -> ../../../bus/usb-serial/drivers/keyspan_4
28496 </pre>
28497 <a name="ASmallTTYDriver"></a><font color="red"><b>A Small TTY Driver</b></font><br>
28498 <br>
28499 To explain how the tty core works, we create a small tty driver that can be loaded,
28500 written to and read from, and unloaded. The main data structure of any tty driver is
28501 the <font class="fixd">struct tty_driver</font>. It it used to register and unregister a tty driver with the tty
28502 core and is described in the kernel header file <i><linux/tty_driver.h></i>.<br>
28503 <br>
28504 <A name="549"></a><font color="blue">PAGE 549</font><br>
28505 <br>
28506 To create a <font class="fixd">struct tty_driver</font>, the function <i>alloc_tty_driver </i>must be called with the
28507 number of tty devices this driver supports as the paramater. This can be done with
28508 the following brief code:<br>
28509 <pre>
28510 /* allocate the tty driver */
28511 tiny_tty_driver = alloc_tty_driver(TINY_TTY_MINORS);
28512 if (!tiny_tty_driver)
28513 return -ENOMEM;
28514 </pre>
28515 After the <i>alloc_tty_driver </i>function is successfully called, the <font class="fixd">struct tty_driver</font>
28516 should be initialized with the proper information based on the needs of the tty
28517 driver. This structure contains a lot of different fields, but not all of them have to be
28518 initialized in order to have a working tty driver. Here is an example that shows how
28519 to initialize the structure and sets up enough of the fields to create a working tty
28520 driver. It uses the <i>tty_set_operations </i>function to help copy over the set of function
28521 operations that is defined in the driver:<br>
28522 <pre>
28523 static struct tty_operations serial_ops = {
28524 .open = tiny_open,
28525 .close = tiny_close,
28526 .write = tiny_write,
28527 .write_room = tiny_write_room,
28528 .set_termios = tiny_set_termios,
28529 };
28531 ...
28533 /* initialize the tty driver */
28534 tiny_tty_driver->owner = THIS_MODULE;
28535 tiny_tty_driver->driver_name = "tiny_tty";
28536 tiny_tty_driver->name = "ttty";
28537 tiny_tty_driver->devfs_name = "tts/ttty%d";
28538 tiny_tty_driver->major = TINY_TTY_MAJOR,
28539 tiny_tty_driver->type = TTY_DRIVER_TYPE_SERIAL,
28540 tiny_tty_driver->subtype = SERIAL_TYPE_NORMAL,
28541 tiny_tty_driver->flags = TTY_DRIVER_REAL_RAW | TTY_DRIVER_NO_DEVFS,
28542 tiny_tty_driver->init_termios = tty_std_termios;
28543 tiny_tty_driver->init_termios.c_cflag = B9600 | CS8 | CREAD | HUPCL | CLOCAL;
28544 tty_set_operations(tiny_tty_driver, &serial_ops);
28545 </pre>
28546 The variables and functions listed above, and how this structure is used, are
28547 explained in the rest of the chapter.<br>
28548 <br>
28549 To register this driver with the tty core, the <font class="fixd">struct tty_driver</font> must be passed to the
28550 <i>tty_register_driver</i> function:<br>
28551 <pre>
28552 /* register the tty driver */
28553 retval = tty_register_driver(tiny_tty_driver);
28554 if (retval) {
28555 printk(KERN_ERR "failed to register tiny tty driver");
28556 put_tty_driver(tiny_tty_driver);
28557 return retval;
28558 }
28559 </pre>
28560 <A name="550"></a><font color="blue">PAGE 550</font><br>
28561 <br>
28562 When <i>tty_register_driver </i>is called, the kernel creates all of the different sysfs tty files
28563 for the whole range of minor devices that this tty driver can have. If you use <i>devfs
28564 </i>(not covered in this book) and unless the <font class="fixd">TTY_DRIVER_NO_DEVFS</font> flag is specified, <i>devfs
28565 </i>files are created, too. The flag may be specified if you want to call <i>tty_register_device
28566 </i>only for the devices that actually exist on the system, so the user always has an up-todate
28567 view of the devices present in the kernel, which is what <i>devfs</i> users expect.<br>
28568 <br>
28569 After registering itself, the driver registers the devices it controls through the <i>tty_
28570 register_device</i> function. This function has three arguments:<br>
28571 <ul>
28572 <li> A pointer to the <font class="fixd">struct tty_driver</font> that the device belongs to.
28573 <li> The minor number of the device.
28574 <li> A pointer to the <font class="fixd">struct device</font> that this tty device is bound to. If the tty device is
28575 not bound to any <font class="fixd">struct device</font>, this argument can be set to <font class="fixd">NULL</font>.
28576 </ul>
28577 Our driver registers all of the tty devices at once, as they are virtual and not bound to
28578 any physical devices:<br>
28579 <pre>
28580 for (i = 0; i < TINY_TTY_MINORS; ++i)
28581 tty_register_device(tiny_tty_driver, i, NULL);
28582 </pre>
28583 To unregister the driver with the tty core, all tty devices that were registered by calling
28584 <i>tty_register_device </i>need to be cleaned up with a call to <i>tty_unregister_device</i>.
28585 Then the <font class="fixd">struct tty_driver</font> must be unregistered with a call to <i>tty_unregister_driver</i>:<br>
28586 <pre>
28587 for (i = 0; i < TINY_TTY_MINORS; ++i)
28588 tty_unregister_device(tiny_tty_driver, i);
28589 tty_unregister_driver(tiny_tty_driver);
28590 </pre>
28591 <a name="StructTermios"></a><font color="red"><b>struct termios</b></font><br>
28592 <br>
28593 The <font class="fixd">init_termios</font> variable in the <font class="fixd">struct tty_driver</font> is a <font class="fixd">struct termios.</font> This variable
28594 is used to provide a sane set of line settings if the port is used before it is initialized by
28595 a user. The driver initializes the variable with a standard set of values, which is copied
28596 from the <font class="fixd">tty_std_termios</font> variable. <font class="fixd">tty_std_termios</font> is defined in the tty core as:<br>
28597 <pre>
28598 struct termios tty_std_termios = {
28599 .c_iflag = ICRNL | IXON,
28600 .c_oflag = OPOST | ONLCR,
28601 .c_cflag = B38400 | CS8 | CREAD | HUPCL,
28602 .c_lflag = ISIG | ICANON | ECHO | ECHOE | ECHOK |
28603 ECHOCTL | ECHOKE | IEXTEN,
28604 .c_cc = INIT_C_CC
28605 };
28606 </pre>
28607 The <font class="fixd">struct termios</font> structure is used to hold all of the current line settings for a specific
28608 port on the tty device. These line settings control the current baud rate, data<br>
28609 <br>
28610 <A name="551"></a><font color="blue">PAGE 551</font><br>
28611 <br>
28612 size, data flow settings, and many other values. The different fields of this structure
28613 are:<br>
28614 <br>
28615 <font class="fixd">tcflag_t c_iflag;</font><br>
28616 <div class="bq">
28617 The input mode flags</div>
28618 <br>
28619 <font class="fixd">tcflag_t c_oflag;</font><br>
28620 <div class="bq">
28621 The output mode flags</div>
28622 <br>
28623 <font class="fixd">tcflag_t c_cflag;</font><br>
28624 <div class="bq">
28625 The control mode flags</div>
28626 <br>
28627 <font class="fixd">tcflag_t c_lflag;</font><br>
28628 <div class="bq">
28629 The local mode flags</div>
28630 <br>
28631 <font class="fixd">cc_t c_line;</font><br>
28632 <div class="bq">
28633 The line discipline type</div>
28634 <br>
28635 <font class="fixd">cc_t c_cc[NCCS];</font><br>
28636 <div class="bq">
28637 An array of control characters</div>
28638 <br>
28639 All of the mode flags are defined as a large bitfield. The different values of the modes,
28640 and what they are used for, can be seen in the termios manpages available in any
28641 Linux distribution. The kernel provides a set of useful macros to get at the different
28642 bits. These macros are defined in the header file <i>include/linux/tty.h</i>.<br>
28643 <br>
28644 All the fields that were defined in the <font class="fixd">tiny_tty_driver</font> variable are necessary to have
28645 a working tty driver. The <font class="fixd">owner</font> field is necessary in order to prevent the tty driver
28646 from being unloaded while the tty port is open. In previous kernel versions, it was up
28647 to the tty driver itself to handle the module reference counting logic. But kernel programmers
28648 determined that it would to be difficult to solve all of the different possible
28649 race conditions, and so the tty core now handles all of this control for the tty
28650 drivers.<br>
28651 <br>
28652 The <font class="fixd">driver_name</font> and <font class="fixd">name</font> fields look very similar, yet are used for different purposes.
28653 The <font class="fixd">driver_name</font> variable should be set to something short, descriptive, and unique
28654 among all tty drivers in the kernel. This is because it shows up in the <i>/proc/tty/
28655 drivers </i>file to describe the driver to the user and in the sysfs tty class directory of tty
28656 drivers currently loaded. The <font class="fixd">name</font> field is used to define a name for the individual tty
28657 nodes assigned to this tty driver in the <i>/dev </i>tree. This string is used to create a tty
28658 device by appending the number of the tty device being used at the end of the string.
28659 It is also used to create the device name in the sysfs <i>/sys/class/tty/ </i>directory. If devfs is
28660 enabled in the kernel, this name should include any subdirectory that the tty driver
28661 wants to be placed into. As an example, the serial driver in the kernel sets the name
28662 field to <font class="fixd">tts/</font> if devfs is enabled and <font class="fixd">ttyS</font> if it is not. This string is also displayed in the
28663 <i>/proc/tty/drivers</i> file.<br>
28664 <br>
28665 <A name="552"></a><font color="blue">PAGE 552</font><br>
28666 <br>
28667 As we mentioned, the <i>/proc/tty/drivers </i>file shows all of the currently registered tty
28668 drivers. With the <i>tiny_tty </i>driver registered in the kernel and no <i>devfs</i>, this file looks
28669 something like the following:<br>
28670 <pre>
28671 $ <b>cat /proc/tty/drivers
28672 </b>tiny_tty /dev/ttty 240 0-3 serial
28673 usbserial /dev/ttyUSB 188 0-254 serial
28674 serial /dev/ttyS 4 64-107 serial
28675 <font class="fixd">pty_slave</font> /dev/pts 136 0-255 pty:slave
28676 <font class="fixd">pty_master</font> /dev/ptm 128 0-255 pty:master
28677 <font class="fixd">pty_slave</font> /dev/ttyp 3 0-255 pty:slave
28678 <font class="fixd">pty_master</font> /dev/pty 2 0-255 pty:master
28679 unknown /dev/vc/ 4 1-63 console
28680 /dev/vc/0 /dev/vc/0 4 0 system:vtmaster
28681 /dev/ptmx /dev/ptmx 5 2 system
28682 /dev/console /dev/console 5 1 system:console
28683 /dev/tty /dev/tty 5 0 system:/dev/tty
28684 </pre>
28685 Also, the sysfs directory <i>/sys/class/tty </i>looks something like the following when the
28686 <font class="fixd">tiny_tty</font> driver is registered with the tty core:<br>
28687 <pre>
28688 $ <b>tree /sys/class/tty/ttty*
28689 </b>/sys/class/tty/ttty0
28690 `-- dev
28691 /sys/class/tty/ttty1
28692 `-- dev
28693 /sys/class/tty/ttty2
28694 `-- dev
28695 /sys/class/tty/ttty3
28696 `-- dev
28698 $ <b>cat /sys/class/tty/ttty0/dev
28699 </b>240:0
28700 </pre>
28701 The major variable describes what the major number for this driver is. The type and
28702 subtype variables declare what type of tty driver this driver is. For our example, we
28703 are a serial driver of a "normal" type. The only other subtype for a tty driver would
28704 be a "callout" type. Callout devices were traditionally used to control the line settings
28705 of a device. The data would be sent and received through one device node, and
28706 any line setting changes would be sent to a different device node, which was the callout
28707 device. This required the use of two minor numbers for every single tty device.
28708 Thankfully, almost all drivers handle both the data and line settings on the same
28709 device node, and the callout type is rarely used for new drivers.<br>
28710 <br>
28711 The <font class="fixd">flags</font> variable is used by both the tty driver and the tty core to indicate the current
28712 state of the driver and what kind of tty driver it is. Several bitmask macros are
28713 defined that you must use when testing or manipulating the flags. Three bits in the
28714 <font class="fixd">flags</font> variable can be set by the driver:<br>
28715 <br>
28716 <font class="fixd">TTY_DRIVER_RESET_TERMIOS</font><br>
28717 <div class="bq">
28718 This flag states that the tty core resets the termios setting whenever the last process
28719 has closed the device. This is useful for the console and pty drivers. For</div>
28720 <br>
28721 <A name="553"></a><font color="blue">PAGE 553</font><br>
28722 <br>
28723 <div class="bq">instance, suppose the user leaves a terminal in a weird state. With this flag set,
28724 the terminal is reset to a normal value when the user logs out or the process that
28725 controlled the session is "killed."</div>
28726 <br>
28727 <font class="fixd">TTY_DRIVER_REAL_RAW</font><br>
28728 <div class="bq">
28729 This flag states that the tty driver guarantees to send notifications of parity or
28730 break characters up-to-the-line discipline. This allows the line discipline to process
28731 received characters in a much quicker manner, as it does not have to inspect
28732 every character received from the tty driver. Because of the speed benefits, this
28733 value is usually set for all tty drivers.</div>
28734 <br>
28735 <font class="fixd">TTY_DRIVER_NO_DEVFS</font><br>
28736 <div class="bq">
28737 This flag states that when the call to <i>tty_register_driver </i>is made, the tty core does
28738 not create any devfs entries for the tty devices. This is useful for any driver that
28739 dynamically creates and destroys the minor devices. Examples of drivers that set
28740 this are the USB-to-serial drivers, the USB modem driver, the USB Bluetooth tty
28741 driver, and a number of the standard serial port drivers.<br>
28742 <br>
28743 When the tty driver later wants to register a specific tty device with the tty core,
28744 it must call <i>tty_register_device</i>, with a pointer to the tty driver, and the minor
28745 number of the device that has been created. If this is not done, the tty core still
28746 passes all calls to the tty driver, but some of the internal tty-related functionality
28747 might not be present. This includes <i>/sbin/hotplug </i>notification of new tty devices
28748 and sysfs representation of the tty device. When the registered tty device is
28749 removed from the machine, the tty driver must call <i>tty_unregister_device</i>.</div>
28750 <br>
28751 The one remaining bit in this variable is controlled by the tty core and is called
28752 <font class="fixd">TTY_DRIVER_INSTALLED</font>. This flag is set by the tty core after the driver has been registered
28753 and should never be set by a tty driver.<br>
28754 <br>
28755 <a name="TtydriverFunctionPointers"></a><font color="red"><b>tty_driver Function Pointers</b></font><br>
28756 <br>
28757 Finally, the <i>tiny_tty</i> driver declares four function pointers.<br>
28758 <br>
28759 <a name="OpenAndClose"></a><font color="red"><b>open and close</b></font><br>
28760 <br>
28761 The <i>open </i>function is called by the tty core when a user calls open on the device node
28762 the tty driver is assigned to. The tty core calls this with a pointer to the <font class="fixd">tty_struct</font>
28763 structure assigned to this device, and a file pointer. The <font class="fixd">open</font> field must be set by a tty
28764 driver for it to work properly; otherwise, <font class="fixd">-ENODEV</font> is returned to the user when open is
28765 called.<br>
28766 <br>
28767 When this <i>open </i>function is called, the tty driver is expected to either save some data
28768 within the <font class="fixd">tty_struct</font> variable that is passed to it, or save the data within a static array
28769 that can be referenced based on the minor number of the port. This is necessary so the<br>
28770 <br>
28771 <A name="554"></a><font color="blue">PAGE 554</font><br>
28772 <br>
28773 tty driver knows which device is being referenced when the later close, write, and
28774 other functions are called.<br>
28775 <br>
28776 The <i>tiny_tty </i>driver saves a pointer within the tty structure, as can be seen with the
28777 following code:<br>
28778 <pre>
28779 static int tiny_open(struct tty_struct *tty, struct file *file)
28780 {
28781 struct tiny_serial *tiny;
28782 struct timer_list *timer;
28783 int index;
28785 /* initialize the pointer in case something fails */
28786 tty->driver_data = NULL;
28788 /* get the serial object associated with this tty pointer */
28789 index = tty->index;
28790 tiny = tiny_table[index];
28791 if (tiny = = NULL) {
28792 /* first time accessing this device, let's create it */
28793 tiny = kmalloc(sizeof(*tiny), GFP_KERNEL);
28794 if (!tiny)
28795 return -ENOMEM;
28797 init_MUTEX(&tiny->sem);
28798 tiny->open_count = 0;
28799 tiny->timer = NULL;
28801 tiny_table[index] = tiny;
28802 }
28804 down(&tiny->sem);
28806 /* save our structure within the tty structure */
28807 tty->driver_data = tiny;
28808 tiny->tty = tty;
28809 </pre>
28810 In this code, the <font class="fixd">tiny_serial</font> structure is saved within the tty structure. This allows
28811 the <i>tiny_write</i>, <i>tiny_write_room</i>, and <i>tiny_close </i>functions to retrieve the <font class="fixd">tiny_serial</font>
28812 structure and manipulate it properly.<br>
28813 <br>
28814 The <font class="fixd">tiny_serial</font> structure is defined as:<br>
28815 <pre>
28816 struct tiny_serial {
28817 struct tty_struct *tty; /* pointer to the tty for this device */
28818 int open_count; /* number of times this port has been opened */
28819 struct semaphore sem; /* locks this structure */
28820 struct timer_list *timer;
28822 };
28823 </pre>
28824 As we've seen, the <font class="fixd">open_count</font> variable is initialized to <font class="fixd">0</font> in the open call the first time
28825 the port is opened. This is a typical reference counter, needed because the <i>open </i>and
28826 <i>close </i>functions of a tty driver can be called multiple times for the same device in<br>
28827 <br>
28828 <A name="555"></a><font color="blue">PAGE 555</font><br>
28829 <br>
28830 order to allow multiple processes to read and write data. To handle everything correctly,
28831 a count of how many times the port has been opened or closed must be kept;
28832 the driver increments and decrements the count as the port is used. When the port is
28833 opened for the first time, any needed hardware initialization and memory allocation
28834 can be done. When the port is closed for the last time, any needed hardware shutdown
28835 and memory cleanup can be done.<br>
28836 <br>
28837 The rest of the <i>tiny_open </i>function shows how to keep track of the number of times
28838 the device has been opened:<br>
28839 <pre>
28840 ++tiny->open_count;
28841 if (tiny->open_count = = 1) {
28842 /* this is the first time this port is opened */
28843 /* do any hardware initialization needed here */
28844 </pre>
28845 The <i>open </i>function must return either a negative error number if something has happened
28846 to prevent the open from being successful, or a 0 to indicate success.<br>
28847 <br>
28848 The <i>close </i>function pointer is called by the tty core when <i>close </i>is called by a user on
28849 the file handle that was previously created with a call to <i>open</i>. This indicates that the
28850 device should be closed at this time. However, since the <i>open </i>function can be called
28851 more than once, the <i>close </i>function also can be called more than once. So this function
28852 should keep track of how many times it has been called to determine if the hardware
28853 should really be shut down at this time. The <i>tiny_tty </i>driver does this with the
28854 following code:<br>
28855 <pre>
28856 static void do_close(struct tiny_serial *tiny)
28857 {
28858 down(&tiny->sem);
28860 if (!tiny->open_count) {
28861 /* port was never opened */
28862 goto exit;
28863 }
28865 --tiny->open_count;
28866 if (tiny->open_count <= 0) {
28867 /* The port is being closed by the last user. */
28868 /* Do any hardware specific stuff here */
28870 /* shut down our timer */
28871 del_timer(tiny->timer);
28872 }
28873 exit:
28874 up(&tiny->sem);
28875 }
28877 static void tiny_close(struct tty_struct *tty, struct file *file)
28878 {
28879 struct tiny_serial *tiny = tty->driver_data;
28880 </pre>
28881 <A name="556"></a><font color="blue">PAGE 556</font><br>
28882 <pre>
28883 if (tiny)
28884 do_close(tiny);
28885 }
28886 </pre>
28887 The <i>tiny_close </i>function just calls the <i>do_close </i>function to do the real work of closing
28888 the device. This is done so that the shutdown logic does not have to be duplicated
28889 here and when the driver is unloaded and a port is open. The <i>close </i>function has no
28890 return value, as it is not supposed to be able to fail.<br>
28891 <br>
28892 <a name="FlowOfData"></a><font color="red"><b>Flow of Data</b></font><br>
28893 <br>
28894 The <i>write </i>function call is called by the user when there is data to be sent to the hardware.
28895 First the tty core receives the call, and then it passes the data on to the tty
28896 driver's <i>write </i>function. The tty core also tells the tty driver the size of the data being
28897 sent.<br>
28898 <br>
28899 Sometimes, because of the speed and buffer capacity of the tty hardware, not all
28900 characters requested by the writing program can be sent at the moment the <i>write
28901 </i>function is called. The <i>write </i>function should return the number of characters that
28902 was able to be sent to the hardware (or queued to be sent at a later time), so that the
28903 user program can check if all of the data really was written. It is much easier for this
28904 check to be done in user space than it is for a kernel driver to sit and sleep until all of
28905 the requested data is able to be sent out. If any errors happen during the <i>write </i>call, a
28906 negative error value should be returned instead of the number of characters that were
28907 written.<br>
28908 <br>
28909 The <i>write </i>function can be called from both interrupt context and user context. This
28910 is important to know, as the tty driver should not call any functions that might sleep
28911 when it is in interrupt context. These include any function that might possibly call
28912 <i>schedule</i>, such as the common functions <i>copy_from_user</i>, <i>kmalloc</i>, and <i>printk</i>. If you
28913 really want to sleep, make sure to check first whether the driver is in interrupt context
28914 by calling<i> in_interrupt</i>.<br>
28915 <br>
28916 This sample tiny tty driver does not connect to any real hardware, so its write function
28917 simply records in the kernel debug log what data was supposed to be written. It
28918 does this with the following code:<br>
28919 <pre>
28920 static int tiny_write(struct tty_struct *tty,
28921 const unsigned char *buffer, int count)
28922 {
28923 struct tiny_serial *tiny = tty->driver_data;
28924 int i;
28925 int retval = -EINVAL;
28927 if (!tiny)
28928 return -ENODEV;
28930 down(&tiny->sem);
28931 </pre>
28932 <A name="557"></a><font color="blue">PAGE 557</font><br>
28933 <pre>
28934 if (!tiny->open_count)
28935 /* port was not opened */
28936 goto exit;
28938 /* fake sending the data out a hardware port by
28939 * writing it to the kernel debug log.
28940 */
28941 printk(KERN_DEBUG "%s - ", __FUNCTION__);
28942 for (i = 0; i < count; ++i)
28943 printk("%02x ", buffer[i]);
28944 printk("\n");
28946 exit:
28947 up(&tiny->sem);
28948 return retval;
28949 }
28950 </pre>
28951 The <i>write </i>function can be called when the tty subsystem itself needs to send some
28952 data out the tty device. This can happen if the tty driver does not implement the
28953 <i>put_char </i>function in the <font class="fixd">tty_struct</font>. In that case, the tty core uses the <i>write </i>function
28954 callback with a data size of 1. This commonly happens when the tty core wants to
28955 convert a newline character to a line feed plus a newline character. The biggest problem
28956 that can occur here is that the tty driver's <i>write </i>function must not return 0 for
28957 this kind of call. This means that the driver must write that byte of data to the device,
28958 as the caller (the tty core) does not buffer the data and try again at a later time. As
28959 the <i>write </i>function can not determine if it is being called in the place of <i>put_char</i>, even
28960 if only one byte of data is being sent, try to implement the <i>write </i>function so it always
28961 writes at least one byte before returning. A number of the current USB-to-serial tty
28962 drivers do not follow this rule, and because of this, some terminals types do not work
28963 properly when connected to them.<br>
28964 <br>
28965 The <i>write_room </i>function is called when the tty core wants to know how much room
28966 in the write buffer the tty driver has available. This number changes over time as
28967 characters empty out of the write buffers and as the <i>write </i>function is called, adding
28968 characters to the buffer.<br>
28969 <pre>
28970 static int tiny_write_room(struct tty_struct *tty)
28971 {
28972 struct tiny_serial *tiny = tty->driver_data;
28973 int room = -EINVAL;
28975 if (!tiny)
28976 return -ENODEV;
28978 down(&tiny->sem);
28980 if (!tiny->open_count) {
28981 /* port was not opened */
28982 goto exit;
28983 }
28984 </pre>
28985 <A name="558"></a><font color="blue">PAGE 558</font><br>
28986 <pre>
28987 /* calculate how much room is left in the device */
28988 room = 255;
28990 exit:
28991 up(&tiny->sem);
28992 return room;
28993 }
28994 </pre>
28995 <a name="OtherBufferingFunctions"></a><font color="red"><b>Other Buffering Functions</b></font><br>
28996 <br>
28997 The <i>chars_in_buffer </i>function in the <font class="fixd">tty_driver</font> structure is not required in order to
28998 have a working tty driver, but it is recommended. This function is called when the tty
28999 core wants to know how many characters are still remaining in the tty driver's write
29000 buffer to be sent out. If the driver can store characters before it sends them out to the
29001 hardware, it should implement this function in order for the tty core to be able to
29002 determine if all of the data in the driver has drained out.<br>
29003 <br>
29004 Three functions callbacks in the <font class="fixd">tty_driver</font> structure can be used to flush any
29005 remaining data that the driver is holding on to. These are not required to be implemented,
29006 but are recommended if the tty driver can buffer data before it sends it to the
29007 hardware. The first two function callbacks are called <i>flush_chars </i>and <i>wait_until_sent</i>.
29008 These functions are called when the tty core has sent a number of characters to the
29009 tty driver using the <i>put_char </i>function callback. The <i>flush_chars </i>function callback is
29010 called when the tty core wants the tty driver to start sending these characters out to
29011 the hardware, if it hasn't already started. This function is allowed to return before all
29012 of the data is sent out to the hardware. The <i>wait_until_sent </i>function callback works
29013 much the same way; but it must wait until all of the characters are sent before returning
29014 to the tty core or until the passed in <i>timeout </i>value has expired, whichever occurrence
29015 happens first. The tty driver is allowed to sleep within this function in order to
29016 complete it. If the timeout value passed to the <i>wait_until_sent </i>function callback is set
29017 to 0, the function should wait until it is finished with the operation.<br>
29018 <br>
29019 The remaining data flushing function callback is <i>flush_buffer</i>. It is called by the tty
29020 core when the tty driver is to flush all of the data still in its write buffers out of memory.
29021 Any data remaining in the buffer is lost and not sent to the device.<br>
29022 <br>
29023 <a name="NoReadFunction"></a><font color="red"><b>No read Function?</b></font><br>
29024 <br>
29025 With only these functions, the <i>tiny_tty </i>driver can be registered, a device node
29026 opened, data written to the device, the device node closed, and the driver unregistered
29027 and unloaded from the kernel. But the tty core and <font class="fixd">tty_driver</font> structure do not
29028 provide a read function; in other words; no function callback exists to get data from
29029 the driver to the tty core.<br>
29030 <br>
29031 Instead of a conventional read function, the tty driver is responsible for sending any data
29032 received from the hardware to the tty core when it is received. The tty core buffers the<br>
29033 <br>
29034 <A name="559"></a><font color="blue">PAGE 559</font><br>
29035 <br>
29036 data until it is asked for by the user. Because of the buffering logic the tty core provides,
29037 it is not necessary for every tty driver to implement its own buffering logic. The tty core
29038 notifies the tty driver when a user wants the driver to stop and start sending data, but if
29039 the internal tty buffers are full, no such notification occurs.<br>
29040 <br>
29041 The tty core buffers the data received by the tty drivers in a structure called <font class="fixd">struct
29042 tty_flip_buffer</font>. A flip buffer is a structure that contains two main data arrays. Data
29043 being received from the tty device is stored in the first array. When that array is full,
29044 any user waiting on the data is notified that data is available to be read. While the
29045 user is reading the data from this array, any new incoming data is being stored in the
29046 second array. When that array is finished, the data is again flushed to the user, and
29047 the driver starts to fill up the first array. Essentially, the data being received "flips"
29048 from one buffer to the other, hopefully not overflowing both of them. To try to prevent
29049 data from being lost, a tty driver can monitor how big the incoming array is,
29050 and, if it fills up, tell the tty driver to flush the buffer at this moment in time, instead
29051 of waiting for the next available chance.<br>
29052 <br>
29053 The details of the struct <font class="fixd">tty_flip_buffer</font> structure do not really matter to the tty
29054 driver, with one exception, the variable <font class="fixd">count.</font> This variable contains how many
29055 bytes are currently left in the buffer that are being used for receiving data. If this
29056 value is equal to the value <font class="fixd">TTY_FLIPBUF_SIZE,</font> the flip buffer needs to be flushed out to
29057 the user with a call to <i>tty_flip_buffer_push</i>. This is shown in the following bit of
29058 code:<br>
29059 <pre>
29060 for (i = 0; i < data_size; ++i) {
29061 if (tty->flip.count >= TTY_FLIPBUF_SIZE)
29062 tty_flip_buffer_push(tty);
29063 tty_insert_flip_char(tty, data[i], TTY_NORMAL);
29064 }
29065 tty_flip_buffer_push(tty);
29066 </pre>
29067 Characters that are received from the tty driver to be sent to the user are added to the
29068 flip buffer with a call to <i>tty_insert_flip_char</i>. The first parameter of this function is
29069 the <font class="fixd">struct tty_struct</font> the data should be saved in, the second parameter is the character
29070 to be saved, and the third parameter is any flags that should be set for this character.
29071 The flags value should be set to <font class="fixd">TTY_NORMAL</font> if this is a normal character being
29072 received. If this is a special type of character indicating an error receiving data, it
29073 should be set to <font class="fixd">TTY_BREAK, TTY_FRAME, TTY_PARITY,</font> or <font class="fixd">TTY_OVERRUN,</font> depending on the
29074 error.<br>
29075 <br>
29076 In order to "push" the data to the user, a call to <i>tty_flip_buffer_push </i>is made. This
29077 function should also be called if the flip buffer is about to overflow, as is shown in
29078 this example. So whenever data is added to the flip buffer, or when the flip buffer is
29079 full, the tty driver must call <i>tty_flip_buffer_push</i>. If the tty driver can accept data at
29080 very high rates, the <font class="fixd">tty->low_latency</font> flag should be set, which causes the call to
29081 <i>tty_flip_buffer_push </i>to be immediately executed when called. Otherwise, the<br>
29082 <br>
29083 <A name="560"></a><font color="blue">PAGE 560</font><br>
29084 <br>
29085 <i>tty_flip_buffer_push </i>call schedules itself to push the data out of the buffer at some
29086 later point in the near future.<br>
29087 <br>
29088 <a name="TTYLineSettings"></a><font color="red"><b>TTY Line Settings</b></font><br>
29089 <br>
29090 When a user wants to change the line settings of a tty device or retrieve the current
29091 line settings, he makes one of the many different termios user-space library function
29092 calls or directly makes an <i>ioctl </i>call on the tty device node. The tty core converts both
29093 of these interfaces into a number of different tty driver function callbacks and <i>ioctl
29094 </i>calls.<br>
29095 <br>
29096 <a name="Settermios"></a><font color="red"><b>set_termios</b></font><br>
29097 <br>
29098 The majority of the termios user-space functions are translated by the library into an
29099 <i>ioctl </i>call to the driver node. A large number of the different tty <i>ioctl </i>calls are then
29100 translated by the tty core into a single <i>set_termios </i>function call to the tty driver. The
29101 <i>set_termios </i>callback needs to determine which line settings it is being asked to
29102 change, and then make those changes in the tty device. The tty driver must be able to
29103 decode all of the different settings in the termios structure and react to any needed
29104 changes. This is a complicated task, as all of the line settings are packed into the termios
29105 structure in a wide variety of ways.<br>
29106 <br>
29107 The first thing that a <i>set_termios </i>function should do is determine whether anything
29108 actually has to be changed. This can be done with the following code:<br>
29109 <pre>
29110 unsigned int cflag;
29112 cflag = tty->termios->c_cflag;
29114 /* check that they really want us to change something */
29115 if (old_termios) {
29116 if ((cflag = = old_termios->c_cflag) &&
29117 (RELEVANT_IFLAG(tty->termios->c_iflag) = =
29118 RELEVANT_IFLAG(old_termios->c_iflag))) {
29119 printk(KERN_DEBUG " - nothing to change...\n");
29120 return;
29121 }
29122 }
29123 </pre>
29124 The <font class="fixd">RELEVANT_IFLAG</font> macro is defined as:<br>
29125 <pre>
29126 #define RELEVANT_IFLAG(iflag) ((iflag) & (IGNBRK|BRKINT|IGNPAR|PARMRK|INPCK))
29127 </pre>
29128 and is used to mask off the important bits of the <font class="fixd">cflags</font> variable. This is then compared
29129 to the old value, and see if they differ. If not, nothing needs to be changed, so
29130 we return. Note that the <font class="fixd">old_termios</font> variable is first checked to see if it points to a
29131 valid structure first, before it is accessed. This is required, as sometimes this variable
29132 is set to <font class="fixd">NULL</font>. Trying to access a field off of a <font class="fixd">NULL</font> pointer causes the kernel to panic.<br>
29133 <br>
29134 <A name="561"></a><font color="blue">PAGE 561</font><br>
29135 <br>
29136 To look at the requested byte size, the <font class="fixd">CSIZE</font> bitmask can be used to separate out the
29137 proper bits from the <font class="fixd">cflag</font> variable. If the size can not be determined, it is customary
29138 to default to eight data bits. This can be implemented as follows:<br>
29139 <pre>
29140 /* get the byte size */
29141 switch (cflag & CSIZE) {
29142 case CS5:
29143 printk(KERN_DEBUG " - data bits = 5\n");
29144 break;
29145 case CS6:
29146 printk(KERN_DEBUG " - data bits = 6\n");
29147 break;
29148 case CS7:
29149 printk(KERN_DEBUG " - data bits = 7\n");
29150 break;
29151 default:
29152 case CS8:
29153 printk(KERN_DEBUG " - data bits = 8\n");
29154 break;
29155 }
29156 </pre>
29157 To determine the requested parity value, the <font class="fixd">PARENB</font> bitmask can be checked against
29158 the <font class="fixd">cflag</font> variable to tell if any parity is to be set at all. If so, the <font class="fixd">PARODD</font> bitmask can be
29159 used to determine if the parity should be odd or even. An implementation of this is:<br>
29160 <pre>
29161 /* determine the parity */
29162 if (cflag & PARENB)
29163 if (cflag & PARODD)
29164 printk(KERN_DEBUG " - parity = odd\n");
29165 else
29166 printk(KERN_DEBUG " - parity = even\n");
29167 else
29168 printk(KERN_DEBUG " - parity = none\n");
29169 </pre>
29170 The stop bits that are requested can also be determined from the <font class="fixd">cflag</font> variable using
29171 the <font class="fixd">CSTOPB</font> bitmask. An implementation of this is:<br>
29172 <pre>
29173 /* figure out the stop bits requested */
29174 if (cflag & CSTOPB)
29175 printk(KERN_DEBUG " - stop bits = 2\n");
29176 else
29177 printk(KERN_DEBUG " - stop bits = 1\n");
29178 </pre>
29179 There are a two basic types of flow control: hardware and software. To determine if
29180 the user is asking for hardware flow control, the <font class="fixd">CRTSCTS</font> bitmask can be checked
29181 against the <font class="fixd">cflag</font> variable. An exmple of this is:<br>
29182 <pre>
29183 /* figure out the hardware flow control settings */
29184 if (cflag & CRTSCTS)
29185 printk(KERN_DEBUG " - RTS/CTS is enabled\n");
29186 else
29187 printk(KERN_DEBUG " - RTS/CTS is disabled\n");
29188 </pre>
29189 <A name="562"></a><font color="blue">PAGE 562</font><br>
29190 <br>
29191 Determining the different modes of software flow control and the different stop and
29192 start characters is a bit more involved:<br>
29193 <pre>
29194 /* determine software flow control */
29195 /* if we are implementing XON/XOFF, set the start and
29196 * stop character in the device */
29197 if (I_IXOFF(tty) || I_IXON(tty)) {
29198 unsigned char stop_char = STOP_CHAR(tty);
29199 unsigned char start_char = START_CHAR(tty);
29201 /* if we are implementing INBOUND XON/XOFF */
29202 if (I_IXOFF(tty))
29203 printk(KERN_DEBUG " - INBOUND XON/XOFF is enabled, "
29204 "XON = %2x, XOFF = %2x", start_char, stop_char);
29205 else
29206 printk(KERN_DEBUG" - INBOUND XON/XOFF is disabled");
29208 /* if we are implementing OUTBOUND XON/XOFF */
29209 if (I_IXON(tty))
29210 printk(KERN_DEBUG" - OUTBOUND XON/XOFF is enabled, "
29211 "XON = %2x, XOFF = %2x", start_char, stop_char);
29212 else
29213 printk(KERN_DEBUG" - OUTBOUND XON/XOFF is disabled");
29214 }
29215 </pre>
29216 Finally, the baud rate needs to be determined. The tty core provides a function,
29217 <i>tty_get_baud_rate</i>, to help do this. The function returns an integer indicating the
29218 requested baud rate for the specific tty device:<br>
29219 <pre>
29220 /* get the baud rate wanted */
29221 printk(KERN_DEBUG " - baud rate = %d", tty_get_baud_rate(tty));
29222 </pre>
29223 Now that the tty driver has determined all of the different line settings, it can set the
29224 hardware up properly based on these values.<br>
29225 <br>
29226 <a name="TiocmgetAndTiocmset"></a><font color="red"><b>tiocmget and tiocmset</b></font><br>
29227 <br>
29228 In the 2.4 and older kernels, there used to be a number of tty <i>ioctl </i>calls to get and set
29229 the different control line settings. These were denoted by the constants <font class="fixd">TIOCMGET,
29230 TIOCMBIS, TIOCMBIC,</font> and <font class="fixd">TIOCMSET. TIOCMGET</font> was used to get the line setting values of
29231 the kernel, and as of the 2.6 kernel, this <i>ioctl </i>call has been turned into a tty driver
29232 callback function called <i>tiocmget</i>. The other three <i>ioctls </i>have been simplified and are
29233 now represented with a single tty driver callback function called <i>tiocmset</i>.<br>
29234 <br>
29235 The <i>tiocmget </i>function in the tty driver is called by the tty core when the core wants
29236 to know the current physical values of the control lines of a specific tty device. This is
29237 usually done to retrieve the values of the DTR and RTSlines of a serial port. If the tty
29238 driver cannot directly read the MSR or MCR registers of the serial port, because the
29239 hardware does not allow this, a copy of them should be kept locally. A number of the<br>
29240 <br>
29241 <A name="563"></a><font color="blue">PAGE 563</font><br>
29242 <br>
29243 USB-to-serial drivers must implement this kind of "shadow" variable. Here is how
29244 this function could be implemented if a local copy of these values are kept:<br>
29245 <pre>
29246 static int tiny_tiocmget(struct tty_struct *tty, struct file *file)
29247 {
29248 struct tiny_serial *tiny = tty->driver_data;
29250 unsigned int result = 0;
29251 unsigned int msr = tiny->msr;
29252 unsigned int mcr = tiny->mcr;
29254 result = ((mcr & MCR_DTR) ? TIOCM_DTR : 0) | /* DTR is set */
29255 ((mcr & MCR_RTS) ? TIOCM_RTS : 0) | /* RTS is set */
29256 ((mcr & MCR_LOOP) ? TIOCM_LOOP : 0) | /* LOOP is set */
29257 ((msr & MSR_CTS) ? TIOCM_CTS : 0) | /* CTS is set */
29258 ((msr & MSR_CD) ? TIOCM_CAR : 0) | /* Carrier detect is set*/
29259 ((msr & MSR_RI) ? TIOCM_RI : 0) | /* Ring Indicator is set */
29260 ((msr & MSR_DSR) ? TIOCM_DSR : 0); /* DSR is set */
29262 return result;
29263 }
29264 </pre>
29265 The <i>tiocmset </i>function in the tty driver is called by the tty core when the core wants to
29266 set the values of the control lines of a specific tty device. The tty core tells the tty
29267 driver what values to set and what to clear, by passing them in two variables: set and
29268 clear. These variables contain a bitmask of the lines settings that should be changed.
29269 An <i>ioctl </i>call never asks the driver to both set and clear a particular bit at the same
29270 time, so it does not matter which operation occurs first. Here is an example of how
29271 this function could be implemented by a tty driver:<br>
29272 <pre>
29273 static int tiny_tiocmset(struct tty_struct *tty, struct file *file,
29274 unsigned int set, unsigned int clear)
29275 {
29276 struct tiny_serial *tiny = tty->driver_data;
29277 unsigned int mcr = tiny->mcr;
29279 if (set & TIOCM_RTS)
29280 mcr |= MCR_RTS;
29281 if (set & TIOCM_DTR)
29282 mcr |= MCR_RTS;
29284 if (clear & TIOCM_RTS)
29285 mcr &= ~MCR_RTS;
29286 if (clear & TIOCM_DTR)
29287 mcr &= ~MCR_RTS;
29289 /* set the new MCR value in the device */
29290 tiny->mcr = mcr;
29291 return 0;
29292 }
29293 </pre>
29294 <A name="564"></a><font color="blue">PAGE 564</font><br>
29295 <br>
29296 <a name="Ioctls"></a><font color="red"><b>ioctls</b></font><br>
29297 <br>
29298 The <i>ioctl </i>function callback in the <font class="fixd">struct tty_driver</font> is called by the tty core when
29299 <i>ioctl</i>(2) is called on the device node. If the tty driver does not know how to handle
29300 the <i>ioctl </i>value passed to it, it should return <font class="fixd">-ENOIOCTLCMD</font> to try to let the tty core
29301 implement a generic version of the call.<br>
29302 <br>
29303 The 2.6 kernel defines about 70 different tty <i>ioctls </i>that can be be sent to a tty driver.
29304 Most tty drivers do not handle all of these, but only a small subset of the more common
29305 ones. Here is a list of the more popular tty <i>ioctls</i>, what they mean, and how to
29306 implement them:<br>
29307 <br>
29308 <font class="fixd">TIOCSERGETLSR</font><br>
29309 <div class="bq">
29310 Gets the value of this tty device's line status register (LSR).</div>
29311 <br>
29312 <font class="fixd">TIOCGSERIAL</font><br>
29313 <div class="bq">
29314 Gets the serial line information. A caller can potentially get a lot of serial line
29315 information from the tty device all at once in this call. Some programs (such as
29316 <i>setserial </i>and <i>dip</i>) call this function to make sure that the baud rate was properly
29317 set and to get general information on what type of device the tty driver controls.
29318 The caller passes in a pointer to a large struct of type <font class="fixd">serial_struct,</font> which the
29319 tty driver should fill up with the proper values. Here is an example of how this
29320 can be implemented:<br>
29321 <pre>
29322 static int tiny_ioctl(struct tty_struct *tty, struct file *file,
29323 unsigned int cmd, unsigned long arg)
29324 {
29325 struct tiny_serial *tiny = tty->driver_data;
29326 if (cmd = = TIOCGSERIAL) {
29327 struct serial_struct tmp;
29328 if (!arg)
29329 return -EFAULT;
29330 memset(&tmp, 0, sizeof(tmp));
29331 tmp.type = tiny->serial.type;
29332 tmp.line = tiny->serial.line;
29333 tmp.port = tiny->serial.port;
29334 tmp.irq = tiny->serial.irq;
29335 tmp.flags = ASYNC_SKIP_TEST | ASYNC_AUTO_IRQ;
29336 tmp.xmit_fifo_size = tiny->serial.xmit_fifo_size;
29337 tmp.baud_base = tiny->serial.baud_base;
29338 tmp.close_delay = 5*HZ;
29339 tmp.closing_wait = 30*HZ;
29340 tmp.custom_divisor = tiny->serial.custom_divisor;
29341 tmp.hub6 = tiny->serial.hub6;
29342 tmp.io_type = tiny->serial.io_type;
29343 if (copy_to_user((void __user *)arg, &tmp, sizeof(tmp)))
29344 return -EFAULT;
29345 return 0;
29346 }
29347 return -ENOIOCTLCMD;
29348 }
29349 </pre></div>
29350 <A name="565"></a><font color="blue">PAGE 565</font><br>
29351 <br>
29352 <font class="fixd">TIOCSSERIAL</font><br>
29353 <div class="bq">
29354 Sets the serial line information. This is the opposite of <font class="fixd">TIOCGSERIAL</font> and allows
29355 the user to set the serial line status of the tty device all at once. A pointer to a
29356 <font class="fixd">struct serial_struct</font> is passed to this call, full of data that the tty device should
29357 now be set to. If the tty driver does not implement this call, most programs still
29358 works properly.</div>
29359 <br>
29360 <font class="fixd">TIOCMIWAIT</font><br>
29361 <div class="bq">
29362 Waits for MSR change. The user asks for this <i>ioctl </i>in the unusual circumstances
29363 that it wants to sleep within the kernel until something happens to the MSR register
29364 of the tty device. The <font class="fixd">arg</font> parameter contains the type of event that the user
29365 is waiting for. This is commonly used to wait until a status line changes, signaling
29366 that more data is ready to be sent to the device.<br>
29367 <br>
29368 Be careful when implementing this <i>ioctl</i>, and do not use the <i>interruptible_sleep_on
29369 </i>call, as it is unsafe (there are lots of nasty race conditions involved with it).
29370 Instead, a <i>wait_queue </i>should be used to avoid these problems. Here's an example
29371 of how to implement this ioctl:<br>
29372 <pre>
29373 static int tiny_ioctl(struct tty_struct *tty, struct file *file,
29374 unsigned int cmd, unsigned long arg)
29375 {
29376 struct tiny_serial *tiny = tty->driver_data;
29377 if (cmd = = TIOCMIWAIT) {
29378 DECLARE_WAITQUEUE(wait, current);
29379 struct async_icount cnow;
29380 struct async_icount cprev;
29381 cprev = tiny->icount;
29382 while (1) {
29383 add_wait_queue(&tiny->wait, &wait);
29384 set_current_state(TASK_INTERRUPTIBLE);
29385 schedule( );
29386 remove_wait_queue(&tiny->wait, &wait);
29387 /* see if a signal woke us up */
29388 if (signal_pending(current))
29389 return -ERESTARTSYS;
29390 cnow = tiny->icount;
29391 if (cnow.rng = = cprev.rng && cnow.dsr = = cprev.dsr &&
29392 cnow.dcd = = cprev.dcd && cnow.cts = = cprev.cts)
29393 return -EIO; /* no change => error */
29394 if (((arg & TIOCM_RNG) && (cnow.rng != cprev.rng)) ||
29395 ((arg & TIOCM_DSR) && (cnow.dsr != cprev.dsr)) ||
29396 ((arg & TIOCM_CD) && (cnow.dcd != cprev.dcd)) ||
29397 ((arg & TIOCM_CTS) && (cnow.cts != cprev.cts)) ) {
29398 return 0;
29399 }
29400 cprev = cnow;
29401 }
29402 }
29403 return -ENOIOCTLCMD;
29404 }
29405 </pre></div>
29406 <A name="566"></a><font color="blue">PAGE 566</font><br>
29407 <br>
29408 <div class="bq">Somewhere in the tty driver's code that recognizes that the MSR register
29409 changes, the following line must be called for this code to work properly:<br>
29410 <pre>
29411 wake_up_interruptible(&tp->wait);
29412 </pre></div>
29413 <font class="fixd">TIOCGICOUNT</font><br>
29414 <div class="bq">
29415 Gets interrupt counts. This is called when the user wants to know how many
29416 serial line interrupts have happened. If the driver has an interrupt handler, it
29417 should define an internal structure of counters to keep track of these statistics
29418 and increment the proper counter every time the function is run by the kernel.<br>
29419 <br>
29420 This <i>ioctl </i>call passes the kernel a pointer to a structure <font class="fixd">serial_icounter_struct,</font>
29421 which should be filled by the tty driver. This call is often made in conjunction
29422 with the previous <font class="fixd">TIOCMIWAIT</font> <i>ioctl </i>call. If the tty driver keeps track of all of these
29423 interrupts while the driver is operating, the code to implement this call can be
29424 very simple:<br>
29425 <pre>
29426 static int tiny_ioctl(struct tty_struct *tty, struct file *file,
29427 unsigned int cmd, unsigned long arg)
29428 {
29429 struct tiny_serial *tiny = tty->driver_data;
29430 if (cmd = = TIOCGICOUNT) {
29431 struct async_icount cnow = tiny->icount;
29432 struct serial_icounter_struct icount;
29433 icount.cts = cnow.cts;
29434 icount.dsr = cnow.dsr;
29435 icount.rng = cnow.rng;
29436 icount.dcd = cnow.dcd;
29437 icount.rx = cnow.rx;
29438 icount.tx = cnow.tx;
29439 icount.frame = cnow.frame;
29440 icount.overrun = cnow.overrun;
29441 icount.parity = cnow.parity;
29442 icount.brk = cnow.brk;
29443 icount.buf_overrun = cnow.buf_overrun;
29444 if (copy_to_user((void __user *)arg, &icount, sizeof(icount)))
29445 return -EFAULT;
29446 return 0;
29447 }
29448 return -ENOIOCTLCMD;
29449 }
29450 </pre></div>
29451 <a name="ProcAndSysfsHandlingOfTTYDevices"></a><font color="red"><b>proc and sysfs Handling of TTY Devices</b></font><br>
29452 <br>
29453 The tty core provides a very easy way for any tty driver to maintain a file in the <i>/proc/
29454 tty/driver </i>directory. If the driver defines the <i>read_proc </i>or <i>write_proc </i>functions, this
29455 file is created. Then, any read or write call on this file is sent to the driver. The formats
29456 of these functions are just like the standard <i>/proc</i> file-handling functions.<br>
29457 <br>
29458 <A name="567"></a><font color="blue">PAGE 567</font><br>
29459 <br>
29460 As an example, here is a simple implementation of the <i>read_proc tty </i>callback that
29461 merely prints out the number of the currently registered ports:<br>
29462 <pre>
29463 static int tiny_read_proc(char *page, char **start, off_t off, int count,
29464 int *eof, void *data)
29465 {
29466 struct tiny_serial *tiny;
29467 off_t begin = 0;
29468 int length = 0;
29469 int i;
29471 length += sprintf(page, "tinyserinfo:1.0 driver:%s\n", DRIVER_VERSION);
29472 for (i = 0; i < TINY_TTY_MINORS && length < PAGE_SIZE; ++i) {
29473 tiny = tiny_table[i];
29474 if (tiny = = NULL)
29475 continue;
29477 length += sprintf(page+length, "%d\n", i);
29478 if ((length + begin) > (off + count))
29479 goto done;
29480 if ((length + begin) < off) {
29481 begin += length;
29482 length = 0;
29483 }
29484 }
29485 *eof = 1;
29486 done:
29487 if (off >= (length + begin))
29488 return 0;
29489 *start = page + (off-begin);
29490 return (count < begin+length-off) ? count : begin + length-off;
29491 }
29492 </pre>
29493 The tty core handles all of the sysfs directory and device creation when the tty
29494 driver is registered, or when the individual tty devices are created, depending on
29495 the <font class="fixd">TTY_DRIVER_NO_DEVFS</font> flag in the <font class="fixd">struct tty_driver</font>. The individual directory
29496 always contains the <i>dev </i>file, which allows user-space tools to determine the major
29497 and minor number assigned to the device. It also contains a <i>device </i>and <i>driver </i>symlink,
29498 if a pointer to a valid <font class="fixd">struct device</font> is passed in the call to <i>tty_register_device</i>.
29499 Other than these three files, it is not possible for individual tty drivers to create
29500 new sysfs files in this location. This will probably change in future kernel releases.<br>
29501 <br>
29502 <a name="TheTtydriverStructureInDetail"></a><font color="red"><b>The <font class="fixd">tty_driver</font> Structure in Detail</b></font><br>
29503 <br>
29504 The <font class="fixd">tty_driver</font> structure is used to register a tty driver with the tty core. Here is a list
29505 of all of the different fields in the structure and how they are used by the tty core:<br>
29506 <br>
29507 <font class="fixd">struct module *owner;</font><br>
29508 <div class="bq">
29509 The module owner for this driver.</div>
29510 <br>
29511 <A name="568"></a><font color="blue">PAGE 568</font><br>
29512 <br>
29513 <font class="fixd">int magic;</font><br>
29514 <div class="bq">
29515 The "magic" value for this structure. Should always be set to <font class="fixd">TTY_DRIVER_MAGIC</font>.
29516 Is initialized in the <i>alloc_tty_driver</i> function.</div>
29517 <br>
29518 <font class="fixd">const char *driver_name;</font><br>
29519 <div class="bq">
29520 Name of the driver, used in <i>/proc/tty</i> and sysfs.</div>
29521 <br>
29522 <font class="fixd">const char *name;</font><br>
29523 <div class="bq">
29524 Node name of the driver.</div>
29525 <br>
29526 <font class="fixd">int name_base;</font><br>
29527 <div class="bq">
29528 Starting number to use when creating names for devices. This is used when the
29529 kernel creates a string representation of a specific tty device assigned to the tty
29530 driver.</div>
29531 <br>
29532 <font class="fixd">short major;</font><br>
29533 <div class="bq">
29534 Major number for the driver.</div>
29535 <br>
29536 <font class="fixd">short minor_start;</font><br>
29537 <div class="bq">
29538 Starting minor number for the driver. This is usually set to the same value as
29539 <font class="fixd">name_base</font>. Typically, this value is set to 0.</div>
29540 <br>
29541 <font class="fixd">short num;</font><br>
29542 <div class="bq">
29543 Number of minor numbers assigned to the driver. If an entire major number
29544 range is used by the driver, this value should be set to 255. This variable is initialized
29545 in the <i>alloc_tty_driver</i> function.</div>
29546 <br>
29547 <font class="fixd">short type;<br>
29548 short subtype;</font><br>
29549 <div class="bq">
29550 Describe what kind of tty driver is being registered with the tty core. The value
29551 of <font class="fixd">subtype</font> depends on the <font class="fixd">type.</font> The <font class="fixd">type</font> field can be:<br>
29552 <br>
29553 <font class="fixd">TTY_DRIVER_TYPE_SYSTEM</font><br>
29554 <div class="bq">
29555 Used internally by the tty subsystem to remember that it is dealing with an
29556 internal tty driver. subtype should be set to <font class="fixd">SYSTEM_TYPE_TTY, SYSTEM_TYPE_CONSOLE,
29557 SYSTEM_TYPE_SYSCONS,</font> or <font class="fixd">SYSTEM_TYPE_SYSPTMX</font>. This type should not
29558 be used by any "normal" tty driver.</div>
29559 <br>
29560 <font class="fixd">TTY_DRIVER_TYPE_CONSOLE</font><br>
29561 <div class="bq">
29562 Used only by the console driver.</div>
29563 <br>
29564 <font class="fixd">TTY_DRIVER_TYPE_SERIAL</font><br>
29565 <div class="bq">
29566 Used by any serial type driver. <font class="fixd">subtype</font> should be set to <font class="fixd">SERIAL_TYPE_NORMAL</font>
29567 or SERIAL_TYPE_CALLOUT, depending on which type your driver is. This is one
29568 of the most common settings for the <font class="fixd">type</font> field.</div>
29569 <br>
29570 <font class="fixd">TTY_DRIVER_TYPE_PTY</font><br>
29571 <div class="bq">
29572 Used by the pseudo terminal interface (pty). <font class="fixd">subtype</font> needs to be set to either
29573 <font class="fixd">PTY_TYPE_MASTER</font> or <font class="fixd">PTY_TYPE_SLAVE</font>.</div></div>
29574 <br>
29575 <font class="fixd">struct termios init_termios;</font><br>
29576 <div class="bq">
29577 Initial struct termios values for the device when it is created.</div>
29578 <br>
29579 <A name="569"></a><font color="blue">PAGE 569</font><br>
29580 <br>
29581 <font class="fixd">int flags;</font><br>
29582 <div class="bq">
29583 Driver flags, as described earlier in this chapter.</div>
29584 <br>
29585 <font class="fixd">struct proc_dir_entry *proc_entry;</font><br>
29586 <div class="bq">
29587 This driver's <i>/proc </i>entry structure. It is created by the tty core if the driver implements
29588 the <i>write_proc </i>or <i>read_proc </i>functions. This field should not be set by the
29589 tty driver itself.</div>
29590 <br>
29591 <font class="fixd">struct tty_driver *other;</font><br>
29592 <div class="bq">
29593 Pointer to a tty slave driver. This is used only by the pty driver and should not be
29594 used by any other tty driver.</div>
29595 <br>
29596 <font class="fixd">void *driver_state;</font><br>
29597 <div class="bq">
29598 Internal state of the tty driver. Should be used only by the pty driver.</div>
29599 <br>
29600 <font class="fixd">struct tty_driver *next;<br>
29601 struct tty_driver *prev;</font><br>
29602 <div class="bq">
29603 Linking variables. These variables are used by the tty core to chain all of the different
29604 tty drivers together, and should not be touched by any tty driver.</div>
29605 <br>
29606 <a name="TheTtyoperationsStructureInDetail"></a><font color="red"><b>The <font class="fixd">tty_operations</font> Structure in Detail</b></font><br>
29607 <br>
29608 The <font class="fixd">tty_operations</font> structure contains all of the function callbacks that can be set by
29609 a tty driver and called by the tty core. Currently, all of the function pointers contained
29610 in this structure are also in the <font class="fixd">tty_driver</font> structure, but that will be replaced
29611 soon with only an instance of this structure.<br>
29612 <br>
29613 <font class="fixd">int (*open)(struct tty_struct * tty, struct file * filp);</font><br>
29614 <div class="bq">
29615 The <i>open</i> function.</div>
29616 <br>
29617 <font class="fixd">void (*close)(struct tty_struct * tty, struct file * filp);</font><br>
29618 <div class="bq">
29619 The <i>close</i> function.</div>
29620 <br>
29621 <font class="fixd">int (*write)(struct tty_struct * tty, const unsigned char *buf, int count);<</font>br>
29622 <div class="bq">
29623 The <i>write</i> function.</div>
29624 <br>
29625 <font class="fixd">void (*put_char)(struct tty_struct *tty, unsigned char ch);</font><br>
29626 <div class="bq">
29627 The single-character <i>write </i>function. This function is called by the tty core when
29628 a single character is to be written to the device. If a tty driver does not define this
29629 function, the <i>write </i>function is called instead when the tty core wants to send a
29630 single character.</div>
29631 <br>
29632 <font class="fixd">void (*flush_chars)(struct tty_struct *tty);<br>
29633 void (*wait_until_sent)(struct tty_struct *tty, int timeout);</font><br>
29634 <div class="bq">
29635 The function that flushes data to the hardware.</div>
29636 <br>
29637 <font class="fixd">int (*write_room)(struct tty_struct *tty);</font><br>
29638 <div class="bq">
29639 The function that indicates how much of the buffer is free.</div>
29640 <br>
29641 <font class="fixd">int (*chars_in_buffer)(struct tty_struct *tty);</font><br>
29642 <div class="bq">
29643 The function that indicates how much of the buffer is full of data.</div>
29644 <br>
29645 <A name="570"></a><font color="blue">PAGE 570</font><br>
29646 <br>
29647 <font class="fixd">int (*ioctl)(struct tty_struct *tty, struct file * file, unsigned int cmd, unsigned long arg);</font><br>
29648 <div class="bq">
29649 The <i>ioctl </i>function. This function is called by the tty core when <i>ioctl(2) </i>is called
29650 on the device node.</div>
29651 <br>
29652 <font class="fixd">void (*set_termios)(struct tty_struct *tty, struct termios * old);</font><br>
29653 <div class="bq">
29654 The <i>set_termios </i>function. This function is called by the tty core when the
29655 device's termios settings have been changed.</div>
29656 <br>
29657 <font class="fixd">void (*throttle)(struct tty_struct * tty);<br>
29658 void (*unthrottle)(struct tty_struct * tty);<br>
29659 void (*stop)(struct tty_struct *tty);<br>
29660 void (*start)(struct tty_struct *tty);</font><br>
29661 <div class="bq">
29662 Data-throttling functions. These functions are used to help control overruns of
29663 the tty core's input buffers. The <i>throttle </i>function is called when the tty core's
29664 input buffers are getting full. The tty driver should try to signal to the device that
29665 no more characters should be sent to it. The <i>unthrottle </i>function is called when
29666 the tty core's input buffers have been emptied out, and it can now accept more
29667 data. The tty driver should then signal to the device that data can be received.
29668 The <i>stop </i>and <i>start </i>functions are much like the <i>throttle </i>and <i>unthrottle </i>functions,
29669 but they signify that the tty driver should stop sending data to the device and
29670 then later resume sending data.</div>
29671 <br>
29672 <font class="fixd">void (*hangup)(struct tty_struct *tty);</font><br>
29673 <div class="bq">
29674 The <i>hangup </i>function. This function is called when the tty driver should hang up
29675 the tty device. Any special hardware manipulation needed to do this should
29676 occur at this time.</div>
29677 <br>
29678 <font class="fixd">void (*break_ctl)(struct tty_struct *tty, int state);</font><br>
29679 <div class="bq">
29680 The <i>line break </i>control function. This function is called when the tty driver is to
29681 turn on or off the line BREAK status on the RS-232 port. If state is set to <font class="fixd">-1</font>, the
29682 BREAK status should be turned on. If state is set to <font class="fixd">0,</font> the BREAK status should
29683 be turned off. If this function is implemented by the tty driver, the tty core will
29684 handle the <font class="fixd">TCSBRK, TCSBRKP, TIOCSBRK,</font> and <font class="fixd">TIOCCBRK</font> <i>ioctl</i>s. Otherwise, these <i>ioctl</i>s
29685 are sent to the driver to the <i>ioctl</i> function.</div>
29686 <br>
29687 <font class="fixd">void (*flush_buffer)(struct tty_struct *tty);</font><br>
29688 <div class="bq">
29689 Flush buffer and lose any remaining data.</div>
29690 <br>
29691 <font class="fixd">void (*set_ldisc)(struct tty_struct *tty);</font><br>
29692 <div class="bq">
29693 The <i>set line discipline </i>function. This function is called when the tty core has
29694 changed the line discipline of the tty driver. This function is generally not used
29695 and should not be defined by a driver.</div>
29696 <br>
29697 <font class="fixd">void (*send_xchar)(struct tty_struct *tty, char ch);</font><br>
29698 <div class="bq">
29699 Send <i>X-type char </i>function. This function is used to send a high-priority XON or
29700 XOFF character to the tty device. The character to be sent is specified in the ch
29701 variable.</div>
29702 <br>
29703 <A name="571"></a><font color="blue">PAGE 571</font><br>
29704 <br>
29705 <font class="fixd">int (*read_proc)(char *page, char **start, off_t off, int count, int *eof, void *data);<br>
29706 int (*write_proc)(struct file *file, const char *buffer, unsigned long count, void *data);</font><br>
29707 <div class="bq">
29708 <i>/proc read</i> and <i>write</i> functions.</div>
29709 <br>
29710 <font class="fixd">int (*tiocmget)(struct tty_struct *tty, struct file *file);</font><br>
29711 <div class="bq">
29712 Gets the current line settings of the specific tty device. If retrieved successfully
29713 from the tty device, the value should be returned to the caller.</div>
29714 <br>
29715 <font class="fixd">int (*tiocmset)(struct tty_struct *tty, struct file *file, unsigned int set, unsigned int clear);</font><br>
29716 <div class="bq">
29717 Sets the current line settings of the specific tty device. set and clear contain the
29718 different line settings that should either be set or cleared.</div>
29719 <br>
29720 <a name="TheTtystructStructureInDetail"></a><font color="red"><b>The <font class="fixd">tty_struct</font> Structure in Detail</b></font><br>
29721 <br>
29722 The <font class="fixd">tty_struct</font> variable is used by the tty core to keep the current state of a specific
29723 tty port. Almost all of its fields are to be used only by the tty core, with a few exceptions.
29724 The fields that a tty driver can use are described here:<br>
29725 <br>
29726 <font class="fixd">unsigned long flags;</font><br>
29727 <div class="bq">
29728 The current state of the tty device. This is a bitfield variable and is accessed
29729 through the following macros:<br>
29730 <br>
29731 <font class="fixd">TTY_THROTTLED</font><br>
29732 <div class="bq">
29733 Set when the driver has had the <i>throttle </i>function called. Should not be set by
29734 a tty driver, only the tty core.</div>
29735 <br>
29736 <font class="fixd">TTY_IO_ERROR</font><br>
29737 <div class="bq">
29738 Set by the driver when it does not want any data to be read from or written
29739 to the driver. If a user program attempts to do this, it receives an -EIO error
29740 from the kernel. This is usually set as the device is shutting down.</div>
29741 <br>
29742 <font class="fixd">TTY_OTHER_CLOSED</font><br>
29743 <div class="bq">
29744 Used only by the pty driver to notify when the port has been closed.</div>
29745 <br>
29746 <font class="fixd">TTY_EXCLUSIVE</font><br>
29747 <div class="bq">
29748 Set by the tty core to indicate that a port is in exclusive mode and can only
29749 be accessed by one user at a time.</div>
29750 <br>
29751 <font class="fixd">TTY_DEBUG</font><br>
29752 <div class="bq">
29753 Not used anywhere in the kernel.</div>
29754 <br>
29755 <font class="fixd">TTY_DO_WRITE_WAKEUP</font><br>
29756 <div class="bq">
29757 If this is set, the line discipline's <i>write_wakeup </i>function is allowed to be
29758 called. This is usually called at the same time the <i>wake_up_interruptible
29759 </i>function is called by the tty driver.</div></div>
29760 <br>
29761 <A name="572"></a><font color="blue">PAGE 572</font><br>
29762 <br>
29763 <div class="bq">
29764 <font class="fixd">TTY_PUSH</font><br>
29765 <div class="bq">
29766 Used only internally by the default tty line discipline.</div>
29767 <br>
29768 <font class="fixd">TTY_CLOSING</font><br>
29769 <div class="bq">
29770 Used by the tty core to keep track if a port is in the process of closing at that
29771 moment in time or not.</div>
29772 <br>
29773 <font class="fixd">TTY_DONT_FLIP</font><br>
29774 <div class="bq">
29775 Used by the default tty line discipline to notify the tty core that it should not
29776 change the flip buffer when it is set.</div>
29777 <br>
29778 <font class="fixd">TTY_HW_COOK_OUT</font><br>
29779 <div class="bq">
29780 If set by a tty driver, it notifies the line discipline that it will "cook" the output
29781 sent to it. If it is not set, the line discipline copies output of the driver in
29782 chunks; otherwise, it has to evaluate every byte sent individually for line
29783 changes. This flag should generally not be set by a tty driver.</div>
29784 <br>
29785 <font class="fixd">TTY_HW_COOK_IN</font><br>
29786 <div class="bq">
29787 Almost identical to setting the <font class="fixd">TTY_DRIVER_REAL_RAW</font> flag in the driver flags
29788 variable. This flag should generally not be set by a tty driver.</div>
29789 <br>
29790 <font class="fixd">TTY_PTY_LOCK</font><br>
29791 <div class="bq">
29792 Used by the pty driver to lock and unlock a port.</div>
29793 <br>
29794 <font class="fixd">TTY_NO_WRITE_SPLIT</font><br>
29795 <div class="bq">
29796 If set, the tty core does not split up writes to the tty driver into normal-sized
29797 chunks. This value should not be used to prevent denial-of-service attacks
29798 on tty ports by sending large amounts of data to a port.</div></div>
29799 <br>
29800 <font class="fixd">struct tty_flip_buffer flip;</font><br>
29801 <div class="bq">
29802 The flip buffer for the tty device.</div>
29803 <br>
29804 <font class="fixd">struct tty_ldisc ldisc;</font><br>
29805 <div class="bq">
29806 The line discipline for the tty device.</div>
29807 <br>
29808 <font class="fixd">wait_queue_head_t write_wait;</font><br>
29809 <div class="bq">
29810 The <i>wait_queue </i>for the tty writing function. A tty driver should wake this up to
29811 signal when it can receive more data.</div>
29812 <br>
29813 <font class="fixd">struct termios *termios;</font><br>
29814 <div class="bq">
29815 Pointer to the current termios settings for the tty device.</div>
29816 <br>
29817 <font class="fixd">unsigned char stopped:1;</font><br>
29818 <div class="bq">
29819 Indicates whether the tty device is stopped. The tty driver can set this value.</div>
29820 <br>
29821 <font class="fixd">unsigned char hw_stopped:1;</font><br>
29822 <div class="bq">
29823 Indicates whether or not the tty device's hardware is stopped. The tty driver can
29824 set this value.</div>
29825 <br>
29826 <font class="fixd">unsigned char low_latency:1;</font><br>
29827 <div class="bq">
29828 Indicates whether the tty device is a low-latency device, capable of receiving data
29829 at a very high rate of speed. The tty driver can set this value.</div>
29830 <br>
29831 <A name="573"></a><font color="blue">PAGE 573</font><br>
29832 <br>
29833 <font class="fixd">unsigned char closing:1;</font><br>
29834 <div class="bq">
29835 Indicates whether the tty device is in the middle of closing the port. The tty
29836 driver can set this value.</div>
29837 <br>
29838 <font class="fixd">struct tty_driver</font> driver;</font><br>
29839 <div class="bq">
29840 The current <font class="fixd">tty_driver</font> structure that controls this tty device.</div>
29841 <br>
29842 <font class="fixd">void *driver_data;</font><br>
29843 <div class="bq">
29844 A pointer that the <font class="fixd">tty_driver</font> can use to store data local to the tty driver. This
29845 variable is not modified by the tty core.</div>
29846 <br>
29847 <a name="QuickReference18"></a><font color="red"><b>Quick Reference</b></font><br>
29848 <br>
29849 This section provides a reference for the concepts introduced in this chapter. It also
29850 explains the role of each header file that a tty driver needs to include. The lists of
29851 fields in the <font class="fixd">tty_driver</font> and <font class="fixd">tty_device</font> structures, however, are not repeated here.<br>
29852 <br>
29853 <font class="fixd">#include <linux/tty_driver.h></font><br>
29854 <div class="bq">
29855 Header file that contains the definition of <font class="fixd">struct tty_driver</font> and declares some
29856 of the different flags used in this structure.</div>
29857 <br>
29858 <font class="fixd">#include <linux/tty.h></font><br>
29859 <div class="bq">
29860 Header file that contains the definition of <font class="fixd">struct tty_struct</font> and a number of
29861 different macros to access the individual values of the <font class="fixd">struct termios</font> fields easily.
29862 It also contains the function declarations of the tty driver core.</div>
29863 <br>
29864 <font class="fixd">#include <linux/tty_flip.h></font><br>
29865 <div class="bq">
29866 Header file that contains some tty flip buffer inline functions that make it easier
29867 to manipulate the flip buffer structures.</div>
29868 <br>
29869 <font class="fixd">#include <asm/termios.h></font><br>
29870 <div class="bq">
29871 Header file that contains the definition of <font class="fixd">struct termio</font> for the specific hardware
29872 platform the kernel is built for.</div>
29873 <br>
29874 <font class="fixd">struct tty_driver *alloc_tty_driver(int lines);</font><br>
29875 <div class="bq">
29876 Function that creates a <font class="fixd">struct tty_driver</font> that can be later passed to the
29877 <i>tty_register_driver</i> and <i>tty_unregister_driver</i> functions.</div>
29878 <br>
29879 <font class="fixd">void put_tty_driver(struct tty_driver *driver);</font><br>
29880 <div class="bq">
29881 Function that cleans up a <font class="fixd">struct tty_driver</font> structure that has not been successfully
29882 registered with the tty core.</div>
29883 <br>
29884 <font class="fixd">void tty_set_operations(struct tty_driver *driver, struct tty_operations *op);</font><br>
29885 <div class="bq">
29886 Function that initializes the function callbacks of a <font class="fixd">struct tty_driver</font>. This is
29887 necessary to call before <i>tty_register_driver </i>can be called.</div>
29888 <br>
29889 <font class="fixd">int tty_register_driver(struct tty_driver *driver);
29890 int tty_unregister_driver(struct tty_driver *driver);</font><br>
29891 <div class="bq">
29892 Functions that register and unregister a tty driver from the tty core.</div>
29893 <br>
29894 <A name="574"></a><font color="blue">PAGE 574</font><br>
29895 <br>
29896 <font class="fixd">void tty_register_device(struct tty_driver *driver, unsigned minor, struct device *device);<br>
29897 void tty_unregister_device(struct tty_driver *driver, unsigned minor);</font><br>
29898 <div class="bq">
29899 Functions that register and unregister a single tty device with the tty core.</div>
29900 <br>
29901 <font class="fixd">void tty_insert_flip_char(struct tty_struct *tty, unsigned char ch, char flag);</font><br>
29902 <div class="bq">
29903 Function that inserts characters into the tty device's flip buffer to be read by a
29904 user.</div>
29905 <br>
29906 <font class="fixd">TTY_NORMAL<br>
29907 TTY_BREAK<br>
29908 TTY_FRAME<br>
29909 TTY_PARITY<br>
29910 TTY_OVERRUN</font><br>
29911 <div class="bq">
29912 Different values for the flag paramater used in the <i>tty_insert_flip_char</i> function.</div>
29913 <br>
29914 <font class="fixd">int tty_get_baud_rate(struct tty_struct *tty);</font><br>
29915 <div class="bq">
29916 Function that gets the baud rate currently set for the specific tty device.</div>
29917 <br>
29918 <font class="fixd">void tty_flip_buffer_push(struct tty_struct *tty);</font><br>
29919 <div class="bq">
29920 Function that pushes the data in the current flip buffer to the user.</div>
29921 <br>
29922 <font class="fixd">tty_std_termios</font><br>
29923 <div class="bq">
29924 Variable that initializes a termios structure with a common set of default line
29925 settings.</div>
29926 <br>
29927 <br><a name="Index"></a><font color="#7519FF" size="+1"><b>Index</b></font><br>
29928 <br>
29929 <A name="579"></a><font color="blue">PAGE 579</font><br>
29930 <br>
29931 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
29933 <a name="Numbers"></a><font color="red"><b>Numbers</b></font><br><br>
29935 16-bit ports, <a href="#240">240</a>, <a href="#242">242</a><br>
29936 32-bit ports, <a href="#240">240</a><br>
29937 <div class="bql">accessing, <a href="#240">240</a><br>
29938 string functions for, <a href="#242">242</a></div>
29939 8-bit ports, <a href="#240">240</a><br>
29940 <div class="bql">reading/writing, <a href="#240">240</a><br>
29941 string functions for, <a href="#242">242</a></div>
29943 <br><a name="A"></a><font color="red"><b>A</b></font><br><br>
29945 abstractions (hardware), <a href="#318">318</a><br>
29946 access<br>
29947 <div class="bql">blocking open requests, <a href="#176">176</a><br>
29948 character (char) drivers, <a href="#6">6</a>, <a href="#43">43</a>-<a href="#49">49</a><br>
29949 to device files, <a href="#173">173</a>-<a href="#179">179</a><br>
29950 DMA (see DMA)<br>
29951 to drivers, <a href="#47">47</a><br>
29952 interfaces, <a href="#7">7</a><br>
29953 I/O memory, <a href="#249">249</a>, <a href="#250">250</a>, <a href="#252">252</a><br>
29954 ISA memory, <a href="#253">253</a><br>
29955 kobjects, <a href="#365">365</a><br>
29956 locking, <a href="#121">121</a><br>
29957 management, <a href="#108">108</a><br>
29958 NUMA systems, <a href="#216">216</a>, <a href="#417">417</a><br>
29959 PCI, <a href="#305">305</a><br>
29960 <div class="bql">configuration space, <a href="#315">315</a><br>
29961 I/O and memory spaces, <a href="#316">316</a></div>
29962 policies, <a href="#3">3</a><br>
29963 ports, <a href="#255">255</a><br>
29964 <div class="bql">different sizes, <a href="#240">240</a><br>
29965 from user space, <a href="#241">241</a></div>
29966 restriction of, <a href="#144">144</a>, <a href="#174">174</a></div>
29967 </td><td valign="top" width="50%">
29968 <div class="bql">seqlocks, <a href="#127">127</a><br>
29969 unaligned data, <a href="#300">300</a></div>
29970 access_ok function, <a href="#142">142</a><br>
29971 ACTION variable, <a href="#399">399</a><br>
29972 adding<br>
29973 <div class="bql">devices, <a href="#392">392</a>-<a href="#395">395</a><br>
29974 drivers, <a href="#396">396</a><br>
29975 locking, <a href="#109">109</a><br>
29976 VMAs, <a href="#426">426</a></div>
29977 Address Resolution Protocol (see ARP)<br>
29978 addresses<br>
29979 <div class="bql">bounce buffers, <a href="#445">445</a><br>
29980 bus (see bus addresses)<br>
29981 buses, <a href="#443">443</a><br>
29982 hardware, <a href="#508">508</a>, <a href="#515">515</a><br>
29983 hardware (see hardware addresses)<br>
29984 MAC, <a href="#504">504</a>, <a href="#532">532</a>-<a href="#534">534</a><br>
29985 PCI, <a href="#303">303</a>, <a href="#452">452</a><br>
29986 remapping, <a href="#434">434</a><br>
29987 resolution (network management), <a href="#5">5</a><br>
29988 resolving, <a href="#532">532</a><br>
29989 spaces, generic I/O, <a href="#316">316</a><br>
29990 types, <a href="#413">413</a><br>
29991 virtual (conversion), <a href="#444">444</a></div>
29992 aio_fsync operation, <a href="#438">438</a><br>
29993 algorithms (lock-free), <a href="#123">123</a><br>
29994 alignment<br>
29995 <div class="bql">of data, <a href="#293">293</a><br>
29996 unaligned data access, <a href="#300">300</a></div>
29997 allocating<br>
29998 <div class="bql">major device numbers, <a href="#46">46</a>-<a href="#49">49</a><br>
29999 memory, <a href="#60">60</a>-<a href="#62">62</a>
30000 <div class="bql">by page, <a href="#221">221</a></div></div>
30001 </td></tr></table>
30002 <br>
30003 <A name="580"></a><font color="blue">PAGE 580</font><br>
30004 <br>
30005 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
30006 allocation, <a href="#249">249</a>, <a href="#255">255</a><br>
30007 <div class="bql">of block drivers, <a href="#468">468</a><br>
30008 of buffers, <a href="#530">530</a><br>
30009 of device numbers, <a href="#45">45</a><br>
30010 of DMA buffers, <a href="#442">442</a><br>
30011 dynamic allocation of major numbers, <a href="#46">46</a><br>
30012 of gendisk structures, <a href="#468">468</a><br>
30013 of I/O ports, <a href="#239">239</a><br>
30014 of memory, <a href="#60">60</a>-<a href="#63">63</a><br>
30015 <div class="bql">boot time, <a href="#230">230</a>, <a href="#234">234</a><br>
30016 flags, <a href="#215">215</a>, <a href="#218">218</a>, <a href="#231">231</a><br>
30017 I/O, <a href="#249">249</a>, <a href="#255">255</a><br>
30018 kmalloc allocation engine, <a href="#213">213</a>-<a href="#217">217</a><br>
30019 lookaside caches, <a href="#217">217</a>-<a href="#224">224</a>, <a href="#232">232</a><br>
30020 per-CPU variables, <a href="#228">228</a>-<a href="#230">230</a><br>
30021 vmalloc allocation function, <a href="#224">224</a>-<a href="#228">228</a></div>
30022 page-oriented functions, <a href="#221">221</a>, <a href="#233">233</a><br>
30023 of snull drivers, <a href="#503">503</a><br>
30024 of socket buffers, <a href="#522">522</a>, <a href="#530">530</a><br>
30025 structures (registration), <a href="#55">55</a>-<a href="#57">57</a><br>
30026 of urbs, <a href="#354">354</a></div>
30027 alloc_netdev function, <a href="#504">504</a><br>
30028 alloc_pages interface, <a href="#223">223</a><br>
30029 alloc_skb function, <a href="#530">530</a><br>
30030 alloc_tty_driver function, <a href="#549">549</a><br>
30031 Alpha architecture, porting and, <a href="#243">243</a><br>
30032 alternatives to locking, <a href="#123">123</a>-<a href="#130">130</a><br>
30033 API (application programming interface)<br>
30034 <div class="bql">spinlocks, <a href="#117">117</a><br>
30035 timers, <a href="#198">198</a></div>
30036 application programming interface (see API)<br>
30037 applications versus kernel modules, <a href="#18">18</a>-<a href="#22">22</a><br>
30038 architecture<br>
30039 <div class="bql">EISA, <a href="#323">323</a><br>
30040 M68k (porting and), <a href="#243">243</a><br>
30041 MCA, <a href="#322">322</a><br>
30042 NuBus, <a href="#324">324</a><br>
30043 PCI, <a href="#302">302</a>-<a href="#319">319</a><br>
30044 PowerPC (porting and), <a href="#244">244</a><br>
30045 S/390, <a href="#402">402</a><br>
30046 SBus, <a href="#324">324</a><br>
30047 SPARC, <a href="#244">244</a><br>
30048 Super-H, <a href="#244">244</a><br>
30049 VLB, <a href="#323">323</a><br>
30050 x86 (interrupt handlers on), <a href="#268">268</a><br>
30051 zSeries, <a href="#402">402</a></div>
30052 arguments<br>
30053 <div class="bql">cache, <a href="#218">218</a><br>
30054 flags, <a href="#213">213</a><br>
30055 interrupt handlers, <a href="#272">272</a><br>
30056 ioctl method, <a href="#141">141</a></div>
30057 </td><td valign="top" width="50%">
30058 <div class="bql">kmalloc size, <a href="#216">216</a><br>
30059 sfile, <a href="#87">87</a></div>
30060 ARM architecture, porting and, <a href="#243">243</a><br>
30061 ARP (Address Resolution Protocol), <a href="#504">504</a><br>
30062 <div class="bql">Ethernet and, <a href="#532">532</a><br>
30063 IFF_NOARP flag and, <a href="#504">504</a>, <a href="#509">509</a><br>
30064 overriding, <a href="#533">533</a></div>
30065 arrays<br>
30066 <div class="bql">bi_io_vec, <a href="#482">482</a><br>
30067 block drivers, <a href="#468">468</a><br>
30068 memory maps, <a href="#417">417</a><br>
30069 parameters (declaration of), <a href="#37">37</a><br>
30070 quantum sets (memory), <a href="#61">61</a></div>
30071 asm directory, <a href="#19">19</a><br>
30072 assignment<br>
30073 <div class="bql">dynamic allocation of major numbers, <a href="#46">46</a><br>
30074 of hardware addresses, <a href="#515">515</a><br>
30075 of IP numbers, <a href="#499">499</a><br>
30076 of parameter values, <a href="#35">35</a>-<a href="#37">37</a></div>
30077 asynchronous DMA, <a href="#441">441</a><br>
30078 asynchronous I/O, <a href="#437">437</a>-<a href="#440">440</a><br>
30079 asynchronous notification, <a href="#169">169</a>-<a href="#171">171</a><br>
30080 asynchronous running of timers, <a href="#197">197</a><br>
30081 asynctest program, <a href="#169">169</a><br>
30082 atomic context (spinlocks), <a href="#118">118</a><br>
30083 atomic variables, <a href="#124">124</a><br>
30084 atomic_add operation, <a href="#125">125</a><br>
30085 atomic_dec operation, <a href="#125">125</a><br>
30086 atomic_dec_and_test operation, <a href="#125">125</a><br>
30087 atomic_inc operation, <a href="#125">125</a><br>
30088 atomic_inc_and_test operation, <a href="#125">125</a><br>
30089 atomic_read operation, <a href="#125">125</a><br>
30090 atomic_set operation, <a href="#125">125</a><br>
30091 atomic_sub operation, <a href="#125">125</a><br>
30092 atomic_sub_and_test operation, <a href="#125">125</a><br>
30093 atomic_t count field (memory), <a href="#417">417</a><br>
30094 attributes<br>
30095 <div class="bql">binary (kobjects), <a href="#374">374</a><br>
30096 buses, <a href="#380">380</a><br>
30097 data (firmware), <a href="#407">407</a><br>
30098 default (kobjects), <a href="#372">372</a><br>
30099 deleting, <a href="#374">374</a>, <a href="#381">381</a><br>
30100 devices, <a href="#383">383</a>, <a href="#407">407</a><br>
30101 drivers, <a href="#386">386</a><br>
30102 loading (firmware), <a href="#407">407</a><br>
30103 nondefault (kobjects), <a href="#373">373</a></div>
30104 authorization, <a href="#8">8</a><br>
30105 autodetection, <a href="#264">264</a><br>
30106 automatic, IRQ number detection, <a href="#264">264</a><br>
30107 </td></tr></table>
30108 <br>
30109 <A name="581"></a><font color="blue">PAGE 581</font><br>
30110 <br>
30111 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
30113 <a name="B"></a><font color="red"><b>B</b></font><br><br>
30115 back-casting kobject pointers, <a href="#365">365</a><br>
30116 barriers<br>
30117 <div class="bql">memory, <a href="#237">237</a>, <a href="#238">238</a>, <a href="#255">255</a><br>
30118 requests, <a href="#485">485</a></div>
30119 base module parameter, <a href="#247">247</a><br>
30120 baud rates (tty drivers), <a href="#562">562</a><br>
30121 BCD (binary-coded decimal) forms, <a href="#346">346</a><br>
30122 bEndpointAddress field (USB), <a href="#330">330</a><br>
30123 bibliography, <a href="#575">575</a><br>
30124 big-endian byte order, <a href="#293">293</a><br>
30125 bi_io_vec array, <a href="#482">482</a><br>
30126 binary attributes (kobjects), <a href="#374">374</a><br>
30127 binary-coded decimal (BCD) forms, <a href="#346">346</a><br>
30128 bin_attribute structure, <a href="#374">374</a><br>
30129 bInterval field (USB), <a href="#331">331</a><br>
30130 bio structure, <a href="#482">482</a>, <a href="#487">487</a><br>
30131 bitfields (ioctl commands), <a href="#137">137</a>, <a href="#180">180</a><br>
30132 bits<br>
30133 <div class="bql">clearing, <a href="#269">269</a><br>
30134 operations, <a href="#126">126</a><br>
30135 specifications, <a href="#246">246</a></div>
30136 BLK_BOUNCE_HIGH symbol, <a href="#480">480</a><br>
30137 blk_cleanup_queue function, <a href="#479">479</a><br>
30138 blkdev_dequeue_request function, <a href="#479">479</a><br>
30139 blk_queue_hardsect_size function, <a href="#470">470</a><br>
30140 blk_queue_segment_boundary function, <a href="#481">481</a><br>
30141 block devices, <a href="#7">7</a><br>
30142 block drivers<br>
30143 <div class="bql">command pre-preparation, <a href="#491">491</a><br>
30144 functions, <a href="#494">494</a>-<a href="#496">496</a><br>
30145 operations, <a href="#471">471</a>-<a href="#474">474</a><br>
30146 registration, <a href="#465">465</a>-<a href="#470">470</a><br>
30147 request processing, <a href="#474">474</a>-<a href="#491">491</a><br>
30148 TCQ, <a href="#492">492</a>-<a href="#493">493</a></div>
30149 block_fsync method, <a href="#167">167</a><br>
30150 blocking<br>
30151 <div class="bql">I/O, <a href="#147">147</a>-<a href="#162">162</a>, <a href="#176">176</a><br>
30152 open method, <a href="#176">176</a><br>
30153 operations, <a href="#151">151</a><br>
30154 release method, <a href="#176">176</a></div>
30155 bmAttributes field (USB), <a href="#330">330</a><br>
30156 BogoMips value, <a href="#195">195</a><br>
30157 boot time (memory allocation), <a href="#230">230</a>, <a href="#234">234</a><br>
30158 booting (PCI), <a href="#306">306</a><br>
30159 bottom halves<br>
30160 <div class="bql">interrupt handlers, <a href="#275">275</a>-<a href="#278">278</a><br>
30161 tasklets and, <a href="#276">276</a></div>
30162 bounce buffers, <a href="#445">445</a><br>
30163 <div class="bql">block drivers, <a href="#480">480</a><br>
30164 streaming DMA mappings and, <a href="#449">449</a></div>
30165 bridges, <a href="#303">303</a><br>
30166 </td><td valign="top" width="50%">
30167 BSS segments, <a href="#419">419</a><br>
30168 buffers<br>
30169 <div class="bql">allocation of, <a href="#530">530</a><br>
30170 bounce, <a href="#445">445</a><br>
30171 <div class="bql">block drivers, <a href="#480">480</a><br>
30172 streaming DMA mappings and, <a href="#449">449</a></div>
30173 circular, <a href="#78">78</a>, <a href="#123">123</a><br>
30174 DMA (unmapping), <a href="#449">449</a><br>
30175 freeing, <a href="#531">531</a><br>
30176 I/O, <a href="#151">151</a><br>
30177 large (obtaining), <a href="#230">230</a>, <a href="#234">234</a><br>
30178 output, <a href="#152">152</a><br>
30179 overrun errors, <a href="#9">9</a>, <a href="#95">95</a><br>
30180 for printk function, <a href="#78">78</a><br>
30181 ring (DMA), <a href="#441">441</a><br>
30182 socket (see socket buffers)<br>
30183 sockets, <a href="#522">522</a>, <a href="#528">528</a>-<a href="#532">532</a><br>
30184 synchronization, <a href="#452">452</a><br>
30185 transfers, <a href="#448">448</a><br>
30186 tty drivers, <a href="#558">558</a><br>
30187 USB, <a href="#338">338</a><br>
30188 user space (direct I/O), <a href="#436">436</a><br>
30189 write-buffering example, <a href="#282">282</a></div>
30190 bugs (see debugging; troubleshooting)<br>
30191 BULK endpoints (USB), <a href="#330">330</a><br>
30192 bulk urbs (USB), <a href="#343">343</a><br>
30193 bus_add_driver function, <a href="#396">396</a><br>
30194 BUS_ATTR macro, <a href="#380">380</a><br>
30195 bus_attribute type, <a href="#380">380</a><br>
30196 buses<br>
30197 <div class="bql">addresses, <a href="#413">413</a>, <a href="#443">443</a><br>
30198 attributes, <a href="#380">380</a><br>
30199 functions, <a href="#409">409</a><br>
30200 IEEE1394 (Firewire), <a href="#400">400</a><br>
30201 iteration, <a href="#379">379</a><br>
30202 Linux device model, <a href="#377">377</a>-<a href="#381">381</a><br>
30203 match function, <a href="#379">379</a><br>
30204 methods, <a href="#379">379</a><br>
30205 PCI (see PCI)<br>
30206 registers, <a href="#445">445</a><br>
30207 registration, <a href="#378">378</a><br>
30208 USB (see USB)</div>
30209 bus_for_each_dev function, <a href="#380">380</a><br>
30210 bus_register function, <a href="#378">378</a><br>
30211 bus_type structure, <a href="#378">378</a><br>
30212 busy loops, <a href="#191">191</a><br>
30213 busy-waiting implementation, <a href="#190">190</a><br>
30214 bytes<br>
30215 <div class="bql">CSIZE bitmask, <a href="#561">561</a><br>
30216 order, <a href="#293">293</a><br>
30217 orders, <a href="#300">300</a></div>
30218 </td></tr></table>
30219 <br>
30220 <A name="582"></a><font color="blue">PAGE 582</font><br>
30221 <br>
30222 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
30224 <a name="C"></a><font color="red"><b>C</b></font><br><br>
30226 caches<br>
30227 <div class="bql">argument, <a href="#218">218</a><br>
30228 coherency issues, <a href="#445">445</a><br>
30229 lookaside, <a href="#217">217</a>-<a href="#224">224</a>, <a href="#232">232</a><br>
30230 troubleshooting, <a href="#237">237</a>, <a href="#425">425</a></div>
30231 calling<br>
30232 <div class="bql">current process, <a href="#21">21</a><br>
30233 firmware, <a href="#407">407</a><br>
30234 ioctl method, <a href="#136">136</a><br>
30235 ioremap function, <a href="#249">249</a><br>
30236 memory barriers, <a href="#238">238</a><br>
30237 perror calls, <a href="#93">93</a><br>
30238 preparation functions, <a href="#492">492</a><br>
30239 release, <a href="#174">174</a></div>
30240 cancellation of urbs, <a href="#345">345</a><br>
30241 capabilities, restricted operations and, <a href="#144">144</a><br>
30242 capability.h header file, <a href="#144">144</a>, <a href="#181">181</a><br>
30243 capable function, <a href="#145">145</a>, <a href="#181">181</a><br>
30244 CAP_DAC_OVERRIDE capability, <a href="#144">144</a><br>
30245 <div class="bql">single-user access to devices, <a href="#175">175</a></div>
30246 CAP_NET_ADMIN capability, <a href="#144">144</a><br>
30247 CAP_SYS_ADMIN capability, <a href="#144">144</a><br>
30248 CAP_SYS_MODULE capability, <a href="#144">144</a><br>
30249 CAP_SYS_RAWIO capability, <a href="#144">144</a><br>
30250 CAP_SYS_TTY_CONFIG capability, <a href="#144">144</a><br>
30251 card select number (CSN), <a href="#321">321</a><br>
30252 cardctl utility, <a href="#3">3</a><br>
30253 carrier signals, <a href="#528">528</a><br>
30254 cdev structure, <a href="#56">56</a><br>
30255 change_bit operation, <a href="#126">126</a><br>
30256 change_mtu method, <a href="#513">513</a><br>
30257 <div class="bql">improving performance using socket<br>
30258 <div class="bql">buffers, <a href="#522">522</a></div></div>
30259 channels, DMA, <a href="#454">454</a>-<a href="#456">456</a><br>
30260 char *buffer field (request structure), <a href="#477">477</a><br>
30261 char bus_id field, <a href="#382">382</a><br>
30262 char disk_name field (gendisk), <a href="#467">467</a><br>
30263 char (character) drivers, <a href="#6">6</a><br>
30264 <div class="bql">access, <a href="#43">43</a>-<a href="#49">49</a><br>
30265 asynchronous notification, <a href="#169">169</a>-<a href="#171">171</a><br>
30266 defining mechanism of, <a href="#42">42</a><br>
30267 files<br>
30268 <div class="bql">access to, <a href="#173">173</a>-<a href="#179">179</a><br>
30269 operations, <a href="#49">49</a>-<a href="#53">53</a><br>
30270 structures, <a href="#53">53</a></div>
30271 inode structure, <a href="#55">55</a><br>
30272 I/O, <a href="#147">147</a>-<a href="#162">162</a><br>
30273 ioctl method, <a href="#135">135</a>-<a href="#147">147</a><br>
30274 llseek method, <a href="#171">171</a><br>
30275 memory usage (scull), <a href="#60">60</a>-<a href="#63">63</a><br>
30276 open method, <a href="#58">58</a>-<a href="#59">59</a></div>
30277 </td><td valign="top" width="50%">
30278 <div class="bql">poll method, <a href="#163">163</a>-<a href="#169">169</a><br>
30279 read method, <a href="#63">63</a>-<a href="#69">69</a><br>
30280 readv calls, <a href="#69">69</a><br>
30281 registration, <a href="#55">55</a>-<a href="#57">57</a><br>
30282 release method, <a href="#59">59</a><br>
30283 scull (design of), <a href="#42">42</a><br>
30284 select method, <a href="#163">163</a>-<a href="#169">169</a><br>
30285 testing, <a href="#70">70</a><br>
30286 version numbers, <a href="#43">43</a><br>
30287 write method, <a href="#63">63</a>-<a href="#69">69</a><br>
30288 writev calls, <a href="#69">69</a></div>
30289 char name field (net_device structure), <a href="#506">506</a><br>
30290 char *name variable (USB), <a href="#352">352</a><br>
30291 character drivers (see char drivers)<br>
30292 chars_in_buffer function, <a href="#558">558</a><br>
30293 check_flags method, <a href="#52">52</a><br>
30294 CHECKSUM_ symbols, <a href="#523">523</a><br>
30295 circular buffers, <a href="#123">123</a><br>
30296 <div class="bql">DMA ring buffers, <a href="#441">441</a><br>
30297 implementing interrupt handlers, <a href="#270">270</a><br>
30298 for printk function, <a href="#78">78</a></div>
30299 claim_dma_lock function, <a href="#457">457</a><br>
30300 class register (PCI), <a href="#309">309</a><br>
30301 classes<br>
30302 <div class="bql">devices, <a href="#5">5</a>, <a href="#362">362</a>, <a href="#390">390</a><br>
30303 functions, <a href="#410">410</a><br>
30304 interfaces, <a href="#391">391</a><br>
30305 Linux device model, <a href="#387">387</a>-<a href="#391">391</a><br>
30306 management, <a href="#389">389</a><br>
30307 modules, <a href="#5">5</a>-<a href="#8">8</a></div>
30308 class_id field, <a href="#390">390</a><br>
30309 class_simple interface, <a href="#388">388</a><br>
30310 class_simple_create function, <a href="#404">404</a><br>
30311 class_simple_device_add function, <a href="#404">404</a><br>
30312 class_simple_device_remove function, <a href="#405">405</a><br>
30313 cleanup function, <a href="#32">32</a><br>
30314 clear_bit operation, <a href="#126">126</a><br>
30315 clear_dma_ff function, <a href="#458">458</a><br>
30316 clearing bits on interface boards, <a href="#269">269</a><br>
30317 clock ticks (see jiffies, values)<br>
30318 clocks, <a href="#208">208</a><br>
30319 <div class="bql">cycles (counting), <a href="#186">186</a><br>
30320 (see also time)</div>
30321 cloning devices, <a href="#177">177</a><br>
30322 close function (tty drivers), <a href="#553">553</a>-<a href="#556">556</a><br>
30323 close method, <a href="#59">59</a><br>
30324 <div class="bql">vm_operations_struct structure, <a href="#421">421</a></div>
30325 cmd field (request structure), <a href="#492">492</a><br>
30326 coarse-grained locking, <a href="#122">122</a><br>
30327 code<br>
30328 <div class="bql">concurrency in, <a href="#20">20</a><br>
30329 delaying execution of, <a href="#196">196</a></div>
30330 </td></tr></table>
30331 <br>
30332 <A name="583"></a><font color="blue">PAGE 583</font><br>
30333 <br>
30334 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
30335 <div class="bql">execution, <a href="#190">190</a>-<a href="#196">196</a>, <a href="#209">209</a><br>
30336 hello world module, <a href="#16">16</a>-<a href="#18">18</a><br>
30337 inline assembly (example), <a href="#187">187</a><br>
30338 ISA, <a href="#321">321</a><br>
30339 kernels (see kernels)<br>
30340 memory (scull), <a href="#107">107</a><br>
30341 module requirements, <a href="#30">30</a><br>
30342 runtime, <a href="#5">5</a><br>
30343 scilluid, <a href="#175">175</a><br>
30344 sleeps, <a href="#158">158</a><br>
30345 test system setup, <a href="#15">15</a><br>
30346 user space programming, <a href="#19">19</a>, <a href="#37">37</a>-<a href="#39">39</a></div>
30347 coherency<br>
30348 <div class="bql">caches, <a href="#445">445</a><br>
30349 DMA, <a href="#446">446</a></div>
30350 command pre-preparation (block drivers), <a href="#491">491</a><br>
30351 command-oriented drivers, <a href="#146">146</a><br>
30352 commands<br>
30353 <div class="bql">dmesg, <a href="#77">77</a><br>
30354 FIOASYNC, <a href="#141">141</a><br>
30355 FIOCLEX, <a href="#141">141</a><br>
30356 FIONBIO, <a href="#141">141</a><br>
30357 FIONCLEX, <a href="#141">141</a><br>
30358 FIOQSIZE, <a href="#141">141</a><br>
30359 F_SETFL fcntl, <a href="#169">169</a><br>
30360 F_SETOWN, <a href="#169">169</a><br>
30361 gdb, <a href="#99">99</a><br>
30362 ifconfig<br>
30363 <div class="bql">net_device structure and, <a href="#506">506</a><br>
30364 opening network drivers, <a href="#515">515</a>-<a href="#516">516</a><br>
30365 snull interfaces, <a href="#501">501</a></div>
30366 ioctl, <a href="#137">137</a>, <a href="#140">140</a><br>
30367 <div class="bql">creating, <a href="#180">180</a><br>
30368 customizing for networking, <a href="#535">535</a><br>
30369 implementation, <a href="#145">145</a></div>
30370 printk (see printk function)<br>
30371 SIOCDEVPRIVATE, <a href="#535">535</a><br>
30372 strace, <a href="#91">91</a><br>
30373 wc, <a href="#92">92</a><br>
30374 (see also functions)</div>
30375 communication with user space, <a href="#362">362</a><br>
30376 compilers<br>
30377 <div class="bql">gcc, <a href="#188">188</a><br>
30378 optimizations, <a href="#236">236</a></div>
30379 compiling<br>
30380 <div class="bql">char drivers, <a href="#70">70</a><br>
30381 modules, <a href="#23">23</a>-<a href="#25">25</a></div>
30382 complete function (urbs), <a href="#345">345</a><br>
30383 complete module, <a href="#115">115</a><br>
30384 </td><td valign="top" width="50%">
30385 completion<br>
30386 <div class="bql">of DMA, <a href="#458">458</a><br>
30387 request functions, <a href="#486">486</a><br>
30388 semaphores, <a href="#114">114</a>-<a href="#116">116</a><br>
30389 urbs, <a href="#345">345</a></div>
30390 concurrency<br>
30391 <div class="bql">alternatives to locking, <a href="#123">123</a>-<a href="#130">130</a><br>
30392 controlling transmission, <a href="#518">518</a><br>
30393 debugging, <a href="#21">21</a><br>
30394 in kernel programming, <a href="#20">20</a><br>
30395 locking<br>
30396 <div class="bql">adding, <a href="#109">109</a><br>
30397 traps, <a href="#121">121</a>-<a href="#123">123</a></div>
30398 management, <a href="#107">107</a>-<a href="#109">109</a><br>
30399 scull (troubleshooting memory), <a href="#107">107</a><br>
30400 semaphores<br>
30401 <div class="bql">completion, <a href="#114">114</a>-<a href="#116">116</a><br>
30402 implementation, <a href="#110">110</a>-<a href="#114">114</a></div>
30403 spinlocks, <a href="#116">116</a>-<a href="#121">121</a><br>
30404 transmission, <a href="#518">518</a></div>
30405 CONFIG_ACPI_DEBUG option, <a href="#75">75</a><br>
30406 CONFIG_DEBUG_DRIVER option, <a href="#75">75</a><br>
30407 CONFIG_DEBUG_INFO option, <a href="#74">74</a><br>
30408 CONFIG_DEBUG_KERNEL option, <a href="#73">73</a><br>
30409 CONFIG_DEBUG_PAGEALLOC option, <a href="#74">74</a><br>
30410 CONFIG_DEBUG_SLAB option, <a href="#73">73</a><br>
30411 CONFIG_DEBUG_SPINLOCK option, <a href="#74">74</a><br>
30412 CONFIG_DEBUG_SPINLOCK_SLEEP option, <a href="#74">74</a><br>
30413 CONFIG_DEBUG_STACKOVERFLOW option, <a href="#74">74</a><br>
30414 CONFIG_DEBUG_STACK_USAGE option, <a href="#74">74</a><br>
30415 CONFIG_IKCONFIG option, <a href="#75">75</a><br>
30416 CONFIG_IKCONFIG_PROC option, <a href="#75">75</a><br>
30417 CONFIG_INIT_DEBUG option, <a href="#74">74</a><br>
30418 CONFIG_INPUT_EVBUG option, <a href="#75">75</a><br>
30419 CONFIG_KALLSYMS option, <a href="#74">74</a><br>
30420 CONFIG_MAGIC_SYSRQ option, <a href="#74">74</a><br>
30421 CONFIG_PROFILING option, <a href="#75">75</a><br>
30422 CONFIG_SCSI_CONSTANTS option, <a href="#75">75</a><br>
30423 configuration<br>
30424 <div class="bql">cdev structure, <a href="#56">56</a><br>
30425 char drivers, <a href="#45">45</a><br>
30426 <div class="bql">dynamic allocation of major numbers, <a href="#46">46</a><br>
30427 internal representation of device numbers, <a href="#44">44</a><br>
30428 major/minor numbers, <a href="#43">43</a><br>
30429 (see also char drivers)</div></div>
30430 </td></tr></table>
30431 <br>
30432 <A name="584"></a><font color="blue">PAGE 584</font><br>
30433 <br>
30434 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
30435 configuration <i>(continued)</i><br>
30436 <div class="bql">coherent DMA mappings, <a href="#446">446</a><br>
30437 critical sections, <a href="#109">109</a><br>
30438 DMA controllers, <a href="#456">456</a>-<a href="#459">459</a><br>
30439 drivers, <a href="#35">35</a>-<a href="#37">37</a><br>
30440 ether_setup function, <a href="#507">507</a>-<a href="#514">514</a><br>
30441 interrupt handlers, <a href="#259">259</a>-<a href="#269">269</a><br>
30442 kernels, <a href="#73">73</a>-<a href="#75">75</a><br>
30443 line settings (tty drivers), <a href="#560">560</a>-<a href="#566">566</a><br>
30444 multicasting, <a href="#539">539</a><br>
30445 net_device structure, <a href="#502">502</a><br>
30446 network devices, <a href="#512">512</a><br>
30447 parameter assignment, <a href="#35">35</a>-<a href="#37">37</a><br>
30448 PCI, <a href="#306">306</a><br>
30449 <div class="bql">accessing configuration space, <a href="#315">315</a><br>
30450 registers, <a href="#308">308</a></div>
30451 serial lines, <a href="#565">565</a><br>
30452 single-page streaming mappings, <a href="#450">450</a><br>
30453 snull drivers, <a href="#498">498</a>-<a href="#502">502</a><br>
30454 streaming DMA mappings, <a href="#448">448</a><br>
30455 test system setup, <a href="#15">15</a><br>
30456 timeouts, <a href="#193">193</a><br>
30457 USB interfaces, <a href="#332">332</a><br>
30458 version dependency, <a href="#26">26</a></div>
30459 CONFIG_USB_DYNAMIC_MINORS configuration option, <a href="#353">353</a><br>
30460 connections<br>
30461 <div class="bql">Firewire, <a href="#400">400</a><br>
30462 IP numbers, <a href="#500">500</a><br>
30463 network drivers to kernels, <a href="#502">502</a>-<a href="#514">514</a><br>
30464 PCI (see PCI)<br>
30465 /proc file hierarchies, <a href="#86">86</a><br>
30466 USB (see USB)<br>
30467 (see also hotplugs)</div>
30468 connectors (ISA), <a href="#323">323</a><br>
30469 console_loglevel variable, <a href="#77">77</a><br>
30470 <div class="bql">debugging system hangs, <a href="#97">97</a></div>
30471 consoles<br>
30472 <div class="bql">messages (redirecting), <a href="#77">77</a><br>
30473 wrong font on, <a href="#147">147</a></div>
30474 const char *dev_name functions, <a href="#260">260</a><br>
30475 const char *name field (PCI registration), <a href="#311">311</a><br>
30476 const char *name function, <a href="#348">348</a><br>
30477 const struct pci_device_id *id_table field (PCI registration), <a href="#311">311</a><br>
30478 const struct usb_device_id *id_table function, <a href="#348">348</a><br>
30479 constructor function (kmem_cache_create), <a href="#218">218</a><br>
30480 CONTROL endpoints (USB), <a href="#329">329</a><br>
30481 control functions (queues), <a href="#480">480</a><br>
30482 control urbs (USB), <a href="#343">343</a><br>
30483 </td><td valign="top" width="50%">
30484 controllers (PCI), <a href="#318">318</a><br>
30485 controlling<br>
30486 <div class="bql">transmission concurrency, <a href="#518">518</a><br>
30487 urbs (USB), <a href="#354">354</a><br>
30488 by writing control sequences, <a href="#146">146</a></div>
30489 conventional memory, I/O registers, <a href="#236">236</a><br>
30490 <div class="bql">(see also memory)</div>
30491 conversion (virtual addresses), <a href="#444">444</a><br>
30492 copying (cross-space), <a href="#64">64</a><br>
30493 core files, <a href="#99">99</a><br>
30494 counters<br>
30495 <div class="bql">jiffies, <a href="#184">184</a><br>
30496 reference (kobjects), <a href="#366">366</a><br>
30497 registers, <a href="#186">186</a><br>
30498 TSC, <a href="#186">186</a></div>
30499 counts (interrupts), <a href="#566">566</a><br>
30500 CPU modalities (levels), <a href="#20">20</a><br>
30501 create_module system call, <a href="#226">226</a><br>
30502 create_proc_read_entry function, <a href="#86">86</a><br>
30503 creating<br>
30504 <div class="bql">queues, <a href="#479">479</a><br>
30505 urbs (USB), <a href="#341">341</a></div>
30506 critical sections, <a href="#109">109</a><br>
30507 cross-space copying, <a href="#64">64</a><br>
30508 CRTSCTS bitmask, <a href="#561">561</a><br>
30509 CSIZE bitmask, <a href="#561">561</a><br>
30510 CSN (card select number), <a href="#321">321</a><br>
30511 CSTOPB bitmask, <a href="#561">561</a><br>
30512 current process, <a href="#21">21</a>, <a href="#40">40</a><br>
30513 current time, retrieving, <a href="#188">188</a>-<a href="#190">190</a><br>
30514 current.h header file, <a href="#21">21</a><br>
30515 currentime file (jit module), <a href="#189">189</a><br>
30516 custom<br>
30517 <div class="bql">data types, <a href="#291">291</a><br>
30518 ioctl methods for networking, <a href="#535">535</a></div>
30519 cycles_t type, <a href="#187">187</a><br>
30521 <br><a name="D"></a><font color="red"><b>D</b></font><br><br>
30523 daemons<br>
30524 <div class="bql">klogd, <a href="#17">17</a>, <a href="#77">77</a><br>
30525 syslogd, <a href="#79">79</a></div>
30526 data<br>
30527 <div class="bql">explicitly sizing, <a href="#290">290</a><br>
30528 physical packet transport, <a href="#501">501</a><br>
30529 transferring with DMA, <a href="#440">440</a>-<a href="#459">459</a><br>
30530 unaligned, portability and, <a href="#293">293</a></div>
30531 data attribute (firmware), <a href="#407">407</a><br>
30532 data functions (USB), <a href="#358">358</a><br>
30533 data structures, <a href="#49">49</a><br>
30534 <div class="bql">file operations, <a href="#49">49</a>-<a href="#53">53</a><br>
30535 portability of, <a href="#294">294</a></div>
30536 </td></tr></table>
30537 <br>
30538 <A name="585"></a><font color="blue">PAGE 585</font><br>
30539 <br>
30540 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
30541 data types<br>
30542 <div class="bql">for explicitly sizing data, <a href="#290">290</a><br>
30543 inptr_t (C99 standard), <a href="#289">289</a><br>
30544 int, <a href="#289">289</a><br>
30545 interface-specific, <a href="#291">291</a><br>
30546 loose typing for I/O functions, <a href="#292">292</a><br>
30547 mixing different, <a href="#289">289</a><br>
30548 portability and, <a href="#288">288</a>-<a href="#292">292</a><br>
30549 standard C types, <a href="#288">288</a><br>
30550 u8, u16, u32, u64, <a href="#290">290</a><br>
30551 uint8_t/unit32_t, <a href="#290">290</a></div>
30552 dataalign program, <a href="#294">294</a><br>
30553 datasize program, <a href="#288">288</a><br>
30554 dd utility and scull driver example, <a href="#61">61</a><br>
30555 deadline schedulers (I/O), <a href="#478">478</a><br>
30556 deadlocks, avoiding, <a href="#117">117</a><br>
30557 <div class="bql">(see also locking)</div>
30558 debugging, <a href="#73">73</a>-<a href="#105">105</a><br>
30559 <div class="bql">concurrency, <a href="#21">21</a><br>
30560 using a debugger, <a href="#99">99</a>-<a href="#105">105</a><br>
30561 using Dynamic Probes, <a href="#105">105</a><br>
30562 interrupt handlers, <a href="#273">273</a><br>
30563 with ioctl method, <a href="#90">90</a><br>
30564 using kdb kernel debugger, <a href="#101">101</a>-<a href="#103">103</a><br>
30565 kernels<br>
30566 <div class="bql">monitoring, <a href="#91">91</a><br>
30567 by printing, <a href="#75">75</a>-<a href="#82">82</a><br>
30568 by querying, <a href="#82">82</a>-<a href="#91">91</a><br>
30569 support, <a href="#73">73</a>-<a href="#75">75</a></div>
30570 using kgdb, <a href="#103">103</a><br>
30571 levels (implementation of), <a href="#81">81</a><br>
30572 using LTT, <a href="#105">105</a><br>
30573 locked keyboard, <a href="#97">97</a><br>
30574 by printing, <a href="#81">81</a><br>
30575 by querying, <a href="#91">91</a><br>
30576 system faults, <a href="#93">93</a>-<a href="#98">98</a><br>
30577 system hangs, <a href="#96">96</a><br>
30578 using User-Mode Linux, <a href="#104">104</a><br>
30579 (see also troubleshooting)</div>
30580 declaration of array parameters, <a href="#37">37</a><br>
30581 DECLARE_TASKLET macro, <a href="#276">276</a><br>
30582 default attributes (kobjects), <a href="#372">372</a><br>
30583 default_attrs field (kobjects), <a href="#372">372</a><br>
30584 DEFAULT_CONSOLE_LOGLEVEL, <a href="#77">77</a><br>
30585 DEFAULT_MESSAGE_LOGLEVEL, <a href="#77">77</a><br>
30586 delaying execution of code, <a href="#190">190</a>-<a href="#196">196</a>, <a href="#209">209</a><br>
30587 deleting<br>
30588 <div class="bql">attributes, <a href="#374">374</a>, <a href="#381">381</a><br>
30589 devices, <a href="#395">395</a><br>
30590 drivers, <a href="#396">396</a><br>
30591 mappings (DMA), <a href="#448">448</a><br>
30592 /proc files, <a href="#86">86</a></div>
30593 </td><td valign="top" width="50%">
30594 <div class="bql">queues, <a href="#479">479</a><br>
30595 symbolic links, <a href="#375">375</a></div>
30596 del_timer_sync function, <a href="#200">200</a><br>
30597 dentry field (file structure), <a href="#54">54</a><br>
30598 dependency<br>
30599 <div class="bql">platform, <a href="#27">27</a><br>
30600 version, <a href="#26">26</a></div>
30601 dereferencing memory addresses, <a href="#289">289</a><br>
30602 descriptors (USB), <a href="#358">358</a><br>
30603 design<br>
30604 <div class="bql">concurrency, <a href="#107">107</a>-<a href="#109">109</a><br>
30605 policy-free drivers, <a href="#3">3</a><br>
30606 of scull, <a href="#42">42</a><br>
30607 (see also configuration)</div>
30608 desktops<br>
30609 <div class="bql">PCI (see PCI)<br>
30610 USB (see USB)</div>
30611 destroying urbs (USB), <a href="#341">341</a><br>
30612 destructor function (kmem_cache_create), <a href="#218">218</a><br>
30613 /dev directory, <a href="#43">43</a><br>
30614 /dev nodes, <a href="#6">6</a><br>
30615 <div class="bql">char devices and, <a href="#43">43</a><br>
30616 dynamic major number allocation, <a href="#46">46</a><br>
30617 /dev/random device, <a href="#260">260</a><br>
30618 /dev/urandom device, <a href="#260">260</a></div>
30619 /dev tree, <a href="#403">403</a><br>
30620 dev_alloc_skb function, <a href="#530">530</a><br>
30621 development community (kernel), joining, <a href="#12">12</a><br>
30622 development kernels, <a href="#10">10</a><br>
30623 device attribute (firmware), <a href="#407">407</a><br>
30624 DEVICE variable, <a href="#402">402</a><br>
30625 deviceID register (PCI), <a href="#309">309</a><br>
30626 devices<br>
30627 <div class="bql">access to files, <a href="#173">173</a>-<a href="#179">179</a><br>
30628 adding, <a href="#392">392</a>-<a href="#395">395</a><br>
30629 allocation of numbers, <a href="#45">45</a><br>
30630 attributes, <a href="#383">383</a><br>
30631 block (see block drivers)<br>
30632 caching problems, <a href="#425">425</a><br>
30633 char drivers (see char drivers)<br>
30634 character (see char drivers)<br>
30635 classes of, <a href="#5">5</a>-<a href="#8">8</a>, <a href="#362">362</a>, <a href="#390">390</a><br>
30636 cloning, <a href="#177">177</a><br>
30637 concurrency, <a href="#107">107</a>-<a href="#109">109</a><br>
30638 control operations, <a href="#5">5</a><br>
30639 deleting, <a href="#395">395</a><br>
30640 DMA and, <a href="#440">440</a>-<a href="#459">459</a><br>
30641 drivers, <a href="#385">385</a><br>
30642 dynamic, <a href="#397">397</a><br>
30643 dynamic allocation of major numbers, <a href="#46">46</a></div>
30644 </td></tr></table>
30645 <br>
30646 <A name="586"></a><font color="blue">PAGE 586</font><br>
30647 <br>
30648 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
30649 devices <i>(continued)</i><br>
30650 <div class="bql">FIFO, <a href="#43">43</a><br>
30651 file operations on, <a href="#49">49</a><br>
30652 files, <a href="#43">43</a><br>
30653 functions, <a href="#409">409</a><br>
30654 hotpluggable, <a href="#362">362</a><br>
30655 identifying type with ls command, <a href="#43">43</a><br>
30656 initialization, <a href="#503">503</a><br>
30657 input (hotplugging), <a href="#401">401</a><br>
30658 internal representation of numbers, <a href="#44">44</a><br>
30659 ioctl method, <a href="#135">135</a>-<a href="#147">147</a><br>
30660 ISA, <a href="#320">320</a><br>
30661 iteration, <a href="#379">379</a><br>
30662 Linux device model, <a href="#362">362</a>-<a href="#364">364</a>, <a href="#381">381</a>-<a href="#387">387</a><br>
30663 <div class="bql">buses, <a href="#377">377</a>-<a href="#381">381</a><br>
30664 classes, <a href="#387">387</a>-<a href="#391">391</a><br>
30665 firmware, <a href="#405">405</a>-<a href="#407">407</a><br>
30666 hotplug events, <a href="#375">375</a><br>
30667 hotplugging, <a href="#397">397</a>-<a href="#405">405</a><br>
30668 kobjects, <a href="#364">364</a>-<a href="#371">371</a><br>
30669 lifecycles, <a href="#391">391</a>-<a href="#397">397</a><br>
30670 low-level sysfs operations, <a href="#371">371</a>-<a href="#375">375</a></div>
30671 methods, <a href="#511">511</a><br>
30672 names of, <a href="#46">46</a><br>
30673 network, <a href="#400">400</a><br>
30674 network drivers, <a href="#497">497</a><br>
30675 numbers (printing), <a href="#82">82</a><br>
30676 operations, <a href="#513">513</a><br>
30677 reading and writing, <a href="#63">63</a><br>
30678 reading data from, <a href="#166">166</a><br>
30679 registration, <a href="#382">382</a>, <a href="#502">502</a><br>
30680 SCSI, <a href="#402">402</a><br>
30681 scullpipe (example), <a href="#153">153</a>-<a href="#162">162</a><br>
30682 scullsingle, <a href="#174">174</a><br>
30683 seeking, <a href="#171">171</a><br>
30684 single-open, <a href="#173">173</a><br>
30685 structures (embedding), <a href="#383">383</a><br>
30686 truncating on open, <a href="#59">59</a><br>
30687 USB (see USB)<br>
30688 version (see versions, numbering)<br>
30689 writing<br>
30690 <div class="bql">control sequences to, <a href="#146">146</a><br>
30691 data to, <a href="#166">166</a></div>
30692 (see also drivers)</div>
30693 dev_id pointer (installing shared handlers), <a href="#278">278</a><br>
30694 dev_kfree_skb function, <a href="#524">524</a>, <a href="#531">531</a><br>
30695 dev_mc_list structure, <a href="#538">538</a><br>
30696 DEVPATH variable, <a href="#399">399</a><br>
30697 dev_t i_rdev (inode structure field), <a href="#55">55</a><br>
30698 </td><td valign="top" width="50%">
30699 direct I/O, <a href="#435">435</a>-<a href="#440">440</a><br>
30700 <div class="bql">implementation, <a href="#460">460</a><br>
30701 (see also I/O)</div>
30702 direct memory access (see DMA)<br>
30703 directories<br>
30704 <div class="bql">/dev, <a href="#43">43</a><br>
30705 entries (file structure), <a href="#54">54</a><br>
30706 of kernel headers, <a href="#19">19</a><br>
30707 misc-progs source, <a href="#77">77</a>, <a href="#162">162</a><br>
30708 /proc file hierarchy connections, <a href="#86">86</a><br>
30709 /proc/tty/driver, <a href="#547">547</a><br>
30710 sysfs<br>
30711 <div class="bql">low-level operations, <a href="#371">371</a>-<a href="#375">375</a><br>
30712 tty driver, <a href="#552">552</a><br>
30713 USB, <a href="#333">333</a>-<a href="#335">335</a></div>
30714 tty drivers, <a href="#566">566</a></div>
30715 *dir_notify method, <a href="#52">52</a><br>
30716 disable_dma function, <a href="#458">458</a><br>
30717 disable_irq function, <a href="#279">279</a><br>
30718 disabling<br>
30719 <div class="bql">interrupt handlers, <a href="#273">273</a><br>
30720 packet transmissions, <a href="#518">518</a><br>
30721 print statements, <a href="#79">79</a></div>
30722 disclosure of data, <a href="#9">9</a><br>
30723 disconnect function (USB), <a href="#349">349</a>, <a href="#353">353</a><br>
30724 disks<br>
30725 <div class="bql">files versus open files, <a href="#53">53</a><br>
30726 freeing, <a href="#468">468</a><br>
30727 registration, <a href="#466">466</a></div>
30728 distribution, writing drivers for, <a href="#28">28</a><br>
30729 DMA (direct memory access), <a href="#440">440</a>-<a href="#459">459</a>, <a href="#461">461</a><br>
30730 <div class="bql">block requests and, <a href="#489">489</a><br>
30731 configuring controller, <a href="#456">456</a>-<a href="#459">459</a><br>
30732 for ISA memory, <a href="#454">454</a>-<a href="#459">459</a><br>
30733 mappings (scatter-gather), <a href="#450">450</a><br>
30734 PCI devices and, <a href="#453">453</a><br>
30735 registering usage, <a href="#455">455</a><br>
30736 ring buffers, <a href="#441">441</a></div>
30737 dma_addr_t setup_dma field (USB), <a href="#338">338</a><br>
30738 dma_addr_t transfer_dma field (USB), <a href="#338">338</a><br>
30739 DMA_BIDIRECTIONAL symbol, <a href="#448">448</a>, <a href="#461">461</a><br>
30740 DMAC (DMA controller), <a href="#454">454</a><br>
30741 DMA-capable memory zone, <a href="#215">215</a><br>
30742 <div class="bql">SLAB_CACHE_DMA flag and, <a href="#218">218</a></div>
30743 dma_free_coherent function, <a href="#447">447</a><br>
30744 DMA_FROM_DEVICE symbol, <a href="#448">448</a>, <a href="#461">461</a><br>
30745 dma.h header file, <a href="#455">455</a><br>
30746 DMA_NONE symbol, <a href="#448">448</a>, <a href="#461">461</a><br>
30747 dma_spin_lock, <a href="#457">457</a><br>
30748 DMA_TO_DEVICE symbol, <a href="#448">448</a>, <a href="#461">461</a><br>
30749 </td></tr></table>
30750 <br>
30751 <A name="587"></a><font color="blue">PAGE 587</font><br>
30752 <br>
30753 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
30754 dmesg command, <a href="#77">77</a><br>
30755 do_close function, <a href="#556">556</a><br>
30756 do_gettimeofday function, <a href="#188">188</a><br>
30757 do_ioctl method, <a href="#513">513</a>, <a href="#535">535</a><br>
30758 do_IRQ function, <a href="#268">268</a><br>
30759 do-it-yourself probing, <a href="#266">266</a><br>
30760 double underscore (__) functions, <a href="#22">22</a><br>
30761 double-address cycle mappings (PCI), <a href="#452">452</a><br>
30762 doubly linked lists (portability), <a href="#299">299</a>, <a href="#300">300</a><br>
30763 down function, <a href="#111">111</a><br>
30764 DRIVER_ATTR macro, <a href="#386">386</a><br>
30765 drivers<br>
30766 <div class="bql">adding, <a href="#396">396</a><br>
30767 asynchronous notification and, <a href="#170">170</a><br>
30768 attributes, <a href="#386">386</a><br>
30769 block (see block drivers)<br>
30770 char (see char drivers)<br>
30771 command-oriented, <a href="#146">146</a><br>
30772 configuring, <a href="#35">35</a>-<a href="#37">37</a><br>
30773 deleting, <a href="#396">396</a><br>
30774 devices, <a href="#385">385</a><br>
30775 file operations, <a href="#49">49</a><br>
30776 FireWire, <a href="#7">7</a><br>
30777 functions, <a href="#409">409</a><br>
30778 I2O, <a href="#7">7</a><br>
30779 ioctl numbers for, <a href="#137">137</a><br>
30780 iteration, <a href="#379">379</a><br>
30781 lddbus, <a href="#379">379</a><br>
30782 mechanism, <a href="#42">42</a><br>
30783 <div class="bql">policy versus, <a href="#2">2</a><br>
30784 separation from policies, <a href="#2">2</a>-<a href="#4">4</a></div>
30785 modules, <a href="#7">7</a><br>
30786 monitoring with preprocessor, <a href="#79">79</a>-<a href="#81">81</a><br>
30787 network, <a href="#497">497</a><br>
30788 <div class="bql">connecting to kernels, <a href="#502">502</a>-<a href="#514">514</a><br>
30789 functions, <a href="#542">542</a>-<a href="#545">545</a><br>
30790 interrupt handlers for, <a href="#523">523</a><br>
30791 ioctl commands, <a href="#535">535</a><br>
30792 link state (changes in), <a href="#528">528</a><br>
30793 MAC addresses (resolution of), <a href="#532">532</a>-<a href="#534">534</a><br>
30794 multicasting, <a href="#537">537</a>-<a href="#540">540</a><br>
30795 opening, <a href="#515">515</a>-<a href="#516">516</a><br>
30796 snull, <a href="#498">498</a>-<a href="#502">502</a><br>
30797 statistics, <a href="#536">536</a></div>
30798 sbull<br>
30799 <div class="bql">initialization, <a href="#468">468</a><br>
30800 request method, <a href="#475">475</a></div>
30801 SCSI, <a href="#7">7</a><br>
30802 scull (see scull)<br>
30803 scullc (example), <a href="#219">219</a><br>
30804 scullp (example), <a href="#223">223</a><br>
30805 </td><td valign="top" width="50%">
30806 <div class="bql">scullv (example), <a href="#227">227</a>, <a href="#233">233</a><br>
30807 security issues, <a href="#8">8</a><br>
30808 short (example), <a href="#246">246</a><br>
30809 <div class="bql">accessing I/O memory, <a href="#252">252</a><br>
30810 implementing interrupt handlers, <a href="#270">270</a><br>
30811 installing interrupt handlers, <a href="#261">261</a><br>
30812 probing, <a href="#266">266</a></div>
30813 shortprint, <a href="#282">282</a>-<a href="#286">286</a><br>
30814 structures (embedding), <a href="#386">386</a><br>
30815 tty, <a href="#546">546</a>-<a href="#550">550</a><br>
30816 <div class="bql">buffers, <a href="#558">558</a><br>
30817 directories, <a href="#566">566</a><br>
30818 functions, <a href="#573">573</a><br>
30819 line settings, <a href="#560">560</a>-<a href="#566">566</a><br>
30820 pointers, <a href="#553">553</a>-<a href="#560">560</a><br>
30821 struct termios, <a href="#550">550</a>-<a href="#553">553</a><br>
30822 tty_driver structure, <a href="#567">567</a><br>
30823 tty_operations structure, <a href="#569">569</a><br>
30824 tty_struct structure, <a href="#571">571</a></div>
30825 USB (see USB)<br>
30826 user-space, <a href="#37">37</a><br>
30827 version (see versions, numbering)</div>
30828 driver_unregister function, <a href="#397">397</a><br>
30829 dynamic devices, <a href="#397">397</a><br>
30830 Dynamic Probes debugging tool, <a href="#105">105</a><br>
30832 <br><a name="E"></a><font color="red"><b>E</b></font><br><br>
30834 EBUSY error, <a href="#176">176</a><br>
30835 EISA (Extended ISA), <a href="#323">323</a><br>
30836 elevators (I/O), <a href="#478">478</a><br>
30837 elv_next_request function, <a href="#476">476</a>, <a href="#479">479</a>, <a href="#492">492</a><br>
30838 embedding<br>
30839 <div class="bql">device structures, <a href="#383">383</a><br>
30840 driver structures, <a href="#386">386</a><br>
30841 kobjects, <a href="#365">365</a></div>
30842 enable_dma function, <a href="#458">458</a><br>
30843 enable_irq function, <a href="#279">279</a><br>
30844 enabling<br>
30845 <div class="bql">configuration for kernels, <a href="#73">73</a>-<a href="#75">75</a><br>
30846 interrupt handlers, <a href="#273">273</a><br>
30847 PCI drivers, <a href="#314">314</a></div>
30848 endless loops, preventing, <a href="#97">97</a><br>
30849 end-of-file<br>
30850 <div class="bql">poll method and, <a href="#165">165</a><br>
30851 seeking relative to, <a href="#172">172</a></div>
30852 endpoints<br>
30853 <div class="bql">interfaces, <a href="#331">331</a><br>
30854 USB, <a href="#328">328</a></div>
30855 entropy pool and SA_SAMPLE_RANDOM flag, <a href="#260">260</a><br>
30856 errno.h header file, <a href="#33">33</a><br>
30857 error handling during initialization, <a href="#32">32</a><br>
30858 </td></tr></table>
30859 <br>
30860 <A name="588"></a><font color="blue">PAGE 588</font><br>
30861 <br>
30862 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
30863 errors<br>
30864 <div class="bql">buffer overrun, <a href="#95">95</a><br>
30865 codes, <a href="#33">33</a><br>
30866 handling at module initialization, <a href="#32">32</a>-<a href="#35">35</a><br>
30867 read/write, <a href="#65">65</a><br>
30868 values (pointers), <a href="#295">295</a><br>
30869 (see also troubleshooting)</div>
30870 /etc/networks file, <a href="#500">500</a><br>
30871 /etc/syslog.conf file, <a href="#79">79</a><br>
30872 ETH_ALEN macro, <a href="#515">515</a><br>
30873 Ethernet<br>
30874 <div class="bql">address resolution, <a href="#532">532</a><br>
30875 ARP and, <a href="#532">532</a><br>
30876 non-Ethernet headers, <a href="#534">534</a><br>
30877 non-Ethernet interfaces, <a href="#507">507</a><br>
30878 snull interfaces, <a href="#501">501</a></div>
30879 ether_setup function, <a href="#504">504</a>, <a href="#507">507</a>-<a href="#514">514</a><br>
30880 eth_header method, <a href="#512">512</a><br>
30881 Ethtool, <a href="#541">541</a><br>
30882 events<br>
30883 <div class="bql">hotplug, <a href="#375">375</a><br>
30884 race conditions, <a href="#107">107</a></div>
30885 exclusive waits, <a href="#159">159</a><br>
30886 execution<br>
30887 <div class="bql">asynchronous (interrupt mode), <a href="#197">197</a><br>
30888 of code (delaying), <a href="#190">190</a>-<a href="#196">196</a>, <a href="#209">209</a><br>
30889 modes, <a href="#20">20</a><br>
30890 shared interrupt handlers, <a href="#279">279</a><br>
30891 threads, <a href="#109">109</a></div>
30892 experimental kernels, <a href="#10">10</a><br>
30893 exporting symbols, <a href="#28">28</a>-<a href="#29">29</a><br>
30894 EXPORT_SYMBOL macro, <a href="#32">32</a>, <a href="#41">41</a><br>
30895 EXPORT_SYMBOL_GPL macro, <a href="#41">41</a><br>
30896 extended buses, <a href="#325">325</a><br>
30897 Extended ISA (EISA), <a href="#323">323</a><br>
30899 <br><a name="F"></a><font color="red"><b>F</b></font><br><br>
30901 fast interrupt handlers, <a href="#268">268</a><br>
30902 FASYNC flag, <a href="#52">52</a>, <a href="#169">169</a><br>
30903 fasync method, <a href="#52">52</a><br>
30904 fasync_helper function, <a href="#170">170</a>, <a href="#182">182</a><br>
30905 fasync_struct structure, <a href="#170">170</a><br>
30906 faults, <a href="#19">19</a>, <a href="#93">93</a>-<a href="#98">98</a><br>
30907 faulty module (oops messages), <a href="#94">94</a><br>
30908 faulty_read function, <a href="#96">96</a><br>
30909 faulty_write function, <a href="#96">96</a><br>
30910 fcntl system call, <a href="#141">141</a>, <a href="#169">169</a><br>
30911 fcntl.h header file, <a href="#151">151</a><br>
30912 fc_setup function, <a href="#507">507</a><br>
30913 fdatasync system call, <a href="#167">167</a><br>
30914 FDDI networks, configuring interfaces, <a href="#507">507</a><br>
30915 fddi_setup function, <a href="#507">507</a><br>
30916 </td><td valign="top" width="50%">
30917 f_dentry pointer, <a href="#54">54</a><br>
30918 f_flags field (file structure), <a href="#54">54</a><br>
30919 <div class="bql">O_NONBLOCK flag, <a href="#141">141</a>, <a href="#151">151</a></div>
30920 fiber channel devices, initializing, <a href="#507">507</a><br>
30921 FIFO (first-in-first-out) devices, <a href="#43">43</a><br>
30922 <div class="bql">poll method and, <a href="#165">165</a></div>
30923 File System header (fs.h), <a href="#71">71</a><br>
30924 file_operations structure, <a href="#49">49</a>, <a href="#54">54</a><br>
30925 <div class="bql">declaring using tagged initialization, <a href="#53">53</a><br>
30926 mmap method and, <a href="#424">424</a></div>
30927 files<br>
30928 <div class="bql">access to, <a href="#173">173</a>-<a href="#179">179</a><br>
30929 capability.h header file, <a href="#144">144</a>, <a href="#181">181</a><br>
30930 devices, <a href="#43">43</a><br>
30931 /etc/networks, <a href="#500">500</a><br>
30932 flags, <a href="#54">54</a><br>
30933 inode structure, <a href="#55">55</a><br>
30934 interrupts, <a href="#262">262</a><br>
30935 ioctl. header file, <a href="#179">179</a><br>
30936 kmsg, <a href="#78">78</a><br>
30937 ksyms, <a href="#32">32</a><br>
30938 modes, <a href="#53">53</a><br>
30939 net_int c, <a href="#507">507</a><br>
30940 open, <a href="#53">53</a><br>
30941 operations, <a href="#49">49</a>-<a href="#53">53</a><br>
30942 poll.h header file, <a href="#163">163</a>, <a href="#182">182</a><br>
30943 /proc, <a href="#84">84</a><br>
30944 stat, <a href="#263">263</a><br>
30945 structure, <a href="#53">53</a><br>
30946 structures, <a href="#49">49</a><br>
30947 uaccess.h header file, <a href="#180">180</a></div>
30948 filesystems, <a href="#4">4</a><br>
30949 <div class="bql">char drivers, <a href="#43">43</a>-<a href="#49">49</a><br>
30950 modules, <a href="#8">8</a><br>
30951 nodes, <a href="#4">4</a>, <a href="#7">7</a><br>
30952 /proc, <a href="#86">86</a>-<a href="#90">90</a><br>
30953 <div class="bql">installing interrupt handlers, <a href="#262">262</a><br>
30954 shared interrupts and, <a href="#280">280</a></div>
30955 sysfs, <a href="#409">409</a></div>
30956 filp pointer, <a href="#53">53</a><br>
30957 <div class="bql">in ioctl method, <a href="#136">136</a><br>
30958 in read/write methods, <a href="#63">63</a></div>
30959 filp->f_op, <a href="#54">54</a><br>
30960 filter hotplug operation, <a href="#376">376</a><br>
30961 fine-grained locking, <a href="#122">122</a><br>
30962 FIOASYNC command, <a href="#141">141</a><br>
30963 FIOCLEX command, <a href="#141">141</a><br>
30964 FIONBIO command, <a href="#141">141</a><br>
30965 FIONCLEX command, <a href="#141">141</a><br>
30966 FIOQSIZE command, <a href="#141">141</a><br>
30967 FireWire, <a href="#400">400</a><br>
30968 <div class="bql">drivers, <a href="#7">7</a></div>
30969 </td></tr></table>
30970 <br>
30971 <A name="589"></a><font color="blue">PAGE 589</font><br>
30972 <br>
30973 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
30974 firmware<br>
30975 <div class="bql">calling, <a href="#407">407</a><br>
30976 functions, <a href="#411">411</a><br>
30977 interfaces, <a href="#405">405</a><br>
30978 Linux device model, <a href="#405">405</a>-<a href="#407">407</a><br>
30979 PCI boot time configuration, <a href="#307">307</a></div>
30980 first-in-first-out (FIFO) devices (see FIFO devices)<br>
30981 flags<br>
30982 <div class="bql">argument, <a href="#213">213</a><br>
30983 FASYNC, <a href="#169">169</a><br>
30984 file, <a href="#54">54</a><br>
30985 GFP_ATOMIC, <a href="#214">214</a>, <a href="#222">222</a><br>
30986 GFP_COLD, <a href="#215">215</a><br>
30987 GFP_DMA, <a href="#215">215</a><br>
30988 GFP_HIGH, <a href="#215">215</a><br>
30989 GFP_HIGHMEM, <a href="#215">215</a><br>
30990 GFP_HIGHUSER, <a href="#214">214</a><br>
30991 GFP_KERNEL, <a href="#221">221</a><br>
30992 GFP_NOFAIL, <a href="#215">215</a><br>
30993 GFP_NOFS, <a href="#214">214</a><br>
30994 GFP_NOIO, <a href="#215">215</a><br>
30995 GFP_NORETRY, <a href="#215">215</a><br>
30996 GFP_NOWARN, <a href="#215">215</a><br>
30997 GFP_REPEAT, <a href="#215">215</a><br>
30998 GFP_USER, <a href="#214">214</a><br>
30999 GTP_KERNEL, <a href="#214">214</a><br>
31000 IFF_ALLMULTI, <a href="#509">509</a><br>
31001 IFF_AUTOMEDIA, <a href="#510">510</a><br>
31002 IFF_BROADCAST, <a href="#509">509</a><br>
31003 IFF_DEBUG, <a href="#509">509</a><br>
31004 IFF_DYNAMIC, <a href="#510">510</a><br>
31005 IFF_LOOPBACK, <a href="#509">509</a><br>
31006 IFF_MASTER, <a href="#510">510</a><br>
31007 IFF_MULTICAST, <a href="#509">509</a><br>
31008 IFF_NOARP, <a href="#504">504</a>, <a href="#509">509</a><br>
31009 IFF_NOTRAILERS, <a href="#510">510</a><br>
31010 IFF_POINTTOPOINT, <a href="#509">509</a><br>
31011 IFF_PORTSEL, <a href="#510">510</a><br>
31012 IFF_PROMISC, <a href="#509">509</a><br>
31013 IFF_RUNNING, <a href="#510">510</a><br>
31014 IFF_SLAVE, <a href="#510">510</a><br>
31015 IFF_UP, <a href="#509">509</a><br>
31016 media_change, <a href="#473">473</a><br>
31017 memory allocation, <a href="#215">215</a>, <a href="#218">218</a>, <a href="#231">231</a><br>
31018 for net_device structure, <a href="#509">509</a><br>
31019 O_NONBLOCK (f_flags field), <a href="#166">166</a><br>
31020 PACKET_HOST, <a href="#530">530</a><br>
31021 PG_locked, <a href="#417">417</a><br>
31022 POLLERR, <a href="#164">164</a><br>
31023 POLLHUP, <a href="#164">164</a><br>
31024 POLLIN, <a href="#164">164</a></div>
31025 </td><td valign="top" width="50%">
31026 <div class="bql">POLLOUT, <a href="#164">164</a><br>
31027 POLLPRI, <a href="#164">164</a><br>
31028 POLLRDBAND, <a href="#164">164</a><br>
31029 POLLRDNORM, <a href="#164">164</a><br>
31030 POLLWRBAND, <a href="#164">164</a><br>
31031 POLLWRNORM, <a href="#164">164</a><br>
31032 resource (PCI), <a href="#317">317</a><br>
31033 SA_INTERRUPT, <a href="#260">260</a>, <a href="#286">286</a><br>
31034 SA_SAMPLE_RANDOM, <a href="#260">260</a><br>
31035 SA_SHIRQ, <a href="#260">260</a>, <a href="#278">278</a><br>
31036 SLAB_CACHE_DMA, <a href="#218">218</a><br>
31037 SLAB_CTOR_CONSTRUCTOR, <a href="#218">218</a><br>
31038 SLAB_HWCACHE_ALIGN, <a href="#218">218</a><br>
31039 SLAB_NO_REAP, <a href="#218">218</a><br>
31040 TTY_DRIVER_NO_DEVFS, <a href="#553">553</a><br>
31041 TTY_DRIVER_REAL_RAW, <a href="#553">553</a><br>
31042 TTY_DRIVER_RESET_TERMIOS, <a href="#552">552</a><br>
31043 VM_IO, <a href="#421">421</a><br>
31044 Wall, <a href="#291">291</a></div>
31045 flips (tty drivers), <a href="#559">559</a><br>
31046 flow of data (tty drivers), <a href="#556">556</a><br>
31047 flush method, <a href="#51">51</a><br>
31048 <div class="bql">close system call and, <a href="#60">60</a></div>
31049 flush operation, <a href="#51">51</a><br>
31050 flushing pending output, <a href="#167">167</a><br>
31051 f_mode field (file structure), <a href="#53">53</a><br>
31052 fonts (incorrect on console), <a href="#147">147</a><br>
31053 f_op pointer, <a href="#54">54</a><br>
31054 fops pointers, <a href="#49">49</a><br>
31055 forms (BCD), <a href="#346">346</a><br>
31056 f_pos field (file structure), <a href="#54">54</a><br>
31057 <div class="bql">read_proc function and, <a href="#84">84</a></div>
31058 fragmentation, <a href="#442">442</a><br>
31059 free command, <a href="#70">70</a><br>
31060 free_dma function, <a href="#455">455</a><br>
31061 freeing<br>
31062 <div class="bql">buffers, <a href="#531">531</a><br>
31063 device numbers, <a href="#45">45</a><br>
31064 disks, <a href="#468">468</a><br>
31065 DMA pools, <a href="#447">447</a><br>
31066 semaphores, <a href="#111">111</a></div>
31067 free_irq function, <a href="#279">279</a><br>
31068 free_netdev functions, <a href="#505">505</a><br>
31069 free_pages function, <a href="#222">222</a><br>
31070 F_SETFL command, <a href="#141">141</a><br>
31071 <div class="bql">fcntl system call and, <a href="#169">169</a></div>
31072 F_SETFL fcntl command, <a href="#169">169</a><br>
31073 F_SETOWN command, <a href="#169">169</a><br>
31074 <div class="bql">fcntl system call and, <a href="#169">169</a></div>
31075 fs.h header file, <a href="#71">71</a>, <a href="#179">179</a><br>
31076 <div class="bql">asynchronous notification and, <a href="#170">170</a><br>
31077 blocking/nonblocking operations, <a href="#151">151</a></div>
31078 </td></tr></table>
31079 <br>
31080 <A name="590"></a><font color="blue">PAGE 590</font><br>
31081 <br>
31082 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
31083 fsync method, <a href="#51">51</a>, <a href="#167">167</a><br>
31084 full class interfaces, <a href="#389">389</a><br>
31085 functions<br>
31086 <div class="bql">access_ok, <a href="#142">142</a><br>
31087 alloc_netdev, <a href="#504">504</a><br>
31088 alloc_skb, <a href="#530">530</a><br>
31089 alloc_tty_driver, <a href="#549">549</a><br>
31090 blk_cleanup_queue, <a href="#479">479</a><br>
31091 blkdev_dequeue_request, <a href="#479">479</a><br>
31092 blk_queue_hardsect_size, <a href="#470">470</a><br>
31093 blk_queue_segment_boundary, <a href="#481">481</a><br>
31094 block drivers, <a href="#494">494</a>-<a href="#496">496</a><br>
31095 bus_add_driver, <a href="#396">396</a><br>
31096 buses, <a href="#409">409</a><br>
31097 bus_for_each_dev, <a href="#380">380</a><br>
31098 bus_register, <a href="#378">378</a><br>
31099 calling from modules/applications, <a href="#18">18</a><br>
31100 capable, <a href="#145">145</a>, <a href="#181">181</a><br>
31101 chars_in_buffer, <a href="#558">558</a><br>
31102 claim_dma_lock, <a href="#457">457</a><br>
31103 classes, <a href="#410">410</a><br>
31104 class_simple_create, <a href="#404">404</a><br>
31105 class_simple_device_add, <a href="#404">404</a><br>
31106 class_simple_device_remove, <a href="#405">405</a><br>
31107 cleanup, <a href="#32">32</a><br>
31108 clear_dma_ff, <a href="#458">458</a><br>
31109 close (tty drivers), <a href="#553">553</a>-<a href="#556">556</a><br>
31110 complete (urbs), <a href="#345">345</a><br>
31111 const char *dev_name, <a href="#260">260</a><br>
31112 const char *name, <a href="#348">348</a><br>
31113 const struct usb_device_id*id_table, <a href="#348">348</a><br>
31114 constructor (kmem_cache_create), <a href="#218">218</a><br>
31115 create_proc_read_entry, <a href="#86">86</a><br>
31116 del_timer_sync, <a href="#200">200</a><br>
31117 dev_alloc_skb, <a href="#530">530</a><br>
31118 devices, <a href="#409">409</a><br>
31119 dev_kfree_skb, <a href="#524">524</a>, <a href="#531">531</a><br>
31120 disable_dma, <a href="#458">458</a><br>
31121 disable_irq, <a href="#279">279</a><br>
31122 disconnect (USB), <a href="#349">349</a>, <a href="#353">353</a><br>
31123 dma_free_coherent, <a href="#447">447</a><br>
31124 do_close, <a href="#556">556</a><br>
31125 do_gettimeofday, <a href="#188">188</a><br>
31126 do_IRQ, <a href="#268">268</a><br>
31127 double underscore (__), <a href="#22">22</a><br>
31128 down, <a href="#111">111</a><br>
31129 drivers, <a href="#409">409</a><br>
31130 driver_unregister, <a href="#397">397</a><br>
31131 elv_next_request, <a href="#476">476</a>, <a href="#479">479</a>, <a href="#492">492</a><br>
31132 enable_dma, <a href="#458">458</a><br>
31133 enable_irq, <a href="#279">279</a></div>
31134 </td><td valign="top" width="50%">
31135 <div class="bql">ether_setup, <a href="#504">504</a>, <a href="#507">507</a>-<a href="#514">514</a><br>
31136 fasync_helper, <a href="#170">170</a>, <a href="#182">182</a><br>
31137 faulty_read, <a href="#96">96</a><br>
31138 faulty_write, <a href="#96">96</a><br>
31139 fc_setup, <a href="#507">507</a><br>
31140 fddi_setup, <a href="#507">507</a><br>
31141 firmware, <a href="#411">411</a><br>
31142 free_dma, <a href="#455">455</a><br>
31143 free_irq, <a href="#279">279</a><br>
31144 free_netdev, <a href="#505">505</a><br>
31145 free_pages, <a href="#222">222</a><br>
31146 get_cycles, <a href="#187">187</a><br>
31147 get_dma_residue, <a href="#458">458</a><br>
31148 get_fast_time, <a href="#189">189</a><br>
31149 get_free_page, <a href="#221">221</a><br>
31150 get_free_pages, <a href="#214">214</a>, <a href="#221">221</a>, <a href="#225">225</a><br>
31151 get_page, <a href="#427">427</a><br>
31152 get_unaligned, <a href="#293">293</a><br>
31153 get_user, <a href="#143">143</a>, <a href="#180">180</a><br>
31154 get_user_pages, <a href="#435">435</a><br>
31155 get_zeroed_page, <a href="#221">221</a><br>
31156 handle_IRQ_event, <a href="#269">269</a><br>
31157 hello world module, <a href="#16">16</a><br>
31158 hippi_setup, <a href="#508">508</a><br>
31159 in_atomic, <a href="#198">198</a><br>
31160 inb, <a href="#240">240</a><br>
31161 inb_p, <a href="#242">242</a><br>
31162 in_interrupt, <a href="#198">198</a><br>
31163 initialization, <a href="#31">31</a>-<a href="#35">35</a><br>
31164 inl, <a href="#240">240</a><br>
31165 insb, <a href="#242">242</a><br>
31166 inserting schedules, <a href="#97">97</a><br>
31167 insl, <a href="#242">242</a><br>
31168 insw, <a href="#242">242</a><br>
31169 int pci_enable_device, <a href="#314">314</a><br>
31170 int printk_ratelimit(void), <a href="#81">81</a><br>
31171 int seq_escape, <a href="#88">88</a><br>
31172 int seq_path, <a href="#89">89</a><br>
31173 int seq_printf, <a href="#88">88</a><br>
31174 int seq_putc, <a href="#88">88</a><br>
31175 int seq_puts, <a href="#88">88</a><br>
31176 int (USB), <a href="#348">348</a><br>
31177 inw, <a href="#240">240</a><br>
31178 ioctl (tty drivers), <a href="#564">564</a><br>
31179 ioremap, <a href="#226">226</a>, <a href="#249">249</a>, <a href="#256">256</a><br>
31180 ioremap_nocache, <a href="#250">250</a><br>
31181 iounmap, <a href="#225">225</a>, <a href="#250">250</a><br>
31182 irqreturn_t, <a href="#260">260</a><br>
31183 isa_readb, <a href="#254">254</a><br>
31184 kfree_skb, <a href="#531">531</a><br>
31185 kill_fasync, <a href="#170">170</a>, <a href="#182">182</a></div>
31186 </td></tr></table>
31187 <br>
31188 <A name="591"></a><font color="blue">PAGE 591</font><br>
31189 <br>
31190 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
31191 <div class="bql">kmalloc, <a href="#61">61</a><br>
31192 <div class="bql">allocation engine, <a href="#213">213</a>-<a href="#217">217</a><br>
31193 performance degradation issues, <a href="#222">222</a></div>
31194 kmap, <a href="#418">418</a><br>
31195 kmap_skb_frag, <a href="#532">532</a><br>
31196 kmem_cache_alloc, <a href="#218">218</a><br>
31197 kmem_cache_create, <a href="#217">217</a><br>
31198 kmem_cache_t type, <a href="#217">217</a><br>
31199 list_add, <a href="#297">297</a><br>
31200 list_add_tail, <a href="#297">297</a><br>
31201 list_del, <a href="#297">297</a><br>
31202 list_empty, <a href="#297">297</a><br>
31203 list_move, <a href="#297">297</a><br>
31204 list_splice, <a href="#297">297</a><br>
31205 locking, <a href="#121">121</a><br>
31206 match (buses), <a href="#379">379</a><br>
31207 mod_timer, <a href="#200">200</a>, <a href="#202">202</a><br>
31208 module_init, <a href="#31">31</a><br>
31209 netif_carrier_off, <a href="#528">528</a><br>
31210 netif_carrier_ok, <a href="#528">528</a><br>
31211 netif_carrier_on, <a href="#528">528</a><br>
31212 netif_start_queue, <a href="#515">515</a><br>
31213 netif_stop_queue, <a href="#516">516</a>, <a href="#518">518</a><br>
31214 netif_wake_queue, <a href="#518">518</a><br>
31215 network drivers, <a href="#542">542</a>-<a href="#545">545</a><br>
31216 open (tty drivers), <a href="#553">553</a>-<a href="#556">556</a><br>
31217 outb, <a href="#240">240</a><br>
31218 outb_p, <a href="#242">242</a><br>
31219 outl, <a href="#240">240</a><br>
31220 outsb, <a href="#242">242</a><br>
31221 outsl, <a href="#242">242</a><br>
31222 outsw, <a href="#242">242</a><br>
31223 outw, <a href="#240">240</a><br>
31224 page-oriented allocation, <a href="#221">221</a>, <a href="#233">233</a><br>
31225 pci_map-sg, <a href="#451">451</a><br>
31226 pci_remove_bus_device, <a href="#395">395</a><br>
31227 pci_resource_, <a href="#317">317</a><br>
31228 pfn_to_page, <a href="#417">417</a><br>
31229 poll_wait, <a href="#163">163</a>, <a href="#182">182</a><br>
31230 printk, <a href="#17">17</a>, <a href="#76">76</a>-<a href="#82">82</a><br>
31231 <div class="bql">circular buffers for, <a href="#78">78</a><br>
31232 logging messages from, <a href="#78">78</a><br>
31233 seq_file interface (avoiding in), <a href="#88">88</a><br>
31234 turning debug messages on/off, <a href="#79">79</a></div>
31235 probe (USB), <a href="#350">350</a><br>
31236 probe_irq_off, <a href="#265">265</a><br>
31237 probe_irq_on, <a href="#265">265</a><br>
31238 put_unaligned, <a href="#293">293</a><br>
31239 put_user, <a href="#143">143</a>, <a href="#180">180</a><br>
31240 queues, <a href="#479">479</a><br>
31241 rdtscl, <a href="#187">187</a><br>
31242 read (tty drivers), <a href="#558">558</a></div>
31243 </td><td valign="top" width="50%">
31244 <div class="bql">read_proc, <a href="#85">85</a><br>
31245 register_blkdev, <a href="#465">465</a><br>
31246 register_chrdev, <a href="#404">404</a><br>
31247 register_netdev, <a href="#503">503</a><br>
31248 relaease_dma_lock, <a href="#457">457</a><br>
31249 release (kobjects), <a href="#367">367</a><br>
31250 remap_pfn_range, <a href="#424">424</a><br>
31251 remove_proc_entry, <a href="#86">86</a><br>
31252 request (block drivers), <a href="#474">474</a>-<a href="#491">491</a><br>
31253 request_dma, <a href="#455">455</a><br>
31254 request_firmware, <a href="#406">406</a><br>
31255 SAK, <a href="#97">97</a><br>
31256 sbull_request, <a href="#469">469</a><br>
31257 schedule, <a href="#181">181</a><br>
31258 <div class="bql">execution of code (delaying), <a href="#193">193</a><br>
31259 preventing endless loops with, <a href="#97">97</a></div>
31260 schedule_timeout, <a href="#194">194</a><br>
31261 scull<br>
31262 <div class="bql">open method, <a href="#58">58</a>-<a href="#59">59</a><br>
31263 release method, <a href="#59">59</a></div>
31264 scull_cleanup, <a href="#179">179</a><br>
31265 scull_getwritespace, <a href="#158">158</a><br>
31266 semaphores (see semaphores)<br>
31267 set_dma_addr, <a href="#457">457</a><br>
31268 set_dma_count, <a href="#457">457</a><br>
31269 set_dma_mode, <a href="#457">457</a><br>
31270 set_mb, <a href="#238">238</a><br>
31271 set_multicast_list, <a href="#539">539</a><br>
31272 set_rmb, <a href="#238">238</a><br>
31273 set_termios, <a href="#560">560</a><br>
31274 set_wmb, <a href="#238">238</a><br>
31275 sg_dma_address, <a href="#462">462</a><br>
31276 sg_dma_len, <a href="#462">462</a><br>
31277 show, <a href="#386">386</a><br>
31278 skb_headlen, <a href="#532">532</a><br>
31279 skb_headroom, <a href="#531">531</a><br>
31280 skb_is_nonlinear, <a href="#532">532</a><br>
31281 skb_pull, <a href="#532">532</a><br>
31282 skb_push, <a href="#531">531</a><br>
31283 skb_put, <a href="#531">531</a><br>
31284 skb_reserve, <a href="#531">531</a><br>
31285 skb_tailroom, <a href="#531">531</a><br>
31286 sleep_on, <a href="#162">162</a><br>
31287 acting on socket buffers, <a href="#530">530</a><br>
31288 spinlocks, <a href="#119">119</a><br>
31289 struct module *owner, <a href="#348">348</a><br>
31290 sysfs filesystem, <a href="#409">409</a><br>
31291 sys_syslog, <a href="#77">77</a><br>
31292 tasklet_schedule, <a href="#276">276</a><br>
31293 tiny_close, <a href="#556">556</a><br>
31294 tiocmget, <a href="#562">562</a><br>
31295 tiomset, <a href="#562">562</a></div>
31296 </td></tr></table>
31297 <br>
31298 <A name="592"></a><font color="blue">PAGE 592</font><br>
31299 <br>
31300 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
31301 functions <i>(continued)</i><br>
31302 <div class="bql">tr_configure, <a href="#508">508</a><br>
31303 tty drivers, <a href="#573">573</a><br>
31304 tty_driver (pointers), <a href="#553">553</a>-<a href="#560">560</a><br>
31305 tty_get_baud_rate, <a href="#562">562</a><br>
31306 tty_register_driver, <a href="#549">549</a><br>
31307 unregister_netdev, <a href="#505">505</a><br>
31308 unsigned int irq, <a href="#260">260</a><br>
31309 unsigned long flags, <a href="#260">260</a><br>
31310 unsigned long pci_resource_end, <a href="#317">317</a><br>
31311 unsigned long pci_resource_start, <a href="#317">317</a><br>
31312 unsigned pci_resource_flags, <a href="#317">317</a><br>
31313 up, <a href="#111">111</a><br>
31314 urbs_completion, <a href="#345">345</a><br>
31315 usb_alloc_urb, <a href="#342">342</a><br>
31316 usb_bulk_msg, <a href="#356">356</a><br>
31317 usb_control_msg, <a href="#357">357</a><br>
31318 usb_fill_bulk_urb, <a href="#343">343</a><br>
31319 usb_fill_control_urb, <a href="#343">343</a><br>
31320 usb_fill_int_urb, <a href="#342">342</a><br>
31321 usb_get_descriptor, <a href="#358">358</a><br>
31322 usb_kill_urb, <a href="#345">345</a><br>
31323 usb_register_dev, <a href="#352">352</a><br>
31324 usb_set_intfdata, <a href="#351">351</a><br>
31325 usb_string, <a href="#359">359</a><br>
31326 usb_submit_urb, <a href="#344">344</a><br>
31327 usb_unlink_urb, <a href="#345">345</a><br>
31328 vfree, <a href="#225">225</a><br>
31329 virt_to_page, <a href="#417">417</a><br>
31330 vmalloc allocation, <a href="#224">224</a>-<a href="#228">228</a><br>
31331 void, <a href="#348">348</a><br>
31332 void barrier, <a href="#237">237</a><br>
31333 void blk_queue_bounce_limit, <a href="#480">480</a><br>
31334 void blk_queue_dma_alignment, <a href="#481">481</a><br>
31335 void blk_queue_hardsect_size, <a href="#481">481</a><br>
31336 void blk_queue_max_hw_segments, <a href="#480">480</a><br>
31337 void blk_queue_max_phys_segments, <a href="#480">480</a><br>
31338 void blk_queue_max_sectors, <a href="#480">480</a><br>
31339 void blk_queue_max_segment_size, <a href="#480">480</a><br>
31340 void blk_start_queue, <a href="#480">480</a><br>
31341 void blk_stop_queue, <a href="#480">480</a><br>
31342 void mb, <a href="#237">237</a><br>
31343 void read_barrier_depends, <a href="#237">237</a><br>
31344 void rmb, <a href="#237">237</a><br>
31345 void smp_mb, <a href="#238">238</a><br>
31346 void smp_rmb, <a href="#238">238</a><br>
31347 void smp_wmb, <a href="#238">238</a><br>
31348 void tasklet_disable, <a href="#204">204</a><br>
31349 void tasklet_disable_nosync, <a href="#204">204</a><br>
31350 void tasklet_enable, <a href="#204">204</a><br>
31351 void tasklet_hi_schedule, <a href="#204">204</a></div>
31352 </td><td valign="top" width="50%">
31353 <div class="bql">void tasklet_kill, <a href="#204">204</a><br>
31354 void tasklet_schedule, <a href="#204">204</a><br>
31355 void wmb, <a href="#237">237</a><br>
31356 void*dev_id, <a href="#260">260</a><br>
31357 wait_event_interruptible_timeout, <a href="#194">194</a><br>
31358 wake-up, <a href="#150">150</a>, <a href="#181">181</a><br>
31359 wake_up, <a href="#159">159</a>, <a href="#181">181</a><br>
31360 wake_up_interruptible, <a href="#181">181</a><br>
31361 wake_up_interruptible_sync, <a href="#181">181</a><br>
31362 wake_up_sync, <a href="#181">181</a><br>
31363 workqueues, <a href="#206">206</a><br>
31364 write (tty drivers), <a href="#556">556</a><br>
31365 xmit_lock, <a href="#514">514</a></div>
31367 <br><a name="G"></a><font color="red"><b>G</b></font><br><br>
31369 gcc compiler, <a href="#188">188</a><br>
31370 gdb commands, <a href="#99">99</a>, <a href="#103">103</a><br>
31371 gendisk structure, <a href="#467">467</a><br>
31372 general distribution, writing drivers for, <a href="#28">28</a><br>
31373 General Public License (GPL), <a href="#11">11</a><br>
31374 generic DMA layers, <a href="#444">444</a><br>
31375 generic I/O address spaces, <a href="#316">316</a><br>
31376 geographical addressing, <a href="#305">305</a><br>
31377 get_cycles function, <a href="#187">187</a><br>
31378 get_dma_residue function, <a href="#458">458</a><br>
31379 get_fast_time function, <a href="#189">189</a><br>
31380 get_free_page function, <a href="#221">221</a><br>
31381 get_free_pages function, <a href="#214">214</a>, <a href="#221">221</a>, <a href="#225">225</a><br>
31382 get_kernel_syms system call, <a href="#25">25</a><br>
31383 get_page function, <a href="#427">427</a><br>
31384 get_stats method, <a href="#512">512</a>, <a href="#536">536</a><br>
31385 get_unaligned function, <a href="#293">293</a><br>
31386 get_user function, <a href="#143">143</a>, <a href="#180">180</a><br>
31387 get_user_pages function, <a href="#435">435</a><br>
31388 get_zeroed_page function, <a href="#221">221</a><br>
31389 GFP_ATOMIC flag, <a href="#214">214</a><br>
31390 <div class="bql">page-oriented allocation functions, <a href="#221">221</a><br>
31391 preparing for allocation failure, <a href="#222">222</a></div>
31392 GFP_COLD flag, <a href="#215">215</a><br>
31393 GFP_DMA flag, <a href="#215">215</a><br>
31394 gfp.h header file, <a href="#214">214</a><br>
31395 GFP_HIGH flag, <a href="#215">215</a><br>
31396 GFP_HIGHMEM flag, <a href="#215">215</a><br>
31397 GFP_HIGHUSER flag, <a href="#214">214</a><br>
31398 GFP_KERNEL flag, <a href="#214">214</a>, <a href="#221">221</a><br>
31399 GFP_NOFAIL flag, <a href="#215">215</a><br>
31400 GFP_NOFS flag, <a href="#214">214</a><br>
31401 GFP_NOIO flag, <a href="#215">215</a><br>
31402 GFP_NORETRY flag, <a href="#215">215</a><br>
31403 GFP_NOWARN flag, <a href="#215">215</a><br>
31404 GFP_REPEAT flag, <a href="#215">215</a><br>
31405 GFP_USER flag, <a href="#214">214</a><br>
31406 </td></tr></table>
31407 <br>
31408 <A name="593"></a><font color="blue">PAGE 593</font><br>
31409 <br>
31410 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
31411 global information (net_device structure), <a href="#506">506</a><br>
31412 global memory areas, <a href="#43">43</a><br>
31413 global messages (enabling/disabling), <a href="#79">79</a><br>
31414 GNU General Public License (GPL), <a href="#11">11</a><br>
31415 goto statement, <a href="#33">33</a><br>
31416 GPL (GNU General Public License), <a href="#11">11</a><br>
31418 <br><a name="I"></a><font color="red"><b>I</b></font><br><br>
31420 hacking kernels options, <a href="#73">73</a>-<a href="#75">75</a><br>
31421 handle_IRQ_event function, <a href="#269">269</a><br>
31422 hangs (system), <a href="#96">96</a>-<a href="#98">98</a><br>
31423 hard_header method, <a href="#512">512</a>, <a href="#532">532</a><br>
31424 hard_start_transmit method, <a href="#516">516</a><br>
31425 hard_start_xmit method, <a href="#512">512</a>, <a href="#517">517</a><br>
31426 hardware<br>
31427 <div class="bql">addresses, <a href="#508">508</a><br>
31428 <div class="bql">assignment of, <a href="#515">515</a><br>
31429 modification of, <a href="#513">513</a></div>
31430 DMA, <a href="#440">440</a>, <a href="#444">444</a><br>
31431 headers, <a href="#533">533</a><br>
31432 <div class="bql">adding before transmitting packets, <a href="#531">531</a><br>
31433 building, <a href="#512">512</a><br>
31434 encapsulating information, <a href="#534">534</a></div>
31435 ioctl method, <a href="#135">135</a>-<a href="#147">147</a><br>
31436 ISA, <a href="#320">320</a><br>
31437 management, <a href="#235">235</a>-<a href="#254">254</a>, <a href="#255">255</a><br>
31438 net_device structure, <a href="#506">506</a><br>
31439 PCI (abstractions), <a href="#318">318</a><br>
31440 removable media (supporting), <a href="#472">472</a></div>
31441 header_cache method, <a href="#513">513</a><br>
31442 header_cache_update method, <a href="#514">514</a><br>
31443 headers<br>
31444 <div class="bql">Ethernet (see Ethernet)<br>
31445 files, <a href="#19">19</a>, <a href="#29">29</a><br>
31446 hardware, <a href="#533">533</a><br>
31447 non-Ethernet, <a href="#534">534</a></div>
31448 hello world module, <a href="#16">16</a>-<a href="#18">18</a><br>
31449 hierarchies<br>
31450 <div class="bql">kobjects, <a href="#368">368</a><br>
31451 ksets, <a href="#370">370</a><br>
31452 /proc file connections, <a href="#86">86</a><br>
31453 (see also filesystems)</div>
31454 high memory, <a href="#216">216</a>, <a href="#415">415</a><br>
31455 HIPPI drivers, preparing fields for, <a href="#508">508</a><br>
31456 hippi_setup function, <a href="#508">508</a><br>
31457 hostnames (snull interfaces), <a href="#500">500</a><br>
31458 hotplugs<br>
31459 <div class="bql">devices, <a href="#362">362</a><br>
31460 events, <a href="#375">375</a></div>
31461 </td><td valign="top" width="50%">
31462 <div class="bql">Linux device model, <a href="#397">397</a>-<a href="#405">405</a><br>
31463 scripts, <a href="#403">403</a></div>
31464 hubs (USB), <a href="#334">334</a><br>
31465 hung system, <a href="#96">96</a><br>
31466 hyperthreaded processors, avoiding deadlocks, <a href="#117">117</a><br>
31467 HZ (time frequency) symbol, <a href="#183">183</a>, <a href="#292">292</a><br>
31468 group, device, <a href="#47">47</a><br>
31469 <br><a name="H"></a><font color="red"><b>H</b></font><br><br>
31470 I2O drivers, <a href="#7">7</a><br>
31471 IA-64 architecture<br>
31472 <div class="bql">porting and, <a href="#243">243</a><br>
31473 /proc/interrupts file, snapshot of, <a href="#263">263</a></div>
31474 IEEE1394 bus (Firewire), <a href="#400">400</a><br>
31475 ifconfig command<br>
31476 <div class="bql">net_device structure and, <a href="#506">506</a><br>
31477 opening network drivers, <a href="#515">515</a>-<a href="#516">516</a><br>
31478 snull interfaces, <a href="#501">501</a></div>
31479 IFF_ symbols, <a href="#509">509</a>, <a href="#538">538</a><br>
31480 IFF_ALLMULTI flag, <a href="#509">509</a><br>
31481 IFF_AUTOMEDIA flag, <a href="#510">510</a><br>
31482 IFF_BROADCAST flag, <a href="#509">509</a><br>
31483 IFF_DEBUG flag, <a href="#509">509</a><br>
31484 IFF_DYNAMIC flag, <a href="#510">510</a><br>
31485 IFF_LOOPBACK flag, <a href="#509">509</a><br>
31486 IFF_MASTER flag, <a href="#510">510</a><br>
31487 IFF_MULTICAST flag, <a href="#509">509</a><br>
31488 IFF_NOARP flag, <a href="#504">504</a>, <a href="#509">509</a><br>
31489 IFF_NOTRAILERS flag, <a href="#510">510</a><br>
31490 IFF_POINTOPOINT flag, <a href="#509">509</a><br>
31491 IFF_PORTSEL flag, <a href="#510">510</a><br>
31492 IFF_PROMISC flag, <a href="#509">509</a><br>
31493 IFF_RUNNING flag, <a href="#510">510</a><br>
31494 IFF_SLAVE flag, <a href="#510">510</a><br>
31495 IFF_UP flag, <a href="#509">509</a><br>
31496 if.h header file, <a href="#509">509</a>, <a href="#535">535</a><br>
31497 ifreq structure, <a href="#535">535</a><br>
31498 implementation<br>
31499 <div class="bql">asynchronous I/O, <a href="#437">437</a><br>
31500 busy-waiting, <a href="#190">190</a><br>
31501 of classes, <a href="#5">5</a><br>
31502 of debugging levels, <a href="#81">81</a><br>
31503 direct I/O, <a href="#460">460</a><br>
31504 of files in /proc filesystems, <a href="#84">84</a><br>
31505 interrupt handlers, <a href="#269">269</a>-<a href="#275">275</a><br>
31506 ioctl commands, <a href="#145">145</a><br>
31507 ISA (PCI), <a href="#319">319</a>-<a href="#322">322</a><br>
31508 llseek method, <a href="#171">171</a><br>
31509 mmap, <a href="#412">412</a>-<a href="#416">416</a>, <a href="#460">460</a><br>
31510 multicasting, <a href="#539">539</a><br>
31511 of policies, <a href="#3">3</a><br>
31512 removable media (supporting), <a href="#472">472</a></div>
31513 </td></tr></table>
31514 <br>
31515 <A name="594"></a><font color="blue">PAGE 594</font><br>
31516 <br>
31517 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
31518 implementation <i>(continued)</i><br>
31519 <div class="bql">semaphores, <a href="#110">110</a>-<a href="#114">114</a><br>
31520 timers, <a href="#201">201</a></div>
31521 in_atomic function, <a href="#198">198</a><br>
31522 inb function, <a href="#240">240</a><br>
31523 inb_p function, <a href="#242">242</a><br>
31524 infinite loops, preventing, <a href="#97">97</a><br>
31525 information leakage, <a href="#9">9</a><br>
31526 in_interrupt function, <a href="#198">198</a><br>
31527 init scripts and loading/unloading modules, <a href="#48">48</a><br>
31528 init.h header file, <a href="#39">39</a><br>
31529 initialization<br>
31530 <div class="bql">completions (semaphores), <a href="#115">115</a><br>
31531 devices, <a href="#503">503</a><br>
31532 gendisk structure, <a href="#468">468</a><br>
31533 interrupt handlers, <a href="#261">261</a><br>
31534 kobjects, <a href="#366">366</a><br>
31535 modules, <a href="#31">31</a>-<a href="#35">35</a><br>
31536 mutexes, <a href="#110">110</a><br>
31537 net_device structure, <a href="#503">503</a><br>
31538 PCI, <a href="#306">306</a><br>
31539 reader/writer semaphores, <a href="#113">113</a><br>
31540 registers (PCI), <a href="#308">308</a><br>
31541 sbull drivers, <a href="#468">468</a><br>
31542 seqlocks, <a href="#128">128</a><br>
31543 struct usb_driver structure, <a href="#349">349</a><br>
31544 structures (registration), <a href="#55">55</a>-<a href="#57">57</a></div>
31545 INIT_LIST_HEAD macro, <a href="#296">296</a><br>
31546 inl function, <a href="#240">240</a><br>
31547 inline assembly code (example), <a href="#187">187</a><br>
31548 inode pointer in ioctl method, <a href="#136">136</a><br>
31549 inode structure, <a href="#55">55</a><br>
31550 input devices (hotplugging), <a href="#401">401</a><br>
31551 input files, enabling asynchronous notification from, <a href="#169">169</a><br>
31552 input module, <a href="#28">28</a><br>
31553 input pins, <a href="#235">235</a>, <a href="#245">245</a><br>
31554 <div class="bql">reading values from parallel port, <a href="#248">248</a></div>
31555 insb function, <a href="#242">242</a><br>
31556 insl function, <a href="#242">242</a><br>
31557 insmod program, <a href="#5">5</a>, <a href="#17">17</a>, <a href="#25">25</a><br>
31558 <div class="bql">assigning parameter values, <a href="#36">36</a><br>
31559 dynamically allocating major numbers, <a href="#48">48</a><br>
31560 modprobe program versus, <a href="#29">29</a><br>
31561 testing modules using, <a href="#17">17</a></div>
31562 installation<br>
31563 <div class="bql">interrupt handlers, <a href="#259">259</a>-<a href="#269">269</a>, <a href="#278">278</a><br>
31564 mainline kernels, <a href="#15">15</a></div>
31565 insw function, <a href="#242">242</a><br>
31566 </td><td valign="top" width="50%">
31567 int actual_length field (USB), <a href="#339">339</a><br>
31568 int data type, <a href="#289">289</a><br>
31569 int error_count field (USB), <a href="#341">341</a><br>
31570 int field<br>
31571 <div class="bql">net_device structure, <a href="#506">506</a><br>
31572 PCI registration, <a href="#312">312</a></div>
31573 int flags field (gendisk), <a href="#467">467</a><br>
31574 int function (USB), <a href="#348">348</a><br>
31575 int interval field (USB), <a href="#341">341</a><br>
31576 int major field (gendisk), <a href="#467">467</a><br>
31577 int minor field (USB), <a href="#332">332</a><br>
31578 int minor_base variable (USB), <a href="#353">353</a><br>
31579 int minors field (gendisk), <a href="#467">467</a><br>
31580 int number_of_packets field (USB), <a href="#341">341</a><br>
31581 int pci_enable_device function, <a href="#314">314</a><br>
31582 int printk_ratelimit(void) function, <a href="#81">81</a><br>
31583 int seq_escape function, <a href="#88">88</a><br>
31584 int seq_path function, <a href="#89">89</a><br>
31585 int seq_printf function, <a href="#88">88</a><br>
31586 int seq_putc function, <a href="#88">88</a><br>
31587 int seq_puts function, <a href="#88">88</a><br>
31588 int start_frame field (USB), <a href="#341">341</a><br>
31589 int status field (USB), <a href="#339">339</a><br>
31590 int transfer_buffer_length field (USB), <a href="#338">338</a><br>
31591 interactive kernel debugger (kdb), <a href="#101">101</a>-<a href="#103">103</a><br>
31592 INTERFACE variable, <a href="#401">401</a><br>
31593 interfaces<br>
31594 <div class="bql">alloc_pages, <a href="#223">223</a><br>
31595 block drivers<br>
31596 <div class="bql">command pre-preparation, <a href="#491">491</a><br>
31597 functions, <a href="#494">494</a>-<a href="#496">496</a><br>
31598 operations, <a href="#471">471</a>-<a href="#474">474</a><br>
31599 registration, <a href="#465">465</a>-<a href="#470">470</a><br>
31600 request processing, <a href="#474">474</a>-<a href="#491">491</a><br>
31601 TCQ, <a href="#492">492</a>-<a href="#493">493</a></div>
31602 classes, <a href="#391">391</a><br>
31603 class_simple, <a href="#388">388</a><br>
31604 cleanup function, <a href="#32">32</a><br>
31605 configuration (USB), <a href="#332">332</a><br>
31606 firmware, <a href="#405">405</a><br>
31607 flags for net_device structure, <a href="#509">509</a><br>
31608 full class, <a href="#389">389</a><br>
31609 interface-specific data types, <a href="#291">291</a><br>
31610 ksets, <a href="#370">370</a><br>
31611 loopback, <a href="#498">498</a><br>
31612 MII, <a href="#540">540</a><br>
31613 networks, <a href="#7">7</a><br>
31614 non-Ethernet, <a href="#507">507</a><br>
31615 older<br>
31616 <div class="bql">char device registration, <a href="#57">57</a><br>
31617 /proc file implementation, <a href="#85">85</a></div></div>
31618 </td></tr></table>
31619 <br>
31620 <A name="595"></a><font color="blue">PAGE 595</font><br>
31621 <br>
31622 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
31623 <div class="bql">parallel ports (see parallel ports)<br>
31624 PCI, <a href="#302">302</a>-<a href="#319">319</a><br>
31625 reader/writer semaphores, <a href="#114">114</a><br>
31626 seq_file, <a href="#87">87</a>-<a href="#90">90</a><br>
31627 snull, <a href="#498">498</a>-<a href="#502">502</a><br>
31628 spinlocks, <a href="#117">117</a><br>
31629 timers, <a href="#198">198</a><br>
31630 USB, <a href="#331">331</a><br>
31631 version dependency, <a href="#26">26</a><br>
31632 VLB, <a href="#323">323</a></div>
31633 interface-specific data types, <a href="#291">291</a><br>
31634 internal functions (locking), <a href="#121">121</a><br>
31635 internal representation of device numbers, <a href="#44">44</a><br>
31636 Internet protocol (IP), <a href="#498">498</a><br>
31637 interrupt handlers<br>
31638 <div class="bql">autodetecting IRQ numbers, <a href="#264">264</a><br>
31639 sharing interrupts, <a href="#281">281</a></div>
31640 interrupt mode<br>
31641 <div class="bql">and asynchronous execution, <a href="#197">197</a><br>
31642 tasklets, <a href="#202">202</a>-<a href="#204">204</a></div>
31643 interrupt request lines (see IRQs)<br>
31644 interruptible sleeps, <a href="#157">157</a><br>
31645 interrupts<br>
31646 <div class="bql">counts, <a href="#566">566</a><br>
31647 file, <a href="#262">262</a><br>
31648 handlers<br>
31649 <div class="bql">implementation of, <a href="#269">269</a>-<a href="#275">275</a><br>
31650 installation of, <a href="#259">259</a>-<a href="#269">269</a><br>
31651 I/O, <a href="#281">281</a>-<a href="#286">286</a><br>
31652 management, <a href="#286">286</a><br>
31653 for network drivers, <a href="#523">523</a><br>
31654 preparing parallel ports, <a href="#259">259</a><br>
31655 /proc files for, <a href="#262">262</a><br>
31656 registration, <a href="#286">286</a><br>
31657 sharing, <a href="#278">278</a>-<a href="#281">281</a><br>
31658 tasklets, <a href="#276">276</a><br>
31659 top and bottom halves, <a href="#275">275</a>-<a href="#278">278</a></div>
31660 installation at, <a href="#261">261</a><br>
31661 mitigation of, <a href="#525">525</a><br>
31662 for network drivers, <a href="#523">523</a><br>
31663 PCI, <a href="#317">317</a><br>
31664 reports, <a href="#261">261</a><br>
31665 shared interrupts and, <a href="#280">280</a><br>
31666 timers, <a href="#183">183</a><br>
31667 tty drivers, <a href="#556">556</a><br>
31668 urbs, <a href="#342">342</a></div>
31669 intervals of time (data type portability), <a href="#292">292</a><br>
31670 intptr_t type (C99 standard), <a href="#289">289</a><br>
31671 inw function, <a href="#240">240</a><br>
31672 </td><td valign="top" width="50%">
31673 I/O, <a href="#167">167</a><br>
31674 <div class="bql">asynchronous, <a href="#437">437</a>-<a href="#440">440</a><br>
31675 blocking, <a href="#147">147</a>-<a href="#162">162</a><br>
31676 direct, <a href="#435">435</a>-<a href="#440">440</a>, <a href="#460">460</a><br>
31677 flushing pending, <a href="#167">167</a><br>
31678 generic address spaces, <a href="#316">316</a><br>
31679 hardware management, <a href="#235">235</a>-<a href="#254">254</a><br>
31680 interrupt handlers, <a href="#281">281</a>-<a href="#286">286</a><br>
31681 mapping, <a href="#249">249</a>, <a href="#255">255</a><br>
31682 memory (access), <a href="#249">249</a><br>
31683 pausing, <a href="#242">242</a><br>
31684 PCI, <a href="#305">305</a>, <a href="#316">316</a><br>
31685 regions, <a href="#429">429</a><br>
31686 registers, <a href="#236">236</a><br>
31687 scatter/gather, <a href="#520">520</a><br>
31688 schedulers, <a href="#478">478</a><br>
31689 string operations, <a href="#241">241</a><br>
31690 transferring data with DMA, <a href="#440">440</a>-<a href="#459">459</a></div>
31691 I/O Memory Management Unit (see IOMMU)<br>
31692 I/O ports, parallel (see parallel ports)<br>
31693 I/O registers versus RAM, <a href="#236">236</a><br>
31694 _IOC_DIRBITS macro, <a href="#180">180</a><br>
31695 _IOC_NRBITS macro, <a href="#180">180</a><br>
31696 _IOC_SIZEBITS macro, <a href="#180">180</a><br>
31697 _IOC_TYPEBITS macro, <a href="#180">180</a><br>
31698 ioctl commands (creating), <a href="#180">180</a><br>
31699 ioctl function (tty drivers), <a href="#564">564</a><br>
31700 ioctl method, <a href="#51">51</a>, <a href="#135">135</a>-<a href="#147">147</a><br>
31701 <div class="bql">using bitfields to define commands, <a href="#137">137</a><br>
31702 block drivers, <a href="#473">473</a><br>
31703 controlling devices without, <a href="#146">146</a><br>
31704 customizing for networking, <a href="#535">535</a><br>
31705 debugging with, <a href="#90">90</a><br>
31706 network devices and, <a href="#513">513</a><br>
31707 TIOCLINUX command, <a href="#77">77</a></div>
31708 ioctl.h header file, <a href="#137">137</a>, <a href="#179">179</a><br>
31709 <div class="bql">setting up command numbers, <a href="#138">138</a></div>
31710 ioctl-number.txt file, <a href="#137">137</a><br>
31711 IOMMU (I/O memory management unit), <a href="#413">413</a>, <a href="#445">445</a><br>
31712 ioremap function, <a href="#226">226</a>, <a href="#249">249</a>, <a href="#256">256</a><br>
31713 ioremap, <a href="#225">225</a><br>
31714 ioremap_nocache function, <a href="#250">250</a><br>
31715 iounmap function, <a href="#225">225</a>, <a href="#250">250</a><br>
31716 IP (Internet protocol), <a href="#498">498</a><br>
31717 IP numbers, resolving to physical addresses, <a href="#532">532</a><br>
31718 ip_summed field (sk_buff), <a href="#522">522</a>, <a href="#530">530</a><br>
31719 irq argument (interrupt number), <a href="#260">260</a><br>
31720 </td></tr></table>
31721 <br>
31722 <A name="596"></a><font color="blue">PAGE 596</font><br>
31723 <br>
31724 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
31725 irq.h header file, <a href="#267">267</a><br>
31726 irqreturn_t function, <a href="#260">260</a><br>
31727 IRQs (interrupt request lines)<br>
31728 <div class="bql">autodetecting, <a href="#264">264</a><br>
31729 statistics on, <a href="#263">263</a></div>
31730 ISA<br>
31731 <div class="bql">bus master DMA, <a href="#454">454</a><br>
31732 devices, DMA for, <a href="#454">454</a>-<a href="#459">459</a><br>
31733 I/O (pausing devices), <a href="#242">242</a><br>
31734 memory (access), <a href="#253">253</a><br>
31735 <div class="bql">below IMB, <a href="#252">252</a>-<a href="#254">254</a><br>
31736 DMA for, <a href="#454">454</a>-<a href="#459">459</a></div>
31737 PCI, <a href="#319">319</a>-<a href="#322">322</a></div>
31738 isa_readb function, <a href="#254">254</a><br>
31739 ISOCHRONOUS endpoints (USB), <a href="#330">330</a><br>
31740 isochronous urbs (USB), <a href="#344">344</a><br>
31741 iteration of buses, <a href="#379">379</a><br>
31743 <br><a name="J"></a><font color="red"><b>J</b></font><br><br>
31745 jiffies<br>
31746 <div class="bql">in busy-waiting implementation, <a href="#191">191</a><br>
31747 counters, <a href="#184">184</a><br>
31748 no solution for short delays, <a href="#195">195</a><br>
31749 values, <a href="#184">184</a>, <a href="#514">514</a></div>
31750 jit (just in time) module<br>
31751 <div class="bql">current time (retrieving), <a href="#189">189</a><br>
31752 delaying code execution, <a href="#191">191</a></div>
31753 jitbusy program, <a href="#191">191</a><br>
31754 joysticks (hotplugging), <a href="#401">401</a><br>
31755 just in time (jit) module (see jit module)<br>
31757 <br><a name="K"></a><font color="red"><b>K</b></font><br><br>
31759 kcore file, <a href="#99">99</a><br>
31760 kdataalign program, <a href="#294">294</a><br>
31761 kdatasize module, <a href="#289">289</a><br>
31762 kdb kernel debugger, <a href="#101">101</a>-<a href="#103">103</a><br>
31763 KERN_ALERT macro, <a href="#76">76</a><br>
31764 KERN_CRIT macro, <a href="#76">76</a><br>
31765 KERN_DEBUG macro, <a href="#76">76</a><br>
31766 kernel-assisted probing, <a href="#265">265</a><br>
31767 kernels<br>
31768 <div class="bql">applications (comparisons to), <a href="#18">18</a>-<a href="#22">22</a><br>
31769 capabilities and restricted operations, <a href="#144">144</a><br>
31770 code requirements, <a href="#30">30</a><br>
31771 concurrency, <a href="#20">20</a><br>
31772 <div class="bql">adding locking, <a href="#109">109</a><br>
31773 alternatives to locking, <a href="#123">123</a>-<a href="#130">130</a><br>
31774 locking traps, <a href="#121">121</a>-<a href="#123">123</a><br>
31775 management of, <a href="#107">107</a>-<a href="#109">109</a><br>
31776 semaphore completion, <a href="#114">114</a>-<a href="#116">116</a><br>
31777 semaphore implementation, <a href="#110">110</a>-<a href="#114">114</a></div></div>
31778 </td><td valign="top" width="50%">
31779 <div class="bql">current process and, <a href="#21">21</a><br>
31780 data structures, <a href="#49">49</a><br>
31781 data types in<br>
31782 <div class="bql">assigning explicit sizes to, <a href="#290">290</a><br>
31783 interface-specific, <a href="#291">291</a><br>
31784 linked lists, <a href="#295">295</a>-<a href="#299">299</a><br>
31785 portability, <a href="#292">292</a>-<a href="#295">295</a><br>
31786 standard C types, <a href="#288">288</a></div>
31787 debuggers, <a href="#99">99</a>-<a href="#105">105</a><br>
31788 development community, joining, <a href="#12">12</a><br>
31789 developmental (experimental), <a href="#10">10</a><br>
31790 exclusive waits, <a href="#160">160</a><br>
31791 filesystem modules, <a href="#8">8</a><br>
31792 handling system faults (see system faults)<br>
31793 headers, <a href="#19">19</a><br>
31794 inode structure, <a href="#55">55</a><br>
31795 interrupts<br>
31796 <div class="bql">implementing handlers, <a href="#269">269</a>-<a href="#275">275</a><br>
31797 installing handlers, <a href="#259">259</a>-<a href="#269">269</a></div>
31798 introduction to, <a href="#1">1</a><br>
31799 kgdb patch and, <a href="#103">103</a><br>
31800 linked lists, <a href="#295">295</a>-<a href="#299">299</a><br>
31801 Linux device model, <a href="#362">362</a>-<a href="#364">364</a><br>
31802 <div class="bql">buses, <a href="#377">377</a>-<a href="#381">381</a><br>
31803 classes, <a href="#387">387</a>-<a href="#391">391</a><br>
31804 devices, <a href="#381">381</a>-<a href="#387">387</a><br>
31805 firmware, <a href="#405">405</a>-<a href="#407">407</a><br>
31806 hotplugging, <a href="#375">375</a>, <a href="#397">397</a>-<a href="#405">405</a><br>
31807 kobjects, <a href="#364">364</a>-<a href="#371">371</a><br>
31808 lifecycles, <a href="#391">391</a>-<a href="#397">397</a><br>
31809 low-level sysfs operations, <a href="#371">371</a>-<a href="#375">375</a></div>
31810 loading modules into (see loading, modules)<br>
31811 logical addresses, <a href="#413">413</a><br>
31812 mainline (installation of), <a href="#15">15</a><br>
31813 messages, <a href="#18">18</a><br>
31814 modules<br>
31815 <div class="bql">loading, <a href="#25">25</a>-<a href="#28">28</a><br>
31816 unloading, <a href="#25">25</a></div>
31817 monitoring, <a href="#91">91</a><br>
31818 multicasting support, <a href="#538">538</a><br>
31819 network driver connections, <a href="#502">502</a>-<a href="#514">514</a><br>
31820 platform dependency, <a href="#27">27</a><br>
31821 printing, <a href="#75">75</a>-<a href="#82">82</a><br>
31822 querying, <a href="#82">82</a>-<a href="#91">91</a><br>
31823 security, <a href="#8">8</a><br>
31824 sources, <a href="#575">575</a><br>
31825 space, <a href="#19">19</a><br>
31826 splitting role of, <a href="#4">4</a>-<a href="#5">5</a><br>
31827 support, <a href="#73">73</a>-<a href="#75">75</a><br>
31828 symbols, <a href="#28">28</a>-<a href="#29">29</a><br>
31829 system hangs, <a href="#96">96</a></div>
31830 </td></tr></table>
31831 <br>
31832 <A name="597"></a><font color="blue">PAGE 597</font><br>
31833 <br>
31834 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
31835 <div class="bql">tasklets, <a href="#202">202</a>-<a href="#204">204</a>, <a href="#211">211</a><br>
31836 test system setup, <a href="#15">15</a><br>
31837 time, <a href="#208">208</a><br>
31838 <div class="bql">measurement of lapses, <a href="#183">183</a>-<a href="#188">188</a><br>
31839 retrieving current time, <a href="#188">188</a>-<a href="#190">190</a></div>
31840 timers, <a href="#196">196</a>-<a href="#202">202</a>, <a href="#210">210</a><br>
31841 USB<br>
31842 <div class="bql">sysfs directory trees, <a href="#333">333</a>-<a href="#335">335</a><br>
31843 transfers without urbs, <a href="#356">356</a>-<a href="#359">359</a><br>
31844 urbs, <a href="#335">335</a>-<a href="#346">346</a><br>
31845 writing, <a href="#346">346</a>-<a href="#355">355</a></div>
31846 versions<br>
31847 <div class="bql">dependency, <a href="#26">26</a><br>
31848 numbering, <a href="#10">10</a>-<a href="#11">11</a></div>
31849 viewing, <a href="#5">5</a><br>
31850 virtual addresses, <a href="#414">414</a>, <a href="#434">434</a><br>
31851 VMAs, <a href="#419">419</a>-<a href="#422">422</a><br>
31852 workqueues, <a href="#205">205</a>-<a href="#208">208</a>, <a href="#211">211</a><br>
31853 (see also modules)</div>
31854 kernel_ulong_t driver_info field (USB), <a href="#347">347</a><br>
31855 KERNEL_VERSION macro, <a href="#27">27</a><br>
31856 KERN_EMERG macro, <a href="#76">76</a><br>
31857 KERN_ERR macro, <a href="#76">76</a><br>
31858 KERN_INFO macro, <a href="#76">76</a><br>
31859 KERN_NOTICE macro, <a href="#76">76</a><br>
31860 KERN_WARNING macro, <a href="#76">76</a><br>
31861 keyboards<br>
31862 <div class="bql">debugging when locked, <a href="#97">97</a><br>
31863 hotplugging, <a href="#401">401</a></div>
31864 keys (magic SysRq), <a href="#97">97</a><br>
31865 kfree, <a href="#61">61</a><br>
31866 kfree_skb function, <a href="#531">531</a><br>
31867 kgdb patch, <a href="#103">103</a><br>
31868 kill_fasync function, <a href="#170">170</a>, <a href="#182">182</a><br>
31869 killing urbs, <a href="#345">345</a><br>
31870 klogd daemon, <a href="#17">17</a>, <a href="#77">77</a><br>
31871 <div class="bql">logging messages, <a href="#78">78</a>, <a href="#79">79</a></div>
31872 kmalloc<br>
31873 <div class="bql">flags argument, <a href="#213">213</a><br>
31874 returning virtual addresses, <a href="#225">225</a><br>
31875 versus vmalloc, <a href="#225">225</a></div>
31876 kmalloc function, <a href="#61">61</a><br>
31877 <div class="bql">allocation engine, <a href="#213">213</a>-<a href="#217">217</a><br>
31878 performance degradation issues, <a href="#222">222</a></div>
31879 kmap function, <a href="#418">418</a><br>
31880 kmap_skb_frag function, <a href="#532">532</a><br>
31881 kmem_cache_alloc function, <a href="#218">218</a><br>
31882 kmem_cache_create function, <a href="#217">217</a><br>
31883 kmem_cache_t type function, <a href="#217">217</a><br>
31884 kmsg file, <a href="#78">78</a><br>
31885 </td><td valign="top" width="50%">
31886 kobjects, <a href="#364">364</a>-<a href="#371">371</a><br>
31887 <div class="bql">hotplug event generation, <a href="#375">375</a><br>
31888 low-level sysfs operations, <a href="#371">371</a>-<a href="#375">375</a><br>
31889 nondefault attributes, <a href="#373">373</a><br>
31890 release functions, <a href="#367">367</a><br>
31891 store method, <a href="#373">373</a><br>
31892 symbolic links, <a href="#375">375</a></div>
31893 kset_hotplug_ops structure, <a href="#376">376</a><br>
31894 ksets, <a href="#368">368</a><br>
31895 <div class="bql">operations on, <a href="#370">370</a><br>
31896 subsystems, <a href="#370">370</a></div>
31897 ksyms file, <a href="#32">32</a><br>
31899 <br><a name="L"></a><font color="red"><b>L</b></font><br><br>
31901 lapses of time, measurement of, <a href="#183">183</a>-<a href="#188">188</a><br>
31902 laptop docking stations, <a href="#402">402</a><br>
31903 large buffers, obtaining, <a href="#230">230</a>, <a href="#234">234</a><br>
31904 large file implementations (/proc files), <a href="#87">87</a><br>
31905 layers<br>
31906 <div class="bql">generic DMA, <a href="#444">444</a><br>
31907 modularization, <a href="#28">28</a></div>
31908 lddbus driver, <a href="#379">379</a><br>
31909 ldd_driver structure, <a href="#386">386</a><br>
31910 LEDs, soldering to output pins, <a href="#247">247</a><br>
31911 levels<br>
31912 <div class="bql">CPU (modalities), <a href="#20">20</a><br>
31913 debugging, <a href="#81">81</a><br>
31914 message priority (see loglevels)</div>
31915 libraries, <a href="#19">19</a><br>
31916 license terms, <a href="#11">11</a><br>
31917 lifecycles<br>
31918 <div class="bql">Linux device model, <a href="#391">391</a>-<a href="#397">397</a><br>
31919 objects, <a href="#363">363</a><br>
31920 urbs, <a href="#335">335</a></div>
31921 limitations of debug messages (prink function), <a href="#81">81</a><br>
31922 line settings (tty drivers), <a href="#560">560</a>-<a href="#566">566</a><br>
31923 line status register (LSR), <a href="#564">564</a><br>
31924 link state (changes in), <a href="#528">528</a><br>
31925 linked lists, <a href="#295">295</a>-<a href="#299">299</a><br>
31926 <div class="bql">traversal of, <a href="#298">298</a></div>
31927 linking libraries, <a href="#18">18</a><br>
31928 links (symbolic), <a href="#375">375</a><br>
31929 Linux<br>
31930 <div class="bql">license terms, <a href="#11">11</a><br>
31931 version numbering, <a href="#10">10</a></div>
31932 Linux device model, <a href="#362">362</a>-<a href="#364">364</a><br>
31933 <div class="bql">buses, <a href="#377">377</a>-<a href="#381">381</a><br>
31934 classes, <a href="#387">387</a>-<a href="#391">391</a><br>
31935 devices, <a href="#381">381</a>-<a href="#387">387</a></div>
31936 </td></tr></table>
31937 <br>
31938 <A name="598"></a><font color="blue">PAGE 598</font><br>
31939 <br>
31940 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
31941 Linux device model <i>(continued)</i><br>
31942 <div class="bql">firmware, <a href="#405">405</a>-<a href="#407">407</a><br>
31943 hotplugging, <a href="#397">397</a>-<a href="#405">405</a><br>
31944 kobjects, <a href="#364">364</a>-<a href="#371">371</a><br>
31945 <div class="bql">hotplug events, <a href="#375">375</a><br>
31946 low-level sysfs operations, <a href="#371">371</a>-<a href="#375">375</a></div>
31947 lifecycles, <a href="#391">391</a>-<a href="#397">397</a></div>
31948 Linux Documentation Project web site, <a href="#576">576</a><br>
31949 Linux Trace Toolkit (LTT), <a href="#105">105</a><br>
31950 linux-kernel mailing list, <a href="#12">12</a>, <a href="#299">299</a><br>
31951 LINUX_VERSION_CODE macro, <a href="#27">27</a>, <a href="#40">40</a><br>
31952 list_add function, <a href="#297">297</a><br>
31953 list_add_tail function, <a href="#297">297</a><br>
31954 list_del function, <a href="#297">297</a><br>
31955 list_empty function, <a href="#297">297</a><br>
31956 list_entry macro, <a href="#297">297</a><br>
31957 list_for_each macro, <a href="#299">299</a><br>
31958 list.h header file, <a href="#299">299</a><br>
31959 list_head data structure, <a href="#299">299</a><br>
31960 list_move function, <a href="#297">297</a><br>
31961 lists, linked, <a href="#295">295</a>-<a href="#299">299</a><br>
31962 lists (PCI), <a href="#326">326</a><br>
31963 list_splice function, <a href="#297">297</a><br>
31964 little-endian byte order, <a href="#293">293</a><br>
31965 llseek method, <a href="#50">50</a>, <a href="#171">171</a><br>
31966 loadable modules, <a href="#5">5</a><br>
31967 loading<br>
31968 <div class="bql">attribute (firmware), <a href="#407">407</a><br>
31969 drivers, <a href="#46">46</a><br>
31970 modules, <a href="#25">25</a>-<a href="#28">28</a><br>
31971 <div class="bql">dynamically assigned device numbers, <a href="#47">47</a><br>
31972 parameters, <a href="#35">35</a>-<a href="#37">37</a><br>
31973 races, <a href="#35">35</a></div></div>
31974 local0 (IP number), <a href="#499">499</a><br>
31975 LocalTalk devices, setting up fields for, <a href="#507">507</a><br>
31976 lock method, <a href="#52">52</a><br>
31977 locked keyboard (debugging), <a href="#97">97</a><br>
31978 lock-free algorithms, <a href="#123">123</a><br>
31979 locking, <a href="#108">108</a><br>
31980 <div class="bql">adding, <a href="#109">109</a><br>
31981 alternatives to, <a href="#123">123</a>-<a href="#130">130</a><br>
31982 atomic variables, <a href="#124">124</a><br>
31983 rules for, <a href="#122">122</a><br>
31984 seqlocks, <a href="#127">127</a><br>
31985 traps, <a href="#121">121</a>-<a href="#123">123</a></div>
31986 lockmeter tool, <a href="#123">123</a><br>
31987 loff_t f_pos (struct file field), <a href="#54">54</a><br>
31988 loff_t (long offset), <a href="#50">50</a>, <a href="#54">54</a><br>
31989 LOG_BUF_LEN circular buffer, <a href="#78">78</a><br>
31990 logging messages (printk function), <a href="#78">78</a><br>
31991 logical addresses, <a href="#413">413</a><br>
31992 </td><td valign="top" width="50%">
31993 logical units (USB), <a href="#332">332</a><br>
31994 login process, <a href="#173">173</a><br>
31995 loglevels, <a href="#76">76</a><br>
31996 <div class="bql">message priorities, <a href="#17">17</a></div>
31997 long data type, <a href="#289">289</a><br>
31998 long delays (of code execution), <a href="#190">190</a><br>
31999 lookaside caches, <a href="#217">217</a>-<a href="#224">224</a>, <a href="#232">232</a><br>
32000 loopback interfaces, <a href="#498">498</a><br>
32001 loops<br>
32002 <div class="bql">busy, <a href="#191">191</a><br>
32003 endless, <a href="#97">97</a><br>
32004 software, <a href="#195">195</a></div>
32005 loops_per_jiffy value, <a href="#196">196</a><br>
32006 low memory, <a href="#415">415</a><br>
32007 low-level sysfs operations, <a href="#371">371</a>-<a href="#375">375</a><br>
32008 ls command, identifying device type, <a href="#43">43</a><br>
32009 LSR (line status register), <a href="#564">564</a><br>
32010 ltalk_setup, <a href="#507">507</a><br>
32011 ltalk_setup function, <a href="#507">507</a><br>
32012 LTT (Linux Trace Toolkit), <a href="#105">105</a><br>
32014 <br><a name="M"></a><font color="red"><b>M</b></font><br><br>
32016 M68k architecture (porting and), <a href="#243">243</a><br>
32017 MAC (medium access control) addresses, <a href="#504">504</a>, <a href="#508">508</a><br>
32018 <div class="bql">resolution of, <a href="#532">532</a>-<a href="#534">534</a><br>
32019 set_mac_address method and, <a href="#513">513</a></div>
32020 macros<br>
32021 <div class="bql">BUS_ATTR, <a href="#380">380</a><br>
32022 completion, <a href="#115">115</a><br>
32023 DECLARE_TASKLET, <a href="#276">276</a><br>
32024 DIVER_ATTR, <a href="#386">386</a><br>
32025 hello world module, <a href="#16">16</a><br>
32026 INIT_LIST_HEAD, <a href="#296">296</a><br>
32027 internal representation of device<br>
32028 numbers, <a href="#44">44</a><br>
32029 ioctl commands (creating), <a href="#180">180</a><br>
32030 KERN_ALERT, <a href="#76">76</a><br>
32031 KERN_CRIT, <a href="#76">76</a><br>
32032 KERN_DEBUG, <a href="#76">76</a><br>
32033 KERN_EMERG, <a href="#76">76</a><br>
32034 KERN_ERR, <a href="#76">76</a><br>
32035 KERN_INFO, <a href="#76">76</a><br>
32036 KERN_NOTICE, <a href="#76">76</a><br>
32037 KERN_WARNING, <a href="#76">76</a><br>
32038 list_entry, <a href="#297">297</a><br>
32039 list_for_each, <a href="#299">299</a><br>
32040 MINOR, <a href="#71">71</a><br>
32041 MODULE_DEVICE_TABLE, <a href="#311">311</a><br>
32042 page_address, <a href="#417">417</a><br>
32043 PAGE_SHIFT, <a href="#415">415</a><br>
32044 PCI_DEVICE, <a href="#310">310</a></div>
32045 </td></tr></table>
32046 <br>
32047 <A name="599"></a><font color="blue">PAGE 599</font><br>
32048 <br>
32049 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
32050 <div class="bql">PCI_DEVICE_CLASS, <a href="#310">310</a><br>
32051 RELEVANT_IFLAG, <a href="#560">560</a><br>
32052 sg_dma_address, <a href="#451">451</a><br>
32053 sg_dma_len, <a href="#451">451</a><br>
32054 symbols, <a href="#29">29</a><br>
32055 UBS_DEVICE_VER, <a href="#347">347</a><br>
32056 USB_DEVICE, <a href="#347">347</a><br>
32057 USB_DEVICE_INFO, <a href="#347">347</a><br>
32058 USB_INTERFACE_INFO, <a href="#347">347</a><br>
32059 version dependency, <a href="#26">26</a><br>
32060 wait queues, <a href="#156">156</a><br>
32061 wait-event, <a href="#149">149</a></div>
32062 magic SysRq key, <a href="#97">97</a><br>
32063 mailing list, linux-kernel, <a href="#12">12</a><br>
32064 mainline kernels, installation of, <a href="#15">15</a><br>
32065 major device numbers, <a href="#44">44</a><br>
32066 <div class="bql">dynamic allocation of, <a href="#46">46</a>-<a href="#49">49</a></div>
32067 MAJOR macro, <a href="#71">71</a><br>
32068 major numbers<br>
32069 <div class="bql">char drivers, <a href="#43">43</a>-<a href="#49">49</a><br>
32070 dynamic allocation of, <a href="#46">46</a></div>
32071 make command, <a href="#24">24</a><br>
32072 makefiles, <a href="#24">24</a><br>
32073 <div class="bql">printk function, <a href="#80">80</a></div>
32074 management, <a href="#4">4</a><br>
32075 <div class="bql">classes, <a href="#389">389</a><br>
32076 concurrency, <a href="#107">107</a>-<a href="#109">109</a><br>
32077 <div class="bql">alternatives to locking, <a href="#123">123</a>-<a href="#130">130</a><br>
32078 locking traps, <a href="#121">121</a>-<a href="#123">123</a></div>
32079 fragmentation, <a href="#442">442</a><br>
32080 hardware (I/O ports and I/O memory), <a href="#235">235</a>-<a href="#254">254</a><br>
32081 interrupt handlers, <a href="#286">286</a><br>
32082 memory, <a href="#4">4</a>, <a href="#412">412</a>-<a href="#416">416</a><br>
32083 <div class="bql">direct I/O, <a href="#435">435</a>-<a href="#440">440</a><br>
32084 DMA, <a href="#440">440</a>-<a href="#459">459</a>, <a href="#461">461</a><br>
32085 mapping, <a href="#416">416</a>-<a href="#418">418</a><br>
32086 mmap device operations, <a href="#422">422</a>-<a href="#434">434</a><br>
32087 page tables, <a href="#418">418</a><br>
32088 process memory maps, <a href="#422">422</a><br>
32089 scull, <a href="#60">60</a>-<a href="#63">63</a>, <a href="#107">107</a><br>
32090 VMAs, <a href="#419">419</a>-<a href="#422">422</a></div>
32091 networks, <a href="#5">5</a><br>
32092 physical memory, <a href="#216">216</a><br>
32093 power, <a href="#362">362</a><br>
32094 process, <a href="#4">4</a><br>
32095 security, <a href="#8">8</a><br>
32096 tasklets, <a href="#202">202</a>-<a href="#204">204</a></div>
32097 manual sleeps, <a href="#156">156</a><br>
32098 mapper program, <a href="#430">430</a><br>
32099 </td><td valign="top" width="50%">
32100 mapping<br>
32101 <div class="bql">deleting, <a href="#448">448</a><br>
32102 DMA, <a href="#445">445</a><br>
32103 I/O, <a href="#249">249</a>, <a href="#255">255</a><br>
32104 memory, <a href="#416">416</a>-<a href="#418">418</a><br>
32105 <div class="bql">mmap device operations, <a href="#422">422</a>-<a href="#434">434</a><br>
32106 process memory maps, <a href="#422">422</a></div>
32107 PCI double-address cycle, <a href="#452">452</a><br>
32108 registers, <a href="#445">445</a>, <a href="#450">450</a><br>
32109 scatter-gather DMA, <a href="#450">450</a><br>
32110 scatterlists and, <a href="#450">450</a><br>
32111 single-page streaming, <a href="#450">450</a><br>
32112 software-mapped memory, <a href="#250">250</a><br>
32113 streaming DMA configuration, <a href="#448">448</a><br>
32114 video memory, <a href="#423">423</a></div>
32115 match function (buses), <a href="#379">379</a><br>
32116 MCA (Micro Channel Architecture), <a href="#322">322</a><br>
32117 mdelay, <a href="#196">196</a><br>
32118 measurement of time lapses, <a href="#183">183</a>-<a href="#188">188</a><br>
32119 Media Independent Interface (MII), <a href="#540">540</a><br>
32120 media_changed method, <a href="#472">472</a><br>
32121 medium access control addresses (see MAC addresses)<br>
32122 memory<br>
32123 <div class="bql">allocation, <a href="#60">60</a>-<a href="#62">62</a><br>
32124 <div class="bql">boot time, <a href="#230">230</a>, <a href="#234">234</a><br>
32125 flags, <a href="#215">215</a>, <a href="#218">218</a>, <a href="#231">231</a><br>
32126 I/O, <a href="#249">249</a>, <a href="#255">255</a><br>
32127 kmalloc allocation engine, <a href="#213">213</a>-<a href="#217">217</a><br>
32128 lookaside caches, <a href="#217">217</a>-<a href="#224">224</a>, <a href="#232">232</a><br>
32129 by page, <a href="#221">221</a><br>
32130 per-CPU variables, <a href="#228">228</a>-<a href="#230">230</a><br>
32131 performance degradation issues, <a href="#222">222</a><br>
32132 vmalloc allocation function, <a href="#224">224</a>-<a href="#228">228</a></div>
32133 barriers, <a href="#237">237</a>, <a href="#238">238</a>, <a href="#255">255</a><br>
32134 block drivers, <a href="#468">468</a><br>
32135 DMA (see DMA)<br>
32136 global areas, <a href="#43">43</a><br>
32137 hardware, <a href="#506">506</a><br>
32138 high, <a href="#415">415</a><br>
32139 I/O, <a href="#235">235</a>-<a href="#254">254</a>, <a href="#255">255</a><br>
32140 ISA<br>
32141 <div class="bql">access, <a href="#253">253</a><br>
32142 memory range, <a href="#252">252</a>-<a href="#254">254</a></div>
32143 limitations on, <a href="#415">415</a><br>
32144 locking, <a href="#109">109</a><br>
32145 low, <a href="#415">415</a><br>
32146 management, <a href="#4">4</a>, <a href="#412">412</a>-<a href="#416">416</a><br>
32147 <div class="bql">direct I/O, <a href="#435">435</a>-<a href="#440">440</a><br>
32148 DMA, <a href="#440">440</a>-<a href="#459">459</a>, <a href="#461">461</a></div></div>
32149 </td></tr></table>
32150 <br>
32151 <A name="600"></a><font color="blue">PAGE 600</font><br>
32152 <br>
32153 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
32154 memory, management <i>(continued)</i><br>
32155 <div class="bql"><div class="bql">fragmentation, <a href="#442">442</a><br>
32156 mapping, <a href="#416">416</a>-<a href="#418">418</a><br>
32157 mmap device operations, <a href="#422">422</a>-<a href="#434">434</a><br>
32158 page tables, <a href="#418">418</a><br>
32159 process memory maps, <a href="#422">422</a><br>
32160 VMAs, <a href="#419">419</a>-<a href="#422">422</a></div>
32161 modules (loading), <a href="#25">25</a><br>
32162 page size and portability, <a href="#292">292</a><br>
32163 PCI, <a href="#305">305</a>, <a href="#316">316</a><br>
32164 persistence, <a href="#43">43</a><br>
32165 pools, <a href="#220">220</a>, <a href="#232">232</a><br>
32166 remapping RAM, <a href="#430">430</a><br>
32167 scull<br>
32168 <div class="bql">design of, <a href="#43">43</a><br>
32169 troubleshooting, <a href="#107">107</a><br>
32170 usage, <a href="#60">60</a>-<a href="#63">63</a></div>
32171 software-mapped (and ioremap function), <a href="#250">250</a><br>
32172 user space, <a href="#437">437</a><br>
32173 verifying user-space addresses, <a href="#142">142</a><br>
32174 versus I/O registers, <a href="#236">236</a><br>
32175 zones, <a href="#215">215</a></div>
32176 memory management<br>
32177 <div class="bql">DMA, <a href="#440">440</a>-<a href="#459">459</a><br>
32178 theory of, <a href="#422">422</a><br>
32179 VMAs, <a href="#422">422</a></div>
32180 messages<br>
32181 <div class="bql">consoles, <a href="#77">77</a><br>
32182 debug<br>
32183 <div class="bql">disabling, <a href="#79">79</a><br>
32184 limitation of (printk function), <a href="#81">81</a></div>
32185 globally enabling/disabling, <a href="#79">79</a><br>
32186 kernels, <a href="#18">18</a><br>
32187 logging, <a href="#78">78</a><br>
32188 oops, <a href="#94">94</a>-<a href="#96">96</a><br>
32189 priorities (loglevels) of, <a href="#17">17</a>, <a href="#76">76</a></div>
32190 methods, <a href="#88">88</a><br>
32191 <div class="bql">block_fsync, <a href="#167">167</a><br>
32192 buses, <a href="#379">379</a><br>
32193 change_mtu, <a href="#513">513</a><br>
32194 check_flags, <a href="#52">52</a><br>
32195 close, <a href="#59">59</a>, <a href="#421">421</a><br>
32196 devices, <a href="#511">511</a><br>
32197 *dir_notify, <a href="#52">52</a><br>
32198 do_ioctl, <a href="#513">513</a>, <a href="#535">535</a><br>
32199 fasync, <a href="#52">52</a><br>
32200 flush, <a href="#51">51</a>, <a href="#60">60</a><br>
32201 fsync, <a href="#51">51</a>, <a href="#167">167</a><br>
32202 get_stats, <a href="#512">512</a>, <a href="#536">536</a><br>
32203 hard_header, <a href="#512">512</a>, <a href="#532">532</a><br>
32204 hard_start_transmit, <a href="#516">516</a></div>
32205 </td><td valign="top" width="50%">
32206 <div class="bql">hard_start_xmit, <a href="#512">512</a>, <a href="#517">517</a><br>
32207 header_cache, <a href="#513">513</a><br>
32208 header_cache_update, <a href="#514">514</a><br>
32209 ioctl, <a href="#51">51</a>, <a href="#135">135</a>-<a href="#147">147</a><br>
32210 <div class="bql">block drivers, <a href="#473">473</a><br>
32211 customizing for networking, <a href="#535">535</a><br>
32212 debugging with, <a href="#90">90</a><br>
32213 inode pointer in, <a href="#136">136</a></div>
32214 llseek, <a href="#50">50</a>, <a href="#171">171</a><br>
32215 lock, <a href="#52">52</a><br>
32216 media_changed, <a href="#472">472</a><br>
32217 mmap, <a href="#51">51</a><br>
32218 next, <a href="#87">87</a><br>
32219 nopage, <a href="#422">422</a>, <a href="#427">427</a>, <a href="#431">431</a><br>
32220 open, <a href="#51">51</a>, <a href="#58">58</a>-<a href="#59">59</a><br>
32221 <div class="bql">block drivers, <a href="#471">471</a><br>
32222 blocking, <a href="#176">176</a><br>
32223 for network devices, <a href="#511">511</a><br>
32224 private_data and, <a href="#54">54</a><br>
32225 requesting DMA channels, <a href="#455">455</a><br>
32226 restricting simultaneous users<br>
32227 and, <a href="#175">175</a><br>
32228 for single-open devices, <a href="#174">174</a><br>
32229 vm_operations_struct structure, <a href="#421">421</a></div>
32230 operations<br>
32231 <div class="bql">aio_fsync, <a href="#438">438</a><br>
32232 atomic_add, <a href="#125">125</a><br>
32233 atomic_dec, <a href="#125">125</a><br>
32234 atomic_dec_and_test, <a href="#125">125</a><br>
32235 atomic_inc, <a href="#125">125</a><br>
32236 atomic_inc_and_test, <a href="#125">125</a><br>
32237 atomic_read, <a href="#125">125</a><br>
32238 atomic_set, <a href="#125">125</a><br>
32239 atomic_sub, <a href="#125">125</a><br>
32240 atomic_sub_and_test, <a href="#125">125</a><br>
32241 bit, <a href="#126">126</a><br>
32242 block drivers, <a href="#466">466</a><br>
32243 blocking/nonblocking, <a href="#151">151</a><br>
32244 change_bit, <a href="#126">126</a><br>
32245 clear_bit, <a href="#126">126</a><br>
32246 devices, <a href="#513">513</a><br>
32247 files, <a href="#49">49</a>-<a href="#53">53</a><br>
32248 filter hotplug, <a href="#376">376</a><br>
32249 flush, <a href="#51">51</a><br>
32250 hotplugs, <a href="#376">376</a><br>
32251 mmap devices, <a href="#422">422</a>-<a href="#434">434</a><br>
32252 set_bit, <a href="#126">126</a><br>
32253 spinlocks, <a href="#120">120</a><br>
32254 string, <a href="#241">241</a>, <a href="#255">255</a><br>
32255 sysrq, <a href="#98">98</a><br>
32256 test_and_change_bit, <a href="#127">127</a><br>
32257 test_and_clear_bit, <a href="#127">127</a></div></div>
32258 </td></tr></table>
32259 <br>
32260 <A name="601"></a><font color="blue">PAGE 601</font><br>
32261 <br>
32262 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
32263 <div class="bql"><div class="bql">test_and_set_bit, <a href="#127">127</a><br>
32264 test_bit, <a href="#127">127</a><br>
32265 vector, <a href="#69">69</a></div>
32266 poll, <a href="#51">51</a>, <a href="#163">163</a>-<a href="#169">169</a>, <a href="#513">513</a><br>
32267 poll_controller, <a href="#542">542</a><br>
32268 populate, <a href="#422">422</a><br>
32269 pread, <a href="#65">65</a><br>
32270 proc_read, <a href="#84">84</a><br>
32271 pwrite, <a href="#65">65</a><br>
32272 read, <a href="#50">50</a>, <a href="#63">63</a>-<a href="#69">69</a><br>
32273 <div class="bql">arguments to, <a href="#65">65</a><br>
32274 code for, <a href="#67">67</a><br>
32275 configuring DMA controllers, <a href="#456">456</a><br>
32276 f_pso field (file structure) and, <a href="#54">54</a><br>
32277 oops messages, <a href="#95">95</a><br>
32278 poll method and, <a href="#166">166</a><br>
32279 rules for interpreting return values, <a href="#66">66</a><br>
32280 strace command and, <a href="#92">92</a></div>
32281 readdir, <a href="#50">50</a><br>
32282 readv, <a href="#52">52</a><br>
32283 rebuild_header, <a href="#512">512</a><br>
32284 release, <a href="#51">51</a>, <a href="#59">59</a><br>
32285 <div class="bql">block drivers, <a href="#471">471</a><br>
32286 blocking, <a href="#176">176</a><br>
32287 cloning devices, <a href="#179">179</a><br>
32288 kobjects, <a href="#367">367</a></div>
32289 revalidate, <a href="#473">473</a><br>
32290 sbull ioctl, <a href="#473">473</a><br>
32291 select, <a href="#163">163</a>-<a href="#169">169</a><br>
32292 select, poll method and, <a href="#51">51</a><br>
32293 set_config, <a href="#512">512</a><br>
32294 set_mac_address, <a href="#513">513</a><br>
32295 set_multicast_list, <a href="#510">510</a>, <a href="#513">513</a>, <a href="#538">538</a><br>
32296 show<br>
32297 <div class="bql">kobjects, <a href="#373">373</a><br>
32298 seq_file interface, <a href="#88">88</a></div>
32299 start, <a href="#87">87</a><br>
32300 stop, <a href="#512">512</a><br>
32301 store (kobjects), <a href="#373">373</a><br>
32302 strace command and, <a href="#92">92</a><br>
32303 struct module *owner, <a href="#50">50</a><br>
32304 tx_timeout, <a href="#512">512</a><br>
32305 unsigned long, <a href="#52">52</a><br>
32306 write, <a href="#50">50</a>, <a href="#63">63</a>-<a href="#69">69</a><br>
32307 <div class="bql">code for, <a href="#68">68</a><br>
32308 f_pos field (file structure) and, <a href="#54">54</a><br>
32309 interpreting rules for return values, <a href="#68">68</a><br>
32310 oops messages, <a href="#94">94</a><br>
32311 poll method and, <a href="#166">166</a></div>
32312 writev, <a href="#52">52</a>, <a href="#69">69</a></div>
32313 </td><td valign="top" width="50%">
32314 mice<br>
32315 <div class="bql">asynchronous notification, <a href="#170">170</a><br>
32316 hotplugging, <a href="#401">401</a></div>
32317 Micro Channel Architecture (MCA), <a href="#322">322</a><br>
32318 microsecond resolution, <a href="#189">189</a><br>
32319 MII (Media Independent Interface), <a href="#540">540</a><br>
32320 minor device numbers, <a href="#44">44</a><br>
32321 MINOR macro, <a href="#71">71</a><br>
32322 minor numbers, char drivers, <a href="#43">43</a>-<a href="#49">49</a><br>
32323 MIPS processor<br>
32324 <div class="bql">inline assembly code and, <a href="#187">187</a><br>
32325 porting and, <a href="#243">243</a></div>
32326 misc-progs directory, <a href="#77">77</a>, <a href="#162">162</a><br>
32327 mitigation of interrupts, <a href="#525">525</a><br>
32328 MKDEV macro, <a href="#71">71</a><br>
32329 mlock system call, <a href="#39">39</a><br>
32330 mmap<br>
32331 <div class="bql">device operations, <a href="#422">422</a>-<a href="#434">434</a><br>
32332 implementation, <a href="#412">412</a>-<a href="#416">416</a>, <a href="#460">460</a><br>
32333 (see also memory management)</div>
32334 mmap method, <a href="#51">51</a><br>
32335 <div class="bql">usage count and, <a href="#426">426</a><br>
32336 vm_area_struct structure and, <a href="#420">420</a></div>
32337 modalities (levels), CPU, <a href="#20">20</a><br>
32338 models (Linux device), <a href="#362">362</a>-<a href="#364">364</a><br>
32339 <div class="bql">buses, <a href="#377">377</a>-<a href="#381">381</a><br>
32340 classes, <a href="#387">387</a>-<a href="#391">391</a><br>
32341 devices, <a href="#381">381</a>-<a href="#387">387</a><br>
32342 firmware, <a href="#405">405</a>-<a href="#407">407</a><br>
32343 hotplugging, <a href="#375">375</a>, <a href="#397">397</a>-<a href="#405">405</a><br>
32344 kobjects, <a href="#364">364</a>-<a href="#371">371</a><br>
32345 lifecycles, <a href="#391">391</a>-<a href="#397">397</a><br>
32346 low-level sysfs operations, <a href="#371">371</a>-<a href="#375">375</a></div>
32347 modes<br>
32348 <div class="bql">device modes, <a href="#47">47</a><br>
32349 file modes, <a href="#53">53</a><br>
32350 interrupt<br>
32351 <div class="bql">asynchronous execution, <a href="#197">197</a><br>
32352 tasklets, <a href="#202">202</a>-<a href="#204">204</a></div></div>
32353 mode_t f_mode (struct file field), <a href="#53">53</a><br>
32354 mode_t mode variable (USB), <a href="#353">353</a><br>
32355 modprobe utility, <a href="#25">25</a>, <a href="#29">29</a><br>
32356 <div class="bql">assigning parameter values, <a href="#36">36</a><br>
32357 insmod program versus, <a href="#29">29</a></div>
32358 mod_timer function, <a href="#200">200</a>, <a href="#202">202</a><br>
32359 modularization, layered, <a href="#28">28</a><br>
32360 MODULE_ALIAS macro, <a href="#41">41</a><br>
32361 MODULE_AUTHOR macro, <a href="#41">41</a><br>
32362 MODULE_DESCRIPTION macro, <a href="#41">41</a><br>
32363 MODULE_DEVICE_TABLE macro, <a href="#41">41</a>, <a href="#311">311</a><br>
32364 </td></tr></table>
32365 <br>
32366 <A name="602"></a><font color="blue">PAGE 602</font><br>
32367 <br>
32368 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
32369 module.h header file, <a href="#40">40</a><br>
32370 module_init function, <a href="#31">31</a><br>
32371 module_param macro, <a href="#36">36</a>, <a href="#41">41</a><br>
32372 modules, <a href="#5">5</a><br>
32373 <div class="bql">applications, <a href="#18">18</a>-<a href="#22">22</a><br>
32374 authorization, <a href="#8">8</a><br>
32375 base module parameter, <a href="#247">247</a><br>
32376 classes, <a href="#5">5</a>-<a href="#8">8</a><br>
32377 code requirements, <a href="#30">30</a><br>
32378 compiling, <a href="#23">23</a>-<a href="#25">25</a><br>
32379 complete, <a href="#115">115</a><br>
32380 current process and, <a href="#21">21</a><br>
32381 dynamic module assignment, <a href="#47">47</a><br>
32382 dynamic number assignment, <a href="#47">47</a><br>
32383 faulty (oops messages), <a href="#94">94</a><br>
32384 files, <a href="#40">40</a><br>
32385 filesystem, <a href="#8">8</a><br>
32386 header files of, <a href="#19">19</a><br>
32387 hello world, <a href="#16">16</a>-<a href="#18">18</a><br>
32388 initialization, <a href="#31">31</a>-<a href="#35">35</a><br>
32389 initializing, <a href="#31">31</a>-<a href="#35">35</a><br>
32390 kdatasize, <a href="#289">289</a><br>
32391 license terms, <a href="#11">11</a><br>
32392 loading, <a href="#18">18</a>, <a href="#25">25</a>-<a href="#28">28</a><br>
32393 <div class="bql">insmod program and, <a href="#25">25</a><br>
32394 races, <a href="#35">35</a><br>
32395 using init scripts, <a href="#48">48</a></div>
32396 parameters, <a href="#35">35</a>-<a href="#37">37</a><br>
32397 platform dependency, <a href="#27">27</a><br>
32398 SCSI, <a href="#7">7</a><br>
32399 security (see security)<br>
32400 short, <a href="#265">265</a><br>
32401 stacking, <a href="#28">28</a><br>
32402 symbols, <a href="#28">28</a>-<a href="#29">29</a><br>
32403 test system setup, <a href="#15">15</a><br>
32404 unloading, <a href="#18">18</a>, <a href="#25">25</a>, <a href="#505">505</a><br>
32405 user-space programming, <a href="#37">37</a>-<a href="#39">39</a><br>
32406 version dependency, <a href="#26">26</a></div>
32407 monitoring<br>
32408 <div class="bql">kernels (debugging by), <a href="#91">91</a><br>
32409 preprocessor for, <a href="#79">79</a>-<a href="#81">81</a></div>
32410 mremap system calls, <a href="#427">427</a>, <a href="#430">430</a><br>
32411 MSR register, <a href="#565">565</a><br>
32412 MTU, network devices and, <a href="#513">513</a><br>
32413 multicasting<br>
32414 <div class="bql">IFF_MULTICAST flag and, <a href="#509">509</a><br>
32415 network drivers, <a href="#537">537</a>-<a href="#540">540</a></div>
32416 mutexes, <a href="#109">109</a><br>
32417 <div class="bql">initialization, <a href="#110">110</a></div>
32418 mutual exclusion, <a href="#108">108</a><br>
32419 </td><td valign="top" width="50%">
32421 <a name="N"></a><font color="red"><b>N</b></font><br><br>
32423 name field (buses), <a href="#378">378</a><br>
32424 NAME variable, <a href="#401">401</a><br>
32425 naming<br>
32426 <div class="bql">IP numbers, <a href="#499">499</a><br>
32427 sysfs directory tree (USB), <a href="#334">334</a></div>
32428 native DMA, <a href="#454">454</a>-<a href="#459">459</a><br>
32429 natural alignment of data items, <a href="#294">294</a><br>
32430 nbtest program, <a href="#162">162</a><br>
32431 net_device structure, <a href="#502">502</a>, <a href="#506">506</a>-<a href="#507">507</a><br>
32432 <div class="bql">device methods of, <a href="#514">514</a><br>
32433 interface flags for, <a href="#509">509</a></div>
32434 net_device_stats structure, <a href="#505">505</a>, <a href="#536">536</a><br>
32435 netif_carrier_off function, <a href="#528">528</a><br>
32436 netif_carrier_ok function, <a href="#528">528</a><br>
32437 netif_carrier_on function, <a href="#528">528</a><br>
32438 netif_start_queue function, <a href="#515">515</a><br>
32439 netif_stop_queue function, <a href="#516">516</a>, <a href="#518">518</a><br>
32440 netif_wake_queue function, <a href="#518">518</a><br>
32441 net_init.c file, <a href="#507">507</a><br>
32442 netpoll, <a href="#541">541</a><br>
32443 network devices, <a href="#400">400</a><br>
32444 network drivers, <a href="#497">497</a><br>
32445 <div class="bql">functions, <a href="#542">542</a>-<a href="#545">545</a><br>
32446 interrupt handlers for, <a href="#523">523</a><br>
32447 ioctl commands, <a href="#535">535</a><br>
32448 kernel connections, <a href="#502">502</a>-<a href="#514">514</a><br>
32449 link state (changes in), <a href="#528">528</a><br>
32450 MAC addresses (resolution of), <a href="#532">532</a>-<a href="#534">534</a><br>
32451 methods of, <a href="#514">514</a><br>
32452 multicasting, <a href="#537">537</a>-<a href="#540">540</a><br>
32453 opening, <a href="#515">515</a>-<a href="#516">516</a><br>
32454 snull, <a href="#498">498</a>-<a href="#502">502</a><br>
32455 statistics, <a href="#536">536</a></div>
32456 networks, <a href="#5">5</a><br>
32457 <div class="bql">interfaces, <a href="#7">7</a><br>
32458 management, <a href="#5">5</a></div>
32459 next method, <a href="#87">87</a><br>
32460 nonblocking operations, <a href="#151">151</a><br>
32461 nondefault attributes (kobjects), <a href="#373">373</a><br>
32462 non-Ethernet headers, <a href="#534">534</a><br>
32463 non-Ethernet interfaces, <a href="#507">507</a><br>
32464 nonpreemption and concurrency, <a href="#21">21</a><br>
32465 nonretryable requests, <a href="#486">486</a><br>
32466 nonuniform memory access (NUMA) systems (see NUMA systems)<br>
32467 nopage method, <a href="#422">422</a>, <a href="#427">427</a><br>
32468 <div class="bql">mremap system call with, <a href="#427">427</a><br>
32469 preventing extension of mapping, <a href="#430">430</a><br>
32470 remapping RAM, <a href="#431">431</a></div>
32471 normal memory zone, <a href="#215">215</a><br>
32472 notification (asynchronous), <a href="#169">169</a>-<a href="#171">171</a><br>
32473 </td></tr></table>
32474 <br>
32475 <A name="603"></a><font color="blue">PAGE 603</font><br>
32476 <br>
32477 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
32478 nr_frags field, <a href="#520">520</a><br>
32479 NR_IRQS symbol, <a href="#267">267</a><br>
32480 NuBus, <a href="#324">324</a><br>
32481 NUMA (nonuniform memory access) systems, <a href="#216">216</a>, <a href="#417">417</a><br>
32482 numbering versions (see versions, numbering)<br>
32483 numbers<br>
32484 <div class="bql">devices (printing), <a href="#82">82</a><br>
32485 interrupt, <a href="#260">260</a><br>
32486 IP (assignment of), <a href="#499">499</a><br>
32487 major and minor, <a href="#43">43</a>-<a href="#49">49</a><br>
32488 PFN, <a href="#415">415</a><br>
32489 root hubs (USB), <a href="#334">334</a><br>
32490 versions, <a href="#10">10</a>-<a href="#11">11</a></div>
32492 <br><a name="O"></a><font color="red"><b>O</b></font><br><br>
32494 objects<br>
32495 <div class="bql">kobjects, <a href="#364">364</a>-<a href="#371">371</a><br>
32496 <div class="bql">hotplug event generation, <a href="#375">375</a><br>
32497 low-level sysfs operations, <a href="#371">371</a>-<a href="#375">375</a><br>
32498 (see also kobjects)</div>
32499 lifecycles, <a href="#363">363</a><br>
32500 sharing, <a href="#108">108</a></div>
32501 octets, <a href="#498">498</a><br>
32502 older interfaces<br>
32503 <div class="bql">char device registration, <a href="#57">57</a><br>
32504 /proc file implementation, <a href="#85">85</a></div>
32505 O_NDELAY flag (f_flags field), <a href="#151">151</a><br>
32506 O_NONBLOCK flag (f_flags field), <a href="#54">54</a>, <a href="#141">141</a>, <a href="#151">151</a><br>
32507 <div class="bql">read/write methods and, <a href="#166">166</a></div>
32508 oops messages, <a href="#94">94</a>-<a href="#96">96</a><br>
32509 open files, <a href="#53">53</a><br>
32510 open function (tty drivers), <a href="#553">553</a>-<a href="#556">556</a><br>
32511 open method, <a href="#51">51</a>, <a href="#58">58</a>-<a href="#59">59</a><br>
32512 <div class="bql">block drivers, <a href="#471">471</a><br>
32513 blocking, <a href="#176">176</a><br>
32514 for network devices, <a href="#511">511</a><br>
32515 private_data and, <a href="#54">54</a><br>
32516 requesting DMA channels, <a href="#455">455</a><br>
32517 restricting simultaneous users and, <a href="#175">175</a><br>
32518 for single-open devices, <a href="#174">174</a><br>
32519 vm_operations_struct structure, <a href="#421">421</a></div>
32520 opening network drivers, <a href="#515">515</a>-<a href="#516">516</a><br>
32521 operations<br>
32522 <div class="bql">aio_fsync, <a href="#438">438</a><br>
32523 atomic_add, <a href="#125">125</a><br>
32524 atomic_dec, <a href="#125">125</a><br>
32525 atomic_dec_and_test, <a href="#125">125</a><br>
32526 atomic_inc, <a href="#125">125</a><br>
32527 atomic_inc_and_test, <a href="#125">125</a></div>
32528 </td><td valign="top" width="50%">
32529 <div class="bql">atomic_read, <a href="#125">125</a><br>
32530 atomic_set, <a href="#125">125</a><br>
32531 atomic_sub, <a href="#125">125</a><br>
32532 atomic_sub_and_test, <a href="#125">125</a><br>
32533 bit, <a href="#126">126</a><br>
32534 block drivers, <a href="#466">466</a>, <a href="#471">471</a>-<a href="#474">474</a><br>
32535 blocking, <a href="#151">151</a><br>
32536 change_bit, <a href="#126">126</a><br>
32537 clear_bit, <a href="#126">126</a><br>
32538 devices, <a href="#513">513</a><br>
32539 files, <a href="#49">49</a>-<a href="#53">53</a><br>
32540 filter operation, <a href="#376">376</a><br>
32541 flush, <a href="#51">51</a><br>
32542 hotplugs, <a href="#376">376</a><br>
32543 on ksets, <a href="#370">370</a><br>
32544 low-level sysfs, <a href="#371">371</a>-<a href="#375">375</a><br>
32545 methods<br>
32546 <div class="bql">buses, <a href="#379">379</a><br>
32547 close, <a href="#421">421</a><br>
32548 nopage, <a href="#422">422</a><br>
32549 open, <a href="#421">421</a><br>
32550 populate, <a href="#422">422</a><br>
32551 (see also methods)</div>
32552 mmap devices, <a href="#422">422</a>-<a href="#434">434</a><br>
32553 nonblocking, <a href="#151">151</a><br>
32554 set_bit, <a href="#126">126</a><br>
32555 snull interfaces, <a href="#500">500</a><br>
32556 spinlocks, <a href="#120">120</a><br>
32557 string, <a href="#241">241</a>, <a href="#255">255</a><br>
32558 sysrq, <a href="#98">98</a><br>
32559 test_and_change_bit, <a href="#127">127</a><br>
32560 test_and_clear_bit, <a href="#127">127</a><br>
32561 test_and_set_bit, <a href="#127">127</a><br>
32562 test_bit, <a href="#127">127</a><br>
32563 tty_operations structure, <a href="#569">569</a><br>
32564 vector, <a href="#69">69</a><br>
32565 VMAs (adding), <a href="#426">426</a></div>
32566 optimizations, compiler, <a href="#236">236</a><br>
32567 options (configuration), <a href="#73">73</a>-<a href="#75">75</a><br>
32568 ordering locking (rules for), <a href="#122">122</a><br>
32569 O_RDONLY flag (f_flags field), <a href="#54">54</a><br>
32570 O_SYNC flag (f_flags field), <a href="#54">54</a><br>
32571 outb function, <a href="#240">240</a><br>
32572 outb_p function, <a href="#242">242</a><br>
32573 outl function, <a href="#240">240</a><br>
32574 output<br>
32575 <div class="bql">buffers, <a href="#152">152</a><br>
32576 flushing pending, <a href="#167">167</a><br>
32577 pins, <a href="#235">235</a>, <a href="#245">245</a>, <a href="#247">247</a></div>
32578 outsb function, <a href="#242">242</a><br>
32579 outsl function, <a href="#242">242</a><br>
32580 outsw function, <a href="#242">242</a><br>
32581 </td></tr></table>
32582 <br>
32583 <A name="605"></a><font color="blue">PAGE 605</font><br>
32584 <br>
32585 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
32586 outw function, <a href="#240">240</a><br>
32587 overriding ARP, <a href="#533">533</a><br>
32588 overruns (buffers), <a href="#95">95</a><br>
32590 <br><a name="P"></a><font color="red"><b>P</b></font><br><br>
32592 packages, upgrading, <a href="#10">10</a><br>
32593 PACKET_BROADCAST flag, <a href="#530">530</a><br>
32594 PACKET_HOST flag, <a href="#530">530</a><br>
32595 PACKET_MULTICAST flag, <a href="#530">530</a><br>
32596 PACKET_OTHERHOST flag, <a href="#530">530</a><br>
32597 packets<br>
32598 <div class="bql">management, <a href="#5">5</a><br>
32599 multicasting, <a href="#538">538</a><br>
32600 reception, <a href="#523">523</a><br>
32601 reception of, <a href="#501">501</a>, <a href="#521">521</a><br>
32602 transmission, <a href="#501">501</a>, <a href="#516">516</a>-<a href="#520">520</a></div>
32603 page frame number (PFN), <a href="#415">415</a><br>
32604 page_address macro, <a href="#417">417</a><br>
32605 page.h header file, <a href="#292">292</a><br>
32606 page-oriented allocation functions, <a href="#221">221</a>, <a href="#233">233</a><br>
32607 pages<br>
32608 <div class="bql">allocators, <a href="#224">224</a><br>
32609 faults caused by invalid pointers, <a href="#94">94</a><br>
32610 physical addresses, <a href="#415">415</a><br>
32611 size and portability, <a href="#292">292</a><br>
32612 tables, <a href="#418">418</a><br>
32613 <div class="bql">I/O memory and, <a href="#249">249</a><br>
32614 nopage VMA method, <a href="#427">427</a></div></div>
32615 PAGE_SHIFT macro, <a href="#415">415</a><br>
32616 PAGE_SHIFT symbol, <a href="#292">292</a><br>
32617 PAGE_SIZE symbol, <a href="#292">292</a>, <a href="#423">423</a><br>
32618 Parallel Line Internet Protocol (see PLIP)<br>
32619 parallel ports, <a href="#245">245</a>-<a href="#248">248</a><br>
32620 <div class="bql">interrupt handlers<br>
32621 <div class="bql">disabling, <a href="#274">274</a><br>
32622 preparing for, <a href="#259">259</a></div>
32623 stacking driver modules, <a href="#28">28</a></div>
32624 parameters<br>
32625 <div class="bql">assigning values, <a href="#36">36</a><br>
32626 base module, <a href="#247">247</a><br>
32627 modules, <a href="#35">35</a>-<a href="#37">37</a></div>
32628 param.h header file, <a href="#183">183</a><br>
32629 PARENB bitmask, <a href="#561">561</a><br>
32630 PARODD bitmask, <a href="#561">561</a><br>
32631 partial data transfers<br>
32632 <div class="bql">read method, <a href="#66">66</a><br>
32633 write method, <a href="#68">68</a></div>
32634 passwords, <a href="#9">9</a><br>
32635 pausing I/O, <a href="#242">242</a><br>
32636 PC parallel interface, <a href="#245">245</a><br>
32637 </td><td valign="top" width="50%">
32638 PCI (Peripheral Component Interconnect), <a href="#226">226</a><br>
32639 <div class="bql">devices<br>
32640 <div class="bql">adding, <a href="#392">392</a>-<a href="#395">395</a><br>
32641 deleting, <a href="#395">395</a></div>
32642 DMA, <a href="#453">453</a><br>
32643 double-address cycle mappings, <a href="#452">452</a><br>
32644 drivers<br>
32645 <div class="bql">adding, <a href="#396">396</a><br>
32646 deleting, <a href="#396">396</a></div>
32647 EISA, <a href="#323">323</a><br>
32648 extended buses, <a href="#325">325</a><br>
32649 interfaces, <a href="#302">302</a>-<a href="#319">319</a><br>
32650 ISA, <a href="#319">319</a>-<a href="#322">322</a><br>
32651 lists, <a href="#326">326</a><br>
32652 MCA, <a href="#322">322</a><br>
32653 NuBus, <a href="#324">324</a><br>
32654 PC/104 and PC/104+, <a href="#322">322</a><br>
32655 SBus, <a href="#323">323</a><br>
32656 searching, <a href="#326">326</a><br>
32657 VLB, <a href="#323">323</a></div>
32658 pci_bus_type variable, <a href="#392">392</a><br>
32659 PCI_CLASS variable, <a href="#400">400</a><br>
32660 PCI_DEVICE macro, <a href="#310">310</a><br>
32661 PCI_DEVICE_CLASS macro, <a href="#310">310</a><br>
32662 PCI_DMA_FROMDEVICE symbol, <a href="#449">449</a><br>
32663 PCI_DMA_TODEVICE symbol, <a href="#449">449</a><br>
32664 PCI_ID variable, <a href="#400">400</a><br>
32665 pci_map_sg function, <a href="#451">451</a><br>
32666 pci_remove_bus_device function, <a href="#395">395</a><br>
32667 pci_resource_ functions, <a href="#317">317</a><br>
32668 PCI_SLOT_NAME variable, <a href="#400">400</a><br>
32669 PCI_SUBSYS_ID variable, <a href="#400">400</a><br>
32670 PDEBUG/PDEBUGG symbols, <a href="#80">80</a><br>
32671 pending output, flushing, <a href="#167">167</a><br>
32672 per-CPU variables, <a href="#228">228</a>-<a href="#230">230</a><br>
32673 performance<br>
32674 <div class="bql">allocating socket buffers, <a href="#522">522</a><br>
32675 degrading by allocating too much memory, <a href="#222">222</a><br>
32676 memory barriers and, <a href="#238">238</a><br>
32677 mmap method, <a href="#423">423</a><br>
32678 output buffers and, <a href="#152">152</a><br>
32679 string operations and, <a href="#241">241</a></div>
32680 Peripheral Component Interconnect (see PCI)<br>
32681 peripherals (DMA), <a href="#440">440</a>-<a href="#459">459</a><br>
32682 perror calls, <a href="#93">93</a><br>
32683 persistence of memory, <a href="#43">43</a><br>
32684 PFN (page frame number), <a href="#415">415</a><br>
32685 pfn_to_page function, <a href="#417">417</a><br>
32686 PG_locked flag, <a href="#417">417</a><br>
32687 </td></tr></table>
32688 <br>
32689 <A name="605"></a><font color="blue">PAGE 605</font><br>
32690 <br>
32691 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
32692 PG_reserved flag, <a href="#417">417</a><br>
32693 PHYS variable, <a href="#401">401</a><br>
32694 physical addresses, <a href="#413">413</a><br>
32695 <div class="bql">pages, <a href="#415">415</a><br>
32696 (see also addresses)</div>
32697 physical memory, management of, <a href="#216">216</a><br>
32698 <div class="bql">(see also memory)</div>
32699 pins<br>
32700 <div class="bql">9/10 of parallel connector, <a href="#259">259</a><br>
32701 interrupts (generating), <a href="#271">271</a><br>
32702 output, <a href="#235">235</a>, <a href="#245">245</a>, <a href="#247">247</a></div>
32703 pipes (scull), <a href="#43">43</a><br>
32704 platform dependency, <a href="#11">11</a>, <a href="#27">27</a><br>
32705 <div class="bql">for modules, <a href="#27">27</a><br>
32706 porting and, <a href="#242">242</a><br>
32707 /proc/stat file, <a href="#263">263</a></div>
32708 PLIP (Parallel Line Internet Protocol)<br>
32709 <div class="bql">using Ethernet headers, <a href="#533">533</a><br>
32710 interrupt handling differences, <a href="#523">523</a></div>
32711 plug and play (PnP), <a href="#321">321</a><br>
32712 PnP (plug and play), <a href="#321">321</a><br>
32713 pointers<br>
32714 <div class="bql">data type portability, <a href="#295">295</a><br>
32715 inode in ioctl method, <a href="#136">136</a><br>
32716 kobject, <a href="#365">365</a><br>
32717 scull, <a href="#61">61</a><br>
32718 tty_driver function, <a href="#553">553</a>-<a href="#560">560</a></div>
32719 Point-to-Point Protocol (PPP) and interrupt handling differences, <a href="#523">523</a><br>
32720 policies<br>
32721 <div class="bql">controlling devices by printing and, <a href="#147">147</a><br>
32722 memory, <a href="#4">4</a><br>
32723 allocation (scull), <a href="#60">60</a>, <a href="#63">63</a><br>
32724 security, <a href="#8">8</a><br>
32725 separation from mechanism, <a href="#2">2</a>-<a href="#4">4</a></div>
32726 policy, driver, <a href="#2">2</a>-<a href="#4">4</a><br>
32727 poll method, <a href="#51">51</a>, <a href="#163">163</a>-<a href="#169">169</a>, <a href="#513">513</a><br>
32728 poll_controller method, <a href="#542">542</a><br>
32729 POLLERR flag, <a href="#164">164</a><br>
32730 poll.h header file, <a href="#163">163</a>, <a href="#182">182</a><br>
32731 POLLHUP flag, <a href="#164">164</a><br>
32732 POLLIN flag, <a href="#164">164</a><br>
32733 POLLOUT flag, <a href="#164">164</a><br>
32734 POLLPRI flag, <a href="#164">164</a><br>
32735 POLLRDBAND flag, <a href="#164">164</a><br>
32736 POLLRDNORM flag, <a href="#164">164</a><br>
32737 poll_table structure, <a href="#163">163</a>, <a href="#167">167</a><br>
32738 poll_table_entry structure, <a href="#167">167</a><br>
32739 poll_wait function, <a href="#163">163</a>, <a href="#182">182</a><br>
32740 POLLWRBAND flag, <a href="#164">164</a><br>
32741 POLLWRNORM flag, <a href="#164">164</a><br>
32742 </td><td valign="top" width="50%">
32743 pools<br>
32744 <div class="bql">DMA, <a href="#447">447</a><br>
32745 memory, <a href="#220">220</a>, <a href="#232">232</a></div>
32746 populate method, <a href="#422">422</a><br>
32747 portability, <a href="#292">292</a>-<a href="#299">299</a><br>
32748 <div class="bql">data types and, <a href="#288">288</a>-<a href="#292">292</a><br>
32749 porting and, <a href="#242">242</a></div>
32750 ports<br>
32751 <div class="bql">access, <a href="#255">255</a><br>
32752 accessing different sizes, <a href="#240">240</a><br>
32753 I/O, <a href="#235">235</a>-<a href="#254">254</a>, <a href="#255">255</a><br>
32754 parallel, <a href="#245">245</a>-<a href="#248">248</a><br>
32755 <div class="bql">disabling interrupt handlers, <a href="#274">274</a><br>
32756 preparing for interrupt handlers, <a href="#259">259</a></div>
32757 platform dependency and, <a href="#242">242</a><br>
32758 (see also connections; parallel ports)</div>
32759 POS (Programmable Option Select), <a href="#322">322</a><br>
32760 power management, <a href="#362">362</a><br>
32761 PowerPC architecture (porting and), <a href="#244">244</a><br>
32762 PPP (Point-to-Point Protocol) and interrupt handling differences, <a href="#523">523</a><br>
32763 pread method, <a href="#65">65</a><br>
32764 precision, temporal, <a href="#189">189</a><br>
32765 predefined commands, ioctl method, <a href="#140">140</a><br>
32766 <div class="bql">(see also commands)</div>
32767 preemption and concurrency, <a href="#21">21</a><br>
32768 preprocessor, using to monitor driver, <a href="#79">79</a>-<a href="#81">81</a><br>
32769 printing<br>
32770 <div class="bql">controlling devices by, <a href="#147">147</a><br>
32771 to debug code, <a href="#81">81</a><br>
32772 device numbers, <a href="#82">82</a><br>
32773 from gdb debugger, <a href="#99">99</a><br>
32774 interface-specific data, <a href="#291">291</a><br>
32775 kernels, <a href="#75">75</a>-<a href="#82">82</a><br>
32776 _t data items, <a href="#291">291</a></div>
32777 printk function, <a href="#17">17</a>, <a href="#76">76</a>-<a href="#82">82</a><br>
32778 <div class="bql">circular buffers for, <a href="#78">78</a><br>
32779 debugging with, <a href="#78">78</a><br>
32780 logging messages from, <a href="#78">78</a><br>
32781 seq_file interface (avoiding in), <a href="#88">88</a><br>
32782 turning debug messages on/off, <a href="#79">79</a></div>
32783 priorities, <a href="#76">76</a><br>
32784 <div class="bql">allocation, <a href="#214">214</a><br>
32785 <div class="bql">memory, <a href="#213">213</a></div>
32786 message (see loglevels)</div>
32787 private_data field (file structure), <a href="#54">54</a><br>
32788 privileged operations, <a href="#144">144</a><br>
32789 probe function (USB), <a href="#350">350</a><br>
32790 probe_irq_off function, <a href="#265">265</a><br>
32791 probe_irq_on function, <a href="#265">265</a><br>
32792 Probes, Dynamic, <a href="#105">105</a><br>
32793 </td></tr></table>
32794 <br>
32795 <A name="606"></a><font color="blue">PAGE 606</font><br>
32796 <br>
32797 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
32798 probing, <a href="#264">264</a><br>
32799 <div class="bql">do-it-yourself, <a href="#266">266</a><br>
32800 for IRQ numbers, <a href="#264">264</a><br>
32801 kernel-assisted, <a href="#265">265</a><br>
32802 PCI, <a href="#313">313</a></div>
32803 /proc filesystem, <a href="#86">86</a>-<a href="#90">90</a><br>
32804 <div class="bql">installing interrupt handlers, <a href="#262">262</a><br>
32805 removing /proc entries, <a href="#86">86</a><br>
32806 shared interrupts and, <a href="#280">280</a></div>
32807 /proc/devices file, <a href="#46">46</a><br>
32808 processes<br>
32809 <div class="bql">current, <a href="#21">21</a><br>
32810 kernel timers for, <a href="#202">202</a><br>
32811 kernels (splitting), <a href="#4">4</a>-<a href="#5">5</a><br>
32812 login, <a href="#173">173</a><br>
32813 managing, <a href="#4">4</a><br>
32814 memory maps, <a href="#422">422</a><br>
32815 opening devices for each process, <a href="#173">173</a><br>
32816 sleeps, <a href="#147">147</a>-<a href="#162">162</a></div>
32817 processor-specific registers, <a href="#186">186</a><br>
32818 /proc/interrupts file, <a href="#262">262</a>, <a href="#280">280</a><br>
32819 /proc/kcore file, <a href="#99">99</a><br>
32820 /proc/kmsg file, <a href="#78">78</a><br>
32821 /proc/*/maps, <a href="#420">420</a><br>
32822 /proc/modules file, <a href="#40">40</a><br>
32823 proc_read method, <a href="#84">84</a><br>
32824 /proc/slabinfo file, <a href="#219">219</a><br>
32825 /proc/stat file, <a href="#263">263</a><br>
32826 /proc/sys/kernel/printk file, reading console loglevel with, <a href="#77">77</a><br>
32827 /proc/tty/driver/ directory, <a href="#547">547</a><br>
32828 PRODUCT variable, <a href="#401">401</a><br>
32829 Programmable Option Select (POS), <a href="#322">322</a><br>
32830 programming<br>
32831 <div class="bql">concurrency in, <a href="#20">20</a><br>
32832 hello world module, <a href="#16">16</a>-<a href="#18">18</a><br>
32833 ISA, <a href="#321">321</a><br>
32834 module requirements, <a href="#30">30</a><br>
32835 test system setup, <a href="#15">15</a><br>
32836 user space, <a href="#19">19</a>, <a href="#37">37</a>-<a href="#39">39</a></div>
32837 programming drivers (see writing, drivers)<br>
32838 programs, <a href="#3">3</a><br>
32839 <div class="bql">asynctest, <a href="#169">169</a><br>
32840 dataalign, <a href="#294">294</a><br>
32841 datasize, <a href="#288">288</a><br>
32842 insmod, <a href="#5">5</a><br>
32843 jitbusy, <a href="#191">191</a><br>
32844 mapper, <a href="#430">430</a><br>
32845 nbtest, <a href="#162">162</a><br>
32846 obtaining, <a href="#12">12</a><br>
32847 rmmod, <a href="#5">5</a><br>
32848 /sbin/hotplug utility, <a href="#398">398</a></div>
32849 </td><td valign="top" width="50%">
32850 <div class="bql">setconsole, <a href="#77">77</a><br>
32851 setterm, <a href="#147">147</a><br>
32852 tcpdump, <a href="#501">501</a><br>
32853 tracing, <a href="#105">105</a><br>
32854 tunelp, <a href="#3">3</a><br>
32855 (see also applications versus kernel modules)</div>
32856 public kernel symbols, <a href="#28">28</a>-<a href="#29">29</a><br>
32857 put_unaligned function, <a href="#293">293</a><br>
32858 put_user function, <a href="#143">143</a>, <a href="#180">180</a><br>
32859 pwrite method, <a href="#65">65</a><br>
32861 <br><a name="Q"></a><font color="red"><b>Q</b></font><br><br>
32863 quantums/quantum sets (memory), <a href="#61">61</a><br>
32864 querying kernels, <a href="#82">82</a>-<a href="#91">91</a><br>
32865 querying to debug, <a href="#91">91</a><br>
32866 queues<br>
32867 <div class="bql">control functions, <a href="#480">480</a><br>
32868 creating/deleting, <a href="#479">479</a><br>
32869 functions, <a href="#479">479</a><br>
32870 network drivers, <a href="#515">515</a><br>
32871 request function, <a href="#475">475</a><br>
32872 request method, <a href="#478">478</a><br>
32873 TCQ, <a href="#492">492</a>-<a href="#493">493</a><br>
32874 transmissions, <a href="#518">518</a><br>
32875 wait, <a href="#149">149</a>, <a href="#156">156</a>, <a href="#181">181</a><br>
32876 workqueues, <a href="#205">205</a>-<a href="#208">208</a>, <a href="#211">211</a>, <a href="#277">277</a></div>
32878 <br><a name="R"></a><font color="red"><b>R</b></font><br><br>
32880 race conditions, <a href="#21">21</a><br>
32881 <div class="bql">kernel timers and, <a href="#198">198</a><br>
32882 module loading, <a href="#35">35</a><br>
32883 sequences, <a href="#107">107</a></div>
32884 RAM (random access memory)<br>
32885 <div class="bql">remapping, <a href="#430">430</a><br>
32886 versus I/O registers, <a href="#236">236</a></div>
32887 random access memory (see RAM)<br>
32888 random numbers, <a href="#260">260</a><br>
32889 rates, limitations of, <a href="#81">81</a><br>
32890 RCU (read-copy-update), <a href="#129">129</a><br>
32891 rdtscl function, <a href="#187">187</a><br>
32892 read function (tty drivers), <a href="#558">558</a><br>
32893 read method, <a href="#50">50</a>, <a href="#63">63</a>-<a href="#69">69</a><br>
32894 <div class="bql">arguments to, <a href="#65">65</a><br>
32895 code for, <a href="#67">67</a><br>
32896 configuring DMA controllers, <a href="#456">456</a><br>
32897 f_pos field (file structure) and, <a href="#54">54</a><br>
32898 oops messages, <a href="#95">95</a><br>
32899 poll method and, <a href="#166">166</a><br>
32900 return values, rules for interpreting, <a href="#66">66</a><br>
32901 strace command and, <a href="#92">92</a></div>
32902 </td></tr></table>
32903 <br>
32904 <A name="607"></a><font color="blue">PAGE 607</font><br>
32905 <br>
32906 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
32907 read-copy-update (RCU), <a href="#129">129</a><br>
32908 readdir method, <a href="#50">50</a><br>
32909 reader/writer semaphores, <a href="#113">113</a><br>
32910 reader/writer spinlocks, <a href="#120">120</a><br>
32911 reading<br>
32912 <div class="bql">blocking/nonblocking operations, <a href="#151">151</a><br>
32913 from a device, <a href="#63">63</a>-<a href="#67">67</a></div>
32914 read-only /proc files, creating, <a href="#84">84</a><br>
32915 read_proc function, <a href="#85">85</a><br>
32916 readv calls, <a href="#69">69</a><br>
32917 readv method, <a href="#52">52</a><br>
32918 read/write instructions, reordering, <a href="#236">236</a><br>
32919 read/write position, changing, <a href="#50">50</a><br>
32920 rebuild_header method, <a href="#512">512</a><br>
32921 reception of packets, <a href="#501">501</a>, <a href="#521">521</a>-<a href="#523">523</a><br>
32922 recovery, error, <a href="#33">33</a><br>
32923 redirecting console messages, <a href="#77">77</a><br>
32924 reentrant<br>
32925 <div class="bql">calls, <a href="#97">97</a><br>
32926 code, <a href="#21">21</a></div>
32927 reference counters (kobjects), <a href="#366">366</a><br>
32928 regions<br>
32929 <div class="bql">generic I/O address spaces, <a href="#316">316</a><br>
32930 I/O memory management, <a href="#429">429</a></div>
32931 register_blkdev function, <a href="#465">465</a><br>
32932 register_chrdev function, <a href="#404">404</a><br>
32933 register_netdev function, <a href="#503">503</a><br>
32934 registers<br>
32935 <div class="bql">counters, <a href="#186">186</a><br>
32936 I/O, <a href="#236">236</a><br>
32937 LSR, <a href="#564">564</a><br>
32938 mapping, <a href="#445">445</a>, <a href="#450">450</a><br>
32939 MSR, <a href="#565">565</a><br>
32940 PCI, <a href="#308">308</a>, <a href="#325">325</a><br>
32941 <div class="bql">class, <a href="#309">309</a><br>
32942 deviceID, <a href="#309">309</a><br>
32943 subsystem deviceID, <a href="#309">309</a><br>
32944 subsystem vendorID, <a href="#309">309</a><br>
32945 vendorID, <a href="#309">309</a></div>
32946 processor-specific, <a href="#186">186</a><br>
32947 scatterlists (and mapping), <a href="#450">450</a></div>
32948 registration<br>
32949 <div class="bql">block drivers, <a href="#465">465</a>-<a href="#470">470</a><br>
32950 buses, <a href="#378">378</a><br>
32951 char drivers, <a href="#55">55</a>-<a href="#57">57</a><br>
32952 cleanup function, <a href="#32">32</a><br>
32953 devices, <a href="#382">382</a>, <a href="#502">502</a><br>
32954 disks, <a href="#466">466</a><br>
32955 DMA usage, <a href="#455">455</a><br>
32956 interrupt handlers, <a href="#286">286</a><br>
32957 module-loading races, <a href="#35">35</a></div>
32958 </td><td valign="top" width="50%">
32959 <div class="bql">PCI drivers, <a href="#311">311</a><br>
32960 struct usb_driver structure, <a href="#349">349</a><br>
32961 tiny_tty_driver variable, <a href="#551">551</a><br>
32962 tracking, <a href="#33">33</a><br>
32963 tty drivers, <a href="#549">549</a><br>
32964 USB drivers, <a href="#348">348</a></div>
32965 release calls, <a href="#174">174</a><br>
32966 release functions (kobjects), <a href="#367">367</a><br>
32967 release method, <a href="#51">51</a>, <a href="#59">59</a><br>
32968 <div class="bql">block drivers, <a href="#471">471</a><br>
32969 blocking, <a href="#176">176</a><br>
32970 cloning devices, <a href="#179">179</a><br>
32971 kobjects, <a href="#367">367</a></div>
32972 release_dma_lock function, <a href="#457">457</a><br>
32973 releasing spinlocks, <a href="#120">120</a><br>
32974 RELEVANT_IFLAG macro, <a href="#560">560</a><br>
32975 remap_pfn_range function, <a href="#424">424</a><br>
32976 remapping<br>
32977 <div class="bql">kernel virtual addresses, <a href="#434">434</a><br>
32978 RAM, <a href="#430">430</a><br>
32979 (see also mapping)</div>
32980 remote0 (IP number), <a href="#499">499</a><br>
32981 removable media (supporting), <a href="#472">472</a><br>
32982 remove_proc_entry function, <a href="#86">86</a><br>
32983 reordering read/write instructions, <a href="#236">236</a><br>
32984 repatch program, <a href="#575">575</a><br>
32985 reports (interrupts), <a href="#261">261</a><br>
32986 request_dma function, <a href="#455">455</a><br>
32987 request_firmware function, <a href="#406">406</a><br>
32988 requests<br>
32989 <div class="bql">blocking, <a href="#176">176</a><br>
32990 processing, <a href="#474">474</a>-<a href="#491">491</a><br>
32991 state of (processing), <a href="#483">483</a></div>
32992 requeuing/rescheduling tasks, <a href="#198">198</a><br>
32993 requirements, code, <a href="#30">30</a><br>
32994 resolution of time, <a href="#189">189</a><br>
32995 resolving Ethernet addresses, <a href="#532">532</a><br>
32996 resource flags (PCI), <a href="#317">317</a><br>
32997 restriction of access, <a href="#174">174</a><br>
32998 retrieval of current time, <a href="#188">188</a>-<a href="#190">190</a><br>
32999 return values<br>
33000 <div class="bql">interrupt handlers, <a href="#272">272</a><br>
33001 switch statements, <a href="#140">140</a></div>
33002 revalidate method, <a href="#473">473</a><br>
33003 ring buffers (DMA), <a href="#441">441</a><br>
33004 RISC processor and inline assembly code, <a href="#187">187</a><br>
33005 rmmod program, <a href="#5">5</a>, <a href="#17">17</a><br>
33006 <div class="bql">dynamically allocating major<br>
33007 <div class="bql">numbers, <a href="#48">48</a></div>
33008 testing modules using, <a href="#17">17</a></div>
33009 </td></tr></table>
33010 <br>
33011 <A name="608"></a><font color="blue">PAGE 608</font><br>
33012 <br>
33013 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
33014 roles<br>
33015 <div class="bql">of device drivers, <a href="#2">2</a>-<a href="#4">4</a><br>
33016 kernels, <a href="#4">4</a>-<a href="#5">5</a></div>
33017 root hubs (USB), <a href="#334">334</a><br>
33018 routing, network management, <a href="#5">5</a><br>
33019 rq_data_dir field (request structure), <a href="#477">477</a><br>
33020 rules<br>
33021 <div class="bql">locking, <a href="#121">121</a><br>
33022 ordering, <a href="#122">122</a></div>
33023 running (see execution)<br>
33024 runtime, code, <a href="#5">5</a><br>
33025 rwsems (reader/writer semaphores), <a href="#113">113</a><br>
33027 <br><a name="S"></a><font color="red"><b>S</b></font><br><br>
33029 S/390 architecture, <a href="#402">402</a><br>
33030 <div class="bql">porting and, <a href="#244">244</a></div>
33031 SA_INTERRUPT flag, <a href="#260">260</a>, <a href="#286">286</a><br>
33032 SAK (secure attention key) function, <a href="#97">97</a><br>
33033 sample programs, obtaining, <a href="#12">12</a><br>
33034 SA_SAMPLE_RANDOM flag, <a href="#260">260</a>, <a href="#286">286</a><br>
33035 SA_SHIRQ flag, <a href="#260">260</a>, <a href="#278">278</a>, <a href="#286">286</a><br>
33036 /sbin/hotplug utility, <a href="#398">398</a><br>
33037 sbull drivers<br>
33038 <div class="bql">initialization, <a href="#468">468</a><br>
33039 request method, <a href="#475">475</a></div>
33040 sbull ioctl method, <a href="#473">473</a><br>
33041 sbull_request function, <a href="#469">469</a><br>
33042 SBus, <a href="#324">324</a><br>
33043 scatter/gather<br>
33044 <div class="bql">DMA mappings, <a href="#450">450</a><br>
33045 I/O, <a href="#520">520</a></div>
33046 scatterlists<br>
33047 <div class="bql">mapping, <a href="#450">450</a><br>
33048 structure, <a href="#462">462</a></div>
33049 sched.h header file, <a href="#40">40</a>, <a href="#184">184</a><br>
33050 schedule function, <a href="#181">181</a><br>
33051 <div class="bql">execution of code (delaying), <a href="#193">193</a><br>
33052 preventing endless loops with, <a href="#97">97</a></div>
33053 schedulers (I/O), <a href="#478">478</a><br>
33054 schedule_timeout function, <a href="#194">194</a><br>
33055 scheduling kernel timers, <a href="#196">196</a>-<a href="#202">202</a><br>
33056 scripts (hotplug), <a href="#403">403</a><br>
33057 SCSI<br>
33058 <div class="bql">devices, <a href="#402">402</a><br>
33059 modules, <a href="#7">7</a></div>
33060 scull, <a href="#42">42</a>, <a href="#47">47</a><br>
33061 <div class="bql">char drivers, <a href="#70">70</a><br>
33062 concurrency (see concurrency)<br>
33063 design of, <a href="#42">42</a><br>
33064 device registration, <a href="#56">56</a><br>
33065 drivers (example), <a href="#80">80</a>, <a href="#138">138</a></div>
33066 </td><td valign="top" width="50%">
33067 <div class="bql">file operations, <a href="#49">49</a>-<a href="#53">53</a><br>
33068 inode structure, <a href="#55">55</a><br>
33069 locking (adding), <a href="#109">109</a><br>
33070 memory<br>
33071 <div class="bql">troubleshooting, <a href="#107">107</a><br>
33072 usage, <a href="#60">60</a>-<a href="#63">63</a></div>
33073 next method, <a href="#87">87</a><br>
33074 open method, <a href="#58">58</a>-<a href="#59">59</a><br>
33075 pointers, <a href="#61">61</a><br>
33076 race conditions, <a href="#107">107</a><br>
33077 read method, <a href="#63">63</a>-<a href="#69">69</a><br>
33078 read_proc method, <a href="#85">85</a><br>
33079 readv calls, <a href="#69">69</a><br>
33080 release method, <a href="#59">59</a><br>
33081 semaphores, <a href="#112">112</a><br>
33082 show method, <a href="#88">88</a><br>
33083 stop method, <a href="#88">88</a><br>
33084 write method, <a href="#63">63</a>-<a href="#69">69</a><br>
33085 writev calls, <a href="#69">69</a></div>
33086 scull driver (example), <a href="#42">42</a><br>
33087 scullc driver (example), <a href="#219">219</a><br>
33088 scull_cleanup function, <a href="#179">179</a><br>
33089 scull_getwritespace function, <a href="#158">158</a><br>
33090 scullp<br>
33091 <div class="bql">example, <a href="#223">223</a><br>
33092 mmap implementations, <a href="#431">431</a></div>
33093 scullpipe devices (example), <a href="#153">153</a>-<a href="#162">162</a><br>
33094 scullsingle device, <a href="#174">174</a><br>
33095 sculluid code, <a href="#175">175</a><br>
33096 scullv driver (example), <a href="#227">227</a>, <a href="#233">233</a><br>
33097 searching PCI drivers, <a href="#326">326</a><br>
33098 sectors (size of), <a href="#470">470</a><br>
33099 sector_t bi_sector field (bio structure), <a href="#482">482</a><br>
33100 sector_t capacity field (gendisk), <a href="#467">467</a><br>
33101 sector_t sector field (request structure), <a href="#476">476</a><br>
33102 secure attention key (SAK) function, <a href="#97">97</a><br>
33103 security, <a href="#8">8</a><br>
33104 seeking devices, <a href="#171">171</a><br>
33105 select method, <a href="#163">163</a>-<a href="#169">169</a><br>
33106 <div class="bql">poll method and, <a href="#51">51</a></div>
33107 semaphores, <a href="#109">109</a><br>
33108 <div class="bql">completion, <a href="#114">114</a>-<a href="#116">116</a><br>
33109 implementation, <a href="#110">110</a>-<a href="#114">114</a><br>
33110 reader/writer, <a href="#113">113</a><br>
33111 unlocking, <a href="#110">110</a></div>
33112 sendfile system, <a href="#52">52</a><br>
33113 sendpage system, <a href="#52">52</a><br>
33114 seq_file interface, <a href="#87">87</a>-<a href="#90">90</a><br>
33115 seqlocks, <a href="#127">127</a><br>
33116 SEQNUM variable, <a href="#399">399</a><br>
33117 sequences (race conditions), <a href="#107">107</a><br>
33118 </td></tr></table>
33119 <br>
33120 <A name="609"></a><font color="blue">PAGE 609</font><br>
33121 <br>
33122 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
33123 serial line configuration, <a href="#565">565</a><br>
33124 serial_icounter_struct structure, <a href="#566">566</a><br>
33125 set_bit operation, <a href="#126">126</a><br>
33126 set_config method, <a href="#512">512</a><br>
33127 setconsole program, <a href="#77">77</a><br>
33128 set_dma_addr function, <a href="#457">457</a><br>
33129 set_dma_count function, <a href="#457">457</a><br>
33130 set_dma_mode function, <a href="#457">457</a><br>
33131 set_mac_address method, <a href="#513">513</a><br>
33132 set_mb function, <a href="#238">238</a><br>
33133 set_multicast_list function, <a href="#539">539</a><br>
33134 set_multicast_list method, <a href="#510">510</a>, <a href="#513">513</a><br>
33135 set_rmb function, <a href="#238">238</a><br>
33136 setterm program, <a href="#147">147</a><br>
33137 set_termios function, <a href="#560">560</a><br>
33138 set_wmb function, <a href="#238">238</a><br>
33139 sfile argument, <a href="#87">87</a><br>
33140 sg_dma_address function, <a href="#462">462</a><br>
33141 sg_dma_address macro, <a href="#451">451</a><br>
33142 sg_dma_len function, <a href="#462">462</a><br>
33143 sg_dma_len macro, <a href="#451">451</a><br>
33144 sharing<br>
33145 <div class="bql">code, <a href="#108">108</a><br>
33146 interrupt handlers, <a href="#278">278</a>-<a href="#281">281</a><br>
33147 queues, <a href="#207">207</a></div>
33148 short delays, <a href="#195">195</a>-<a href="#196">196</a><br>
33149 <div class="bql">sleeps, <a href="#196">196</a></div>
33150 short driver (example), <a href="#246">246</a><br>
33151 <div class="bql">accessing I/O memory, <a href="#252">252</a><br>
33152 implementing interrupt handlers, <a href="#270">270</a><br>
33153 installing interrupt handlers, <a href="#261">261</a><br>
33154 probing, <a href="#266">266</a></div>
33155 short module, <a href="#265">265</a><br>
33156 shortprint drivers, <a href="#282">282</a>-<a href="#286">286</a><br>
33157 show function, <a href="#386">386</a><br>
33158 show method<br>
33159 <div class="bql">kobjects, <a href="#373">373</a><br>
33160 seq_file interface, <a href="#88">88</a></div>
33161 shutdown, <a href="#31">31</a>, <a href="#362">362</a><br>
33162 shutting down modules (see unloading, modules)<br>
33163 SIGIO signal, <a href="#169">169</a><br>
33164 signal handling, <a href="#154">154</a><br>
33165 Simple Character Utility for Loading Localitie (see scull)<br>
33166 Simple Hardware Operations and Raw Tests (see short driver)<br>
33167 simple sleeping, <a href="#149">149</a><br>
33168 single-open devices, <a href="#173">173</a><br>
33169 single-page streaming mappings, <a href="#450">450</a><br>
33170 </td><td valign="top" width="50%">
33171 SIOCDEVPRIVATE commands, <a href="#535">535</a><br>
33172 SIOCSIFADDR command, <a href="#535">535</a><br>
33173 SIOCSIFMAP command, <a href="#535">535</a><br>
33174 size<br>
33175 <div class="bql">data explicitly, <a href="#290">290</a><br>
33176 explicit, <a href="#290">290</a><br>
33177 kmalloc argument, <a href="#216">216</a><br>
33178 pages, <a href="#292">292</a><br>
33179 ports, <a href="#240">240</a><br>
33180 of sectors, <a href="#470">470</a></div>
33181 skb_headlen function, <a href="#532">532</a><br>
33182 skb_headroom function, <a href="#531">531</a><br>
33183 skb_is_nonlinear functions, <a href="#532">532</a><br>
33184 skb_pull function, <a href="#532">532</a><br>
33185 skb_push function, <a href="#531">531</a><br>
33186 skb_put function, <a href="#531">531</a><br>
33187 skb_reserve function, <a href="#531">531</a><br>
33188 skb_tailroom function, <a href="#531">531</a><br>
33189 sk_buff structure<br>
33190 <div class="bql">fields for, <a href="#529">529</a><br>
33191 transmitting packets, <a href="#516">516</a></div>
33192 skbuff.h header file, <a href="#516">516</a><br>
33193 SLAB_CACHE_DMA flag, <a href="#218">218</a><br>
33194 SLAB_CTOR_ATOMIC flag, <a href="#218">218</a><br>
33195 SLAB_CTOR_CONSTRUCTOR flag, <a href="#218">218</a><br>
33196 SLAB_HWCACHE_ALIGN flag, <a href="#218">218</a><br>
33197 SLAB_NO_REAP flag, <a href="#218">218</a><br>
33198 sleep_on function, <a href="#162">162</a><br>
33199 sleeps<br>
33200 <div class="bql">locking, <a href="#110">110</a><br>
33201 manual, <a href="#156">156</a><br>
33202 processes, <a href="#147">147</a>-<a href="#162">162</a><br>
33203 short delays, <a href="#196">196</a><br>
33204 spinlocks, <a href="#118">118</a></div>
33205 slow downs (avoiding), <a href="#82">82</a><br>
33206 slow interrupt handlers, <a href="#268">268</a><br>
33207 SMP (symmetric multiprocessor) systems, <a href="#21">21</a><br>
33208 snullnet0 (IP number), <a href="#499">499</a><br>
33209 socket buffers, <a href="#516">516</a>, <a href="#528">528</a>-<a href="#532">532</a><br>
33210 <div class="bql">allocation, <a href="#522">522</a></div>
33211 software<br>
33212 <div class="bql">loops, <a href="#195">195</a><br>
33213 versions (see versions, numbering)<br>
33214 (see also applications versus kernel modules)</div>
33215 software-mapped I/O memory (ioremap function), <a href="#250">250</a><br>
33216 SPARC architecture, <a href="#244">244</a><br>
33217 SPARC64 platform (data alignment), <a href="#294">294</a><br>
33218 special files, <a href="#43">43</a><br>
33219 </td></tr></table>
33220 <br>
33221 <A name="610"></a><font color="blue">PAGE 610</font><br>
33222 <br>
33223 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
33224 spinlocks<br>
33225 <div class="bql">dma_spin_lock, <a href="#457">457</a><br>
33226 hard_start_xmit function, <a href="#518">518</a><br>
33227 releasing, <a href="#120">120</a><br>
33228 xmit_lock function, <a href="#514">514</a></div>
33229 splitting kernels, <a href="#4">4</a>-<a href="#5">5</a><br>
33230 stacking modules, <a href="#28">28</a><br>
33231 standard C data types, <a href="#288">288</a><br>
33232 start method, <a href="#87">87</a><br>
33233 stat file, <a href="#263">263</a><br>
33234 state of request processing, <a href="#483">483</a><br>
33235 statements<br>
33236 <div class="bql">goto, <a href="#33">33</a><br>
33237 printk (see printk function)<br>
33238 switch<br>
33239 <div class="bql">with ioctl method, <a href="#136">136</a><br>
33240 return values, <a href="#140">140</a></div></div>
33241 static functions (locking), <a href="#121">121</a><br>
33242 static numbers, assignment of, <a href="#46">46</a><br>
33243 statistics<br>
33244 <div class="bql">on caches, <a href="#219">219</a><br>
33245 on interrupts, <a href="#263">263</a><br>
33246 on network drivers, <a href="#536">536</a><br>
33247 on network interfaces, <a href="#504">504</a>, <a href="#512">512</a>, <a href="#536">536</a></div>
33248 status information, <a href="#514">514</a><br>
33249 stop method, <a href="#88">88</a>, <a href="#512">512</a><br>
33250 store method (kobjects), <a href="#373">373</a><br>
33251 strace command, <a href="#91">91</a><br>
33252 strace tool, <a href="#162">162</a><br>
33253 streaming<br>
33254 <div class="bql">DMA mappings, <a href="#446">446</a>, <a href="#448">448</a><br>
33255 single-page mappings, <a href="#450">450</a></div>
33256 string operations, <a href="#241">241</a>, <a href="#255">255</a><br>
33257 struct block_device_operations *fops field (gendisk), <a href="#467">467</a><br>
33258 struct bus_type *bus field, <a href="#382">382</a><br>
33259 struct cdev *i_cdev (inode structure field), <a href="#55">55</a><br>
33260 struct dentry *f_dentry (struct file field), <a href="#54">54</a><br>
33261 struct device fields, <a href="#381">381</a><br>
33262 struct device *parent field, <a href="#381">381</a><br>
33263 struct device_driver *driver field, <a href="#382">382</a><br>
33264 struct device_driver structure, <a href="#385">385</a><br>
33265 struct file, <a href="#53">53</a><br>
33266 struct file_operations *f_op (struct file field), <a href="#54">54</a><br>
33267 struct file_operations *fops variable (USB), <a href="#353">353</a><br>
33268 struct kobject kobj field, <a href="#381">381</a><br>
33269 struct module *owner function, <a href="#348">348</a><br>
33270 struct module *owner method, <a href="#50">50</a><br>
33271 struct net_device *next field (net_device structure), <a href="#506">506</a><br>
33272 </td><td valign="top" width="50%">
33273 struct pci_device_id structure (PCI), <a href="#309">309</a><br>
33274 struct request structure, <a href="#476">476</a><br>
33275 struct request_queue *queue field (gendisk), <a href="#467">467</a><br>
33276 struct scull_qset structure, <a href="#62">62</a><br>
33277 struct termios structure (tty drivers), <a href="#550">550</a>-<a href="#553">553</a><br>
33278 struct timeval pointer, <a href="#188">188</a><br>
33279 struct tty_flip_buffer structure, <a href="#559">559</a><br>
33280 struct urb structure, <a href="#336">336</a><br>
33281 struct usb_device *dev field (USB), <a href="#336">336</a><br>
33282 struct usb_device_id structure (USB), <a href="#346">346</a><br>
33283 struct usb_driver structure, <a href="#349">349</a><br>
33284 struct usb_host_interface *altsetting field (USB), <a href="#331">331</a><br>
33285 struct usb_host_interface *cur_altsetting field (USB), <a href="#332">332</a><br>
33286 struct usb_interface structure, <a href="#351">351</a><br>
33287 struct usb_iso_packet_descriptor iso_frame_desc field (USB), <a href="#341">341</a><br>
33288 structures<br>
33289 <div class="bql">bin_attribute, <a href="#374">374</a><br>
33290 bio, <a href="#482">482</a>, <a href="#487">487</a><br>
33291 bus_type, <a href="#378">378</a><br>
33292 cdev configuration, <a href="#56">56</a><br>
33293 data, <a href="#49">49</a>, <a href="#49">49</a>-<a href="#53">53</a><br>
33294 devices, <a href="#383">383</a><br>
33295 dev_mc_list, <a href="#538">538</a><br>
33296 drivers, <a href="#386">386</a><br>
33297 file_operations (mmap method and), <a href="#424">424</a><br>
33298 gendisk, <a href="#467">467</a><br>
33299 ifreq, <a href="#535">535</a><br>
33300 kobjects, <a href="#364">364</a>-<a href="#371">371</a><br>
33301 kset_hotplug_ops, <a href="#376">376</a><br>
33302 ldd_driver, <a href="#386">386</a><br>
33303 net_device, <a href="#502">502</a>, <a href="#506">506</a>-<a href="#507">507</a><br>
33304 net_device_stats, <a href="#505">505</a>, <a href="#536">536</a><br>
33305 registration, <a href="#55">55</a>-<a href="#57">57</a><br>
33306 scatterlist, <a href="#462">462</a><br>
33307 serial_icounter_struct, <a href="#566">566</a><br>
33308 sk_buff, <a href="#529">529</a><br>
33309 struct device_driver, <a href="#385">385</a><br>
33310 struct request, <a href="#476">476</a><br>
33311 struct scull_qset, <a href="#62">62</a><br>
33312 struct termios (tty drivers), <a href="#550">550</a>-<a href="#553">553</a><br>
33313 struct tty_flip_buffer, <a href="#559">559</a><br>
33314 struct urb, <a href="#336">336</a><br>
33315 struct usb_driver, <a href="#349">349</a><br>
33316 struct usb_interface, <a href="#351">351</a><br>
33317 tty_driver, <a href="#567">567</a><br>
33318 tty_operations, <a href="#569">569</a><br>
33319 tty_struct, <a href="#571">571</a></div>
33320 </td></tr></table>
33321 <br>
33322 <A name="611"></a><font color="blue">PAGE 611</font><br>
33323 <br>
33324 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
33325 <div class="bql">vm_area_struct, <a href="#420">420</a><br>
33326 vm_operations_struct, <a href="#421">421</a></div>
33327 submission of urbs, <a href="#344">344</a>, <a href="#354">354</a><br>
33328 SUBSYSTEM variable, <a href="#399">399</a><br>
33329 subsystems, <a href="#368">368</a><br>
33330 <div class="bql">classes, <a href="#391">391</a><br>
33331 deviceID register (PCI), <a href="#309">309</a><br>
33332 firmware, <a href="#407">407</a><br>
33333 ksets, <a href="#370">370</a><br>
33334 memory management, <a href="#4">4</a><br>
33335 module stacking, <a href="#29">29</a><br>
33336 USB (see USB)<br>
33337 vendorID register (PCI), <a href="#309">309</a></div>
33338 Super-H architecture, <a href="#244">244</a><br>
33339 supervisor mode, <a href="#20">20</a><br>
33340 support<br>
33341 <div class="bql">Ethtool, <a href="#541">541</a><br>
33342 kernels (debugging), <a href="#73">73</a>-<a href="#75">75</a><br>
33343 MII, <a href="#540">540</a><br>
33344 multicasting, <a href="#538">538</a></div>
33345 swappers, <a href="#193">193</a><br>
33346 switch statements<br>
33347 <div class="bql">return values, <a href="#140">140</a><br>
33348 with ioctl method, <a href="#136">136</a></div>
33349 symbolic links (kobjects), <a href="#375">375</a><br>
33350 symbols, <a href="#28">28</a>-<a href="#29">29</a><br>
33351 <div class="bql">BLK_BOUNCE_HIGH, <a href="#480">480</a><br>
33352 bytes, <a href="#300">300</a><br>
33353 CHECKSUM, <a href="#523">523</a><br>
33354 DMA_BIDIRECTIONAL, <a href="#448">448</a><br>
33355 DMA_FROM_DEVICE, <a href="#448">448</a><br>
33356 DMA_NONE, <a href="#448">448</a><br>
33357 DMA_TO_DEVICE, <a href="#448">448</a>, <a href="#461">461</a><br>
33358 IFF_, <a href="#538">538</a><br>
33359 NR_IRQS, <a href="#267">267</a><br>
33360 PAGE_SIZE, <a href="#423">423</a><br>
33361 PCI_DMA_FROMDEVICE, <a href="#449">449</a><br>
33362 PCI_DMA_TODEVICE, <a href="#449">449</a><br>
33363 PDEBUG/PDEBUGG, <a href="#80">80</a><br>
33364 symbol table, <a href="#28">28</a>-<a href="#29">29</a></div>
33365 symmetric multiprocessor (SMP) systems, <a href="#21">21</a><br>
33366 synchronization<br>
33367 <div class="bql">DMA buffers, <a href="#452">452</a><br>
33368 semaphores, <a href="#114">114</a></div>
33369 sysfs directory<br>
33370 <div class="bql">trees (USB), <a href="#333">333</a>-<a href="#335">335</a><br>
33371 tty driver, <a href="#552">552</a></div>
33372 sysfs filesystem, <a href="#409">409</a><br>
33373 <div class="bql">low-level operations, <a href="#371">371</a>-<a href="#375">375</a></div>
33374 syslogd daemon, <a href="#79">79</a><br>
33375 sysrq operations, <a href="#98">98</a><br>
33376 </td><td valign="top" width="50%">
33377 sysrq.txt file, <a href="#97">97</a><br>
33378 sys_syslog function, <a href="#77">77</a><br>
33379 system calls, <a href="#25">25</a><br>
33380 system faults<br>
33381 <div class="bql">debugging, <a href="#93">93</a>-<a href="#98">98</a><br>
33382 handling, <a href="#19">19</a></div>
33383 system hangs, <a href="#96">96</a>-<a href="#98">98</a><br>
33384 system shutdown, <a href="#362">362</a><br>
33386 <br><a name="T"></a><font color="red"><b>T</b></font><br><br>
33388 _t data types, <a href="#291">291</a><br>
33389 table pages, <a href="#418">418</a><br>
33390 <div class="bql">I/O memory and, <a href="#249">249</a><br>
33391 nopage VMA method, <a href="#427">427</a></div>
33392 tables, symbols, <a href="#28">28</a>-<a href="#29">29</a><br>
33393 tagged command queuing (TCQ), <a href="#492">492</a>-<a href="#493">493</a><br>
33394 tagged initialization formats, <a href="#53">53</a><br>
33395 tasklets, <a href="#202">202</a>-<a href="#204">204</a>, <a href="#211">211</a><br>
33396 <div class="bql">interrupt handlers, <a href="#276">276</a></div>
33397 tasklet_schedule function, <a href="#276">276</a><br>
33398 tcpdump program, <a href="#501">501</a><br>
33399 TCQ (tagged command queueing), <a href="#492">492</a>-<a href="#493">493</a><br>
33400 tearing down single-page streaming mappings, <a href="#450">450</a><br>
33401 templates, scull (design of), <a href="#42">42</a><br>
33402 terminals, selecting for messages, <a href="#77">77</a><br>
33403 termios userspace functions, <a href="#560">560</a><br>
33404 test system setup, <a href="#15">15</a><br>
33405 test_and_change_bit operation, <a href="#127">127</a><br>
33406 test_and_clear_bit operations, <a href="#127">127</a><br>
33407 test_and_set_bit operation, <a href="#127">127</a><br>
33408 test_bit operation, <a href="#127">127</a><br>
33409 testing<br>
33410 <div class="bql">block drivers, <a href="#468">468</a><br>
33411 char drivers, <a href="#70">70</a><br>
33412 hello world modules, <a href="#17">17</a><br>
33413 scullpipe drivers, <a href="#162">162</a></div>
33414 thread execution, <a href="#109">109</a><br>
33415 throughput (DMA), <a href="#440">440</a>-<a href="#459">459</a><br>
33416 time, <a href="#208">208</a><br>
33417 <div class="bql">boot (PCI), <a href="#306">306</a><br>
33418 current time (retrieving), <a href="#188">188</a>-<a href="#190">190</a><br>
33419 execution of code (delaying), <a href="#190">190</a>-<a href="#196">196</a>, <a href="#209">209</a><br>
33420 HZ (time frequency), <a href="#183">183</a>, <a href="#292">292</a><br>
33421 intervals of (data type portability), <a href="#292">292</a><br>
33422 kernel timers, <a href="#202">202</a><br>
33423 lapses (measurement of), <a href="#183">183</a>-<a href="#188">188</a><br>
33424 tasklets, <a href="#202">202</a>-<a href="#204">204</a><br>
33425 time intervals in the kernel, <a href="#292">292</a><br>
33426 workqueues, <a href="#205">205</a>-<a href="#208">208</a></div>
33427 </td></tr></table>
33428 <br>
33429 <A name="612"></a><font color="blue">PAGE 612</font><br>
33430 <br>
33431 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
33432 timeouts<br>
33433 <div class="bql">configuration, <a href="#193">193</a><br>
33434 scheduling, <a href="#194">194</a><br>
33435 transmission (see transmission timeouts)</div>
33436 timer.h header file, <a href="#198">198</a><br>
33437 timer_list structure, <a href="#198">198</a><br>
33438 timers, <a href="#202">202</a><br>
33439 <div class="bql">interrupts, <a href="#183">183</a><br>
33440 kernels, <a href="#196">196</a>-<a href="#202">202</a>, <a href="#210">210</a></div>
33441 timestamp counter (TSC), <a href="#186">186</a><br>
33442 tiny_close function, <a href="#556">556</a><br>
33443 tiny_tty_driver variable, <a href="#551">551</a><br>
33444 TIOCLINUX command, <a href="#77">77</a><br>
33445 tiocmget function, <a href="#562">562</a><br>
33446 tiocmset functions, <a href="#562">562</a><br>
33447 token ring networks, setting up interfaces for, <a href="#508">508</a><br>
33448 tools<br>
33449 <div class="bql">debuggers, <a href="#99">99</a>-<a href="#105">105</a><br>
33450 Ethtool, <a href="#541">541</a><br>
33451 kernels (enabling configuration options), <a href="#73">73</a>-<a href="#75">75</a><br>
33452 lockmeter, <a href="#123">123</a><br>
33453 /sbin/hotplug utility, <a href="#398">398</a><br>
33454 strace, <a href="#162">162</a><br>
33455 timers, <a href="#196">196</a>-<a href="#202">202</a><br>
33456 (see also debugging; utilities)</div>
33457 top halves (interrupt handlers), <a href="#275">275</a>-<a href="#278">278</a><br>
33458 tracing programs, <a href="#105">105</a><br>
33459 tracking<br>
33460 <div class="bql">registration, <a href="#33">33</a><br>
33461 struct scull_qset (structure), <a href="#62">62</a></div>
33462 transfers<br>
33463 <div class="bql">buffers, <a href="#448">448</a><br>
33464 DMA, <a href="#440">440</a>-<a href="#459">459</a>, <a href="#461">461</a><br>
33465 USB without urbs, <a href="#356">356</a>-<a href="#359">359</a></div>
33466 transistor-transistor logic (TTL) levels, <a href="#245">245</a><br>
33467 transmission concurrency, controlling, <a href="#518">518</a><br>
33468 transmission of packets, <a href="#501">501</a>, <a href="#516">516</a>-<a href="#520">520</a><br>
33469 transmission timeouts, <a href="#504">504</a>, <a href="#519">519</a><br>
33470 <div class="bql">tx_timeout method and, <a href="#512">512</a><br>
33471 watchdog_timeo field and, <a href="#514">514</a></div>
33472 traps (locking), <a href="#121">121</a>-<a href="#123">123</a><br>
33473 traversal of linked lists, <a href="#298">298</a><br>
33474 tr_configure function, <a href="#508">508</a><br>
33475 trees<br>
33476 <div class="bql">/dev, <a href="#403">403</a><br>
33477 sysfs (USB and), <a href="#333">333</a>-<a href="#335">335</a><br>
33478 tty drivers, <a href="#548">548</a></div>
33479 troubleshooting, <a href="#73">73</a><br>
33480 <div class="bql">caches, <a href="#237">237</a>, <a href="#425">425</a>, <a href="#445">445</a><br>
33481 DMA hardware, <a href="#444">444</a></div>
33482 </td><td valign="top" width="50%">
33483 <div class="bql">fragmentation, <a href="#442">442</a><br>
33484 locking, <a href="#121">121</a>-<a href="#123">123</a><br>
33485 memory (scull), <a href="#107">107</a><br>
33486 porting problems, <a href="#242">242</a><br>
33487 system hangs, <a href="#96">96</a><br>
33488 values, <a href="#295">295</a><br>
33489 wrong font on console, <a href="#147">147</a></div>
33490 truncating devices on open, <a href="#59">59</a><br>
33491 TSC (timestamp counter), <a href="#186">186</a><br>
33492 TTL (transistor-transistor logic) levels, <a href="#245">245</a><br>
33493 tty drivers, <a href="#546">546</a>-<a href="#550">550</a><br>
33494 <div class="bql">buffers, <a href="#558">558</a><br>
33495 directories, <a href="#566">566</a><br>
33496 functions, <a href="#573">573</a><br>
33497 line settings, <a href="#560">560</a>-<a href="#566">566</a><br>
33498 pointers, <a href="#553">553</a>-<a href="#560">560</a><br>
33499 struct termios, <a href="#550">550</a>-<a href="#553">553</a><br>
33500 sysfs directories, <a href="#552">552</a><br>
33501 tty_driver structure, <a href="#567">567</a><br>
33502 tty_operations structure, <a href="#569">569</a><br>
33503 tty_struct structure, <a href="#571">571</a></div>
33504 tty_driver structure, <a href="#567">567</a>, <a href="#569">569</a>, <a href="#571">571</a><br>
33505 TTY_DRIVER_NO_DEVFS flag, <a href="#553">553</a><br>
33506 TTY_DRIVER_REAL_RAW flag, <a href="#553">553</a><br>
33507 TTY_DRIVER_RESET_TERMIOS flag, <a href="#552">552</a><br>
33508 tty_get_baud_rate function, <a href="#562">562</a><br>
33509 tty_register_driver function, <a href="#549">549</a><br>
33510 tunelp program, <a href="#3">3</a><br>
33511 turning messages on/off, <a href="#79">79</a><br>
33512 tx_timeout method, <a href="#512">512</a>, <a href="#519">519</a><br>
33513 TYPE variable, <a href="#401">401</a><br>
33514 types<br>
33515 <div class="bql">addresses, <a href="#413">413</a><br>
33516 bus_attribute, <a href="#380">380</a><br>
33517 module parameter support, <a href="#36">36</a><br>
33518 PCI driver support, <a href="#325">325</a></div>
33520 <br><a name="U"></a><font color="red"><b>U</b></font><br><br>
33522 u16 bcdDevice_hi field (USB), <a href="#346">346</a><br>
33523 u16 bcdDevice_lo field (USB), <a href="#346">346</a><br>
33524 u16 idProduct field (USB), <a href="#346">346</a><br>
33525 u16 idVendor field (USB), <a href="#346">346</a><br>
33526 u16 match_flags field (USB), <a href="#346">346</a><br>
33527 u8 bDeviceClass field (USB), <a href="#347">347</a><br>
33528 u8 bDeviceProtocol field (USB), <a href="#347">347</a><br>
33529 u8 bDeviceSubClass field (USB), <a href="#347">347</a><br>
33530 u8 bInterfaceClass field (USB), <a href="#347">347</a><br>
33531 u8 bInterfaceProtocol field (USB), <a href="#347">347</a><br>
33532 u8 bInterfaceSubClass field (USB), <a href="#347">347</a><br>
33533 u8, u16, u32, u64 data types, <a href="#290">290</a><br>
33534 uaccess.h header file, <a href="#64">64</a>, <a href="#72">72</a>, <a href="#142">142</a>, <a href="#180">180</a><br>
33535 udelay, <a href="#196">196</a><br>
33536 </td></tr></table>
33537 <br>
33538 <A name="613"></a><font color="blue">PAGE 613</font><br>
33539 <br>
33540 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
33541 uint8_t/uint32_t types, <a href="#290">290</a><br>
33542 uintptr_t type (C99 standard), <a href="#289">289</a><br>
33543 unaligned data, <a href="#293">293</a><br>
33544 <div class="bql">access, <a href="#300">300</a></div>
33545 unaligned.h header file, <a href="#293">293</a><br>
33546 unidirectional pipes (USB endpoints), <a href="#329">329</a><br>
33547 uniprocessor systems, concurrency in, <a href="#21">21</a><br>
33548 universal serial bus (see USB)<br>
33549 Unix<br>
33550 <div class="bql">filesystems, <a href="#4">4</a><br>
33551 interfaces (access to), <a href="#7">7</a></div>
33552 unlinking urbs, <a href="#345">345</a><br>
33553 unloading<br>
33554 <div class="bql">modules, <a href="#18">18</a>, <a href="#25">25</a>, <a href="#505">505</a><br>
33555 USB drivers, <a href="#349">349</a></div>
33556 unlocking semaphores, <a href="#110">110</a><br>
33557 unmapping, DMA buffers, <a href="#449">449</a><br>
33558 <div class="bql">(see also mapping)</div>
33559 unregistering facilities, <a href="#33">33</a><br>
33560 unregister_netdev function, <a href="#505">505</a><br>
33561 unshielded twisted pair (UTP), <a href="#510">510</a><br>
33562 unsigned char *setup_packet field (USB), <a href="#338">338</a><br>
33563 unsigned int bi_size field (bio structure), <a href="#482">482</a><br>
33564 unsigned int f_flags (struct file field), <a href="#54">54</a><br>
33565 unsigned int irq function, <a href="#260">260</a><br>
33566 unsigned int pipe field (USB), <a href="#336">336</a><br>
33567 unsigned int transfer_flags field (USB), <a href="#337">337</a><br>
33568 unsigned long bi_flags field (bio structure), <a href="#482">482</a><br>
33569 unsigned long flags field (memory), <a href="#417">417</a><br>
33570 unsigned long flags function, <a href="#260">260</a><br>
33571 unsigned long method, <a href="#52">52</a><br>
33572 unsigned long nr_sectors field (request structure), <a href="#476">476</a><br>
33573 unsigned long pci_resource_end function, <a href="#317">317</a><br>
33574 unsigned long pci_resource_flags function, <a href="#317">317</a><br>
33575 unsigned long pci_resource_start function, <a href="#317">317</a><br>
33576 unsigned long state field (net_device structure), <a href="#506">506</a><br>
33577 unsigned num_altsetting field (USB), <a href="#332">332</a><br>
33578 unsigned short bio_hw_segments field (bio structure), <a href="#482">482</a><br>
33579 unsigned short bio_phys_segments field (bio structure), <a href="#482">482</a><br>
33580 unsigned type, <a href="#240">240</a><br>
33581 up function, <a href="#111">111</a><br>
33582 updates, RCU, <a href="#129">129</a><br>
33583 urandom device, <a href="#260">260</a><br>
33584 </td><td valign="top" width="50%">
33585 urbs<br>
33586 <div class="bql">cancellation of, <a href="#345">345</a><br>
33587 interrupts, <a href="#342">342</a><br>
33588 killing, <a href="#345">345</a><br>
33589 submitting, <a href="#344">344</a><br>
33590 unlinking, <a href="#345">345</a><br>
33591 USB, <a href="#335">335</a>-<a href="#346">346</a><br>
33592 <div class="bql">creating/destroying, <a href="#341">341</a><br>
33593 struct urb structure, <a href="#336">336</a><br>
33594 submitting, <a href="#354">354</a><br>
33595 transfers without, <a href="#356">356</a>-<a href="#359">359</a></div></div>
33596 urbs_completion function, <a href="#345">345</a><br>
33597 usage count, <a href="#426">426</a><br>
33598 <div class="bql">decremented by release method, <a href="#59">59</a><br>
33599 incremented by open method, <a href="#58">58</a><br>
33600 nopage method and, <a href="#432">432</a></div>
33601 USB request blocks (see urbs)<br>
33602 USB (universal serial bus), <a href="#7">7</a>, <a href="#327">327</a>-<a href="#332">332</a><br>
33603 <div class="bql">configurations, <a href="#332">332</a><br>
33604 hotplugging, <a href="#401">401</a><br>
33605 stacking, <a href="#28">28</a><br>
33606 sysfs directory tree, <a href="#333">333</a>-<a href="#335">335</a><br>
33607 transfers without urbs, <a href="#356">356</a>-<a href="#359">359</a><br>
33608 urbs, <a href="#335">335</a>-<a href="#346">346</a><br>
33609 writing, <a href="#346">346</a>-<a href="#355">355</a></div>
33610 usb_alloc_urb function, <a href="#342">342</a><br>
33611 usb_bulk_msg function, <a href="#356">356</a><br>
33612 usb_control_msg function, <a href="#357">357</a><br>
33613 usbcore module, <a href="#28">28</a><br>
33614 USB_DEVICE macro, <a href="#347">347</a><br>
33615 USB_DEVICE_INFO macros, <a href="#347">347</a><br>
33616 USB_DEVICE_VER macro, <a href="#347">347</a><br>
33617 usb_fill_bulk_urb function, <a href="#343">343</a><br>
33618 usb_fill_control_urb function, <a href="#343">343</a><br>
33619 usb_fill_int_urb function, <a href="#342">342</a><br>
33620 usb_get_descriptor function, <a href="#358">358</a><br>
33621 USB_INTERFACE_INFO macro, <a href="#347">347</a><br>
33622 usb_kill_urb function, <a href="#345">345</a><br>
33623 usb_register_dev function, <a href="#352">352</a><br>
33624 usb_set_intfdata function, <a href="#351">351</a><br>
33625 usb_string function, <a href="#359">359</a><br>
33626 usb_submit_urb function, <a href="#344">344</a><br>
33627 usb_unlink_urb function, <a href="#345">345</a><br>
33628 user mode, <a href="#20">20</a><br>
33629 user programs, <a href="#3">3</a><br>
33630 user space, <a href="#19">19</a><br>
33631 <div class="bql">capabilities/restrictions in, <a href="#144">144</a><br>
33632 communication with, <a href="#362">362</a><br>
33633 direct I/O, <a href="#435">435</a>-<a href="#440">440</a><br>
33634 explicitly sizing data in, <a href="#290">290</a><br>
33635 I/O port access from, <a href="#241">241</a></div>
33636 </td></tr></table>
33637 <br>
33638 <A name="614"></a><font color="blue">PAGE 614</font><br>
33639 <br>
33640 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
33641 user space <i>(continued)</i><br>
33642 <div class="bql">programming, <a href="#19">19</a>, <a href="#37">37</a>, <a href="#39">39</a><br>
33643 retrieving datum from, <a href="#143">143</a><br>
33644 transferring to/from kernel space, <a href="#63">63</a><br>
33645 tty drivers, <a href="#560">560</a>-<a href="#566">566</a><br>
33646 writing drivers in, <a href="#37">37</a></div>
33647 user virtual addresses, <a href="#413">413</a><br>
33648 User-Mode Linux, <a href="#104">104</a><br>
33649 utilities, <a href="#3">3</a><br>
33650 <div class="bql">insmod, <a href="#17">17</a><br>
33651 modprobe, <a href="#25">25</a>, <a href="#29">29</a><br>
33652 rmmod, <a href="#17">17</a><br>
33653 (see also programs)</div>
33654 utility fields (net_device structure), <a href="#514">514</a><br>
33655 UTP (unshielded twisted pair), <a href="#510">510</a><br>
33656 UTS_RELEASE macro, <a href="#27">27</a><br>
33658 <br><a name="V"></a><font color="red"><b>V</b></font><br><br>
33660 values<br>
33661 <div class="bql">BogoMips, <a href="#195">195</a><br>
33662 errors, <a href="#295">295</a><br>
33663 jiffies, <a href="#184">184</a>, <a href="#514">514</a><br>
33664 loops_per_jiffy, <a href="#196">196</a><br>
33665 return<br>
33666 <div class="bql">interrupt handlers, <a href="#272">272</a><br>
33667 switch statements, <a href="#140">140</a></div></div>
33668 variables<br>
33669 <div class="bql">ACTION, <a href="#399">399</a><br>
33670 atomic, <a href="#124">124</a><br>
33671 char*name (USB), <a href="#352">352</a><br>
33672 console_loglevel, <a href="#77">77</a><br>
33673 DEVICE, <a href="#402">402</a><br>
33674 DEVPATH, <a href="#399">399</a><br>
33675 int minor_base (USB), <a href="#353">353</a><br>
33676 INTERFACE, <a href="#401">401</a><br>
33677 mode_t mode (USB), <a href="#353">353</a><br>
33678 NAME, <a href="#401">401</a><br>
33679 pci_bus_type, <a href="#392">392</a><br>
33680 PCI_CLASS, <a href="#400">400</a><br>
33681 PCI_ID, <a href="#400">400</a><br>
33682 PCI_SLOT_NAME, <a href="#400">400</a><br>
33683 PCI_SUBSYS_ID, <a href="#400">400</a><br>
33684 per-CPU, <a href="#228">228</a>-<a href="#230">230</a><br>
33685 PHYS, <a href="#401">401</a><br>
33686 PRODUCT, <a href="#401">401</a><br>
33687 SEQNUM, <a href="#399">399</a><br>
33688 struct file_operations *fops (USB), <a href="#353">353</a><br>
33689 SUBSYSTEM, <a href="#399">399</a><br>
33690 tiny_tty_driver, <a href="#551">551</a><br>
33691 TYPE, <a href="#401">401</a></div>
33692 vector operations, char drivers, <a href="#69">69</a><br>
33693 vendorID register (PCI), <a href="#309">309</a><br>
33694 </td><td valign="top" width="50%">
33695 VERIFY_ symbols, <a href="#142">142</a>, <a href="#180">180</a><br>
33696 version dependency, <a href="#26">26</a><br>
33697 version.h header file, <a href="#26">26</a>, <a href="#40">40</a><br>
33698 versions<br>
33699 <div class="bql">dependency, <a href="#26">26</a><br>
33700 numbering, <a href="#10">10</a>-<a href="#11">11</a><br>
33701 <div class="bql">char drivers, <a href="#43">43</a><br>
33702 major device numbers, <a href="#44">44</a><br>
33703 minor device numbers, <a href="#44">44</a><br>
33704 older char device registration, <a href="#57">57</a></div></div>
33705 VESA Local Bus (VLB), <a href="#323">323</a><br>
33706 vfree function, <a href="#225">225</a><br>
33707 video memory (mapping), <a href="#423">423</a><br>
33708 viewing kernels, <a href="#5">5</a><br>
33709 virt_to_page function, <a href="#417">417</a><br>
33710 virtual addresses, <a href="#414">414</a><br>
33711 <div class="bql">conversion, <a href="#444">444</a><br>
33712 remapping, <a href="#434">434</a><br>
33713 (see also addresses)</div>
33714 virtual memory, <a href="#413">413</a><br>
33715 <div class="bql">(see also memory)</div>
33716 virtual memory area (see VMA)<br>
33717 VLB (VESA Local Bus), <a href="#323">323</a><br>
33718 VMA (virtual memory area), <a href="#419">419</a>-<a href="#422">422</a>, <a href="#426">426</a><br>
33719 vmalloc allocation function, <a href="#224">224</a>-<a href="#228">228</a><br>
33720 vmalloc.h header file, <a href="#225">225</a><br>
33721 vm_area_struct structure, <a href="#420">420</a><br>
33722 VM_IO flag, <a href="#421">421</a><br>
33723 vm_operations_struct structure, <a href="#421">421</a><br>
33724 VM_RESERVED flag, <a href="#421">421</a><br>
33725 void barrier function, <a href="#237">237</a><br>
33726 void blk_queue_bounce_limit function, <a href="#480">480</a><br>
33727 void blk_queue_dma_alignment function, <a href="#481">481</a><br>
33728 void blk_queue_hardsect_size function, <a href="#481">481</a><br>
33729 void blk_queue_max_hw_segments function, <a href="#480">480</a><br>
33730 void blk_queue_max_phys_segments function, <a href="#480">480</a><br>
33731 void blk_queue_max_sectors function, <a href="#480">480</a><br>
33732 void blk_queue_max_segment_size function, <a href="#480">480</a><br>
33733 void blk_start_queue function, <a href="#480">480</a><br>
33734 void blk_stop_queue function, <a href="#480">480</a><br>
33735 void *context field (USB), <a href="#339">339</a><br>
33736 void *dev_id function, <a href="#260">260</a><br>
33737 void *driver_data field, <a href="#382">382</a><br>
33738 void field (PCI registration), <a href="#312">312</a><br>
33739 void function, <a href="#348">348</a><br>
33740 void mb function, <a href="#237">237</a><br>
33741 void *private_data field (gendisk), <a href="#467">467</a><br>
33742 void *private_data (struct file field), <a href="#54">54</a><br>
33743 </td></tr></table>
33744 <br>
33745 <A name="615"></a><font color="blue">PAGE 615</font><br>
33746 <br>
33747 <table cellspacing="0" cellpadding="0" width="100%"><tr><td valign="top" width="50%">
33748 void read_barrier_depends function, <a href="#237">237</a><br>
33749 void *release field, <a href="#382">382</a><br>
33750 void rmb function, <a href="#237">237</a><br>
33751 void smp_mb functions, <a href="#238">238</a><br>
33752 void smp_read_barrier_depends function, <a href="#238">238</a><br>
33753 void smp_rmb function, <a href="#238">238</a><br>
33754 void smp_wmb function, <a href="#238">238</a><br>
33755 void tasklet_disable function, <a href="#204">204</a><br>
33756 void tasklet_disable_nosync function, <a href="#204">204</a><br>
33757 void tasklet_enable function, <a href="#204">204</a><br>
33758 void tasklet_hi_schedule function, <a href="#204">204</a><br>
33759 void tasklet_kill function, <a href="#204">204</a><br>
33760 void tasklet_schedule function, <a href="#204">204</a><br>
33761 void *transfer_buffer field (USB), <a href="#338">338</a><br>
33762 void *virtual field (memory), <a href="#417">417</a><br>
33763 void wmb function, <a href="#237">237</a><br>
33765 <br><a name="W"></a><font color="red"><b>W</b></font><br><br>
33767 wait queues, <a href="#149">149</a>, <a href="#156">156</a>, <a href="#181">181</a><br>
33768 <div class="bql">delaying code execution, <a href="#194">194</a><br>
33769 poll table entries and, <a href="#167">167</a><br>
33770 putting processes into, <a href="#182">182</a></div>
33771 wait_event macro, <a href="#149">149</a><br>
33772 wait_event_interruptible_timeout function, <a href="#194">194</a><br>
33773 wake_up function, <a href="#150">150</a>, <a href="#159">159</a>, <a href="#181">181</a><br>
33774 wake_up_interruptible function, <a href="#181">181</a><br>
33775 wake_up_interruptible_sync function, <a href="#181">181</a><br>
33776 wake_up_sync function, <a href="#181">181</a><br>
33777 Wall flag, <a href="#291">291</a><br>
33778 watchdog_timeo field (net_device structure), <a href="#514">514</a>, <a href="#519">519</a><br>
33779 wc command, <a href="#92">92</a><br>
33780 wMaxPacketSize field (USB), <a href="#331">331</a><br>
33781 workqueues, <a href="#205">205</a>-<a href="#208">208</a>, <a href="#211">211</a><br>
33782 <div class="bql">interrupt handlers, <a href="#277">277</a></div>
33783 </td><td valign="top" width="50%">
33784 WQ_FLAG_EXCLUSIVE flag set, <a href="#160">160</a><br>
33785 write function (tty drivers), <a href="#556">556</a><br>
33786 write method, <a href="#50">50</a>, <a href="#63">63</a>-<a href="#69">69</a><br>
33787 <div class="bql">code for, <a href="#68">68</a><br>
33788 configuring DMA controller, <a href="#456">456</a><br>
33789 f_pos field (file structure) and, <a href="#54">54</a><br>
33790 oops messages, <a href="#94">94</a><br>
33791 poll method and, <a href="#166">166</a><br>
33792 return values, rules for interpreting, <a href="#68">68</a><br>
33793 select method and, <a href="#166">166</a><br>
33794 strace command and, <a href="#92">92</a></div>
33795 write system, <a href="#50">50</a><br>
33796 write-buffering example, <a href="#282">282</a><br>
33797 writev calls, <a href="#69">69</a><br>
33798 writev method, <a href="#52">52</a><br>
33799 writing, <a href="#73">73</a><br>
33800 <div class="bql">blocking/nonblocking operations, <a href="#151">151</a><br>
33801 control sequences to devices, <a href="#146">146</a><br>
33802 to a device, <a href="#63">63</a>-<a href="#66">66</a>, <a href="#68">68</a><br>
33803 drivers<br>
33804 <div class="bql">in user space, <a href="#37">37</a><br>
33805 role of, <a href="#2">2</a>-<a href="#4">4</a><br>
33806 version numbering, <a href="#10">10</a></div>
33807 UBS drivers, <a href="#346">346</a>-<a href="#355">355</a></div>
33809 <br><a name="X"></a><font color="red"><b>X</b></font><br><br>
33811 x86 architecture<br>
33812 <div class="bql">interrupt handling on, <a href="#268">268</a><br>
33813 porting and, <a href="#243">243</a></div>
33814 xmit_lock function, <a href="#514">514</a><br>
33815 xtime variable, <a href="#189">189</a><br>
33817 <br><a name="Z"></a><font color="red"><b>Z</b></font><br><br>
33819 zero-order limitations, <a href="#432">432</a><br>
33820 zones (memory), <a href="#215">215</a><br>
33821 zSeries architecture, <a href="#402">402</a><br>
33822 </td></tr></table>
33823 <br><br>
33824 <br>
33825 </html>
33826 </body>