%!PS-Adobe-3.0
%%BoundingBox: 0 0 595 792
%%LanguageLevel: 2
%%Creator: htmldoc 1.8.23 Copyright 1997-2002 Easy Software Products, All Rights Reserved.
%%CreationDate: D:20040802124942+0400
%%Title: The Linux Kernel Module Programming Guide
%%Generator: Modular DocBook HTML Stylesheet Version 1.7
%%Pages: 74
%%DocumentNeededResources:
%%+ font Courier
%%+ font Courier-Bold
%%+ font Courier-Oblique
%%+ font Times-Roman
%%+ font Times-Bold
%%+ font Times-Italic
%%+ font Helvetica
%%+ font Helvetica-Bold
%%+ font Helvetica-Oblique
%%+ font Helvetica-BoldOblique
%%+ font Symbol
%%DocumentData: Clean7bit
%%EndComments
%%BeginProlog
%%BeginResource: procset htmldoc-page 1.8 22
/BD{bind def}bind def/B{dup 0 exch rlineto exch 0 rlineto neg 0 exch rlineto
closepath stroke}BD/C{setrgbcolor}BD
/CM{concat}BD/DF{findfont dup length dict begin{1 index/FID ne{def}{pop pop}
ifelse}forall/Encoding fontencoding def currentdict end definefont pop}BD
/F{dup 0 exch rlineto exch 0 rlineto neg 0 exch rlineto closepath fill}BD
/FS{/hdFontSize exch def}BD/GS{gsave}BD/GR{grestore}BD/J{0 exch ashow}BD
/L{0 rlineto stroke}BD/M{moveto}BD/RO{rotate}BD/S{show}BD/SC{dup scale}BD
/SF{findfont hdFontSize scalefont setfont}BD/SP{showpage}BD/T{translate}BD
%%EndResource
/fontencoding[
/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef
/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef
/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef
/.notdef/.notdef/space/exclam/quotedbl/numbersign/dollar/percent/ampersand
/quotesingle/parenleft/parenright/asterisk/plus/comma/minus/period/slash/zero
/one/two/three/four/five/six/seven/eight/nine/colon/semicolon/less/equal/greater
/question/at/A/B/C/D/E/F/G/H/I/J/K/L/M/N/O/P/Q/R/S/T/U/V/W/X/Y/Z/bracketleft
/backslash/bracketright/asciicircum/underscore/grave/a/b/c/d/e/f/g/h/i/j/k/l/m/n
/o/p/q/r/s/t/u/v/w/x/y/z/braceleft/bar/braceright/asciitilde/.notdef/Euro
/.notdef/quotesinglbase/florin/quotedblbase/ellipsis/dagger/daggerdbl/circumflex
/perthousand/Scaron/guilsinglleft/OE/.notdef/.notdef/.notdef/.notdef/quoteleft
/quoteright/quotedblleft/quotedblright/bullet/endash/emdash/tilde/trademark
/scaron/guilsinglright/oe/.notdef/.notdef/Ydieresis/space/exclamdown/cent
/sterling/currency/yen/brokenbar/section/dieresis/copyright/ordfeminine
/guillemotleft/logicalnot/hyphen/registered/macron/degree/plusminus/twosuperior
/threesuperior/acute/mu/paragraph/periodcentered/cedilla/onesuperior
/ordmasculine/guillemotright/onequarter/onehalf/threequarters/questiondown
/Agrave/Aacute/Acircumflex/Atilde/Adieresis/Aring/AE/Ccedilla/Egrave/Eacute
/Ecircumflex/Edieresis/Igrave/Iacute/Icircumflex/Idieresis/Eth/Ntilde/Ograve
/Oacute/Ocircumflex/Otilde/Odieresis/multiply/Oslash/Ugrave/Uacute/Ucircumflex
/Udieresis/Yacute/Thorn/germandbls/agrave/aacute/acircumflex/atilde/adieresis
/aring/ae/ccedilla/egrave/eacute/ecircumflex/edieresis/igrave/iacute/icircumflex
/idieresis/eth/ntilde/ograve/oacute/ocircumflex/otilde/odieresis/divide/oslash
/ugrave/uacute/ucircumflex/udieresis/yacute/thorn/ydieresis]def
/F0/Courier DF
/F1/Courier-Bold DF
/F2/Courier-Oblique DF
/F4/Times-Roman DF
/F5/Times-Bold DF
/F6/Times-Italic DF
/F8/Helvetica DF
/F9/Helvetica-Bold DF
/Fa/Helvetica-Oblique DF
/Fb/Helvetica-BoldOblique DF
/Fc/Symbol findfont definefont pop
%%EndProlog
%%Page: title 3
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0 225.4 M 487.0 2.0 F
20 FS/F9 SF 0 634 M(The Linux Kernel Module Programming Guide)S
11 FS/F4 SF 0 579.4 M(Peter Jay Salzman)S
0 566.2 M(Ori Pomerantz)S
0 539.8 M(Copyright \251 2001 Peter Jay Salzman)S
0 500.2 M(The Linux Kernel Module Programming Guide is a free book; you may reproduce and/or modify it under the)S
0 487 M(terms of the Open Software License, version 1.1. You can obtain a copy of this license at)S
0 473.8 M(http://opensource.org/licenses/osl.php.)S
0 447.4 M(This book is distributed in the hope it will be useful, but without any warranty, without even the implied)S
0 434.2 M(warranty of merchantability or fitness for a particular purpose.)S
0 407.8 M(The author encourages wide distribution of this book for personal or commercial use, provided the above)S
0 394.6 M(copyright notice remains intact and the method adheres to the provisions of the Open Software License. In)S
0 381.4 M(summary, you may copy and distribute this book free of charge or for a profit. No explicit permission is)S
0 368.2 M(required from the author for reproduction of this book in any medium, physical or electronic.)S
0 341.8 M(Derivative works and translations of this document must be placed under the Open Software License, and the)S
0 328.6 M(original copyright notice must remain intact. If you have contributed new material to this book, you must)S
0 315.4 M(make the material and source code available for your revisions. Please make revisions and updates available)S
0 302.2 M(directly to the document maintainer, Peter Jay Salzman )S
/F0 SF (
)S
/F4 SF (. This will allow for the merging of)S
0 289 M(updates and provide consistent revisions to the Linux community.)S
0 262.6 M(If you publish or distribute this book commercially, donations, royalties, and/or printed copies are greatly)S
0 249.4 M(appreciated by the author and the Linux Documentation Project \(LDP\). Contributing in this way shows your)S
0 236.2 M(support for free software and the LDP. If you have questions or comments, please contact the address above.)S
GR
SP
%%Page: i 4
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
20 FS/F9 SF 159.05 674 M(Table of Contents)S
11 FS/F5 SF 0 650 M(Foreword)S
44.25 650 M(..............................................................................................................................................................1)S
/F4 SF 36 636.8 M(1.)S
44.25 636.8 M( Acknowledgements)S
132.25 636.8 M(..............................................................................................................................1)S
36 623.6 M(2.)S
44.25 623.6 M( Authorship)S
96.5 623.6 M( And)S
118.192 623.6 M( Copyright)S
165.25 623.6 M(..................................................................................................................1)S
36 610.4 M(3.)S
44.25 610.4 M( Nota)S
68.384 610.4 M( Bene)S
91 610.4 M(.............................................................................................................................................1)S
/F5 SF 0 584 M(Chapter)S
39.105 584 M( 1.)S
50.105 584 M( Introduction)S
110.25 584 M(......................................................................................................................................2)S
/F4 SF 36 570.8 M(1.1.)S
52.5 570.8 M( What)S
79.076 570.8 M( Is)S
89.768 570.8 M( A)S
100.46 570.8 M( Kernel)S
133.141 570.8 M( Module?)S
173.5 570.8 M(...............................................................................................................2)S
36 557.6 M(1.2.)S
52.5 557.6 M( How)S
76.634 557.6 M( Do)S
92.826 557.6 M( Modules)S
134.076 557.6 M( Get)S
152.71 557.6 M( Into)S
173.181 557.6 M( The)S
193.036 557.6 M( Kernel?)S
228.5 557.6 M(...........................................................................................2)S
/F5 SF 0 531.2 M(Chapter)S
39.105 531.2 M( 2.)S
50.105 531.2 M( Hello)S
77.913 531.2 M( World)S
110.25 531.2 M(......................................................................................................................................5)S
/F4 SF 36 518 M(2.1.)S
52.5 518 M( Hello,)S
82.442 518 M( World)S
113.297 518 M( \(part)S
136.815 518 M( 1\):)S
151.786 518 M( The)S
171.641 518 M( Simplest)S
212.902 518 M( Module)S
247.75 518 M(....................................................................................5)S
36 504.8 M(2.2.)S
52.5 504.8 M( Compiling)S
102.319 504.8 M( Kernel)S
135 504.8 M( Modules)S
176.25 504.8 M(..............................................................................................................6)S
36 491.6 M(2.3.)S
52.5 491.6 M( Hello)S
79.692 491.6 M( World)S
110.547 491.6 M( \(part)S
134.065 491.6 M( 2\))S
143.25 491.6 M(..........................................................................................................................7)S
36 478.4 M(2.4.)S
52.5 478.4 M( Hello)S
79.692 478.4 M( World)S
110.547 478.4 M( \(part)S
134.065 478.4 M( 3\):)S
149.036 478.4 M( The)S
168.891 478.4 M( __init)S
197.315 478.4 M( and)S
215.949 478.4 M( __exit)S
246.199 478.4 M( Macros)S
280.75 478.4 M(........................................................................8)S
36 465.2 M(2.5.)S
52.5 465.2 M( Hello)S
79.692 465.2 M( World)S
110.547 465.2 M( \(part)S
134.065 465.2 M( 4\):)S
149.036 465.2 M( Licensing)S
195.17 465.2 M( and)S
213.804 465.2 M( Module)S
250.775 465.2 M( Documentation)S
319.25 465.2 M(..........................................................9)S
36 452 M(2.6.)S
52.5 452 M( Passing)S
88.866 452 M( Command)S
137.453 452 M( Line)S
160.366 452 M( Arguments)S
212 452 M( to)S
223.308 452 M( a)S
230.942 452 M( Module)S
267 452 M(...........................................................................10)S
36 438.8 M(2.7.)S
52.5 438.8 M( Modules)S
93.75 438.8 M( Spanning)S
138.058 438.8 M( Multiple)S
178.703 438.8 M( Files)S
201 438.8 M(...................................................................................................13)S
/F5 SF 0 412.4 M(Chapter)S
39.105 412.4 M( 3.)S
50.105 412.4 M( Preliminaries)S
115.75 412.4 M(..................................................................................................................................15)S
/F4 SF 36 399.2 M(3.1.)S
52.5 399.2 M( Modules)S
93.75 399.2 M( vs)S
106.279 399.2 M( Programs)S
148.75 399.2 M(......................................................................................................................15)S
/F5 SF 0 372.8 M(Chapter)S
39.105 372.8 M( 4.)S
50.105 372.8 M( Character)S
101.112 372.8 M( Device)S
135.014 372.8 M( Files)S
159.75 372.8 M(..................................................................................................................20)S
/F4 SF 36 359.6 M(4.1.)S
52.5 359.6 M( Character)S
98.007 359.6 M( Device)S
131.909 359.6 M( Drivers)S
165.25 359.6 M(................................................................................................................20)S
/F5 SF 0 333.2 M(Chapter)S
39.105 333.2 M( 5.)S
50.105 333.2 M( The)S
71.192 333.2 M( /proc)S
98.384 333.2 M( File)S
118.855 333.2 M( System)S
154.25 333.2 M(....................................................................................................................26)S
/F4 SF 36 320 M(5.1.)S
52.5 320 M( The)S
72.355 320 M( /proc)S
97.71 320 M( File)S
117.576 320 M( System)S
151.5 320 M(.....................................................................................................................26)S
/F5 SF 0 293.6 M(Chapter)S
39.105 293.6 M( 6.)S
50.105 293.6 M( Using)S
79.75 293.6 M( /proc)S
106.942 293.6 M( For)S
126.797 293.6 M( Input)S
154.25 293.6 M(....................................................................................................................30)S
/F4 SF 36 280.4 M(6.1.)S
52.5 280.4 M( Using)S
81.529 280.4 M( /proc)S
106.884 280.4 M( For)S
124.913 280.4 M( Input)S
148.75 280.4 M(......................................................................................................................30)S
/F5 SF 0 254 M(Chapter)S
39.105 254 M( 7.)S
50.105 254 M( Talking)S
89.54 254 M( To)S
105.127 254 M( Device)S
139.029 254 M( Files)S
162.5 254 M(.................................................................................................................36)S
/F4 SF 36 240.8 M(7.1.)S
52.5 240.8 M( Talking)S
89.471 240.8 M( to)S
100.779 240.8 M( Device)S
134.681 240.8 M( Files)S
158.826 240.8 M( \(writes)S
192.123 240.8 M( and)S
210.757 240.8 M( IOCTLs\)})S
258.75 240.8 M(..............................................................................36)S
/F5 SF 0 214.4 M(Chapter)S
39.105 214.4 M( 8.)S
50.105 214.4 M( System)S
86.46 214.4 M( Calls)S
113 214.4 M(...................................................................................................................................46)S
/F4 SF 36 201.2 M(8.1.)S
52.5 201.2 M( System)S
87.645 201.2 M( Calls)S
113 201.2 M(...................................................................................................................................46)S
/F5 SF 0 174.8 M(Chapter)S
39.105 174.8 M( 9.)S
50.105 174.8 M( Blocking)S
94.424 174.8 M( Processes)S
140.5 174.8 M(.........................................................................................................................51)S
/F4 SF 36 161.6 M(9.1.)S
52.5 161.6 M( Blocking)S
95.587 161.6 M( Processes)S
140.5 161.6 M(.........................................................................................................................51)S
/F5 SF 0 135.2 M(Chapter)S
39.105 135.2 M( 10.)S
55.605 135.2 M( Replacing)S
105.413 135.2 M( Printks)S
140.5 135.2 M(.........................................................................................................................58)S
/F4 SF 36 122 M(10.1.)S
58 122 M( Replacing)S
108.105 122 M(printk)S
132.25 122 M(............................................................................................................................58)S
/F5 SF 0 95.6 M(Chapter)S
39.105 95.6 M( 11.)S
55.605 95.6 M( Scheduling)S
110.319 95.6 M( Tasks)S
140.5 95.6 M(.........................................................................................................................60)S
/F4 SF 36 82.4 M(11.1.)S
58 82.4 M( Scheduling)S
110.25 82.4 M( Tasks)S
137.75 82.4 M(..........................................................................................................................60)S
/F5 SF 0 56 M(Chapter)S
39.105 56 M( 12.)S
55.605 56 M( Interrupt)S
102.96 56 M( Handlers)S
148.75 56 M(......................................................................................................................64)S
/F4 SF 36 42.8 M(12.1.)S
58 42.8 M( Interrupt)S
99.239 42.8 M( Handlers)S
140.5 42.8 M(.........................................................................................................................64)S
/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
484.558 0 M(i)S
GR
SP
%%Page: ii 5
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
20 FS/F9 SF 159.05 674 M(Table of Contents)S
11 FS/F5 SF 0 650 M(Chapter)S
39.105 650 M( 13.)S
55.605 650 M( Symmetric)S
109.67 650 M( Multi)S
138.699 650 M( Processing)S
190 650 M(.......................................................................................................68)S
/F4 SF 36 636.8 M(13.1.)S
58 636.8 M( Symmetrical)S
116.971 636.8 M( Multi-Processing)S
195.5 636.8 M(.....................................................................................................68)S
/F5 SF 0 610.4 M(Chapter)S
39.105 610.4 M( 14.)S
55.605 610.4 M( Common)S
101.739 610.4 M( Pitfalls)S
135 610.4 M(...........................................................................................................................69)S
/F4 SF 36 597.2 M(14.1.)S
58 597.2 M( Common)S
101.703 597.2 M( Pitfalls)S
135 597.2 M(...........................................................................................................................69)S
/F5 SF 0 570.8 M(Appendix)S
45.848 570.8 M( A.)S
59.29 570.8 M( Changes:)S
106.04 570.8 M( 2.0)S
122.54 570.8 M( To)S
138.127 570.8 M( 2.2)S
154.25 570.8 M(....................................................................................................................70)S
/F4 SF 36 557.6 M(A.1.)S
54.942 557.6 M( Changes)S
95.576 557.6 M( between)S
134.978 557.6 M( 2.0)S
151.478 557.6 M( and)S
170.112 557.6 M( 2.2)S
184.5 557.6 M(.........................................................................................................70)S
/F5 SF 0 531.2 M(Appendix)S
45.848 531.2 M( B.)S
58.685 531.2 M( Where)S
93.203 531.2 M( To)S
108.79 531.2 M( Go)S
125.598 531.2 M( From)S
154.616 531.2 M( Here)S
179 531.2 M(...........................................................................................................71)S
/F4 SF 36 518 M(B.1.)S
54.337 518 M( Where)S
86.402 518 M( From)S
112.989 518 M( Here?)S
140.5 518 M(.........................................................................................................................71)S
/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
482.116 0 M(ii)S
GR
SP
%%Page: 1 6
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0 318.6 M 487.0 2.0 F
0 207.4 M 487.0 2.0 F
0 56.6 M 487.0 2.0 F
20 FS/F9 SF 0 678 M(Foreword)S
14 FS/F9 SF 0 646.8 M(1. Acknowledgements)S
11 FS/F4 SF 0 619.8 M(Ori Pomerantz would like to thank Yoav Weiss for many helpful ideas and discussions, as well as finding)S
0 606.6 M(mistakes within this document before its publication. Ori would also like to thank Frodo Looijaard from the)S
0 593.4 M(Netherlands, Stephen Judd from New Zealand, Magnus Ahltorp from Sweeden and Emmanuel Papirakis from)S
0 580.2 M(Quebec, Canada.)S
0 553.8 M(I'd like to thank Ori Pomerantz for authoring this guide in the first place and then letting me maintain it. It was)S
0 540.6 M(a tremendous effort on his part. I hope he likes what I've done with this document.)S
0 514.2 M(I would also like to thank Jeff Newmiller and Rhonda Bailey for teaching me. They've been patient with me)S
0 501 M(and lent me their experience, regardless of how busy they were. David Porter had the unenviable job of)S
0 487.8 M(helping convert the original LaTeX source into docbook. It was a long, boring and dirty job. But someone had)S
0 474.6 M(to do it. Thanks, David.)S
0 448.2 M(Thanks also goes to the fine people at www.kernelnewbies.org. In particular, Mark McLoughlin and John)S
0 435 M(Levon who I'm sure have much better things to do than to hang out on kernelnewbies.org and teach the)S
0 421.8 M(newbies. If this guide teaches you anything, they are partially to blame.)S
0 395.4 M(Both Ori and I would like to thank Richard M. Stallman and Linus Torvalds for giving us the opportunity to)S
0 382.2 M(not only run a high-quality operating system, but to take a close peek at how it works. I've never met Linus,)S
0 369 M(and probably never will, but he has made a profound difference in my life.)S
0 342.6 M(The following people have written to me with corrections or good suggestions: Ignacio Martin, David Porter,)S
0 329.4 M(and Dimo Velev)S
14 FS/F9 SF 0 298 M(2. Authorship And Copyright)S
11 FS/F4 SF 0 271 M(The Linux Kernel Module Programming Guide \(lkmpg\) was originally written by Ori Pomerantz. It became)S
0 257.8 M(very popular as being the best free way to learn how to program Linux kernel modules. Life got busy, and Ori)S
0 244.6 M(no longer had time or inclination to maintain the document. After all, the Linux kernel is a fast moving target.)S
0 231.4 M(Peter Jay Salzman \(that's me\) offered to take over maintainership so at least bug fixes and occaisional)S
0 218.2 M(updating would happen. If you would like to)S
14 FS/F9 SF 0 186.8 M(3. Nota Bene)S
11 FS/F4 SF 0 159.8 M(Ori's original document was good about supporting earlier versions of Linux, going all the way back to the 2.0)S
0 146.6 M(days. I had originally intended to keep with the program, but after thinking about it, opted out. My main)S
0 133.4 M(reason to keep with the compatibility was for GNU/Linux distributions like LEAF, which tended to use older)S
0 120.2 M(kernels. However, even LEAF uses 2.2 and 2.4 kernels these days.)S
0 93.8 M(Both Ori and I use the x86 platform. For the most part, the source code and discussions should apply to other)S
0 80.6 M(architectures, but I can't promise anything. One exception is Chapter 12, Interrupt Handlers, which should not)S
0 67.4 M(work on any architecture except for x86.)S
/F8 SF 0 0 M(Foreword)S
480.884 0 M(1)S
GR
SP
%%Page: 2 7
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0 490.2 M 487.0 2.0 F
0.88 0.88 0.88 C 0 257.535 M 487.7 25.2 F
0.00 0.00 0.00 C 0 282 M 487.7 0.7 F
0 257.535 M 0.7 25.2 F
487 257.535 M 0.7 25.2 F
0 257.535 M 487.7 0.7 F
0.88 0.88 0.88 C 0 37.47 M 487.7 36.0 F
0.00 0.00 0.00 C 0 72.735 M 487.7 0.7 F
0 37.47 M 0.7 36.0 F
487 37.47 M 0.7 36.0 F
0 37.47 M 487.7 0.7 F
20 FS/F9 SF 0 678 M(Chapter 1. Introduction)S
14 FS/F9 SF 0 646.8 M(1.1. What Is A Kernel Module?)S
11 FS/F4 SF 0 619.8 M(So, you want to write a kernel module. You know C, you've written a few normal programs to run as)S
0 606.6 M(processes, and now you want to get to where the real action is, to where a single wild pointer can wipe out)S
0 593.4 M(your file system and a core dump means a reboot.)S
0 567 M(What exactly is a kernel module? Modules are pieces of code that can be loaded and unloaded into the kernel)S
0 553.8 M(upon demand. They extend the functionality of the kernel without the need to reboot the system. For example,)S
0 540.6 M(one type of module is the device driver, which allows the kernel to access hardware connected to the system.)S
0 527.4 M(Without modules, we would have to build monolithic kernels and add new functionality directly into the)S
0 514.2 M(kernel image. Besides having larger kernels, this has the disadvantage of requiring us to rebuild and reboot the)S
0 501 M(kernel every time we want new functionality.)S
14 FS/F9 SF 0 469.6 M(1.2. How Do Modules Get Into The Kernel?)S
11 FS/F4 SF 0 442.6 M(You can see what modules are already loaded into the kernel by running)S
/F5 SF ( lsmod)S
/F4 SF (, which gets its information by)S
0 429.4 M(reading the file )S
/F0 SF (/proc/modules)S
/F4 SF (.)S
0 403 M(How do these modules find their way into the kernel? When the kernel needs a feature that is not resident in)S
0 389.8 M(the kernel, the kernel module daemon kmod)S
([1] execs modprobe to load the module in. modprobe is passed a)S
0 376.6 M(string in one of two forms:)S
36 350.2 M(A module name like )S
/F0 SF (softdog)S
/F4 SF ( or )S
/F0 SF (ppp)S
/F4 SF (.)S
/Fc SF 28.19 350.2 M(\267 )S
/F4 SF 36 337 M(A more generic identifier like)S
/Fa SF ( char-major-10-30)S
/F4 SF (.)S
/Fc SF 28.19 337 M(\267 )S
/F4 SF 0 310.6 M(If modprobe is handed a generic identifier, it first looks for that string in the file )S
/F0 SF (/etc/modules.conf)S
/F4 SF (. If)S
0 297.4 M(it finds an alias line like:)S
9 FS/F0 SF 1.432 271.567 M( alias char-major-10-30 softdog)S
11 FS/F4 SF 0 233.335 M(it knows that the generic identifier refers to the module )S
/F0 SF (softdog.o)S
/F4 SF (.)S
0 206.935 M(Next, modprobe looks through the file )S
/F0 SF (/lib/modules/version/modules.dep)S
/F4 SF (, to see if other)S
0 193.735 M(modules must be loaded before the requested module may be loaded. This file is created by)S
/F5 SF ( depmod -a)S
/F4 SF ( and)S
0 180.535 M(contains module dependencies. For example, )S
/F0 SF (msdos.o)S
/F4 SF ( requires the )S
/F0 SF (fat.o)S
/F4 SF ( module to be already loaded into)S
0 167.335 M(the kernel. The requested module has a dependancy on another module if the other module defines symbols)S
0 154.135 M(\(variables or functions\) that the requested module uses.)S
0 127.735 M(Lastly, modprobe uses insmod to first load any prerequisite modules into the kernel, and then the requested)S
0 114.535 M(module. modprobe directs insmod to )S
/F0 SF (/lib/modules/version/)S
/F4 SF ([2], the standard directory for modules.)S
0 101.335 M(insmod is intended to be fairly dumb about the location of modules, whereas modprobe is aware of the default)S
0 88.135 M(location of modules. So for example, if you wanted to load the msdos module, you'd have to either run:)S
9 FS/F0 SF 1.432 62.303 M( insmod /lib/modules/2.5.1/kernel/fs/fat/fat.o)S
1.432 51.503 M( insmod /lib/modules/2.5.1/kernel/fs/msdos/msdos.o)S
11 FS/F8 SF 0 0 M(Chapter 1. Introduction)S
480.884 0 M(2)S
GR
SP
%%Page: 3 8
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 540.335 M 487.7 79.2 F
0.00 0.00 0.00 C 0 618.8 M 487.7 0.7 F
0 540.335 M 0.7 79.2 F
487 540.335 M 0.7 79.2 F
0 540.335 M 487.7 0.7 F
0 294.135 M 487.0 2.0 F
0 199.735 M 487.0 2.0 F
0 94.535 M 487.0 2.0 F
11 FS/F4 SF 0 687 M(or just run ")S
/F5 SF (modprobe -a msdos)S
/F4 SF (".)S
0 660.6 M(Linux distros provide modprobe, insmod and depmod as a package called modutils or mod-utils.)S
0 634.2 M(Before finishing this chapter, let's take a quick look at a piece of )S
/F0 SF (/etc/modules.conf)S
/F4 SF (:)S
9 FS/F0 SF 1.432 608.368 M( #This file is automatically generated by update-modules)S
1.432 597.568 M( path[misc]=/lib/modules/2.4.?/local)S
1.432 586.768 M( keep)S
1.432 575.968 M( path[net]=~p/mymodules)S
1.432 565.168 M( options mydriver irq=10)S
1.432 554.368 M( alias eth0 eepro)S
11 FS/F4 SF 0 516.135 M(Lines beginning with a '#' are comments. Blank lines are ignored.)S
0 489.735 M(The)S
/Fa SF ( path[misc])S
/F4 SF ( line tells modprobe to replace the search path for misc modules with the directory)S
/F0 SF 0 476.535 M(/lib/modules/2.4.?/local)S
/F4 SF (. As you can see, shell meta characters are honored.)S
0 450.135 M(The)S
/Fa SF ( path[net])S
/F4 SF ( line tells modprobe to look for net modules in the directory )S
/F0 SF (~p/mymodules)S
/F4 SF (, however, the)S
0 436.935 M("keep" directive preceding the)S
/Fa SF ( path[net])S
/F4 SF ( directive tells modprobe to add this directory to the standard search)S
0 423.735 M(path of net modules as opposed to replacing the standard search path, as we did for the misc modules.)S
0 397.335 M(The alias line says to load in )S
/F0 SF (eepro.o)S
/F4 SF ( whenever kmod requests that the generic identifier `eth0' be loaded.)S
0 370.935 M(You won't see lines like "alias block-major-2 floppy" in )S
/F0 SF (/etc/modules.conf)S
/F4 SF ( because modprobe already)S
0 357.735 M(knows about the standard drivers which will be used on most systems.)S
0 331.335 M(Now you know how modules get into the kernel. There's a bit more to the story if you want to write your own)S
0 318.135 M(modules which depend on other modules \(we calling this `stacking modules'\). But this will have to wait for a)S
0 304.935 M(future chapter. We have a lot to cover before addressing this relatively high-level issue.)S
/F9 SF 0 276.535 M(1.2.1. Before We Begin)S
/F4 SF 0 250.135 M(Before we delve into code, there are a few issues we need to cover. Everyone's system is different and)S
0 236.935 M(everyone has their own groove. Getting your first "hello world" program to compile and load correctly can)S
0 223.735 M(sometimes be a trick. Rest assured, after you get over the initial hurdle of doing it for the first time, it will be)S
0 210.535 M(smooth sailing thereafter.)S
9 FS/F9 SF 0 184.135 M(1.2.1.1. Modversioning)S
11 FS/F4 SF 0 158.135 M(A module compiled for one kernel won't load if you boot a different kernel unless you enable)S
/Fa SF 0 144.935 M(CONFIG_MODVERSIONS)S
/F4 SF ( in the kernel. We won't go into module versioning until later in this guide. Until)S
0 131.735 M(we cover modversions, the examples in the guide may not work if you're running a kernel with modversioning)S
0 118.535 M(turned on. However, most stock Linux distro kernels come with it turned on. If you're having trouble loading)S
0 105.335 M(the modules because of versioning errors, compile a kernel with modversioning turned off.)S
/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(1.2. How Do Modules Get Into The Kernel?)S
480.884 0 M(3)S
GR
SP
%%Page: 4 9
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0 573 M 487.0 2.0 F
0 349 M 487.0 2.0 F
9 FS/F9 SF 0 689 M(1.2.1.2. Using X)S
11 FS/F4 SF 0 663 M(It is highly recommended that you type in, compile and load all the examples this guide discusses. It's also)S
0 649.8 M(highly recommended you do this from a console. You should not be working on this stuff in X.)S
0 623.4 M(Modules can't print to the screen like )S
/F0 SF (printf\(\))S
/F4 SF ( can, but they can log information and warnings, which ends)S
0 610.2 M(up being printed on your screen, but only on a console. If you insmod a module from an xterm, the)S
0 597 M(information and warnings will be logged, but only to your log files. You won't see it unless you look through)S
0 583.8 M(your log files. To have immediate access to this information, do all your work from console.)S
9 FS/F9 SF 0 557.4 M(1.2.1.3. Compiling Issues and Kernel Version)S
11 FS/F4 SF 0 531.4 M(Very often, Linux distros will distribute kernel source that has been patched in various non-standard ways,)S
0 518.2 M(which may cause trouble.)S
0 491.8 M(A more common problem is that some Linux distros distribute incomplete kernel headers. You'll need to)S
0 478.6 M(compile your code using various header files from the Linux kernel. Murphy's Law states that the headers that)S
0 465.4 M(are missing are exactly the ones that you'll need for your module work.)S
0 439 M(To avoid these two problems, I highly recommend that you download, compile and boot into a fresh, stock)S
0 425.8 M(Linux kernel which can be downloaded from any of the Linux kernel mirror sites. See the Linux Kernel)S
0 412.6 M(HOWTO for more details.)S
0 386.2 M(Ironically, this can also cause a problem. By default, gcc on your system may look for the kernel headers in)S
0 373 M(their default location rather than where you installed the new copy of the kernel \(usually in )S
/F0 SF (/usr/src/)S
/F4 SF (.)S
0 359.8 M(This can be fixed by using gcc's)S
/Fa SF ( -I)S
/F4 SF ( switch.)S
/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(1.2. How Do Modules Get Into The Kernel?)S
480.884 0 M(4)S
GR
SP
%%Page: 5 10
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 277.535 M 487.0 208.1 F
0.00 0.00 0.00 C 0 57.735 M 487.0 2.0 F
20 FS/F9 SF 0 678 M(Chapter 2. Hello World)S
14 FS/F9 SF 0 646.8 M(2.1. Hello, World \(part 1\): The Simplest Module)S
11 FS/F4 SF 0 619.8 M(When the first caveman programmer chiseled the first program on the walls of the first cave computer, it was)S
0 606.6 M(a program to paint the string `Hello, world' in Antelope pictures. Roman programming textbooks began with)S
0 593.4 M(the `Salut, Mundi' program. I don't know what happens to people who break with this tradition, but I think it's)S
0 580.2 M(safer not to find out. We'll start with a series of hello world programs that demonstrate the different aspects of)S
0 567 M(the basics of writing a kernel module.)S
0 540.6 M(Here's the simplest module possible. Don't compile it yet; we'll cover module compilation in the next section.)S
/F5 SF 0 501 M(Example 2-1. hello-1.c)S
9 FS/F0 SF 1.432 475.168 M(/* hello-1.c - The simplest kernel module.)S
1.432 464.368 M( */)S
1.432 453.568 M(#include /* Needed by all modules */)S
1.432 442.768 M(#include /* Needed for KERN_ALERT */)S
1.432 410.368 M(int init_module\(void\))S
1.432 399.568 M({)S
1.432 388.768 M( printk\("<1>Hello world 1.\\n"\);)S
1.432 367.168 M( // A non 0 return means init_module failed; module can't be loaded.)S
1.432 356.368 M( return 0;)S
1.432 345.568 M(})S
1.432 313.168 M(void cleanup_module\(void\))S
1.432 302.368 M({)S
1.432 291.568 M( printk\(KERN_ALERT "Goodbye world 1.\\n"\);)S
1.432 280.768 M(} )S
11 FS/F4 SF 0 253.335 M(Kernel modules must have at least two functions: a "start" \(initialization\) function called )S
/F0 SF (init_module\(\))S
/F4 SF 0 240.135 M(which is called when the module is insmoded into the kernel, and an "end" \(cleanup\) function called)S
/F0 SF 0 226.935 M(cleanup_module\(\))S
/F4 SF ( which is called just before it is rmmoded. Actually, things have changed starting with)S
0 213.735 M(kernel 2.3.13. You can now use whatever name you like for the start and end functions of a module, and you'll)S
0 200.535 M(learn how to do this in Section 2.3. In fact, the new method is the preferred method. However, many people)S
0 187.335 M(still use )S
/F0 SF (init_module\(\))S
/F4 SF ( and )S
/F0 SF (cleanup_module\(\))S
/F4 SF ( for their start and end functions.)S
0 160.935 M(Typically, )S
/F0 SF (init_module\(\))S
/F4 SF ( either registers a handler for something with the kernel, or it replaces one of the)S
0 147.735 M(kernel functions with its own code \(usually code to do something and then call the original function\). The)S
/F0 SF 0 134.535 M(cleanup_module\(\))S
/F4 SF ( function is supposed to undo whatever )S
/F0 SF (init_module\(\))S
/F4 SF ( did, so the module can be)S
0 121.335 M(unloaded safely.)S
0 94.935 M(Lastly, every kernel module needs to include )S
/F0 SF (linux/module.h)S
/F4 SF (. We needed to include)S
/F0 SF 0 81.735 M(linux/kernel.h)S
/F4 SF ( only for the macro expansion for the )S
/F0 SF (printk\(\))S
/F4 SF ( log level,)S
/Fa SF ( KERN_ALERT)S
/F4 SF (, which)S
0 68.535 M(you'll learn about in Section 2.1.1.)S
/F8 SF 0 0 M(Chapter 2. Hello World)S
480.884 0 M(5)S
GR
SP
%%Page: 6 11
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0 465 M 487.0 2.0 F
11 FS/F9 SF 0 687 M(2.1.1. Introducing )S
/F1 SF (printk\(\))S
/F4 SF 0 660.6 M(Despite what you might think, )S
/F0 SF (printk\(\))S
/F4 SF ( was not meant to communicate information to the user, even)S
0 647.4 M(though we used it for exactly this purpose in hello-1! It happens to be a logging mechanism for the kernel,)S
0 634.2 M(and is used to log information or give warnings. Therefore, each )S
/F0 SF (printk\(\))S
/F4 SF ( statement comes with a priority,)S
0 621 M(which is the)S
/Fa SF ( <1>)S
/F4 SF ( and)S
/Fa SF ( KERN_ALERT)S
/F4 SF ( you see. There are 8 priorities and the kernel has macros for them, so)S
0 607.8 M(you don't have to use cryptic numbers, and you can view them \(and their meanings\) in )S
/F0 SF (linux/kernel.h)S
/F4 SF (.)S
0 594.6 M(If you don't specify a priority level, the default priority,)S
/Fa SF ( DEFAULT_MESSAGE_LOGLEVEL)S
/F4 SF (, will be used.)S
0 568.2 M(Take time to read through the priority macros. The header file also describes what each priority means. In)S
0 555 M(practise, don't use number, like)S
/Fa SF ( <4>)S
/F4 SF (. Always use the macro, like)S
/Fa SF ( KERN_WARNING)S
/F4 SF (.)S
0 528.6 M(If the priority is less than)S
/Fa SF ( int console_loglevel)S
/F4 SF (, the message is printed on your current terminal. If both)S
/F5 SF 0 515.4 M(syslogd)S
/F4 SF ( and klogd are running, then the message will also get appended to )S
/F0 SF (/var/log/messages)S
/F4 SF (, whether)S
0 502.2 M(it got printed to the console or not. We use a high priority, like)S
/Fa SF ( KERN_ALERT)S
/F4 SF (, to make sure the )S
/F0 SF (printk\(\))S
/F4 SF 0 489 M(messages get printed to your console rather than just logged to your logfile. When you write real modules,)S
0 475.8 M(you'll want to use priorities that are meaningful for the situation at hand.)S
14 FS/F9 SF 0 444.4 M(2.2. Compiling Kernel Modules)S
11 FS/F4 SF 0 417.4 M(Kernel modules need to be compiled with certain gcc options to make them work. In addition, they also need)S
0 404.2 M(to be compiled with certain symbols defined. This is because the kernel header files need to behave)S
0 391 M(differently, depending on whether we're compiling a kernel module or an executable. You can define symbols)S
0 377.8 M(using gcc's)S
/Fa SF ( -D)S
/F4 SF ( option, or with the)S
/Fa SF ( #define)S
/F4 SF ( preprocessor command. We'll cover what you need to do in order)S
0 364.6 M(to compile kernel modules in this section.)S
/Fa SF 36 338.2 M(-c)S
/F4 SF (: A kernel module is not an independant executable, but an object file which will be linked into the)S
36 325 M(kernel during runtime using insmod. As a result, modules should be compiled with the)S
/Fa SF ( -c)S
/F4 SF ( flag.)S
/Fc SF 28.19 338.2 M(\267 )S
/Fa SF 36 311.8 M(-O2)S
/F4 SF (: The kernel makes extensive use of inline functions, so modules must be compiled with the)S
36 298.6 M(optimization flag turned on. Without optimization, some of the assembler macros calls will be)S
36 285.4 M(mistaken by the compiler for function calls. This will cause loading the module to fail, since insmod)S
36 272.2 M(won't find those functions in the kernel.)S
/Fc SF 28.19 311.8 M(\267 )S
/Fa SF 36 259 M(-W -Wall)S
/F4 SF (: A programming mistake can take take your system down. You should always turn on)S
36 245.8 M(compiler warnings, and this applies to all your compiling endeavors, not just module compilation.)S
/Fc SF 28.19 259 M(\267 )S
/Fa SF 36 232.6 M(-isystem /lib/modules/`uname -r`/build/include)S
/F4 SF (: You must use the kernel headers of the kernel)S
36 219.4 M(you're compiling against. Using the default )S
/F0 SF (/usr/include/linux)S
/F4 SF ( won't work.)S
/Fc SF 28.19 232.6 M(\267 )S
/Fa SF 36 206.2 M(-D__KERNEL__)S
/F4 SF (: Defining this symbol tells the header files that the code will be run in kernel)S
36 193 M(mode, not as a user process.)S
/Fc SF 28.19 206.2 M(\267 )S
/Fa SF 36 179.8 M(-DMODULE)S
/F4 SF (: This symbol tells the header files to give the appropriate definitions for a kernel)S
36 166.6 M(module.)S
/Fc SF 28.19 179.8 M(\267 )S
/F4 SF 0 140.2 M(We use gcc's)S
/Fa SF ( -isystem)S
/F4 SF ( option instead of)S
/Fa SF ( -I)S
/F4 SF ( because it tells gcc to surpress some "unused variable" warnings)S
0 127 M(that)S
/Fa SF ( -W -Wall)S
/F4 SF ( causes when you include )S
/F0 SF (module.h)S
/F4 SF (. By using)S
/Fa SF ( -isystem)S
/F4 SF ( under gcc-3.0, the kernel header)S
0 113.8 M(files are treated specially, and the warnings are surpressed. If you instead use)S
/Fa SF ( -I)S
/F4 SF ( \(or even)S
/Fa SF ( -isystem)S
/F4 SF ( under gcc)S
0 100.6 M(2.9x\), the "unused variable" warnings will be printed. Just ignore them if they do.)S
0 74.2 M(So, let's look at a simple Makefile for compiling a module named )S
/F0 SF (hello-1.c)S
/F4 SF (:)S
/F5 SF 0 34.6 M(Example 2-2. Makefile for a basic kernel module)S
/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(2.1. Hello, World \(part 1\): The Simplest Module)S
480.884 0 M(6)S
GR
SP
%%Page: 7 12
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 565.535 M 487.7 133.2 F
0.00 0.00 0.00 C 0 698 M 487.7 0.7 F
0 565.535 M 0.7 133.2 F
487 565.535 M 0.7 133.2 F
0 565.535 M 487.7 0.7 F
0 424.935 M 487.0 2.0 F
0.88 0.88 0.88 C 0 22 M 487.0 247.5 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 687.568 M(TARGET := hello-1)S
1.432 676.768 M(WARN := -W -Wall -Wstrict-prototypes -Wmissing-prototypes)S
1.432 665.968 M(INCLUDE := -isystem /lib/modules/`uname -r`/build/include)S
1.432 655.168 M(CFLAGS := -O2 -DMODULE -D__KERNEL__ ${WARN} ${INCLUDE})S
1.432 644.368 M(CC := gcc-3.0)S
1.432 622.768 M(${TARGET}.o: ${TARGET}.c)S
1.432 601.168 M(.PHONY: clean)S
1.432 579.568 M(clean:)S
1.432 568.768 M( rm -rf ${TARGET}.o)S
11 FS/F4 SF 0 541.335 M(As an exercise to the reader, compile )S
/F0 SF (hello-1.c)S
/F4 SF ( and insert it into the kernel with)S
/F5 SF ( insmod ./hello-1.o)S
/F4 SF 0 528.135 M(\(ignore anything you see about tainted kernels; we'll cover that shortly\). Neat, eh? All modules loaded into the)S
0 514.935 M(kernel are listed in )S
/F0 SF (/proc/modules)S
/F4 SF (. Go ahead and cat that file to see that your module is really a part of)S
0 501.735 M(the kernel. Congratulations, you are now the author of Linux kernel code! When the novelty wares off,)S
0 488.535 M(remove your module from the kernel by using)S
/F5 SF ( rmmod hello-1)S
/F4 SF (. Take a look at )S
/F0 SF (/var/log/messages)S
/F4 SF ( just)S
0 475.335 M(to see that it got logged to your system logfile.)S
0 448.935 M(Here's another exercise to the reader. See that comment above the return statement in )S
/F0 SF (init_module\(\))S
/F4 SF (?)S
0 435.735 M(Change the return value to something non-zero, recompile and load the module again. What happens?)S
14 FS/F9 SF 0 404.335 M(2.3. Hello World \(part 2\))S
11 FS/F4 SF 0 377.335 M(As of Linux 2.4, you can rename the init and cleanup functions of your modules; they no longer have to be)S
0 364.135 M(called )S
/F0 SF (init_module\(\))S
/F4 SF ( and )S
/F0 SF (cleanup_module\(\))S
/F4 SF ( respectively. This is done with the )S
/F0 SF (module_init\(\))S
/F4 SF 0 350.935 M(and )S
/F0 SF (module_exit\(\))S
/F4 SF ( macros. These macros are defined in )S
/F0 SF (linux/init.h)S
/F4 SF (. The only caveat is that your)S
0 337.735 M(init and cleanup functions must be defined before calling the macros, otherwise you'll get compilation errors.)S
0 324.535 M(Here's an example of this technique:)S
/F5 SF 0 284.935 M(Example 2-3. hello-2.c)S
9 FS/F0 SF 1.432 259.103 M(/* hello-2.c - Demonstrating the module_init\(\) and module_exit\(\) macros. This is the )S
1.432 248.303 M( * preferred over using init_module\(\) and cleanup_module\(\).)S
1.432 237.503 M( */)S
1.432 226.703 M(#include // Needed by all modules)S
1.432 215.903 M(#include // Needed for KERN_ALERT)S
1.432 205.103 M(#include // Needed for the macros)S
1.432 172.703 M(static int hello_2_init\(void\))S
1.432 161.903 M({)S
1.432 151.103 M( printk\(KERN_ALERT "Hello, world 2\\n"\);)S
1.432 140.303 M( return 0;)S
1.432 129.503 M(})S
1.432 97.103 M(static void hello_2_exit\(void\))S
1.432 86.303 M({)S
1.432 75.503 M( printk\(KERN_ALERT "Goodbye, world 2\\n"\);)S
1.432 64.703 M(})S
1.432 32.303 M(module_init\(hello_2_init\);)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(2.3. Hello World \(part 2\))S
480.884 0 M(7)S
GR
SP
%%Page: 8 13
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 684.335 M 487.0 13.7 F
0 433.071 M 487.7 133.2 F
0.00 0.00 0.00 C 0 565.535 M 487.7 0.7 F
0 433.071 M 0.7 133.2 F
487 433.071 M 0.7 133.2 F
0 433.071 M 487.7 0.7 F
0 384.871 M 487.0 2.0 F
0.88 0.88 0.88 C 0 22 M 487.0 88.7 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 687.568 M(module_exit\(hello_2_exit\);)S
11 FS/F4 SF 0 660.135 M(So now we have two real kernel modules under our belt. With productivity as high as ours, we should have a)S
0 646.935 M(high powered Makefile. Here's a more advanced Makefile which will compile both our modules at the same)S
0 633.735 M(time. It's optimized for brevity and scalability. If you don't understand it, I urge you to read the makefile info)S
0 620.535 M(pages or the GNU Make Manual.)S
/F5 SF 0 580.935 M(Example 2-4. Makefile for both our modules)S
9 FS/F0 SF 1.432 555.103 M(WARN := -W -Wall -Wstrict-prototypes -Wmissing-prototypes)S
1.432 544.303 M(INCLUDE := -isystem /lib/modules/`uname -r`/build/include)S
1.432 533.503 M(CFLAGS := -O2 -DMODULE -D__KERNEL__ ${WARN} ${INCLUDE})S
1.432 522.703 M(CC := gcc-3.0)S
1.432 511.903 M(OBJS := ${patsubst %.c, %.o, ${wildcard *.c}})S
1.432 490.303 M(all: ${OBJS})S
1.432 468.703 M(.PHONY: clean)S
1.432 447.103 M(clean:)S
1.432 436.303 M( rm -rf *.o)S
11 FS/F4 SF 0 408.871 M(As an exercise to the reader, if we had another module in the same directory, say )S
/F0 SF (hello-3.c)S
/F4 SF (, how would)S
0 395.671 M(you modify this Makefile to automatically compile that module?)S
14 FS/F9 SF 0 364.271 M(2.4. Hello World \(part 3\): The)S
/Fb SF ( __init)S
/F9 SF ( and)S
/Fb SF ( __exit)S
/F9 SF ( Macros)S
11 FS/F4 SF 0 337.271 M(This demonstrates a feature of kernel 2.2 and later. Notice the change in the definitions of the init and cleanup)S
0 324.071 M(functions. The )S
/F0 SF (__init)S
/F4 SF ( macro causes the init function to be discarded and its memory freed once the init)S
0 310.871 M(function finishes for built-in drivers, but not loadable modules. If you think about when the init function is)S
0 297.671 M(invoked, this makes perfect sense.)S
0 271.27 M(There is also an )S
/F0 SF (__initdata)S
/F4 SF ( which works similarly to )S
/F0 SF (__init)S
/F4 SF ( but for init variables rather than functions.)S
0 244.87 M(The )S
/F0 SF (__exit)S
/F4 SF ( macro causes the omission of the function when the module is built into the kernel, and like)S
/F0 SF 0 231.67 M(__exit)S
/F4 SF (, has no effect for loadable modules. Again, if you consider when the cleanup function runs, this)S
0 218.47 M(makes complete sense; built-in drivers don't need a cleanup function, while loadable modules do.)S
0 192.07 M(These macros are defined in )S
/F0 SF (linux/init.h)S
/F4 SF ( and serve to free up kernel memory. When you boot your)S
0 178.87 M(kernel and see something like)S
/Fa SF ( Freeing unused kernel memory: 236k freed)S
/F4 SF (, this is precisely what the)S
0 165.67 M(kernel is freeing.)S
/F5 SF 0 126.07 M(Example 2-5. hello-3.c)S
9 FS/F0 SF 1.432 100.238 M(/* hello-3.c - Illustrating the __init, __initdata and __exit macros.)S
1.432 89.438 M( */)S
1.432 78.638 M(#include /* Needed by all modules */)S
1.432 67.838 M(#include /* Needed for KERN_ALERT */)S
1.432 57.038 M(#include /* Needed for the macros */)S
1.432 35.438 M(static int hello3_data __initdata = 3;)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(2.4. Hello World \(part 3\): The __init and __exit Macros)S
480.884 0 M(8)S
GR
SP
%%Page: 9 14
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 522.335 M 487.0 175.7 F
0 425.871 M 487.7 57.6 F
0.00 0.00 0.00 C 0 482.735 M 487.7 0.7 F
0 425.871 M 0.7 57.6 F
487 425.871 M 0.7 57.6 F
0 425.871 M 487.7 0.7 F
0 364.471 M 487.0 2.0 F
0.88 0.88 0.88 C 0 220.606 M 487.7 68.4 F
0.00 0.00 0.00 C 0 288.271 M 487.7 0.7 F
0 220.606 M 0.7 68.4 F
487 220.606 M 0.7 68.4 F
0 220.606 M 487.7 0.7 F
9 FS/F0 SF 1.432 676.768 M(static int __init hello_3_init\(void\))S
1.432 665.968 M({)S
1.432 655.168 M( printk\(KERN_ALERT "Hello, world %d\\n", hello3_data\);)S
1.432 644.368 M( return 0;)S
1.432 633.568 M(})S
1.432 601.168 M(static void __exit hello_3_exit\(void\))S
1.432 590.368 M({)S
1.432 579.568 M( printk\(KERN_ALERT "Goodbye, world 3\\n"\);)S
1.432 568.768 M(})S
1.432 536.368 M(module_init\(hello_3_init\);)S
1.432 525.568 M(module_exit\(hello_3_exit\);)S
11 FS/F4 SF 0 498.135 M(By the way, you may see the directive ")S
/F0 SF (__initfunction\(\))S
/F4 SF (" in drivers written for Linux 2.2 kernels:)S
9 FS/F0 SF 1.432 472.303 M( __initfunction\(int init_module\(void\)\))S
1.432 461.503 M({)S
1.432 450.703 M( printk\(KERN_ALERT "Hi there.\\n"\);)S
1.432 439.903 M( return 0;)S
1.432 429.103 M(})S
11 FS/F4 SF 0 401.671 M(This macro served the same purpose as )S
/F0 SF (__init)S
/F4 SF (, but is now very deprecated in favor of )S
/F0 SF (__init)S
/F4 SF (. I only)S
0 388.471 M(mention it because you might see it modern kernels. As of 2.4.18, there are 38 references to)S
/F0 SF 0 375.271 M(__initfunction\(\))S
/F4 SF (, and of 2.4.20, there are 37 references. However, don't use it in your own code.)S
14 FS/F9 SF 0 343.871 M(2.5. Hello World \(part 4\): Licensing and Module Documentation)S
11 FS/F4 SF 0 316.871 M(If you're running kernel 2.4 or later, you might have noticed something like this when you loaded the previous)S
0 303.671 M(example modules:)S
9 FS/F0 SF 1.432 277.838 M(# insmod hello-3.o)S
1.432 267.038 M(Warning: loading hello-3.o will taint the kernel: no license)S
1.432 256.238 M( See http://www.tux.org/lkml/#export-tainted for information about tainted modules)S
1.432 245.438 M(Hello, world 3)S
1.432 234.638 M(Module hello-3 loaded, with warnings)S
11 FS/F4 SF 0 196.406 M(In kernel 2.4 and later, a mechanism was devised to identify code licensed under the GPL \(and friends\) so)S
0 183.206 M(people can be warned that the code is non open-source. This is accomplished by the )S
/F0 SF (MODULE_LICENSE\(\))S
/F4 SF 0 170.006 M(macro which is demonstrated in the next piece of code. By setting the license to GPL, you can keep the)S
0 156.806 M(warning from being printed. This license mechanism is defined and documented in )S
/F0 SF (linux/module.h)S
/F4 SF (.)S
0 130.406 M(Similarly, )S
/F0 SF (MODULE_DESCRIPTION\(\))S
/F4 SF ( is used to describe what the module does, )S
/F0 SF (MODULE_AUTHOR\(\))S
/F4 SF 0 117.206 M(declares the module's author, and )S
/F0 SF (MODULE_SUPPORTED_DEVICE\(\))S
/F4 SF ( declares what types of devices the)S
0 104.006 M(module supports.)S
0 77.606 M(These macros are all defined in )S
/F0 SF (linux/module.h)S
/F4 SF ( and aren't used by the kernel itself. They're simply for)S
0 64.406 M(documentation and can be viewed by a tool like objdump. As an exercise to the reader, try grepping through)S
/F0 SF 0 51.206 M(linux/drivers)S
/F4 SF ( to see how module authors use these macros to document their modules.)S
/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(2.5. Hello World \(part 4\): Licensing and Module Documentation)S
480.884 0 M(9)S
GR
SP
%%Page: 10 15
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 204.336 M 487.0 467.3 F
0.00 0.00 0.00 C 0 195.736 M 487.0 2.0 F
11 FS/F5 SF 0 687 M(Example 2-6. hello-4.c)S
9 FS/F0 SF 1.432 661.168 M(/* hello-4.c - Demonstrates module documentation.)S
1.432 650.368 M( */)S
1.432 639.568 M(#include )S
1.432 628.768 M(#include )S
1.432 617.968 M(#include )S
1.432 607.168 M(#define DRIVER_AUTHOR "Peiter Jay Salzman ")S
1.432 596.368 M(#define DRIVER_DESC "A sample driver")S
1.432 574.768 M(int init_hello_3\(void\);)S
1.432 563.968 M(void cleanup_hello_3\(void\);)S
1.432 531.568 M(static int init_hello_4\(void\))S
1.432 520.768 M({)S
1.432 509.968 M( printk\(KERN_ALERT "Hello, world 4\\n"\);)S
1.432 499.168 M( return 0;)S
1.432 488.368 M(})S
1.432 455.968 M(static void cleanup_hello_4\(void\))S
1.432 445.168 M({)S
1.432 434.368 M( printk\(KERN_ALERT "Goodbye, world 4\\n"\);)S
1.432 423.568 M(})S
1.432 391.168 M(module_init\(init_hello_4\);)S
1.432 380.368 M(module_exit\(cleanup_hello_4\);)S
1.432 347.968 M(/* You can use strings, like this:)S
1.432 337.168 M( */)S
1.432 326.368 M(MODULE_LICENSE\("GPL"\); // Get rid of taint message by declaring code as GPL.)S
1.432 304.768 M(/* Or with defines, like this:)S
1.432 293.968 M( */)S
1.432 283.168 M(MODULE_AUTHOR\(DRIVER_AUTHOR\); // Who wrote this module?)S
1.432 272.368 M(MODULE_DESCRIPTION\(DRIVER_DESC\); // What does this module do?)S
1.432 250.768 M(/* This module uses /dev/testdevice. The MODULE_SUPPORTED_DEVICE macro might be used in)S
1.432 239.968 M( * the future to help automatic configuration of modules, but is currently unused other)S
1.432 229.168 M( * than for documentation purposes.)S
1.432 218.368 M( */)S
1.432 207.568 M(MODULE_SUPPORTED_DEVICE\("testdevice"\);)S
14 FS/F9 SF 0 175.136 M(2.6. Passing Command Line Arguments to a Module)S
11 FS/F4 SF 0 148.136 M(Modules can take command line arguments, but not with the)S
/Fa SF ( argc)S
/F4 SF (/)S
/Fa SF (argv)S
/F4 SF ( you might be used to.)S
0 121.736 M(To allow arguments to be passed to your module, declare the variables that will take the values of the)S
0 108.536 M(command line arguments as global and then use the )S
/F0 SF (MODULE_PARM\(\))S
/F4 SF ( macro, \(defined in)S
/F0 SF 0 95.336 M(linux/module.h)S
/F4 SF (\) to set the mechanism up. At runtime, insmod will fill the variables with any command)S
0 82.136 M(line arguments that are given, like)S
/F5 SF ( ./insmod mymodule.o myvariable=5)S
/F4 SF (. The variable declarations and)S
0 68.936 M(macros should be placed at the beginning of the module for clarity. The example code should clear up my)S
0 55.736 M(admittedly lousy explanation.)S
/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(2.6. Passing Command Line Arguments to a Module)S
474.768 0 M(10)S
GR
SP
%%Page: 11 16
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 551.135 M 487.7 68.4 F
0.00 0.00 0.00 C 0 618.8 M 487.7 0.7 F
0 551.135 M 0.7 68.4 F
487 551.135 M 0.7 68.4 F
0 551.135 M 487.7 0.7 F
0.88 0.88 0.88 C 0 449.871 M 487.7 36.0 F
0.00 0.00 0.00 C 0 485.135 M 487.7 0.7 F
0 449.871 M 0.7 36.0 F
487 449.871 M 0.7 36.0 F
0 449.871 M 487.7 0.7 F
0.88 0.88 0.88 C 0 22 M 487.0 282.7 F
0.00 0.00 0.00 C 11 FS/F4 SF 0 687 M(The )S
/F0 SF (MODULE_PARM\(\))S
/F4 SF ( macro takes 2 arguments: the name of the variable and its type. The supported)S
0 673.8 M(variable types are ")S
/Fa SF (b)S
/F4 SF (": single byte, ")S
/Fa SF (h)S
/F4 SF (": short int, ")S
/Fa SF (i)S
/F4 SF (": integer, ")S
/Fa SF (l)S
/F4 SF (": long int and ")S
/Fa SF (s)S
/F4 SF (": string, and the integer types)S
0 660.6 M(can be signed as usual or unsigned. Strings should be declared as "char *" and insmod will allocate memory)S
0 647.4 M(for them. You should always try to give the variables an initial default value. This is kernel code, and you)S
0 634.2 M(should program defensively. For example:)S
9 FS/F0 SF 1.432 608.368 M( int myint = 3;)S
1.432 597.568 M( char *mystr;)S
1.432 575.968 M( MODULE_PARM\(myint, "i"\);)S
1.432 565.168 M( MODULE_PARM\(mystr, "s"\);)S
11 FS/F4 SF 0 526.935 M(Arrays are supported too. An integer value preceding the type in MODULE_PARM will indicate an array of)S
0 513.735 M(some maximum length. Two numbers separated by a '-' will give the minimum and maximum number of)S
0 500.535 M(values. For example, an array of shorts with at least 2 and no more than 4 values could be declared as:)S
9 FS/F0 SF 1.432 474.703 M( int myshortArray[4];)S
1.432 463.903 M( MODULE_PARM \(myintArray, "3-9i"\);)S
11 FS/F4 SF 0 425.671 M(A good use for this is to have the module variable's default values set, like an port or IO address. If the)S
0 412.471 M(variables contain the default values, then perform autodetection \(explained elsewhere\). Otherwise, keep the)S
0 399.271 M(current value. This will be made clear later on.)S
0 372.87 M(Lastly, there's a macro function, )S
/F0 SF (MODULE_PARM_DESC\(\))S
/F4 SF (, that is used to document arguments that the)S
0 359.67 M(module can take. It takes two parameters: a variable name and a free form string describing that variable.)S
/F5 SF 0 320.07 M(Example 2-7. hello-5.c)S
9 FS/F0 SF 1.432 294.238 M(/* hello-5.c - Demonstrates command line argument passing to a module.)S
1.432 283.438 M( */)S
1.432 272.638 M(#include )S
1.432 261.838 M(#include )S
1.432 251.038 M(#include )S
1.432 240.238 M(MODULE_LICENSE\("GPL"\);)S
1.432 229.438 M(MODULE_AUTHOR\("Peiter Jay Salzman"\);)S
1.432 207.838 M(// These global variables can be set with command line arguments when you insmod)S
1.432 197.038 M(// the module in. )S
1.432 186.238 M(//)S
1.432 175.438 M(static u8 mybyte = 'A';)S
1.432 164.638 M(static unsigned short myshort = 1;)S
1.432 153.838 M(static int myint = 20;)S
1.432 143.038 M(static long mylong = 9999;)S
1.432 132.238 M(static char *mystring = "blah";)S
1.432 121.438 M(static int myintArray[2] = { 0, 420 };)S
1.432 99.838 M(/* Now we're actually setting the mechanism up -- making the variables command)S
1.432 89.038 M( * line arguments rather than just a bunch of global variables.)S
1.432 78.238 M( */)S
1.432 67.438 M(MODULE_PARM\(mybyte, "b"\);)S
1.432 56.638 M(MODULE_PARM\(myshort, "h"\);)S
1.432 45.838 M(MODULE_PARM\(myint, "i"\);)S
1.432 35.038 M(MODULE_PARM\(mylong, "l"\);)S
1.432 24.238 M(MODULE_PARM\(mystring, "s"\);)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(2.6. Passing Command Line Arguments to a Module)S
474.768 0 M(11)S
GR
SP
%%Page: 12 17
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 403.536 M 487.0 294.5 F
0 91.071 M 487.7 273.6 F
0.00 0.00 0.00 C 0 363.936 M 487.7 0.7 F
0 91.071 M 0.7 273.6 F
487 91.071 M 0.7 273.6 F
0 91.071 M 487.7 0.7 F
0 82.471 M 487.0 2.0 F
9 FS/F0 SF 1.432 687.568 M(MODULE_PARM\(myintArray, "1-2i"\);)S
1.432 665.968 M(MODULE_PARM_DESC\(mybyte, "This byte really does nothing at all."\);)S
1.432 655.168 M(MODULE_PARM_DESC\(myshort, "This short is *extremely* important."\);)S
1.432 644.368 M(// You get the picture. Always use a MODULE_PARM_DESC\(\) for each MODULE_PARM\(\).)S
1.432 611.968 M(static int __init hello_5_init\(void\))S
1.432 601.168 M({)S
1.432 590.368 M( printk\(KERN_ALERT "mybyte is an 8 bit integer: %i\\n", mybyte\);)S
1.432 579.568 M( printk\(KERN_ALERT "myshort is a short integer: %hi\\n", myshort\);)S
1.432 568.768 M( printk\(KERN_ALERT "myint is an integer: %i\\n", myint\);)S
1.432 557.968 M( printk\(KERN_ALERT "mylong is a long integer: %li\\n", mylong\);)S
1.432 547.168 M( printk\(KERN_ALERT "mystring is a string: %s\\n", mystring\);)S
1.432 536.368 M( printk\(KERN_ALERT "myintArray is %i and %i\\n", myintArray[0], myintArray[1]\);)S
1.432 525.568 M( return 0;)S
1.432 514.768 M(})S
1.432 482.368 M(static void __exit hello_5_exit\(void\))S
1.432 471.568 M({)S
1.432 460.768 M( printk\(KERN_ALERT "Goodbye, world 5\\n"\);)S
1.432 449.968 M(})S
1.432 417.568 M(module_init\(hello_5_init\);)S
1.432 406.768 M(module_exit\(hello_5_exit\);)S
11 FS/F4 SF 0 379.336 M(I would recommend playing around with this code:)S
9 FS/F0 SF 1.432 353.503 M( satan# insmod hello-5.o mystring="bebop" mybyte=255 myintArray=-1)S
1.432 342.703 M( mybyte is an 8 bit integer: 255)S
1.432 331.903 M( myshort is a short integer: 1)S
1.432 321.103 M( myint is an integer: 20)S
1.432 310.303 M( mylong is a long integer: 9999)S
1.432 299.503 M( mystring is a string: bebop)S
1.432 288.703 M( myintArray is -1 and 420)S
1.432 267.103 M( satan# rmmod hello-5)S
1.432 256.303 M( Goodbye, world 5)S
1.432 234.703 M( satan# insmod hello-5.o mystring="supercalifragilisticexpialidocious" \\)S
1.432 223.903 M( > mybyte=256 myintArray=-1,-1)S
1.432 213.103 M( mybyte is an 8 bit integer: 0)S
1.432 202.303 M( myshort is a short integer: 1)S
1.432 191.503 M( myint is an integer: 20)S
1.432 180.703 M( mylong is a long integer: 9999)S
1.432 169.903 M( mystring is a string: supercalifragilisticexpialidocious)S
1.432 159.103 M( myintArray is -1 and -1)S
1.432 137.503 M( satan# rmmod hello-5)S
1.432 126.703 M( Goodbye, world 5)S
1.432 105.103 M( satan# insmod hello-5.o mylong=hello)S
1.432 94.303 M( hello-5.o: invalid argument syntax for mylong: 'h')S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(2.6. Passing Command Line Arguments to a Module)S
474.768 0 M(12)S
GR
SP
%%Page: 13 18
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 348.335 M 487.0 121.7 F
0 82.67 M 487.0 186.5 F
0.00 0.00 0.00 C 14 FS/F9 SF 0 684 M(2.7. Modules Spanning Multiple Files)S
11 FS/F4 SF 0 657 M(Sometimes it makes sense to divide a kernel module between several source files. In this case, you need to:)S
36 630.6 M(In all the source files but one, add the line)S
/F5 SF ( #define __NO_VERSION__)S
/F4 SF (. This is important because)S
/F0 SF 36 617.4 M(module.h)S
/F4 SF ( normally includes the definition of)S
/Fa SF ( kernel_version)S
/F4 SF (, a global variable with the kernel)S
36 604.2 M(version the module is compiled for. If you need )S
/F0 SF (version.h)S
/F4 SF (, you need to include it yourself,)S
36 591 M(because )S
/F0 SF (module.h)S
/F4 SF ( won't do it for you with)S
/Fa SF ( __NO_VERSION__)S
/F4 SF (.)S
25 630.6 M(1. )S
36 577.8 M(Compile all the source files as usual.)S
25 577.8 M(2. )S
36 564.6 M(Combine all the object files into a single one. Under x86, use)S
/F5 SF ( ld -m elf_i386 -r -o <1st src file.o> <2nd src file.o>)S
/F4 SF (.)S
25 564.6 M(3. )S
0 525 M(Here's an example of such a kernel module.)S
/F5 SF 0 485.4 M(Example 2-8. start.c)S
9 FS/F0 SF 1.432 459.567 M(/* start.c - Illustration of multi filed modules)S
1.432 448.767 M( */)S
1.432 427.168 M(#include /* We're doing kernel work */)S
1.432 416.368 M(#include /* Specifically, a module */)S
1.432 394.768 M(int init_module\(void\))S
1.432 383.968 M({)S
1.432 373.168 M( printk\("Hello, world - this is the kernel speaking\\n"\);)S
1.432 362.368 M( return 0;)S
1.432 351.568 M(})S
11 FS/F4 SF 0 324.135 M(The next file:)S
/F5 SF 0 284.535 M(Example 2-9. stop.c)S
9 FS/F0 SF 1.432 258.703 M(/* stop.c - Illustration of multi filed modules)S
1.432 247.903 M( */)S
1.432 226.303 M(#if defined\(CONFIG_MODVERSIONS\) && ! defined\(MODVERSIONS\))S
1.432 215.503 M( #include /* Will be explained later */)S
1.432 204.703 M( #define MODVERSIONS)S
1.432 193.903 M(#endif )S
1.432 183.103 M(#include /* We're doing kernel work */)S
1.432 172.303 M(#include /* Specifically, a module */)S
1.432 161.503 M(#define __NO_VERSION__ /* It's not THE file of the kernel module */)S
1.432 150.703 M(#include /* Not included by module.h because of)S
1.432 139.903 M( __NO_VERSION__ */)S
1.432 118.303 M(void cleanup_module\(\))S
1.432 107.503 M({)S
1.432 96.703 M( printk\("<1>Short is the life of a kernel module\\n"\);)S
1.432 85.903 M(} )S
11 FS/F4 SF 0 58.47 M(And finally, the makefile:)S
/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(2.7. Modules Spanning Multiple Files)S
474.768 0 M(13)S
GR
SP
%%Page: 14 19
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 549.935 M 487.7 122.4 F
0.00 0.00 0.00 C 0 671.6 M 487.7 0.7 F
0 549.935 M 0.7 122.4 F
487 549.935 M 0.7 122.4 F
0 549.935 M 487.7 0.7 F
0 541.335 M 487.0 2.0 F
11 FS/F5 SF 0 687 M(Example 2-10. Makefile for a multi-filed module)S
9 FS/F0 SF 1.432 661.168 M(CC=gcc)S
1.432 650.368 M(MODCFLAGS := -O -Wall -DMODULE -D__KERNEL__)S
1.432 628.768 M(hello.o: hello2_start.o hello2_stop.o)S
1.432 617.968 M( ld -m elf_i386 -r -o hello2.o hello2_start.o hello2_stop.o)S
1.432 596.368 M(start.o: hello2_start.c)S
1.432 585.568 M( ${CC} ${MODCFLAGS} -c hello2_start.c)S
1.432 563.968 M(stop.o: hello2_stop.c)S
1.432 553.168 M( ${CC} ${MODCFLAGS} -c hello2_stop.c)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(2.7. Modules Spanning Multiple Files)S
474.768 0 M(14)S
GR
SP
%%Page: 15 20
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0 411 M 487.0 2.0 F
0.88 0.88 0.88 C 0 67.935 M 487.7 46.8 F
0.00 0.00 0.00 C 0 114 M 487.7 0.7 F
0 67.935 M 0.7 46.8 F
487 67.935 M 0.7 46.8 F
0 67.935 M 487.7 0.7 F
20 FS/F9 SF 0 678 M(Chapter 3. Preliminaries)S
14 FS/F9 SF 0 646.8 M(3.1. Modules vs Programs)S
11 FS/F9 SF 0 619.8 M(3.1.1. How modules begin and end)S
/F4 SF 0 593.4 M(A program usually begins with a )S
/F0 SF (main\(\))S
/F4 SF ( function, executes a bunch of instructions and terminates upon)S
0 580.2 M(completion of those instructions. Kernel modules work a bit differently. A module always begin with either)S
0 567 M(the )S
/F0 SF (init_module)S
/F4 SF ( or the function you specify with )S
/F0 SF (module_init)S
/F4 SF ( call. This is the entry function for)S
0 553.8 M(modules; it tells the kernel what functionality the module provides and sets up the kernel to run the module's)S
0 540.6 M(functions when they're needed. Once it does this, entry function returns and the module does nothing until the)S
0 527.4 M(kernel wants to do something with the code that the module provides.)S
0 501 M(All modules end by calling either )S
/F0 SF (cleanup_module)S
/F4 SF ( or the function you specify with the )S
/F0 SF (module_exit)S
/F4 SF 0 487.8 M(call. This is the exit function for modules; it undoes whatever entry function did. It unregisters the)S
0 474.6 M(functionality that the entry function registered.)S
0 448.2 M(Every module must have an entry function and an exit function. Since there's more than one way to specify)S
0 435 M(entry and exit functions, I'll try my best to use the terms `entry function' and `exit function', but if I slip and)S
0 421.8 M(simply refer to them as )S
/F0 SF (init_module)S
/F4 SF ( and )S
/F0 SF (cleanup_module)S
/F4 SF (, I think you'll know what I mean.)S
/F9 SF 0 393.4 M(3.1.2. Functions available to modules)S
/F4 SF 0 367 M(Programmers use functions they don't define all the time. A prime example of this is )S
/F0 SF (printf\(\))S
/F4 SF (. You use)S
0 353.8 M(these library functions which are provided by the standard C library, libc. The definitions for these functions)S
0 340.6 M(don't actually enter your program until the linking stage, which insures that the code \(for )S
/F0 SF (printf\(\))S
/F4 SF ( for)S
0 327.4 M(example\) is available, and fixes the call instruction to point to that code.)S
0 301 M(Kernel modules are different here, too. In the hello world example, you might have noticed that we used a)S
0 287.8 M(function, )S
/F0 SF (printk\(\))S
/F4 SF ( but didn't include a standard I/O library. That's because modules are object files whose)S
0 274.6 M(symbols get resolved upon insmod'ing. The definition for the symbols comes from the kernel itself; the only)S
0 261.4 M(external functions you can use are the ones provided by the kernel. If you're curious about what symbols have)S
0 248.2 M(been exported by your kernel, take a look at )S
/F0 SF (/proc/ksyms)S
/F4 SF (.)S
0 221.8 M(One point to keep in mind is the difference between library functions and system calls. Library functions are)S
0 208.6 M(higher level, run completely in user space and provide a more convenient interface for the programmer to the)S
0 195.4 M(functions that do the real work---system calls. System calls run in kernel mode on the user's behalf and are)S
0 182.2 M(provided by the kernel itself. The library function )S
/F0 SF (printf\(\))S
/F4 SF ( may look like a very general printing function,)S
0 169 M(but all it really does is format the data into strings and write the string data using the low-level system call)S
/F0 SF 0 155.8 M(write\(\))S
/F4 SF (, which then sends the data to standard output.)S
0 129.4 M(Would you like to see what system calls are made by )S
/F0 SF (printf\(\))S
/F4 SF (? It's easy! Compile the following program:)S
9 FS/F0 SF 1.432 103.567 M( #include )S
1.432 92.767 M( int main\(void\))S
1.432 81.967 M( { printf\("hello"\); return 0; })S
11 FS/F4 SF 0 43.735 M(with)S
/F5 SF ( gcc -Wall -o hello hello.c)S
/F4 SF (. Run the exectable with)S
/F5 SF ( strace hello)S
/F4 SF (. Are you impressed? Every line you see)S
0 30.535 M(corresponds to a system call. strace)S
([3] is a handy program that gives you details about what system calls a)S
/F8 SF 0 0 M(Chapter 3. Preliminaries)S
474.768 0 M(15)S
GR
SP
%%Page: 16 21
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0 544.2 M 487.0 2.0 F
0 331 M 487.0 2.0 F
0 91.4 M 487.0 2.0 F
11 FS/F4 SF 0 687 M(program is making, including which call is made, what its arguments are what it returns. It's an invaluable tool)S
0 673.8 M(for figuring out things like what files a program is trying to access. Towards the end, you'll see a line which)S
0 660.6 M(looks like )S
/F0 SF (write\(1, "hello", 5hello\))S
/F4 SF (. There it is. The face behind the )S
/F0 SF (printf\(\))S
/F4 SF ( mask. You may)S
0 647.4 M(not be familiar with write, since most people use library functions for file I/O \(like fopen, fputs, fclose\). If)S
0 634.2 M(that's the case, try looking at)S
/F5 SF ( man 2 write)S
/F4 SF (. The 2nd man section is devoted to system calls \(like )S
/F0 SF (kill\(\))S
/F4 SF ( and)S
/F0 SF 0 621 M(read\(\))S
/F4 SF (. The 3rd man section is devoted to library calls, which you would probably be more familiar with)S
0 607.8 M(\(like )S
/F0 SF (cosh\(\))S
/F4 SF ( and )S
/F0 SF (random\(\))S
/F4 SF (\).)S
0 581.4 M(You can even write modules to replace the kernel's system calls, which we'll do shortly. Crackers often make)S
0 568.2 M(use of this sort of thing for backdoors or trojans, but you can write your own modules to do more benign)S
0 555 M(things, like have the kernel write)S
/F6 SF ( Tee hee, that tickles!)S
/F4 SF ( everytime someone tries to delete a file on your system.)S
/F9 SF 0 526.6 M(3.1.3. User Space vs Kernel Space)S
/F4 SF 0 500.2 M(A kernel is all about access to resources, whether the resource in question happens to be a video card, a hard)S
0 487 M(drive or even memory. Programs often compete for the same resource. As I just saved this document,)S
0 473.8 M(updatedb started updating the locate database. My vim session and updatedb are both using the hard drive)S
0 460.6 M(concurrently. The kernel needs to keep things orderly, and not give users access to resources whenever they)S
0 447.4 M(feel like it. To this end, a CPU can run in different modes. Each mode gives a different level of freedom to do)S
0 434.2 M(what you want on the system. The Intel 80386 architecture has 4 of these modes, which are called rings. Unix)S
0 421 M(uses only two rings; the highest ring \(ring 0, also known as `supervisor mode' where everything is allowed to)S
0 407.8 M(happen\) and the lowest ring, which is called `user mode'.)S
0 381.4 M(Recall the discussion about library functions vs system calls. Typically, you use a library function in user)S
0 368.2 M(mode. The library function calls one or more system calls, and these system calls execute on the library)S
0 355 M(function's behalf, but do so in supervisor mode since they are part of the kernel itself. Once the system call)S
0 341.8 M(completes its task, it returns and execution gets transfered back to user mode.)S
/F9 SF 0 313.4 M(3.1.4. Name Space)S
/F4 SF 0 287 M(When you write a small C program, you use variables which are convenient and make sense to the reader. If,)S
0 273.8 M(on the other hand, you're writing routines which will be part of a bigger problem, any global variables you)S
0 260.6 M(have are part of a community of other peoples' global variables; some of the variable names can clash. When a)S
0 247.4 M(program has lots of global variables which aren't meaningful enough to be distinguished, you get)S
/F6 SF ( namespace)S
0 234.2 M(pollution)S
/F4 SF (. In large projects, effort must be made to remember reserved names, and to find ways to develop a)S
0 221 M(scheme for naming unique variable names and symbols.)S
0 194.6 M(When writing kernel code, even the smallest module will be linked against the entire kernel, so this is)S
0 181.4 M(definitely an issue. The best way to deal with this is to declare all your variables as static and to use a)S
0 168.2 M(well-defined prefix for your symbols. By convention, all kernel prefixes are lowercase. If you don't want to)S
0 155 M(declare everything as static, another option is to declare a)S
/Fa SF ( symbol table)S
/F4 SF ( and register it with a kernel. We'll get)S
0 141.8 M(to this later.)S
0 115.4 M(The file )S
/F0 SF (/proc/ksyms)S
/F4 SF ( holds all the symbols that the kernel knows about and which are therefore accessible)S
0 102.2 M(to your modules since they share the kernel's codespace.)S
/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(3.1. Modules vs Programs)S
474.768 0 M(16)S
GR
SP
%%Page: 17 22
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0 359.4 M 487.0 2.0 F
0 238.6 M 487.0 2.0 F
0.88 0.88 0.88 C 0 111.535 M 487.7 57.6 F
0.00 0.00 0.00 C 0 168.4 M 487.7 0.7 F
0 111.535 M 0.7 57.6 F
487 111.535 M 0.7 57.6 F
0 111.535 M 487.7 0.7 F
11 FS/F9 SF 0 687 M(3.1.5. Code space)S
/F4 SF 0 660.6 M(Memory management is a very complicated subject---the majority of O'Reilly's `Understanding The Linux)S
0 647.4 M(Kernel' is just on memory management! We're not setting out to be experts on memory managements, but we)S
0 634.2 M(do need to know a couple of facts to even begin worrying about writing real modules.)S
0 607.8 M(If you haven't thought about what a segfault really means, you may be surprised to hear that pointers don't)S
0 594.6 M(actually point to memory locations. Not real ones, anyway. When a process is created, the kernel sets aside a)S
0 581.4 M(portion of real physical memory and hands it to the process to use for its executing code, variables, stack, heap)S
0 568.2 M(and other things which a computer scientist would know about)S
([4]. This memory begins with $0$ and extends)S
0 555 M(up to whatever it needs to be. Since the memory space for any two processes don't overlap, every process that)S
0 541.8 M(can access a memory address, say)S
/Fa SF ( 0xbffff978)S
/F4 SF (, would be accessing a different location in real physical)S
0 528.6 M(memory! The processes would be accessing an index named)S
/Fa SF ( 0xbffff978)S
/F4 SF ( which points to some kind of offset)S
0 515.4 M(into the region of memory set aside for that particular process. For the most part, a process like our Hello,)S
0 502.2 M(World program can't access the space of another process, although there are ways which we'll talk about later.)S
0 475.8 M(The kernel has its own space of memory as well. Since a module is code which can be dynamically inserted)S
0 462.6 M(and removed in the kernel \(as opposed to a semi-autonomous object\), it shares the kernel's codespace rather)S
0 449.4 M(than having its own. Therefore, if your module segfaults, the kernel segfaults. And if you start writing over)S
0 436.2 M(data because of an off-by-one error, then you're trampling on kernel code. This is even worse than it sounds,)S
0 423 M(so try your best to be careful.)S
0 396.6 M(By the way, I would like to point out that the above discussion is true for any operating system which uses a)S
0 383.4 M(monolithic kernel)S
([5]. There are things called microkernels which have modules which get their own)S
0 370.2 M(codespace. The GNU Hurd and QNX Neutrino are two examples of a microkernel.)S
/F9 SF 0 341.8 M(3.1.6. Device Drivers)S
/F4 SF 0 315.4 M(One class of module is the device driver, which provides functionality for hardware like a TV card or a serial)S
0 302.2 M(port. On unix, each piece of hardware is represented by a file located in )S
/F0 SF (/dev)S
/F4 SF ( named a )S
/F0 SF (device file)S
/F4 SF 0 289 M(which provides the means to communicate with the hardware. The device driver provides the communication)S
0 275.8 M(on behalf of a user program. So the )S
/F0 SF (es1370.o)S
/F4 SF ( sound card device driver might connect the )S
/F0 SF (/dev/sound)S
/F4 SF 0 262.6 M(device file to the Ensoniq IS1370 sound card. A userspace program like mp3blaster can use )S
/F0 SF (/dev/sound)S
/F4 SF 0 249.4 M(without ever knowing what kind of sound card is installed.)S
9 FS/F9 SF 0 223 M(3.1.6.1. Major and Minor Numbers)S
11 FS/F4 SF 0 197 M(Let's look at some device files. Here are device files which represent the first three partitions on the primary)S
0 183.8 M(master IDE hard drive:)S
9 FS/F0 SF 1.432 157.967 M( # ls -l /dev/hda[1-3])S
1.432 147.167 M( brw-rw---- 1 root disk 3, 1 Jul 5 2000 /dev/hda1)S
1.432 136.367 M( brw-rw---- 1 root disk 3, 2 Jul 5 2000 /dev/hda2)S
1.432 125.567 M( brw-rw---- 1 root disk 3, 3 Jul 5 2000 /dev/hda3)S
11 FS/F4 SF 0 87.335 M(Notice the column of numbers separated by a comma? The first number is called the device's major number.)S
0 74.135 M(The second number is the minor number. The major number tells you which driver is used to access the)S
0 60.935 M(hardware. Each driver is assigned a unique major number; all device files with the same major number are)S
0 47.735 M(controlled by the same driver. All the above major numbers are 3, because they're all controlled by the same)S
0 34.535 M(driver.)S
/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(3.1. Modules vs Programs)S
474.768 0 M(17)S
GR
SP
%%Page: 18 23
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 443.135 M 487.7 57.6 F
0.00 0.00 0.00 C 0 500 M 487.7 0.7 F
0 443.135 M 0.7 57.6 F
487 443.135 M 0.7 57.6 F
0 443.135 M 487.7 0.7 F
0.88 0.88 0.88 C 0 133.07 M 487.7 46.8 F
0.00 0.00 0.00 C 0 179.135 M 487.7 0.7 F
0 133.07 M 0.7 46.8 F
487 133.07 M 0.7 46.8 F
0 133.07 M 487.7 0.7 F
11 FS/F4 SF 0 687 M(The minor number is used by the driver to distinguish between the various hardware it controls. Returning to)S
0 673.8 M(the example above, although all three devices are handled by the same driver they have unique minor numbers)S
0 660.6 M(because the driver sees them as being different pieces of hardware.)S
0 634.2 M(Devices are divided into two types: character devices and block devices. The difference is that block devices)S
0 621 M(have a buffer for requests, so they can choose the best order in which to respond to the requests. This is)S
0 607.8 M(important in the case of storage devices, where it's faster to read or write sectors which are close to each other,)S
0 594.6 M(rather than those which are further apart. Another difference is that block devices can only accept input and)S
0 581.4 M(return output in blocks \(whose size can vary according to the device\), whereas character devices are allowed)S
0 568.2 M(to use as many or as few bytes as they like. Most devices in the world are character, because they don't need)S
0 555 M(this type of buffering, and they don't operate with a fixed block size. You can tell whether a device file is for a)S
0 541.8 M(block device or a character device by looking at the first character in the output of)S
/F5 SF ( ls -l)S
/F4 SF (. If it's `b' then it's a)S
0 528.6 M(block device, and if it's `c' then it's a character device. The devices you see above are block devices. Here are)S
0 515.4 M(some character devices \(the serial ports\):)S
9 FS/F0 SF 1.432 489.567 M( crw-rw---- 1 root dial 4, 64 Feb 18 23:34 /dev/ttyS0)S
1.432 478.767 M( crw-r----- 1 root dial 4, 65 Nov 17 10:26 /dev/ttyS1)S
1.432 467.967 M( crw-rw---- 1 root dial 4, 66 Jul 5 2000 /dev/ttyS2)S
1.432 457.168 M( crw-rw---- 1 root dial 4, 67 Jul 5 2000 /dev/ttyS3)S
11 FS/F4 SF 0 418.935 M(If you want to see which major numbers have been assigned, you can look at)S
/F0 SF 0 405.735 M(/usr/src/linux/Documentation/devices.txt)S
/F4 SF (.)S
0 379.335 M(When the system was installed, all of those device files were created by the)S
/F5 SF ( mknod)S
/F4 SF ( command. To create a)S
0 366.135 M(new char device named `coffee' with major/minor number)S
/Fa SF ( 12)S
/F4 SF ( and)S
/Fa SF ( 2)S
/F4 SF (, simply do)S
/F5 SF ( mknod /dev/coffee c 12 2)S
/F4 SF (.)S
0 352.935 M(You don't)S
/F6 SF ( have)S
/F4 SF ( to put your device files into )S
/F0 SF (/dev)S
/F4 SF (, but it's done by convention. Linus put his device files in)S
/F0 SF 0 339.735 M(/dev)S
/F4 SF (, and so should you. However, when creating a device file for testing purposes, it's probably OK to place)S
0 326.535 M(it in your working directory where you compile the kernel module. Just be sure to put it in the right place)S
0 313.335 M(when you're done writing the device driver.)S
0 286.935 M(I would like to make a few last points which are implicit from the above discussion, but I'd like to make them)S
0 273.735 M(explicit just in case. When a device file is accessed, the kernel uses the major number of the file to determine)S
0 260.535 M(which driver should be used to handle the access. This means that the kernel doesn't really need to use or even)S
0 247.335 M(know about the minor number. The driver itself is the only thing that cares about the minor number. It uses)S
0 234.135 M(the minor number to distinguish between different pieces of hardware.)S
0 207.735 M(By the way, when I say `hardware', I mean something a bit more abstract than a PCI card that you can hold in)S
0 194.535 M(your hand. Look at these two device files:)S
9 FS/F0 SF 1.432 168.703 M( % ls -l /dev/fd0 /dev/fd0u1680)S
1.432 157.903 M( brwxrwxrwx 1 root floppy 2, 0 Jul 5 2000 /dev/fd0)S
1.432 147.103 M( brw-rw---- 1 root floppy 2, 44 Jul 5 2000 /dev/fd0u1680)S
11 FS/F4 SF 0 108.87 M(By now you can look at these two device files and know instantly that they are block devices and are handled)S
0 95.67 M(by same driver \(block major)S
/Fa SF ( 2)S
/F4 SF (\). You might even be aware that these both represent your floppy drive, even if)S
0 82.47 M(you only have one floppy drive. Why two files? One represents the floppy drive with)S
/Fa SF ( 1.44)S
/F4 SF ( MB of storage.)S
0 69.27 M(The other is the)S
/F6 SF ( same)S
/F4 SF ( floppy drive with)S
/Fa SF ( 1.68)S
/F4 SF ( MB of storage, and corresponds to what some people call a)S
0 56.07 M(`superformatted' disk. One that holds more data than a standard formatted floppy. So here's a case where two)S
0 42.87 M(device files with different minor number actually represent the same piece of physical hardware. So just be)S
0 29.67 M(aware that the word `hardware' in our discussion can mean something very abstract.)S
/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(3.1. Modules vs Programs)S
474.768 0 M(18)S
GR
SP
%%Page: 19 24
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0 689.4 M 487.0 2.0 F
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(3.1. Modules vs Programs)S
474.768 0 M(19)S
GR
SP
%%Page: 20 25
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0 635.4 M 487.0 2.0 F
0.88 0.88 0.88 C 0 267.135 M 487.7 230.4 F
0.00 0.00 0.00 C 0 496.8 M 487.7 0.7 F
0 267.135 M 0.7 230.4 F
487 267.135 M 0.7 230.4 F
0 267.135 M 487.7 0.7 F
0.88 0.88 0.88 C 0 83.071 M 487.7 79.2 F
0.00 0.00 0.00 C 0 161.535 M 487.7 0.7 F
0 83.071 M 0.7 79.2 F
487 83.071 M 0.7 79.2 F
0 83.071 M 487.7 0.7 F
20 FS/F9 SF 0 678 M(Chapter 4. Character Device Files)S
14 FS/F9 SF 0 646.8 M(4.1. Character Device Drivers)S
11 FS/F9 SF 0 617.8 M(4.1.1. The file_operations Structure)S
/F4 SF 0 591.4 M(The file_operations structure is defined in )S
/F0 SF (linux/fs.h)S
/F4 SF (, and holds pointers to functions defined by the)S
0 578.2 M(driver that perform various operations on the device. Each field of the structure corresponds to the address of)S
0 565 M(some function defined by the driver to handle a requested operation.)S
0 538.6 M(For example, every character driver needs to define a function that reads from the device. The file_operations)S
0 525.4 M(structure holds the address of the module's function that performs that operation. Here is what the definition)S
0 512.2 M(looks like for kernel)S
/Fa SF ( 2.4.2)S
/F4 SF (:)S
9 FS/F0 SF 1.432 486.368 M( struct file_operations {)S
1.432 475.568 M( struct module *owner;)S
1.432 464.768 M( loff_t \(*llseek\) \(struct file *, loff_t, int\);)S
1.432 453.968 M( ssize_t \(*read\) \(struct file *, char *, size_t, loff_t *\);)S
1.432 443.168 M( ssize_t \(*write\) \(struct file *, const char *, size_t, loff_t *\);)S
1.432 432.368 M( int \(*readdir\) \(struct file *, void *, filldir_t\);)S
1.432 421.568 M( unsigned int \(*poll\) \(struct file *, struct poll_table_struct *\);)S
1.432 410.768 M( int \(*ioctl\) \(struct inode *, struct file *, unsigned int, unsigned long\);)S
1.432 399.968 M( int \(*mmap\) \(struct file *, struct vm_area_struct *\);)S
1.432 389.168 M( int \(*open\) \(struct inode *, struct file *\);)S
1.432 378.368 M( int \(*flush\) \(struct file *\);)S
1.432 367.568 M( int \(*release\) \(struct inode *, struct file *\);)S
1.432 356.768 M( int \(*fsync\) \(struct file *, struct dentry *, int datasync\);)S
1.432 345.968 M( int \(*fasync\) \(int, struct file *, int\);)S
1.432 335.168 M( int \(*lock\) \(struct file *, int, struct file_lock *\);)S
1.432 324.368 M( ssize_t \(*readv\) \(struct file *, const struct iovec *, unsigned long,)S
1.432 313.568 M( loff_t *\);)S
1.432 302.768 M( ssize_t \(*writev\) \(struct file *, const struct iovec *, unsigned long,)S
1.432 291.968 M( loff_t *\);)S
1.432 281.168 M( };)S
11 FS/F4 SF 0 242.935 M(Some operations are not implemented by a driver. For example, a driver that handles a video card won't need)S
0 229.735 M(to read from a directory structure. The corresponding entries in the file_operations structure should be set to)S
/Fa SF 0 216.535 M(NULL)S
/F4 SF (.)S
0 190.135 M(There is a gcc extension that makes assigning to this structure more convenient. You'll see it in modern)S
0 176.935 M(drivers, and may catch you by surprise. This is what the new way of assigning to the structure looks like:)S
9 FS/F0 SF 1.432 151.103 M( struct file_operations fops = {)S
1.432 140.303 M( read: device_read,)S
1.432 129.503 M( write: device_write,)S
1.432 118.703 M( open: device_open,)S
1.432 107.903 M( release: device_release)S
1.432 97.103 M( };)S
11 FS/F4 SF 0 58.871 M(However, there's also a C99 way of assigning to elements of a structure, and this is definitely preferred over)S
0 45.671 M(using the GNU extension. The version of gcc I'm currently using,)S
/Fa SF ( 2.95)S
/F4 SF (, supports the new C99 syntax. You)S
0 32.471 M(should use this syntax in case someone wants to port your driver. It will help with compatibility:)S
/F8 SF 0 0 M(Chapter 4. Character Device Files)S
474.768 0 M(20)S
GR
SP
%%Page: 21 26
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 619.535 M 487.7 79.2 F
0.00 0.00 0.00 C 0 698 M 487.7 0.7 F
0 619.535 M 0.7 79.2 F
487 619.535 M 0.7 79.2 F
0 619.535 M 487.7 0.7 F
0 544.935 M 487.0 2.0 F
0 344.935 M 487.0 2.0 F
0.88 0.88 0.88 C 0 171.07 M 487.7 36.0 F
0.00 0.00 0.00 C 0 206.335 M 487.7 0.7 F
0 171.07 M 0.7 36.0 F
487 171.07 M 0.7 36.0 F
0 171.07 M 487.7 0.7 F
9 FS/F0 SF 1.432 687.568 M( struct file_operations fops = {)S
1.432 676.768 M( .read = device_read,)S
1.432 665.968 M( .write = device_write,)S
1.432 655.168 M( .open = device_open,)S
1.432 644.368 M( .release = device_release)S
1.432 633.568 M( };)S
11 FS/F4 SF 0 595.335 M(The meaning is clear, and you should be aware that any member of the structure which you don't explicitly)S
0 582.135 M(assign will be initialized to)S
/Fa SF ( NULL)S
/F4 SF ( by gcc.)S
0 555.735 M(A pointer to a struct file_operations is commonly named)S
/Fa SF ( fops)S
/F4 SF (.)S
/F9 SF 0 527.335 M(4.1.2. The file structure)S
/F4 SF 0 500.935 M(Each device is represented in the kernel by a file structure, which is defined in )S
/F0 SF (linux/fs.h)S
/F4 SF (. Be aware that a)S
0 487.735 M(file is a kernel level structure and never appears in a user space program. It's not the same thing as a FILE,)S
0 474.535 M(which is defined by glibc and would never appear in a kernel space function. Also, its name is a bit)S
0 461.335 M(misleading; it represents an abstract open `file', not a file on a disk, which is represented by a structure named)S
0 448.135 M(inode.)S
0 421.735 M(A pointer to a)S
/Fa SF ( struct file)S
/F4 SF ( is commonly named )S
/F0 SF (filp)S
/F4 SF (. You'll also see it refered to as)S
/Fa SF ( struct file file)S
/F4 SF (. Resist the)S
0 408.535 M(temptation.)S
0 382.135 M(Go ahead and look at the definition of )S
/F0 SF (file)S
/F4 SF (. Most of the entries you see, like )S
/F0 SF (struct dentry)S
/F4 SF ( aren't used)S
0 368.935 M(by device drivers, and you can ignore them. This is because drivers don't fill)S
/Fa SF ( file)S
/F4 SF ( directly; they only use)S
0 355.735 M(structures contained in)S
/Fa SF ( file)S
/F4 SF ( which are created elsewhere.)S
/F9 SF 0 327.335 M(4.1.3. Registering A Device)S
/F4 SF 0 300.935 M(As discussed earlier, char devices are accessed through device files, usually located in )S
/F0 SF (/dev)S
/F4 SF ([6]. The major)S
0 287.735 M(number tells you which driver handles which device file. The minor number is used only by the driver itself to)S
0 274.535 M(differentiate which device it's operating on, just in case the driver handles more than one device.)S
0 248.135 M(Adding a driver to your system means registering it with the kernel. This is synonymous with assigning it a)S
0 234.935 M(major number during the module's initialization. You do this by using the )S
/F0 SF (register_chrdev)S
/F4 SF ( function,)S
0 221.735 M(defined by )S
/F0 SF (linux/fs.h)S
/F4 SF (.)S
9 FS/F0 SF 1.432 195.903 M( int register_chrdev\(unsigned int major, const char *name,)S
1.432 185.103 M( struct file_operations *fops\); )S
11 FS/F4 SF 0 146.87 M(where)S
/Fa SF ( unsigned int major)S
/F4 SF ( is the major number you want to request,)S
/Fa SF ( const char *name)S
/F4 SF ( is the name of the)S
0 133.67 M(device as it'll appear in )S
/F0 SF (/proc/devices)S
/F4 SF ( and)S
/Fa SF ( struct file_operations *fops)S
/F4 SF ( is a pointer to the)S
/Fa SF 0 120.47 M(file_operations)S
/F4 SF ( table for your driver. A negative return value means the registertration failed. Note that we)S
0 107.27 M(didn't pass the minor number to )S
/F0 SF (register_chrdev)S
/F4 SF (. That's because the kernel doesn't care about the minor)S
0 94.07 M(number; only our driver uses it.)S
0 67.67 M(Now the question is, how do you get a major number without hijacking one that's already in use? The easiest)S
0 54.47 M(way would be to look through )S
/F0 SF (Documentation/devices.txt)S
/F4 SF ( and pick an unused one. That's a bad way)S
0 41.27 M(of doing things because you'll never be sure if the number you picked will be assigned later. The answer is)S
0 28.07 M(that you can ask the kernel to assign you a dynamic major number.)S
/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(4.1. Character Device Drivers)S
474.768 0 M(21)S
GR
SP
%%Page: 22 27
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0 597 M 487.0 2.0 F
0 251.8 M 487.0 2.0 F
0.88 0.88 0.88 C 0 22 M 487.0 64.8 F
0.00 0.00 0.00 C 11 FS/F4 SF 0 687 M(If you pass a major number of 0 to )S
/F0 SF (register_chrdev)S
/F4 SF (, the return value will be the dynamically allocated)S
0 673.8 M(major number. The downside is that you can't make a device file in advance, since you don't know what the)S
0 660.6 M(major number will be. There are a couple of ways to do this. First, the driver itself can print the newly)S
0 647.4 M(assigned number and we can make the device file by hand. Second, the newly registered device will have an)S
0 634.2 M(entry in )S
/F0 SF (/proc/devices)S
/F4 SF (, and we can either make the device file by hand or write a shell script to read the)S
0 621 M(file in and make the device file. The third method is we can have our driver make the the device file using the)S
/F0 SF 0 607.8 M(mknod)S
/F4 SF ( system call after a successful registration and rm during the call to )S
/F0 SF (cleanup_module)S
/F4 SF (.)S
/F9 SF 0 579.4 M(4.1.4. Unregistering A Device)S
/F4 SF 0 553 M(We can't allow the kernel module to be rmmod'ed whenever root feels like it. If the device file is opened by a)S
0 539.8 M(process and then we remove the kernel module, using the file would cause a call to the memory location)S
0 526.6 M(where the appropriate function \(read/write\) used to be. If we're lucky, no other code was loaded there, and)S
0 513.4 M(we'll get an ugly error message. If we're unlucky, another kernel module was loaded into the same location,)S
0 500.2 M(which means a jump into the middle of another function within the kernel. The results of this would be)S
0 487 M(impossible to predict, but they can't be very positive.)S
0 460.6 M(Normally, when you don't want to allow something, you return an error code \(a negative number\) from the)S
0 447.4 M(function which is supposed to do it. With )S
/F0 SF (cleanup_module)S
/F4 SF ( that's impossible because it's a void function.)S
0 434.2 M(However, there's a counter which keeps track of how many processes are using your module. You can see)S
0 421 M(what it's value is by looking at the 3rd field of )S
/F0 SF (/proc/modules)S
/F4 SF (. If this number isn't zero, )S
/F0 SF (rmmod)S
/F4 SF ( will fail.)S
0 407.8 M(Note that you don't have to check the counter from within )S
/F0 SF (cleanup_module)S
/F4 SF ( because the check will be)S
0 394.6 M(performed for you by the system call )S
/F0 SF (sys_delete_module)S
/F4 SF (, defined in )S
/F0 SF (linux/module.c)S
/F4 SF (. You)S
0 381.4 M(shouldn't use this counter directly, but there are macros defined in )S
/F0 SF (linux/modules.h)S
/F4 SF ( which let you)S
0 368.2 M(increase, decrease and display this counter:)S
/Fa SF 36 341.8 M(MOD_INC_USE_COUNT)S
/F4 SF (: Increment the use count.)S
/Fc SF 28.19 341.8 M(\267 )S
/Fa SF 36 328.6 M(MOD_DEC_USE_COUNT)S
/F4 SF (: Decrement the use count.)S
/Fc SF 28.19 328.6 M(\267 )S
/Fa SF 36 315.4 M(MOD_IN_USE)S
/F4 SF (: Display the use count.)S
/Fc SF 28.19 315.4 M(\267 )S
/F4 SF 0 289 M(It's important to keep the counter accurate; if you ever do lose track of the correct usage count, you'll never be)S
0 275.8 M(able to unload the module; it's now reboot time, boys and girls. This is bound to happen to you sooner or later)S
0 262.6 M(during a module's development.)S
/F9 SF 0 234.2 M(4.1.5. chardev.c)S
/F4 SF 0 207.8 M(The next code sample creates a char driver named )S
/F0 SF (chardev)S
/F4 SF (. You can )S
/F0 SF (cat)S
/F4 SF ( its device file \(or )S
/F0 SF (open)S
/F4 SF ( the file)S
0 194.6 M(with a program\) and the driver will put the number of times the device file has been read from into the file.)S
0 181.4 M(We don't support writing to the file \(like)S
/F5 SF ( echo "hi" > /dev/hello)S
/F4 SF (\), but catch these attempts and tell the user)S
0 168.2 M(that the operation isn't supported. Don't worry if you don't see what we do with the data we read into the)S
0 155 M(buffer; we don't do much with it. We simply read in the data and print a message acknowledging that we)S
0 141.8 M(received it.)S
/F5 SF 0 102.2 M(Example 4-1. chardev.c)S
9 FS/F0 SF 1.432 76.367 M(/* chardev.c: Creates a read-only char device that says how many times)S
1.432 65.567 M( * you've read from the dev file)S
1.432 54.767 M( */)S
1.432 33.167 M( #if defined\(CONFIG_MODVERSIONS\) && ! defined\(MODVERSIONS\))S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(4.1. Character Device Drivers)S
474.768 0 M(22)S
GR
SP
%%Page: 23 28
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 687.568 M( #include )S
1.432 676.768 M( #define MODVERSIONS)S
1.432 665.968 M( #endif)S
1.432 655.168 M( #include )S
1.432 644.368 M( #include )S
1.432 633.568 M( #include )S
1.432 622.768 M( #include /* for put_user */)S
1.432 601.168 M( /* Prototypes - this would normally go in a .h file)S
1.432 590.368 M( */)S
1.432 579.568 M( int init_module\(void\);)S
1.432 568.768 M( void cleanup_module\(void\);)S
1.432 557.968 M( static int device_open\(struct inode *, struct file *\);)S
1.432 547.168 M( static int device_release\(struct inode *, struct file *\);)S
1.432 536.368 M( static ssize_t device_read\(struct file *, char *, size_t, loff_t *\);)S
1.432 525.568 M( static ssize_t device_write\(struct file *, const char *, size_t, loff_t *\);)S
1.432 503.968 M( #define SUCCESS 0)S
1.432 493.168 M( #define DEVICE_NAME "chardev" /* Dev name as it appears in /proc/devices */)S
1.432 482.368 M( #define BUF_LEN 80 /* Max length of the message from the device */)S
1.432 449.968 M( /* Global variables are declared as static, so are global within the file. */)S
1.432 428.368 M( static int Major; /* Major number assigned to our device driver */)S
1.432 417.568 M( static int Device_Open = 0; /* Is device open? Used to prevent multiple */)S
1.432 406.768 M( access to the device */)S
1.432 395.968 M( static char msg[BUF_LEN]; /* The msg the device will give when asked */)S
1.432 385.168 M( static char *msg_Ptr;)S
1.432 363.568 M( static struct file_operations fops = {)S
1.432 352.768 M( .read = device_read, )S
1.432 341.968 M( .write = device_write,)S
1.432 331.168 M( .open = device_open,)S
1.432 320.368 M( .release = device_release)S
1.432 309.568 M( };)S
1.432 277.168 M( /* Functions)S
1.432 266.368 M( */)S
1.432 244.768 M( int init_module\(void\))S
1.432 233.968 M( {)S
1.432 223.168 M( Major = register_chrdev\(0, DEVICE_NAME, &fops\);)S
1.432 201.568 M( if \(Major < 0\) {)S
1.432 190.768 M( printk \("Registering the character device failed with %d\\n", Major\);)S
1.432 179.968 M( return Major;)S
1.432 169.168 M( })S
1.432 147.568 M( printk\("<1>I was assigned major number %d. To talk to\\n", Major\);)S
1.432 136.768 M( printk\("<1>the driver, create a dev file with\\n"\);)S
1.432 125.968 M( printk\("'mknod /dev/hello c %d 0'.\\n", Major\);)S
1.432 115.168 M( printk\("<1>Try various minor numbers. Try to cat and echo to\\n"\);)S
1.432 104.368 M( printk\("the device file.\\n"\);)S
1.432 93.568 M( printk\("<1>Remove the device file and module when done.\\n"\);)S
1.432 71.968 M( return 0;)S
1.432 61.168 M( })S
1.432 28.768 M( void cleanup_module\(void\))S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(4.1. Character Device Drivers)S
474.768 0 M(23)S
GR
SP
%%Page: 24 29
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 687.568 M( {)S
1.432 676.768 M( /* Unregister the device */)S
1.432 665.968 M( int ret = unregister_chrdev\(Major, DEVICE_NAME\);)S
1.432 655.168 M( if \(ret < 0\) printk\("Error in unregister_chrdev: %d\\n", ret\);)S
1.432 644.368 M( } )S
1.432 611.968 M( /* Methods)S
1.432 601.168 M( */)S
1.432 579.568 M( /* Called when a process tries to open the device file, like)S
1.432 568.768 M( * "cat /dev/mycharfile")S
1.432 557.968 M( */)S
1.432 547.168 M( static int device_open\(struct inode *inode, struct file *file\))S
1.432 536.368 M( {)S
1.432 525.568 M( static int counter = 0;)S
1.432 514.768 M( if \(Device_Open\) return -EBUSY;)S
1.432 503.968 M( Device_Open++;)S
1.432 493.168 M( sprintf\(msg,"I already told you %d times Hello world!\\n", counter++"\);)S
1.432 482.368 M( msg_Ptr = msg;)S
1.432 471.568 M( MOD_INC_USE_COUNT;)S
1.432 449.968 M( return SUCCESS;)S
1.432 439.168 M( })S
1.432 406.768 M( /* Called when a process closes the device file.)S
1.432 395.968 M( */)S
1.432 385.168 M( static int device_release\(struct inode *inode, struct file *file\))S
1.432 374.368 M( {)S
1.432 363.568 M( Device_Open --; /* We're now ready for our next caller */)S
1.432 341.968 M( /* Decrement the usage count, or else once you opened the file, you'll)S
1.432 331.168 M( never get get rid of the module. */)S
1.432 320.368 M( MOD_DEC_USE_COUNT;)S
1.432 298.768 M( return 0;)S
1.432 287.968 M( })S
1.432 255.568 M( /* Called when a process, which already opened the dev file, attempts to)S
1.432 244.768 M( read from it.)S
1.432 233.968 M( */)S
1.432 223.168 M( static ssize_t device_read\(struct file *filp,)S
1.432 212.368 M( char *buffer, /* The buffer to fill with data */)S
1.432 201.568 M( size_t length, /* The length of the buffer */)S
1.432 190.768 M( loff_t *offset\) /* Our offset in the file */)S
1.432 179.968 M( {)S
1.432 169.168 M( /* Number of bytes actually written to the buffer */)S
1.432 158.368 M( int bytes_read = 0;)S
1.432 136.768 M( /* If we're at the end of the message, return 0 signifying end of file */)S
1.432 125.968 M( if \(*msg_Ptr == 0\) return 0;)S
1.432 104.368 M( /* Actually put the data into the buffer */)S
1.432 93.568 M( while \(length && *msg_Ptr\) {)S
1.432 71.968 M( /* The buffer is in the user data segment, not the kernel segment;)S
1.432 61.168 M( * assignment won't work. We have to use put_user which copies data from)S
1.432 50.368 M( * the kernel data segment to the user data segment. */)S
1.432 39.568 M( put_user\(*\(msg_Ptr++\), buffer++\);)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(4.1. Character Device Drivers)S
474.768 0 M(24)S
GR
SP
%%Page: 25 30
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 500.736 M 487.0 197.3 F
0.00 0.00 0.00 C 0 492.135 M 487.0 2.0 F
0.88 0.88 0.88 C 0 120.271 M 487.0 35.3 F
0.00 0.00 0.00 C 0 72.071 M 487.0 2.0 F
9 FS/F0 SF 1.432 687.568 M( length--;)S
1.432 676.768 M( bytes_read++;)S
1.432 665.968 M( })S
1.432 644.368 M( /* Most read functions return the number of bytes put into the buffer */)S
1.432 633.568 M( return bytes_read;)S
1.432 622.768 M( })S
1.432 590.368 M( /* Called when a process writes to dev file: echo "hi" > /dev/hello */)S
1.432 579.568 M( static ssize_t device_write\(struct file *filp,)S
1.432 568.768 M( const char *buff,)S
1.432 557.968 M( size_t len,)S
1.432 547.168 M( loff_t *off\))S
1.432 536.368 M( {)S
1.432 525.568 M( printk \("<1>Sorry, this operation isn't supported.\\n"\);)S
1.432 514.768 M( return -EINVAL;)S
1.432 503.968 M( })S
11 FS/F9 SF 0 474.535 M(4.1.6. Writing Modules for Multiple Kernel Versions)S
/F4 SF 0 448.135 M(The system calls, which are the major interface the kernel shows to the processes, generally stay the same)S
0 434.935 M(across versions. A new system call may be added, but usually the old ones will behave exactly like they used)S
0 421.735 M(to. This is necessary for backward compatibility -- a new kernel version is not supposed to break regular)S
0 408.535 M(processes. In most cases, the device files will also remain the same. On the other hand, the internal interfaces)S
0 395.335 M(within the kernel can and do change between versions.)S
0 368.935 M(The Linux kernel versions are divided between the stable versions \(n.$<$even number$>$.m\) and the)S
0 355.735 M(development versions \(n.$<$odd number$>$.m\). The development versions include all the cool new ideas,)S
0 342.535 M(including those which will be considered a mistake, or reimplemented, in the next version. As a result, you)S
0 329.335 M(can't trust the interface to remain the same in those versions \(which is why I don't bother to support them in)S
0 316.135 M(this book, it's too much work and it would become dated too quickly\). In the stable versions, on the other)S
0 302.935 M(hand, we can expect the interface to remain the same regardless of the bug fix version \(the m number\).)S
0 276.535 M(There are differences between different kernel versions, and if you want to support multiple kernel versions,)S
0 263.335 M(you'll find yourself having to code conditional compilation directives. The way to do this to compare the)S
0 250.135 M(macro)S
/Fa SF ( LINUX_VERSION_CODE)S
/F4 SF ( to the macro)S
/Fa SF ( KERNEL_VERSION)S
/F4 SF (. In version)S
/Fa SF ( a.b.c)S
/F4 SF ( of the kernel, the)S
0 236.935 M(value of this macro would be $2^{16}a+2^{8}b+c$. Be aware that this macro is not defined for kernel 2.0.35)S
0 223.735 M(and earlier, so if you want to write modules that support really old kernels, you'll have to define it yourself,)S
0 210.535 M(like:)S
/F5 SF 0 170.935 M(Example 4-2. some title)S
9 FS/F0 SF 1.432 145.103 M( #if LINUX_KERNEL_VERSION >= KERNEL_VERSION\(2,2,0\))S
1.432 134.303 M( #define KERNEL_VERSION\(a,b,c\) \(\(a\)*65536+\(b\)*256+\(c\)\))S
1.432 123.503 M( #endif)S
11 FS/F4 SF 0 96.071 M(Of course since these are macros, you can also use)S
/F5 SF ( #ifndef KERNEL_VERSION)S
/F4 SF ( to test the existence of the)S
0 82.871 M(macro, rather than testing the version of the kernel.)S
/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(4.1. Character Device Drivers)S
474.768 0 M(25)S
GR
SP
%%Page: 26 31
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 265.6 F
0.00 0.00 0.00 C 20 FS/F9 SF 0 678 M(Chapter 5. The /proc File System)S
14 FS/F9 SF 0 646.8 M(5.1. The /proc File System)S
11 FS/F4 SF 0 619.8 M(In Linux there is an additional mechanism for the kernel and kernel modules to send information to processes)S
0 606.6 M(--- the )S
/F0 SF (/proc)S
/F4 SF ( file system. Originally designed to allow easy access to information about processes \(hence)S
0 593.4 M(the name\), it is now used by every bit of the kernel which has something interesting to report, such as)S
/F0 SF 0 580.2 M(/proc/modules)S
/F4 SF ( which has the list of modules and )S
/F0 SF (/proc/meminfo)S
/F4 SF ( which has memory usage statistics.)S
0 553.8 M(The method to use the proc file system is very similar to the one used with device drivers --- you create a)S
0 540.6 M(structure with all the information needed for the )S
/F0 SF (/proc)S
/F4 SF ( file, including pointers to any handler functions \(in)S
0 527.4 M(our case there is only one, the one called when somebody attempts to read from the )S
/F0 SF (/proc)S
/F4 SF ( file\). Then,)S
/F0 SF 0 514.2 M(init_module)S
/F4 SF ( registers the structure with the kernel and )S
/F0 SF (cleanup_module)S
/F4 SF ( unregisters it.)S
0 487.8 M(The reason we use )S
/F0 SF (proc_register_dynamic)S
/F4 SF ([7] is because we don't want to determine the inode number)S
0 474.6 M(used for our file in advance, but to allow the kernel to determine it to prevent clashes. Normal file systems are)S
0 461.4 M(located on a disk, rather than just in memory \(which is where )S
/F0 SF (/proc)S
/F4 SF ( is\), and in that case the inode number is)S
0 448.2 M(a pointer to a disk location where the file's index-node \(inode for short\) is located. The inode contains)S
0 435 M(information about the file, for example the file's permissions, together with a pointer to the disk location or)S
0 421.8 M(locations where the file's data can be found.)S
0 395.4 M(Because we don't get called when the file is opened or closed, there's no where for us to put)S
/Fa SF 0 382.2 M(MOD_INC_USE_COUNT)S
/F4 SF ( and)S
/Fa SF ( MOD_DEC_USE_COUNT)S
/F4 SF ( in this module, and if the file is opened and)S
0 369 M(then the module is removed, there's no way to avoid the consequences. In the next chapter we'll see a harder to)S
0 355.8 M(implement, but more flexible, way of dealing with )S
/F0 SF (/proc)S
/F4 SF ( files which will allow us to protect against this)S
0 342.6 M(problem as well.)S
/F5 SF 0 303 M(Example 5-1. procfs.c)S
9 FS/F0 SF 1.432 277.167 M(/* procfs.c - create a "file" in /proc )S
1.432 266.367 M( */)S
1.432 244.767 M(#include /* We're doing kernel work */)S
1.432 233.967 M(#include /* Specifically, a module */)S
1.432 212.367 M(/* Deal with CONFIG_MODVERSIONS */)S
1.432 201.567 M(#if CONFIG_MODVERSIONS==1)S
1.432 190.767 M(#define MODVERSIONS)S
1.432 179.967 M(#include )S
1.432 169.167 M(#endif )S
1.432 136.767 M(/* Necessary because we use the proc fs */)S
1.432 125.967 M(#include )S
1.432 82.767 M(/* In 2.2.3 /usr/include/linux/version.h includes a )S
1.432 71.967 M( * macro for this, but 2.0.35 doesn't - so I add it )S
1.432 61.167 M( * here if necessary. */)S
1.432 50.367 M(#ifndef KERNEL_VERSION)S
1.432 39.567 M(#define KERNEL_VERSION\(a,b,c\) \(\(a\)*65536+\(b\)*256+\(c\)\))S
1.432 28.767 M(#endif)S
11 FS/F8 SF 0 0 M(Chapter 5. The /proc File System)S
474.768 0 M(26)S
GR
SP
%%Page: 27 32
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 655.168 M(/* Put data into the proc fs file.)S
1.432 633.568 M( Arguments)S
1.432 622.768 M( =========)S
1.432 611.968 M( 1. The buffer where the data is to be inserted, if )S
1.432 601.168 M( you decide to use it.)S
1.432 590.368 M( 2. A pointer to a pointer to characters. This is )S
1.432 579.568 M( useful if you don't want to use the buffer )S
1.432 568.768 M( allocated by the kernel.)S
1.432 557.968 M( 3. The current position in the file. )S
1.432 547.168 M( 4. The size of the buffer in the first argument. )S
1.432 536.368 M( 5. Zero \(for future use?\).)S
1.432 503.968 M( Usage and Return Value)S
1.432 493.168 M( ======================)S
1.432 482.368 M( If you use your own buffer, like I do, put its )S
1.432 471.568 M( location in the second argument and return the )S
1.432 460.768 M( number of bytes used in the buffer.)S
1.432 439.168 M( A return value of zero means you have no further )S
1.432 428.368 M( information at this time \(end of file\). A negative )S
1.432 417.568 M( return value is an error condition.)S
1.432 385.168 M( For More Information)S
1.432 374.368 M( ==================== )S
1.432 363.568 M( The way I discovered what to do with this function )S
1.432 352.768 M( wasn't by reading documentation, but by reading the )S
1.432 341.968 M( code which used it. I just looked to see what uses )S
1.432 331.168 M( the get_info field of proc_dir_entry struct \(I used a )S
1.432 320.368 M( combination of find and grep, if you're interested\), )S
1.432 309.568 M( and I saw that it is used in /fs/proc/array.c.)S
1.432 277.168 M( If something is unknown about the kernel, this is )S
1.432 266.368 M( usually the way to go. In Linux we have the great )S
1.432 255.568 M( advantage of having the kernel source code for )S
1.432 244.768 M( free - use it.)S
1.432 233.968 M( */)S
1.432 223.168 M(int procfile_read\(char *buffer, )S
1.432 212.368 M( char **buffer_location, )S
1.432 201.568 M( off_t offset, )S
1.432 190.768 M( int buffer_length, )S
1.432 179.968 M( int zero\))S
1.432 169.168 M({)S
1.432 158.368 M( int len; /* The number of bytes actually used */)S
1.432 136.768 M( /* This is static so it will still be in memory )S
1.432 125.968 M( * when we leave this function */)S
1.432 115.168 M( static char my_buffer[80]; )S
1.432 93.568 M( static int count = 1;)S
1.432 71.968 M( /* We give all of our information in one go, so if the )S
1.432 61.168 M( * user asks us if we have more information the )S
1.432 50.368 M( * answer should always be no. )S
1.432 39.568 M( *)S
1.432 28.768 M( * This is important because the standard read )S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 5. The /proc File System)S
474.768 0 M(27)S
GR
SP
%%Page: 28 33
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 687.568 M( * function from the library would continue to issue )S
1.432 676.768 M( * the read system call until the kernel replies)S
1.432 665.968 M( * that it has no more information, or until its )S
1.432 655.168 M( * buffer is filled.)S
1.432 644.368 M( */)S
1.432 633.568 M( if \(offset > 0\))S
1.432 622.768 M( return 0;)S
1.432 601.168 M( /* Fill the buffer and get its length */)S
1.432 590.368 M( len = sprintf\(my_buffer, )S
1.432 579.568 M( "For the %d%s time, go away!\\n", count,)S
1.432 568.768 M( \(count % 100 > 10 && count % 100 < 14\) ? "th" : )S
1.432 557.968 M( \(count % 10 == 1\) ? "st" :)S
1.432 547.168 M( \(count % 10 == 2\) ? "nd" :)S
1.432 536.368 M( \(count % 10 == 3\) ? "rd" : "th" \);)S
1.432 525.568 M( count++;)S
1.432 503.968 M( /* Tell the function which called us where the )S
1.432 493.168 M( * buffer is */)S
1.432 482.368 M( *buffer_location = my_buffer;)S
1.432 460.768 M( /* Return the length */)S
1.432 449.968 M( return len;)S
1.432 439.168 M(})S
1.432 406.768 M(struct proc_dir_entry Our_Proc_File = )S
1.432 395.968 M( {)S
1.432 385.168 M( 0, /* Inode number - ignore, it will be filled by )S
1.432 374.368 M( * proc_register[_dynamic] */)S
1.432 363.568 M( 4, /* Length of the file name */)S
1.432 352.768 M( "test", /* The file name */)S
1.432 341.968 M( S_IFREG | S_IRUGO, /* File mode - this is a regular )S
1.432 331.168 M( * file which can be read by its )S
1.432 320.368 M( * owner, its group, and everybody)S
1.432 309.568 M( * else */)S
1.432 298.768 M( 1, /* Number of links \(directories where the )S
1.432 287.968 M( * file is referenced\) */)S
1.432 277.168 M( 0, 0, /* The uid and gid for the file - we give it )S
1.432 266.368 M( * to root */)S
1.432 255.568 M( 80, /* The size of the file reported by ls. */)S
1.432 244.768 M( NULL, /* functions which can be done on the inode )S
1.432 233.968 M( * \(linking, removing, etc.\) - we don't )S
1.432 223.168 M( * support any. */)S
1.432 212.368 M( procfile_read, /* The read function for this file, )S
1.432 201.568 M( * the function called when somebody )S
1.432 190.768 M( * tries to read something from it. */)S
1.432 179.968 M( NULL /* We could have here a function to fill the )S
1.432 169.168 M( * file's inode, to enable us to play with )S
1.432 158.368 M( * permissions, ownership, etc. */)S
1.432 147.568 M( }; )S
1.432 82.768 M(/* Initialize the module - register the proc file */)S
1.432 71.968 M(int init_module\(\))S
1.432 61.168 M({)S
1.432 50.368 M( /* Success if proc_register[_dynamic] is a success, )S
1.432 39.568 M( * failure otherwise. */)S
1.432 28.768 M(#if LINUX_VERSION_CODE > KERNEL_VERSION\(2,2,0\))S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 5. The /proc File System)S
474.768 0 M(28)S
GR
SP
%%Page: 29 34
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 457.536 M 487.0 240.5 F
0.00 0.00 0.00 C 0 448.936 M 487.0 2.0 F
9 FS/F0 SF 1.432 687.568 M( /* In version 2.2, proc_register assign a dynamic )S
1.432 676.768 M( * inode number automatically if it is zero in the )S
1.432 665.968 M( * structure , so there's no more need for )S
1.432 655.168 M( * proc_register_dynamic)S
1.432 644.368 M( */)S
1.432 633.568 M( return proc_register\(&proc_root, &Our_Proc_File\);)S
1.432 622.768 M(#else)S
1.432 611.968 M( return proc_register_dynamic\(&proc_root, &Our_Proc_File\);)S
1.432 601.168 M(#endif)S
1.432 579.568 M( /* proc_root is the root directory for the proc )S
1.432 568.768 M( * fs \(/proc\). This is where we want our file to be )S
1.432 557.968 M( * located. )S
1.432 547.168 M( */)S
1.432 536.368 M(})S
1.432 503.968 M(/* Cleanup - unregister our file from /proc */)S
1.432 493.168 M(void cleanup_module\(\))S
1.432 482.368 M({)S
1.432 471.568 M( proc_unregister\(&proc_root, Our_Proc_File.low_ino\);)S
1.432 460.768 M(} )S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 5. The /proc File System)S
474.768 0 M(29)S
GR
SP
%%Page: 30 35
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 28.0 F
0.00 0.00 0.00 C 20 FS/F9 SF 0 678 M(Chapter 6. Using /proc For Input)S
14 FS/F9 SF 0 646.8 M(6.1. Using /proc For Input)S
11 FS/F4 SF 0 619.8 M(So far we have two ways to generate output from kernel modules: we can register a device driver and)S
/F5 SF ( mknod)S
/F4 SF 0 606.6 M(a device file, or we can create a )S
/F0 SF (/proc)S
/F4 SF ( file. This allows the kernel module to tell us anything it likes. The)S
0 593.4 M(only problem is that there is no way for us to talk back. The first way we'll send input to kernel modules will)S
0 580.2 M(be by writing back to the )S
/F0 SF (/proc)S
/F4 SF ( file.)S
0 553.8 M(Because the proc filesystem was written mainly to allow the kernel to report its situation to processes, there)S
0 540.6 M(are no special provisions for input. The)S
/Fa SF ( struct proc_dir_entry)S
/F4 SF ( doesn't include a pointer to an input function,)S
0 527.4 M(the way it includes a pointer to an output function. Instead, to write into a )S
/F0 SF (/proc)S
/F4 SF ( file, we need to use the)S
0 514.2 M(standard filesystem mechanism.)S
0 487.8 M(In Linux there is a standard mechanism for file system registration. Since every file system has to have its)S
0 474.6 M(own functions to handle inode and file operations)S
([8], there is a special structure to hold pointers to all those)S
0 461.4 M(functions,)S
/Fa SF ( struct inode_operations)S
/F4 SF (, which includes a pointer to)S
/Fa SF ( struct file_operations)S
/F4 SF (. In /proc, whenever)S
0 448.2 M(we register a new file, we're allowed to specify which)S
/Fa SF ( struct inode_operations)S
/F4 SF ( will be used for access to it.)S
0 435 M(This is the mechanism we use, a)S
/Fa SF ( struct inode_operations)S
/F4 SF ( which includes a pointer to a)S
/Fa SF ( struct)S
0 421.8 M(file_operations)S
/F4 SF ( which includes pointers to our )S
/F0 SF (module_input)S
/F4 SF ( and )S
/F0 SF (module_output)S
/F4 SF ( functions.)S
0 395.4 M(It's important to note that the standard roles of read and write are reversed in the kernel. Read functions are)S
0 382.2 M(used for output, whereas write functions are used for input. The reason for that is that read and write refer to)S
0 369 M(the user's point of view --- if a process reads something from the kernel, then the kernel needs to output it,)S
0 355.8 M(and if a process writes something to the kernel, then the kernel receives it as input.)S
0 329.4 M(Another interesting point here is the )S
/F0 SF (module_permission)S
/F4 SF ( function. This function is called whenever a)S
0 316.2 M(process tries to do something with the )S
/F0 SF (/proc)S
/F4 SF ( file, and it can decide whether to allow access or not. Right)S
0 303 M(now it is only based on the operation and the uid of the current user \(as available in)S
/Fa SF ( current)S
/F4 SF (, a pointer to a)S
0 289.8 M(structure which includes information on the currently running process\), but it could be based on anything we)S
0 276.6 M(like, such as what other processes are doing with the same file, the time of day, or the last input we received.)S
0 250.2 M(The reason for )S
/F0 SF (put_user)S
/F4 SF ( and )S
/F0 SF (get_user)S
/F4 SF ( is that Linux memory \(under Intel architecture, it may be)S
0 237 M(different under some other processors\) is segmented. This means that a pointer, by itself, does not reference a)S
0 223.8 M(unique location in memory, only a location in a memory segment, and you need to know which memory)S
0 210.6 M(segment it is to be able to use it. There is one memory segment for the kernel, and one of each of the)S
0 197.4 M(processes.)S
0 171 M(The only memory segment accessible to a process is its own, so when writing regular programs to run as)S
0 157.8 M(processes, there's no need to worry about segments. When you write a kernel module, normally you want to)S
0 144.6 M(access the kernel memory segment, which is handled automatically by the system. However, when the content)S
0 131.4 M(of a memory buffer needs to be passed between the currently running process and the kernel, the kernel)S
0 118.2 M(function receives a pointer to the memory buffer which is in the process segment. The )S
/F0 SF (put_user)S
/F4 SF ( and)S
/F0 SF 0 105 M(get_user)S
/F4 SF ( macros allow you to access that memory.)S
/F5 SF 0 65.4 M(Example 6-1. procfs.c)S
9 FS/F0 SF 1.432 39.567 M(/* procfs.c - create a "file" in /proc, which allows both input and output.)S
1.432 28.767 M( */)S
11 FS/F8 SF 0 0 M(Chapter 6. Using /proc For Input)S
474.768 0 M(30)S
GR
SP
%%Page: 31 36
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 676.768 M(#include /* We're doing kernel work */)S
1.432 665.968 M(#include /* Specifically, a module */)S
1.432 644.368 M(/* Necessary because we use proc fs */)S
1.432 633.568 M(#include )S
1.432 601.168 M(/* In 2.2.3 /usr/include/linux/version.h includes a )S
1.432 590.368 M( * macro for this, but 2.0.35 doesn't - so I add it )S
1.432 579.568 M( * here if necessary. */)S
1.432 568.768 M(#ifndef KERNEL_VERSION)S
1.432 557.968 M(#define KERNEL_VERSION\(a,b,c\) \(\(a\)*65536+\(b\)*256+\(c\)\))S
1.432 547.168 M(#endif)S
1.432 503.968 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 493.168 M(#include /* for get_user and put_user */)S
1.432 482.368 M(#endif)S
1.432 460.768 M(/* The module's file functions ********************** */)S
1.432 428.368 M(/* Here we keep the last message received, to prove )S
1.432 417.568 M( * that we can process our input */)S
1.432 406.768 M(#define MESSAGE_LENGTH 80)S
1.432 395.968 M(static char Message[MESSAGE_LENGTH];)S
1.432 363.568 M(/* Since we use the file operations struct, we can't )S
1.432 352.768 M( * use the special proc output provisions - we have to )S
1.432 341.968 M( * use a standard read function, which is this function */)S
1.432 331.168 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 320.368 M(static ssize_t module_output\()S
1.432 309.568 M( struct file *file, /* The file read */)S
1.432 298.768 M( char *buf, /* The buffer to put data to \(in the)S
1.432 287.968 M( * user segment\) */)S
1.432 277.168 M( size_t len, /* The length of the buffer */)S
1.432 266.368 M( loff_t *offset\) /* Offset in the file - ignore */)S
1.432 255.568 M(#else)S
1.432 244.768 M(static int module_output\()S
1.432 233.968 M( struct inode *inode, /* The inode read */)S
1.432 223.168 M( struct file *file, /* The file read */)S
1.432 212.368 M( char *buf, /* The buffer to put data to \(in the)S
1.432 201.568 M( * user segment\) */)S
1.432 190.768 M( int len\) /* The length of the buffer */)S
1.432 179.968 M(#endif)S
1.432 169.168 M({)S
1.432 158.368 M( static int finished = 0;)S
1.432 147.568 M( int i;)S
1.432 136.768 M( char message[MESSAGE_LENGTH+30];)S
1.432 115.168 M( /* We return 0 to indicate end of file, that we have )S
1.432 104.368 M( * no more information. Otherwise, processes will )S
1.432 93.568 M( * continue to read from us in an endless loop. */)S
1.432 82.768 M( if \(finished\) {)S
1.432 71.968 M( finished = 0;)S
1.432 61.168 M( return 0;)S
1.432 50.368 M( })S
1.432 28.768 M( /* We use put_user to copy the string from the kernel's )S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 6. Using /proc For Input)S
474.768 0 M(31)S
GR
SP
%%Page: 32 37
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 687.568 M( * memory segment to the memory segment of the process )S
1.432 676.768 M( * that called us. get_user, BTW, is)S
1.432 665.968 M( * used for the reverse. */)S
1.432 655.168 M( sprintf\(message, "Last input:%s", Message\);)S
1.432 644.368 M( for\(i=0; i<len && message[i]; i++\) )S
1.432 633.568 M( put_user\(message[i], buf+i\);)S
1.432 601.168 M( /* Notice, we assume here that the size of the message )S
1.432 590.368 M( * is below len, or it will be received cut. In a real )S
1.432 579.568 M( * life situation, if the size of the message is less )S
1.432 568.768 M( * than len then we'd return len and on the second call )S
1.432 557.968 M( * start filling the buffer with the len+1'th byte of )S
1.432 547.168 M( * the message. */)S
1.432 536.368 M( finished = 1; )S
1.432 514.768 M( return i; /* Return the number of bytes "read" */)S
1.432 503.968 M(})S
1.432 471.568 M(/* This function receives input from the user when the )S
1.432 460.768 M( * user writes to the /proc file. */)S
1.432 449.968 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 439.168 M(static ssize_t module_input\()S
1.432 428.368 M( struct file *file, /* The file itself */)S
1.432 417.568 M( const char *buf, /* The buffer with input */)S
1.432 406.768 M( size_t length, /* The buffer's length */)S
1.432 395.968 M( loff_t *offset\) /* offset to file - ignore */)S
1.432 385.168 M(#else)S
1.432 374.368 M(static int module_input\()S
1.432 363.568 M( struct inode *inode, /* The file's inode */)S
1.432 352.768 M( struct file *file, /* The file itself */)S
1.432 341.968 M( const char *buf, /* The buffer with the input */)S
1.432 331.168 M( int length\) /* The buffer's length */)S
1.432 320.368 M(#endif)S
1.432 309.568 M({)S
1.432 298.768 M( int i;)S
1.432 277.168 M( /* Put the input into Message, where module_output )S
1.432 266.368 M( * will later be able to use it */)S
1.432 255.568 M( for\(i=0; i= KERNEL_VERSION\(2,2,0\))S
1.432 233.968 M( get_user\(Message[i], buf+i\);)S
1.432 223.168 M( /* In version 2.2 the semantics of get_user changed, )S
1.432 212.368 M( * it not longer returns a character, but expects a )S
1.432 201.568 M( * variable to fill up as its first argument and a )S
1.432 190.768 M( * user segment pointer to fill it from as the its )S
1.432 179.968 M( * second.)S
1.432 169.168 M( *)S
1.432 158.368 M( * The reason for this change is that the version 2.2 )S
1.432 147.568 M( * get_user can also read an short or an int. The way )S
1.432 136.768 M( * it knows the type of the variable it should read )S
1.432 125.968 M( * is by using sizeof, and for that it needs the )S
1.432 115.168 M( * variable itself.)S
1.432 104.368 M( */ )S
1.432 93.568 M(#else )S
1.432 82.768 M( Message[i] = get_user\(buf+i\);)S
1.432 71.968 M(#endif)S
1.432 61.168 M( Message[i] = '\\0'; /* we want a standard, zero )S
1.432 50.368 M( * terminated string */)S
1.432 28.768 M( /* We need to return the number of input characters )S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 6. Using /proc For Input)S
474.768 0 M(32)S
GR
SP
%%Page: 33 38
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 687.568 M( * used */)S
1.432 676.768 M( return i;)S
1.432 665.968 M(})S
1.432 622.768 M(/* This function decides whether to allow an operation )S
1.432 611.968 M( * \(return zero\) or not allow it \(return a non-zero )S
1.432 601.168 M( * which indicates why it is not allowed\).)S
1.432 590.368 M( *)S
1.432 579.568 M( * The operation can be one of the following values:)S
1.432 568.768 M( * 0 - Execute \(run the "file" - meaningless in our case\))S
1.432 557.968 M( * 2 - Write \(input to the kernel module\))S
1.432 547.168 M( * 4 - Read \(output from the kernel module\))S
1.432 536.368 M( *)S
1.432 525.568 M( * This is the real function that checks file )S
1.432 514.768 M( * permissions. The permissions returned by ls -l are )S
1.432 503.968 M( * for referece only, and can be overridden here. )S
1.432 493.168 M( */)S
1.432 482.368 M(static int module_permission\(struct inode *inode, int op\))S
1.432 471.568 M({)S
1.432 460.768 M( /* We allow everybody to read from our module, but )S
1.432 449.968 M( * only root \(uid 0\) may write to it */ )S
1.432 439.168 M( if \(op == 4 || \(op == 2 && current->euid == 0\)\))S
1.432 428.368 M( return 0; )S
1.432 406.768 M( /* If it's anything else, access is denied */)S
1.432 395.968 M( return -EACCES;)S
1.432 385.168 M(})S
1.432 331.168 M(/* The file is opened - we don't really care about )S
1.432 320.368 M( * that, but it does mean we need to increment the )S
1.432 309.568 M( * module's reference count. */)S
1.432 298.768 M(int module_open\(struct inode *inode, struct file *file\))S
1.432 287.968 M({)S
1.432 277.168 M( MOD_INC_USE_COUNT;)S
1.432 255.568 M( return 0;)S
1.432 244.768 M(})S
1.432 212.368 M(/* The file is closed - again, interesting only because )S
1.432 201.568 M( * of the reference count. */)S
1.432 190.768 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 179.968 M(int module_close\(struct inode *inode, struct file *file\))S
1.432 169.168 M(#else)S
1.432 158.368 M(void module_close\(struct inode *inode, struct file *file\))S
1.432 147.568 M(#endif)S
1.432 136.768 M({)S
1.432 125.968 M( MOD_DEC_USE_COUNT;)S
1.432 104.368 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 93.568 M( return 0; /* success */)S
1.432 82.768 M(#endif)S
1.432 71.968 M(})S
1.432 39.568 M(/* Structures to register as the /proc file, with )S
1.432 28.768 M( * pointers to all the relevant functions. ********** */)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 6. Using /proc For Input)S
474.768 0 M(33)S
GR
SP
%%Page: 34 39
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 655.168 M(/* File operations for our proc file. This is where we )S
1.432 644.368 M( * place pointers to all the functions called when )S
1.432 633.568 M( * somebody tries to do something to our file. NULL )S
1.432 622.768 M( * means we don't want to deal with something. */)S
1.432 611.968 M(static struct file_operations File_Ops_4_Our_Proc_File =)S
1.432 601.168 M( {)S
1.432 590.368 M( NULL, /* lseek */)S
1.432 579.568 M( module_output, /* "read" from the file */)S
1.432 568.768 M( module_input, /* "write" to the file */)S
1.432 557.968 M( NULL, /* readdir */)S
1.432 547.168 M( NULL, /* select */)S
1.432 536.368 M( NULL, /* ioctl */)S
1.432 525.568 M( NULL, /* mmap */)S
1.432 514.768 M( module_open, /* Somebody opened the file */)S
1.432 503.968 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 493.168 M( NULL, /* flush, added here in version 2.2 */)S
1.432 482.368 M(#endif)S
1.432 471.568 M( module_close, /* Somebody closed the file */)S
1.432 460.768 M( /* etc. etc. etc. \(they are all given in )S
1.432 449.968 M( * /usr/include/linux/fs.h\). Since we don't put )S
1.432 439.168 M( * anything here, the system will keep the default)S
1.432 428.368 M( * data, which in Unix is zeros \(NULLs when taken as )S
1.432 417.568 M( * pointers\). */)S
1.432 406.768 M( };)S
1.432 363.568 M(/* Inode operations for our proc file. We need it so )S
1.432 352.768 M( * we'll have some place to specify the file operations )S
1.432 341.968 M( * structure we want to use, and the function we use for )S
1.432 331.168 M( * permissions. It's also possible to specify functions )S
1.432 320.368 M( * to be called for anything else which could be done to )S
1.432 309.568 M( * an inode \(although we don't bother, we just put )S
1.432 298.768 M( * NULL\). */)S
1.432 287.968 M(static struct inode_operations Inode_Ops_4_Our_Proc_File =)S
1.432 277.168 M( {)S
1.432 266.368 M( &File_Ops_4_Our_Proc_File,)S
1.432 255.568 M( NULL, /* create */)S
1.432 244.768 M( NULL, /* lookup */)S
1.432 233.968 M( NULL, /* link */)S
1.432 223.168 M( NULL, /* unlink */)S
1.432 212.368 M( NULL, /* symlink */)S
1.432 201.568 M( NULL, /* mkdir */)S
1.432 190.768 M( NULL, /* rmdir */)S
1.432 179.968 M( NULL, /* mknod */)S
1.432 169.168 M( NULL, /* rename */)S
1.432 158.368 M( NULL, /* readlink */)S
1.432 147.568 M( NULL, /* follow_link */)S
1.432 136.768 M( NULL, /* readpage */)S
1.432 125.968 M( NULL, /* writepage */)S
1.432 115.168 M( NULL, /* bmap */)S
1.432 104.368 M( NULL, /* truncate */)S
1.432 93.568 M( module_permission /* check for permissions */)S
1.432 82.768 M( };)S
1.432 50.368 M(/* Directory entry */)S
1.432 39.568 M(static struct proc_dir_entry Our_Proc_File = )S
1.432 28.768 M( {)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 6. Using /proc For Input)S
474.768 0 M(34)S
GR
SP
%%Page: 35 40
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 111.936 M 487.0 586.1 F
0.00 0.00 0.00 C 0 103.336 M 487.0 2.0 F
9 FS/F0 SF 1.432 687.568 M( 0, /* Inode number - ignore, it will be filled by )S
1.432 676.768 M( * proc_register[_dynamic] */)S
1.432 665.968 M( 7, /* Length of the file name */)S
1.432 655.168 M( "rw_test", /* The file name */)S
1.432 644.368 M( S_IFREG | S_IRUGO | S_IWUSR, )S
1.432 633.568 M( /* File mode - this is a regular file which )S
1.432 622.768 M( * can be read by its owner, its group, and everybody)S
1.432 611.968 M( * else. Also, its owner can write to it.)S
1.432 601.168 M( *)S
1.432 590.368 M( * Actually, this field is just for reference, it's)S
1.432 579.568 M( * module_permission that does the actual check. It )S
1.432 568.768 M( * could use this field, but in our implementation it)S
1.432 557.968 M( * doesn't, for simplicity. */)S
1.432 547.168 M( 1, /* Number of links \(directories where the )S
1.432 536.368 M( * file is referenced\) */)S
1.432 525.568 M( 0, 0, /* The uid and gid for the file - )S
1.432 514.768 M( * we give it to root */)S
1.432 503.968 M( 80, /* The size of the file reported by ls. */)S
1.432 493.168 M( &Inode_Ops_4_Our_Proc_File, )S
1.432 482.368 M( /* A pointer to the inode structure for)S
1.432 471.568 M( * the file, if we need it. In our case we)S
1.432 460.768 M( * do, because we need a write function. */)S
1.432 449.968 M( NULL )S
1.432 439.168 M( /* The read function for the file. Irrelevant, )S
1.432 428.368 M( * because we put it in the inode structure above */)S
1.432 417.568 M( }; )S
1.432 374.368 M(/* Module initialization and cleanup ******************* */)S
1.432 352.768 M(/* Initialize the module - register the proc file */)S
1.432 341.968 M(int init_module\(\))S
1.432 331.168 M({)S
1.432 320.368 M( /* Success if proc_register[_dynamic] is a success, )S
1.432 309.568 M( * failure otherwise */)S
1.432 298.768 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 287.968 M( /* In version 2.2, proc_register assign a dynamic )S
1.432 277.168 M( * inode number automatically if it is zero in the )S
1.432 266.368 M( * structure , so there's no more need for )S
1.432 255.568 M( * proc_register_dynamic)S
1.432 244.768 M( */)S
1.432 233.968 M( return proc_register\(&proc_root, &Our_Proc_File\);)S
1.432 223.168 M(#else)S
1.432 212.368 M( return proc_register_dynamic\(&proc_root, &Our_Proc_File\);)S
1.432 201.568 M(#endif)S
1.432 190.768 M(})S
1.432 158.368 M(/* Cleanup - unregister our file from /proc */)S
1.432 147.568 M(void cleanup_module\(\))S
1.432 136.768 M({)S
1.432 125.968 M( proc_unregister\(&proc_root, Our_Proc_File.low_ino\);)S
1.432 115.168 M(} )S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 6. Using /proc For Input)S
474.768 0 M(35)S
GR
SP
%%Page: 36 41
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 173.2 F
0.00 0.00 0.00 C 20 FS/F9 SF 0 678 M(Chapter 7. Talking To Device Files)S
14 FS/F9 SF 0 646.8 M(7.1. Talking to Device Files \(writes and IOCTLs\)})S
11 FS/F4 SF 0 619.8 M(Device files are supposed to represent physical devices. Most physical devices are used for output as well as)S
0 606.6 M(input, so there has to be some mechanism for device drivers in the kernel to get the output to send to the)S
0 593.4 M(device from processes. This is done by opening the device file for output and writing to it, just like writing to)S
0 580.2 M(a file. In the following example, this is implemented by )S
/F0 SF (device_write)S
/F4 SF (.)S
0 553.8 M(This is not always enough. Imagine you had a serial port connected to a modem \(even if you have an internal)S
0 540.6 M(modem, it is still implemented from the CPU's perspective as a serial port connected to a modem, so you don't)S
0 527.4 M(have to tax your imagination too hard\). The natural thing to do would be to use the device file to write things)S
0 514.2 M(to the modem \(either modem commands or data to be sent through the phone line\) and read things from the)S
0 501 M(modem \(either responses for commands or the data received through the phone line\). However, this leaves)S
0 487.8 M(open the question of what to do when you need to talk to the serial port itself, for example to send the rate at)S
0 474.6 M(which data is sent and received.)S
0 448.2 M(The answer in Unix is to use a special function called )S
/F0 SF (ioctl)S
/F4 SF ( \(short for Input Output ConTroL\). Every device)S
0 435 M(can have its own )S
/F0 SF (ioctl)S
/F4 SF ( commands, which can be read )S
/F0 SF (ioctl)S
/F4 SF ('s \(to send information from a process to the)S
0 421.8 M(kernel\), write )S
/F0 SF (ioctl)S
/F4 SF ('s \(to return information to a process\),)S
( [9] both or neither. The )S
/F0 SF (ioctl)S
/F4 SF ( function is called)S
0 408.6 M(with three parameters: the file descriptor of the appropriate device file, the ioctl number, and a parameter,)S
0 395.4 M(which is of type long so you can use a cast to use it to pass anything.)S
( [10])S
0 369 M(The ioctl number encodes the major device number, the type of the ioctl, the command, and the type of the)S
0 355.8 M(parameter. This ioctl number is usually created by a macro call \()S
/Fa SF (_IO)S
/F4 SF (,)S
/Fa SF ( _IOR)S
/F4 SF (,)S
/Fa SF ( _IOW)S
/F4 SF ( or)S
/Fa SF ( _IOWR)S
/F4 SF ( ---)S
0 342.6 M(depending on the type\) in a header file. This header file should then be included both by the programs which)S
0 329.4 M(will use )S
/F0 SF (ioctl)S
/F4 SF ( \(so they can generate the appropriate )S
/F0 SF (ioctl)S
/F4 SF ('s\) and by the kernel module \(so it can)S
0 316.2 M(understand it\). In the example below, the header file is )S
/F0 SF (chardev.h)S
/F4 SF ( and the program which uses it is)S
/F0 SF 0 303 M(ioctl.c)S
/F4 SF (.)S
0 276.6 M(If you want to use )S
/F0 SF (ioctl)S
/F4 SF (s in your own kernel modules, it is best to receive an official )S
/F0 SF (ioctl)S
/F4 SF ( assignment, so)S
0 263.4 M(if you accidentally get somebody else's )S
/F0 SF (ioctl)S
/F4 SF (s, or if they get yours, you'll know something is wrong. For)S
0 250.2 M(more information, consult the kernel source tree at )S
/F0 SF (Documentation/ioctl-number.txt)S
/F4 SF (.)S
/F5 SF 0 210.6 M(Example 7-1. chardev.c)S
9 FS/F0 SF 1.432 184.767 M(/* chardev.c - Create an input/output character device)S
1.432 173.967 M( */)S
1.432 152.367 M(#include /* We're doing kernel work */)S
1.432 141.567 M(#include /* Specifically, a module */)S
1.432 119.967 M(/* Deal with CONFIG_MODVERSIONS */)S
1.432 109.167 M(#if CONFIG_MODVERSIONS==1)S
1.432 98.367 M(#define MODVERSIONS)S
1.432 87.567 M(#include )S
1.432 76.767 M(#endif )S
1.432 55.167 M(/* For character devices */)S
1.432 33.567 M(/* The character device definitions are here */)S
11 FS/F8 SF 0 0 M(Chapter 7. Talking To Device Files)S
474.768 0 M(36)S
GR
SP
%%Page: 37 42
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 687.568 M(#include )S
1.432 665.968 M(/* A wrapper which does next to nothing at)S
1.432 655.168 M( * at present, but may help for compatibility)S
1.432 644.368 M( * with future versions of Linux */)S
1.432 633.568 M(#include )S
1.432 601.168 M(/* Our own ioctl numbers */)S
1.432 590.368 M(#include "chardev.h")S
1.432 557.968 M(/* In 2.2.3 /usr/include/linux/version.h includes a )S
1.432 547.168 M( * macro for this, but 2.0.35 doesn't - so I add it )S
1.432 536.368 M( * here if necessary. */)S
1.432 525.568 M(#ifndef KERNEL_VERSION)S
1.432 514.768 M(#define KERNEL_VERSION\(a,b,c\) \(\(a\)*65536+\(b\)*256+\(c\)\))S
1.432 503.968 M(#endif)S
1.432 460.768 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 449.968 M(#include /* for get_user and put_user */)S
1.432 439.168 M(#endif)S
1.432 395.968 M(#define SUCCESS 0)S
1.432 363.568 M(/* Device Declarations ******************************** */)S
1.432 331.168 M(/* The name for our device, as it will appear in )S
1.432 320.368 M( * /proc/devices */)S
1.432 309.568 M(#define DEVICE_NAME "char_dev")S
1.432 277.168 M(/* The maximum length of the message for the device */)S
1.432 266.368 M(#define BUF_LEN 80)S
1.432 244.768 M(/* Is the device open right now? Used to prevent )S
1.432 233.968 M( * concurent access into the same device */)S
1.432 223.168 M(static int Device_Open = 0;)S
1.432 201.568 M(/* The message the device will give when asked */)S
1.432 190.768 M(static char Message[BUF_LEN];)S
1.432 169.168 M(/* How far did the process reading the message get? )S
1.432 158.368 M( * Useful if the message is larger than the size of the )S
1.432 147.568 M( * buffer we get to fill in device_read. */)S
1.432 136.768 M(static char *Message_Ptr;)S
1.432 104.368 M(/* This function is called whenever a process attempts )S
1.432 93.568 M( * to open the device file */)S
1.432 82.768 M(static int device_open\(struct inode *inode, )S
1.432 71.968 M( struct file *file\))S
1.432 61.168 M({)S
1.432 50.368 M(#ifdef DEBUG)S
1.432 39.568 M( printk \("device_open\(%p\)\\n", file\);)S
1.432 28.768 M(#endif)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 7. Talking To Device Files)S
474.768 0 M(37)S
GR
SP
%%Page: 38 43
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 676.768 M( /* We don't want to talk to two processes at the )S
1.432 665.968 M( * same time */)S
1.432 655.168 M( if \(Device_Open\))S
1.432 644.368 M( return -EBUSY;)S
1.432 622.768 M( /* If this was a process, we would have had to be )S
1.432 611.968 M( * more careful here, because one process might have )S
1.432 601.168 M( * checked Device_Open right before the other one )S
1.432 590.368 M( * tried to increment it. However, we're in the )S
1.432 579.568 M( * kernel, so we're protected against context switches.)S
1.432 568.768 M( *)S
1.432 557.968 M( * This is NOT the right attitude to take, because we)S
1.432 547.168 M( * might be running on an SMP box, but we'll deal with)S
1.432 536.368 M( * SMP in a later chapter.)S
1.432 525.568 M( */ )S
1.432 503.968 M( Device_Open++;)S
1.432 482.368 M( /* Initialize the message */)S
1.432 471.568 M( Message_Ptr = Message;)S
1.432 449.968 M( MOD_INC_USE_COUNT;)S
1.432 428.368 M( return SUCCESS;)S
1.432 417.568 M(})S
1.432 385.168 M(/* This function is called when a process closes the )S
1.432 374.368 M( * device file. It doesn't have a return value because )S
1.432 363.568 M( * it cannot fail. Regardless of what else happens, you )S
1.432 352.768 M( * should always be able to close a device \(in 2.0, a 2.2)S
1.432 341.968 M( * device file could be impossible to close\).)S
1.432 331.168 M( */)S
1.432 320.368 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 309.568 M(static int device_release\(struct inode *inode, )S
1.432 298.768 M( struct file *file\))S
1.432 287.968 M(#else)S
1.432 277.168 M(static void device_release\(struct inode *inode, )S
1.432 266.368 M( struct file *file\))S
1.432 255.568 M(#endif)S
1.432 244.768 M({)S
1.432 233.968 M(#ifdef DEBUG)S
1.432 223.168 M( printk \("device_release\(%p,%p\)\\n", inode, file\);)S
1.432 212.368 M(#endif)S
1.432 190.768 M( /* We're now ready for our next caller */)S
1.432 179.968 M( Device_Open --;)S
1.432 158.368 M( MOD_DEC_USE_COUNT;)S
1.432 136.768 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 125.968 M( return 0;)S
1.432 115.168 M(#endif)S
1.432 104.368 M(})S
1.432 61.168 M(/* This function is called whenever a process which )S
1.432 50.368 M( * has already opened the device file attempts to )S
1.432 39.568 M( * read from it. */)S
1.432 28.768 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 7. Talking To Device Files)S
474.768 0 M(38)S
GR
SP
%%Page: 39 44
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 687.568 M(static ssize_t device_read\()S
1.432 676.768 M( struct file *file,)S
1.432 665.968 M( char *buffer, /* The buffer to fill with the data */ )S
1.432 655.168 M( size_t length, /* The length of the buffer */)S
1.432 644.368 M( loff_t *offset\) /* offset to the file */)S
1.432 633.568 M(#else)S
1.432 622.768 M(static int device_read\()S
1.432 611.968 M( struct inode *inode,)S
1.432 601.168 M( struct file *file,)S
1.432 590.368 M( char *buffer, /* The buffer to fill with the data */ )S
1.432 579.568 M( int length\) /* The length of the buffer )S
1.432 568.768 M( * \(mustn't write beyond that!\) */)S
1.432 557.968 M(#endif)S
1.432 547.168 M({)S
1.432 536.368 M( /* Number of bytes actually written to the buffer */)S
1.432 525.568 M( int bytes_read = 0;)S
1.432 503.968 M(#ifdef DEBUG)S
1.432 493.168 M( printk\("device_read\(%p,%p,%d\)\\n", file, buffer, length\);)S
1.432 482.368 M(#endif)S
1.432 460.768 M( /* If we're at the end of the message, return 0 )S
1.432 449.968 M( * \(which signifies end of file\) */)S
1.432 439.168 M( if \(*Message_Ptr == 0\))S
1.432 428.368 M( return 0;)S
1.432 406.768 M( /* Actually put the data into the buffer */)S
1.432 395.968 M( while \(length && *Message_Ptr\) {)S
1.432 374.368 M( /* Because the buffer is in the user data segment, )S
1.432 363.568 M( * not the kernel data segment, assignment wouldn't )S
1.432 352.768 M( * work. Instead, we have to use put_user which )S
1.432 341.968 M( * copies data from the kernel data segment to the )S
1.432 331.168 M( * user data segment. */)S
1.432 320.368 M( put_user\(*\(Message_Ptr++\), buffer++\);)S
1.432 309.568 M( length --;)S
1.432 298.768 M( bytes_read ++;)S
1.432 287.968 M( })S
1.432 266.368 M(#ifdef DEBUG)S
1.432 255.568 M( printk \("Read %d bytes, %d left\\n", bytes_read, length\);)S
1.432 244.768 M(#endif)S
1.432 223.168 M( /* Read functions are supposed to return the number )S
1.432 212.368 M( * of bytes actually inserted into the buffer */)S
1.432 201.568 M( return bytes_read;)S
1.432 190.768 M(})S
1.432 158.368 M(/* This function is called when somebody tries to )S
1.432 147.568 M( * write into our device file. */ )S
1.432 136.768 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 125.968 M(static ssize_t device_write\(struct file *file,)S
1.432 115.168 M( const char *buffer,)S
1.432 104.368 M( size_t length,)S
1.432 93.568 M( loff_t *offset\))S
1.432 82.768 M(#else)S
1.432 71.968 M(static int device_write\(struct inode *inode,)S
1.432 61.168 M( struct file *file,)S
1.432 50.368 M( const char *buffer,)S
1.432 39.568 M( int length\))S
1.432 28.768 M(#endif)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 7. Talking To Device Files)S
474.768 0 M(39)S
GR
SP
%%Page: 40 45
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 687.568 M({)S
1.432 676.768 M( int i;)S
1.432 655.168 M(#ifdef DEBUG)S
1.432 644.368 M( printk \("device_write\(%p,%s,%d\)",)S
1.432 633.568 M( file, buffer, length\);)S
1.432 622.768 M(#endif)S
1.432 601.168 M( for\(i=0; i= KERNEL_VERSION\(2,2,0\))S
1.432 579.568 M( get_user\(Message[i], buffer+i\);)S
1.432 568.768 M(#else)S
1.432 557.968 M( Message[i] = get_user\(buffer+i\);)S
1.432 547.168 M(#endif )S
1.432 525.568 M( Message_Ptr = Message;)S
1.432 503.968 M( /* Again, return the number of input characters used */)S
1.432 493.168 M( return i;)S
1.432 482.368 M(})S
1.432 449.968 M(/* This function is called whenever a process tries to )S
1.432 439.168 M( * do an ioctl on our device file. We get two extra )S
1.432 428.368 M( * parameters \(additional to the inode and file )S
1.432 417.568 M( * structures, which all device functions get\): the number)S
1.432 406.768 M( * of the ioctl called and the parameter given to the )S
1.432 395.968 M( * ioctl function.)S
1.432 385.168 M( *)S
1.432 374.368 M( * If the ioctl is write or read/write \(meaning output )S
1.432 363.568 M( * is returned to the calling process\), the ioctl call )S
1.432 352.768 M( * returns the output of this function.)S
1.432 341.968 M( */)S
1.432 331.168 M(int device_ioctl\()S
1.432 320.368 M( struct inode *inode,)S
1.432 309.568 M( struct file *file,)S
1.432 298.768 M( unsigned int ioctl_num,/* The number of the ioctl */)S
1.432 287.968 M( unsigned long ioctl_param\) /* The parameter to it */)S
1.432 277.168 M({)S
1.432 266.368 M( int i;)S
1.432 255.568 M( char *temp;)S
1.432 244.768 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 233.968 M( char ch;)S
1.432 223.168 M(#endif)S
1.432 201.568 M( /* Switch according to the ioctl called */)S
1.432 190.768 M( switch \(ioctl_num\) {)S
1.432 179.968 M( case IOCTL_SET_MSG:)S
1.432 169.168 M( /* Receive a pointer to a message \(in user space\) )S
1.432 158.368 M( * and set that to be the device's message. */ )S
1.432 136.768 M( /* Get the parameter given to ioctl by the process */)S
1.432 125.968 M( temp = \(char *\) ioctl_param;)S
1.432 104.368 M( /* Find the length of the message */)S
1.432 93.568 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 82.768 M( get_user\(ch, temp\);)S
1.432 71.968 M( for \(i=0; ch && i= KERNEL_VERSION\(2,2,0\))S
1.432 644.368 M( device_write\(file, \(char *\) ioctl_param, i, 0\);)S
1.432 633.568 M(#else)S
1.432 622.768 M( device_write\(inode, file, \(char *\) ioctl_param, i\);)S
1.432 611.968 M(#endif)S
1.432 601.168 M( break;)S
1.432 579.568 M( case IOCTL_GET_MSG:)S
1.432 568.768 M( /* Give the current message to the calling )S
1.432 557.968 M( * process - the parameter we got is a pointer, )S
1.432 547.168 M( * fill it. */)S
1.432 536.368 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 525.568 M( i = device_read\(file, \(char *\) ioctl_param, 99, 0\); )S
1.432 514.768 M(#else)S
1.432 503.968 M( i = device_read\(inode, file, \(char *\) ioctl_param, 99\); )S
1.432 493.168 M(#endif)S
1.432 482.368 M( /* Warning - we assume here the buffer length is )S
1.432 471.568 M( * 100. If it's less than that we might overflow )S
1.432 460.768 M( * the buffer, causing the process to core dump. )S
1.432 449.968 M( *)S
1.432 439.168 M( * The reason we only allow up to 99 characters is )S
1.432 428.368 M( * that the NULL which terminates the string also )S
1.432 417.568 M( * needs room. */)S
1.432 395.968 M( /* Put a zero at the end of the buffer, so it )S
1.432 385.168 M( * will be properly terminated */)S
1.432 374.368 M( put_user\('\\0', \(char *\) ioctl_param+i\);)S
1.432 363.568 M( break;)S
1.432 341.968 M( case IOCTL_GET_NTH_BYTE:)S
1.432 331.168 M( /* This ioctl is both input \(ioctl_param\) and )S
1.432 320.368 M( * output \(the return value of this function\) */)S
1.432 309.568 M( return Message[ioctl_param];)S
1.432 298.768 M( break;)S
1.432 287.968 M( })S
1.432 266.368 M( return SUCCESS;)S
1.432 255.568 M(})S
1.432 223.168 M(/* Module Declarations *************************** */)S
1.432 190.768 M(/* This structure will hold the functions to be called )S
1.432 179.968 M( * when a process does something to the device we )S
1.432 169.168 M( * created. Since a pointer to this structure is kept in )S
1.432 158.368 M( * the devices table, it can't be local to)S
1.432 147.568 M( * init_module. NULL is for unimplemented functions. */)S
1.432 136.768 M(struct file_operations Fops = {)S
1.432 125.968 M( NULL, /* seek */)S
1.432 115.168 M( device_read, )S
1.432 104.368 M( device_write,)S
1.432 93.568 M( NULL, /* readdir */)S
1.432 82.768 M( NULL, /* select */)S
1.432 71.968 M( device_ioctl, /* ioctl */)S
1.432 61.168 M( NULL, /* mmap */)S
1.432 50.368 M( device_open,)S
1.432 39.568 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 28.768 M( NULL, /* flush */)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 7. Talking To Device Files)S
474.768 0 M(41)S
GR
SP
%%Page: 42 47
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 144.336 M 487.0 553.7 F
0 22 M 487.0 69.5 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 687.568 M(#endif)S
1.432 676.768 M( device_release /* a.k.a. close */)S
1.432 665.968 M(};)S
1.432 633.568 M(/* Initialize the module - Register the character device */)S
1.432 622.768 M(int init_module\(\))S
1.432 611.968 M({)S
1.432 601.168 M( int ret_val;)S
1.432 579.568 M( /* Register the character device \(atleast try\) */)S
1.432 568.768 M( ret_val = module_register_chrdev\(MAJOR_NUM, )S
1.432 557.968 M( DEVICE_NAME,)S
1.432 547.168 M( &Fops\);)S
1.432 525.568 M( /* Negative values signify an error */)S
1.432 514.768 M( if \(ret_val < 0\) {)S
1.432 503.968 M( printk \("%s failed with %d\\n",)S
1.432 493.168 M( "Sorry, registering the character device ",)S
1.432 482.368 M( ret_val\);)S
1.432 471.568 M( return ret_val;)S
1.432 460.768 M( })S
1.432 439.168 M( printk \("%s The major device number is %d.\\n",)S
1.432 428.368 M( "Registeration is a success", )S
1.432 417.568 M( MAJOR_NUM\);)S
1.432 406.768 M( printk \("If you want to talk to the device driver,\\n"\);)S
1.432 395.968 M( printk \("you'll have to create a device file. \\n"\);)S
1.432 385.168 M( printk \("We suggest you use:\\n"\);)S
1.432 374.368 M( printk \("mknod %s c %d 0\\n", DEVICE_FILE_NAME, )S
1.432 363.568 M( MAJOR_NUM\);)S
1.432 352.768 M( printk \("The device file name is important, because\\n"\);)S
1.432 341.968 M( printk \("the ioctl program assumes that's the\\n"\);)S
1.432 331.168 M( printk \("file you'll use.\\n"\);)S
1.432 309.568 M( return 0;)S
1.432 298.768 M(})S
1.432 266.368 M(/* Cleanup - unregister the appropriate file from /proc */)S
1.432 255.568 M(void cleanup_module\(\))S
1.432 244.768 M({)S
1.432 233.968 M( int ret;)S
1.432 212.368 M( /* Unregister the device */)S
1.432 201.568 M( ret = module_unregister_chrdev\(MAJOR_NUM, DEVICE_NAME\);)S
1.432 179.968 M( /* If there's an error, report it */ )S
1.432 169.168 M( if \(ret < 0\))S
1.432 158.368 M( printk\("Error in module_unregister_chrdev: %d\\n", ret\);)S
1.432 147.568 M(} )S
11 FS/F5 SF 0 106.936 M(Example 7-2. chardev.h)S
9 FS/F0 SF 1.432 81.103 M(/* chardev.h - the header file with the ioctl definitions.)S
1.432 70.303 M( *)S
1.432 59.503 M( * The declarations here have to be in a header file, because)S
1.432 48.703 M( * they need to be known both to the kernel module)S
1.432 37.903 M( * \(in chardev.c\) and the process calling ioctl \(ioctl.c\))S
1.432 27.103 M( */)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 7. Talking To Device Files)S
474.768 0 M(42)S
GR
SP
%%Page: 43 48
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 144.336 M 487.0 553.7 F
0 22 M 487.0 69.5 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 676.768 M(#ifndef CHARDEV_H)S
1.432 665.968 M(#define CHARDEV_H)S
1.432 644.368 M(#include )S
1.432 601.168 M(/* The major device number. We can't rely on dynamic )S
1.432 590.368 M( * registration any more, because ioctls need to know )S
1.432 579.568 M( * it. */)S
1.432 568.768 M(#define MAJOR_NUM 100)S
1.432 536.368 M(/* Set the message of the device driver */)S
1.432 525.568 M(#define IOCTL_SET_MSG _IOR\(MAJOR_NUM, 0, char *\))S
1.432 514.768 M(/* _IOR means that we're creating an ioctl command )S
1.432 503.968 M( * number for passing information from a user process)S
1.432 493.168 M( * to the kernel module. )S
1.432 482.368 M( *)S
1.432 471.568 M( * The first arguments, MAJOR_NUM, is the major device )S
1.432 460.768 M( * number we're using.)S
1.432 449.968 M( *)S
1.432 439.168 M( * The second argument is the number of the command )S
1.432 428.368 M( * \(there could be several with different meanings\).)S
1.432 417.568 M( *)S
1.432 406.768 M( * The third argument is the type we want to get from )S
1.432 395.968 M( * the process to the kernel.)S
1.432 385.168 M( */)S
1.432 363.568 M(/* Get the message of the device driver */)S
1.432 352.768 M(#define IOCTL_GET_MSG _IOR\(MAJOR_NUM, 1, char *\))S
1.432 341.968 M( /* This IOCTL is used for output, to get the message )S
1.432 331.168 M( * of the device driver. However, we still need the )S
1.432 320.368 M( * buffer to place the message in to be input, )S
1.432 309.568 M( * as it is allocated by the process.)S
1.432 298.768 M( */)S
1.432 266.368 M(/* Get the n'th byte of the message */)S
1.432 255.568 M(#define IOCTL_GET_NTH_BYTE _IOWR\(MAJOR_NUM, 2, int\))S
1.432 244.768 M( /* The IOCTL is used for both input and output. It )S
1.432 233.968 M( * receives from the user a number, n, and returns )S
1.432 223.168 M( * Message[n]. */)S
1.432 190.768 M(/* The name of the device file */)S
1.432 179.968 M(#define DEVICE_FILE_NAME "char_dev")S
1.432 147.568 M(#endif)S
11 FS/F5 SF 0 106.936 M(Example 7-3. ioctl.c)S
9 FS/F0 SF 1.432 81.103 M(/* ioctl.c - the process to use ioctl's to control the kernel module)S
1.432 70.303 M( *)S
1.432 59.503 M( * Until now we could have used cat for input and output. But now)S
1.432 48.703 M( * we need to do ioctl's, which require writing our own process. )S
1.432 37.903 M( */)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 7. Talking To Device Files)S
474.768 0 M(43)S
GR
SP
%%Page: 44 49
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 687.568 M(/* device specifics, such as ioctl numbers and the )S
1.432 676.768 M( * major device file. */)S
1.432 665.968 M(#include "chardev.h" )S
1.432 633.568 M(#include /* open */ )S
1.432 622.768 M(#include /* exit */)S
1.432 611.968 M(#include /* ioctl */)S
1.432 568.768 M(/* Functions for the ioctl calls */)S
1.432 547.168 M(ioctl_set_msg\(int file_desc, char *message\))S
1.432 536.368 M({)S
1.432 525.568 M( int ret_val;)S
1.432 503.968 M( ret_val = ioctl\(file_desc, IOCTL_SET_MSG, message\);)S
1.432 482.368 M( if \(ret_val < 0\) {)S
1.432 471.568 M( printf \("ioctl_set_msg failed:%d\\n", ret_val\);)S
1.432 460.768 M( exit\(-1\);)S
1.432 449.968 M( })S
1.432 439.168 M(})S
1.432 395.968 M(ioctl_get_msg\(int file_desc\))S
1.432 385.168 M({)S
1.432 374.368 M( int ret_val;)S
1.432 363.568 M( char message[100]; )S
1.432 341.968 M( /* Warning - this is dangerous because we don't tell )S
1.432 331.168 M( * the kernel how far it's allowed to write, so it )S
1.432 320.368 M( * might overflow the buffer. In a real production )S
1.432 309.568 M( * program, we would have used two ioctls - one to tell)S
1.432 298.768 M( * the kernel the buffer length and another to give )S
1.432 287.968 M( * it the buffer to fill)S
1.432 277.168 M( */)S
1.432 266.368 M( ret_val = ioctl\(file_desc, IOCTL_GET_MSG, message\);)S
1.432 244.768 M( if \(ret_val < 0\) {)S
1.432 233.968 M( printf \("ioctl_get_msg failed:%d\\n", ret_val\);)S
1.432 223.168 M( exit\(-1\);)S
1.432 212.368 M( })S
1.432 190.768 M( printf\("get_msg message:%s\\n", message\);)S
1.432 179.968 M(})S
1.432 136.768 M(ioctl_get_nth_byte\(int file_desc\))S
1.432 125.968 M({)S
1.432 115.168 M( int i;)S
1.432 104.368 M( char c;)S
1.432 82.768 M( printf\("get_nth_byte message:"\);)S
1.432 61.168 M( i = 0;)S
1.432 50.368 M( while \(c != 0\) {)S
1.432 39.568 M( c = ioctl\(file_desc, IOCTL_GET_NTH_BYTE, i++\);)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 7. Talking To Device Files)S
474.768 0 M(44)S
GR
SP
%%Page: 45 50
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 338.736 M 487.0 359.3 F
0.00 0.00 0.00 C 0 330.136 M 487.0 2.0 F
9 FS/F0 SF 1.432 687.568 M( if \(c < 0\) {)S
1.432 676.768 M( printf\()S
1.432 665.968 M( "ioctl_get_nth_byte failed at the %d'th byte:\\n", i\);)S
1.432 655.168 M( exit\(-1\);)S
1.432 644.368 M( })S
1.432 622.768 M( putchar\(c\);)S
1.432 611.968 M( } )S
1.432 601.168 M( putchar\('\\n'\);)S
1.432 590.368 M(})S
1.432 536.368 M(/* Main - Call the ioctl functions */)S
1.432 525.568 M(main\(\))S
1.432 514.768 M({)S
1.432 503.968 M( int file_desc, ret_val;)S
1.432 493.168 M( char *msg = "Message passed by ioctl\\n";)S
1.432 471.568 M( file_desc = open\(DEVICE_FILE_NAME, 0\);)S
1.432 460.768 M( if \(file_desc < 0\) {)S
1.432 449.968 M( printf \("Can't open device file: %s\\n", )S
1.432 439.168 M( DEVICE_FILE_NAME\);)S
1.432 428.368 M( exit\(-1\);)S
1.432 417.568 M( })S
1.432 395.968 M( ioctl_get_nth_byte\(file_desc\);)S
1.432 385.168 M( ioctl_get_msg\(file_desc\);)S
1.432 374.368 M( ioctl_set_msg\(file_desc, msg\);)S
1.432 352.768 M( close\(file_desc\); )S
1.432 341.968 M(})S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 7. Talking To Device Files)S
474.768 0 M(45)S
GR
SP
%%Page: 46 51
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
20 FS/F9 SF 0 678 M(Chapter 8. System Calls)S
14 FS/F9 SF 0 646.8 M(8.1. System Calls)S
11 FS/F4 SF 0 619.8 M(So far, the only thing we've done was to use well defined kernel mechanisms to register )S
/F0 SF (/proc)S
/F4 SF ( files and)S
0 606.6 M(device handlers. This is fine if you want to do something the kernel programmers thought you'd want, such as)S
0 593.4 M(write a device driver. But what if you want to do something unusual, to change the behavior of the system in)S
0 580.2 M(some way? Then, you're mostly on your own.)S
0 553.8 M(This is where kernel programming gets dangerous. While writing the example below, I killed the )S
/F0 SF (open\(\))S
/F4 SF 0 540.6 M(system call. This meant I couldn't open any files, I couldn't run any programs, and I couldn't)S
/F5 SF ( shutdown)S
/F4 SF ( the)S
0 527.4 M(computer. I had to pull the power switch. Luckily, no files died. To ensure you won't lose any files either,)S
0 514.2 M(please run)S
/F5 SF ( sync)S
/F4 SF ( right before you do the)S
/F5 SF ( insmod)S
/F4 SF ( and the)S
/F5 SF ( rmmod)S
/F4 SF (.)S
0 487.8 M(Forget about )S
/F0 SF (/proc)S
/F4 SF ( files, forget about device files. They're just minor details. The)S
/F6 SF ( real)S
/F4 SF ( process to kernel)S
0 474.6 M(communication mechanism, the one used by all processes, is system calls. When a process requests a service)S
0 461.4 M(from the kernel \(such as opening a file, forking to a new process, or requesting more memory\), this is the)S
0 448.2 M(mechanism used. If you want to change the behaviour of the kernel in interesting ways, this is the place to do)S
0 435 M(it. By the way, if you want to see which system calls a program uses, run)S
/F5 SF ( strace )S
/F4 SF (.)S
0 408.6 M(In general, a process is not supposed to be able to access the kernel. It can't access kernel memory and it can't)S
0 395.4 M(call kernel functions. The hardware of the CPU enforces this \(that's the reason why it's called `protected)S
0 382.2 M(mode'\).)S
0 355.8 M(System calls are an exception to this general rule. What happens is that the process fills the registers with the)S
0 342.6 M(appropriate values and then calls a special instruction which jumps to a previously defined location in the)S
0 329.4 M(kernel \(of course, that location is readable by user processes, it is not writable by them\). Under Intel CPUs,)S
0 316.2 M(this is done by means of interrupt 0x80. The hardware knows that once you jump to this location, you are no)S
0 303 M(longer running in restricted user mode, but as the operating system kernel --- and therefore you're allowed to)S
0 289.8 M(do whatever you want.)S
0 263.4 M(The location in the kernel a process can jump to is called)S
/F6 SF ( system_call)S
/F4 SF (. The procedure at that location checks)S
0 250.2 M(the system call number, which tells the kernel what service the process requested. Then, it looks at the table of)S
0 237 M(system calls \()S
/Fa SF (sys_call_table)S
/F4 SF (\) to see the address of the kernel function to call. Then it calls the function, and)S
0 223.8 M(after it returns, does a few system checks and then return back to the process \(or to a different process, if the)S
0 210.6 M(process time ran out\). If you want to read this code, it's at the source file)S
/F0 SF 0 197.4 M(arch/$<$architecture$>$/kernel/entry.S)S
/F4 SF (, after the line )S
/F0 SF (ENTRY\(system_call\))S
/F4 SF (.)S
0 171 M(So, if we want to change the way a certain system call works, what we need to do is to write our own function)S
0 157.8 M(to implement it \(usually by adding a bit of our own code, and then calling the original function\) and then)S
0 144.6 M(change the pointer at)S
/Fa SF ( sys_call_table)S
/F4 SF ( to point to our function. Because we might be removed later and we)S
0 131.4 M(don't want to leave the system in an unstable state, it's important for )S
/F0 SF (cleanup_module)S
/F4 SF ( to restore the table)S
0 118.2 M(to its original state.)S
0 91.8 M(The source code here is an example of such a kernel module. We want to `spy' on a certain user, and to)S
/F0 SF 0 78.6 M(printk\(\))S
/F4 SF ( a message whenever that user opens a file. Towards this end, we replace the system call to open a)S
0 65.4 M(file with our own function, called )S
/F0 SF (our_sys_open)S
/F4 SF (. This function checks the uid \(user's id\) of the current)S
0 52.2 M(process, and if it's equal to the uid we spy on, it calls )S
/F0 SF (printk\(\))S
/F4 SF ( to display the name of the file to be opened.)S
0 39 M(Then, either way, it calls the original )S
/F0 SF (open\(\))S
/F4 SF ( function with the same parameters, to actually open the file.)S
/F8 SF 0 0 M(Chapter 8. System Calls)S
474.768 0 M(46)S
GR
SP
%%Page: 47 52
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 319.6 F
0.00 0.00 0.00 C 11 FS/F4 SF 0 687 M(The )S
/F0 SF (init_module)S
/F4 SF ( function replaces the appropriate location in)S
/Fa SF ( sys_call_table)S
/F4 SF ( and keeps the original)S
0 673.8 M(pointer in a variable. The )S
/F0 SF (cleanup_module)S
/F4 SF ( function uses that variable to restore everything back to)S
0 660.6 M(normal. This approach is dangerous, because of the possibility of two kernel modules changing the same)S
0 647.4 M(system call. Imagine we have two kernel modules, A and B. A's open system call will be A_open and B's will)S
0 634.2 M(be B_open. Now, when A is inserted into the kernel, the system call is replaced with A_open, which will call)S
0 621 M(the original sys_open when it's done. Next, B is inserted into the kernel, which replaces the system call with)S
0 607.8 M(B_open, which will call what it thinks is the original system call, A_open, when it's done.)S
0 581.4 M(Now, if B is removed first, everything will be well---it will simply restore the system call to A_open, which)S
0 568.2 M(calls the original. However, if A is removed and then B is removed, the system will crash. A's removal will)S
0 555 M(restore the system call to the original, sys_open, cutting B out of the loop. Then, when B is removed, it will)S
0 541.8 M(restore the system call to what)S
/F6 SF ( it)S
/F4 SF ( thinks is the original, A_open, which is no longer in memory. At first glance,)S
0 528.6 M(it appears we could solve this particular problem by checking if the system call is equal to our open function)S
0 515.4 M(and if so not changing it at all \(so that B won't change the system call when it's removed\), but that will cause)S
0 502.2 M(an even worse problem. When A is removed, it sees that the system call was changed to B_open so that it is)S
0 489 M(no longer pointing to A_open, so it won't restore it to sys_open before it is removed from memory.)S
0 475.8 M(Unfortunately, B_open will still try to call A_open which is no longer there, so that even without removing B)S
0 462.6 M(the system would crash.)S
0 436.2 M(I can think of two ways to prevent this problem. The first is to restore the call to the original value, sys_open.)S
0 423 M(Unfortunately, sys_open is not part of the kernel system table in )S
/F0 SF (/proc/ksyms)S
/F4 SF (, so we can't access it. The)S
0 409.8 M(other solution is to use the reference count to prevent root from)S
/F5 SF ( rmmod)S
/F4 SF ('ing the module once it is loaded. This)S
0 396.6 M(is good for production modules, but bad for an educational sample --- which is why I didn't do it here.)S
/F5 SF 0 357 M(Example 8-1. syscall.c)S
9 FS/F0 SF 1.432 331.167 M(/* syscall.c )S
1.432 320.367 M( * )S
1.432 309.567 M( * System call "stealing" sample.)S
1.432 298.767 M( */)S
1.432 266.367 M(/* Copyright \(C\) 2001 by Peter Jay Salzman */)S
1.432 233.967 M(/* The necessary header files */)S
1.432 212.367 M(/* Standard in kernel modules */)S
1.432 201.567 M(#include /* We're doing kernel work */)S
1.432 190.767 M(#include /* Specifically, a module */)S
1.432 169.167 M(/* Deal with CONFIG_MODVERSIONS */)S
1.432 158.367 M(#if CONFIG_MODVERSIONS==1)S
1.432 147.567 M(#define MODVERSIONS)S
1.432 136.767 M(#include )S
1.432 125.967 M(#endif )S
1.432 104.367 M(#include /* The list of system calls */)S
1.432 82.767 M(/* For the current \(process\) structure, we need)S
1.432 71.967 M( * this to know who the current user is. */)S
1.432 61.167 M(#include )S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 8. System Calls)S
474.768 0 M(47)S
GR
SP
%%Page: 48 53
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 676.768 M(/* In 2.2.3 /usr/include/linux/version.h includes a )S
1.432 665.968 M( * macro for this, but 2.0.35 doesn't - so I add it )S
1.432 655.168 M( * here if necessary. */)S
1.432 644.368 M(#ifndef KERNEL_VERSION)S
1.432 633.568 M(#define KERNEL_VERSION\(a,b,c\) \(\(a\)*65536+\(b\)*256+\(c\)\))S
1.432 622.768 M(#endif)S
1.432 579.568 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 568.768 M(#include )S
1.432 557.968 M(#endif)S
1.432 514.768 M(/* The system call table \(a table of functions\). We )S
1.432 503.968 M( * just define this as external, and the kernel will )S
1.432 493.168 M( * fill it up for us when we are insmod'ed )S
1.432 482.368 M( */)S
1.432 471.568 M(extern void *sys_call_table[];)S
1.432 439.168 M(/* UID we want to spy on - will be filled from the )S
1.432 428.368 M( * command line */)S
1.432 417.568 M(int uid; )S
1.432 395.968 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 385.168 M(MODULE_PARM\(uid, "i"\);)S
1.432 374.368 M(#endif)S
1.432 352.768 M(/* A pointer to the original system call. The reason )S
1.432 341.968 M( * we keep this, rather than call the original function )S
1.432 331.168 M( * \(sys_open\), is because somebody else might have )S
1.432 320.368 M( * replaced the system call before us. Note that this )S
1.432 309.568 M( * is not 100% safe, because if another module )S
1.432 298.768 M( * replaced sys_open before us, then when we're inserted )S
1.432 287.968 M( * we'll call the function in that module - and it )S
1.432 277.168 M( * might be removed before we are.)S
1.432 266.368 M( *)S
1.432 255.568 M( * Another reason for this is that we can't get sys_open.)S
1.432 244.768 M( * It's a static variable, so it is not exported. */)S
1.432 233.968 M(asmlinkage int \(*original_call\)\(const char *, int, int\);)S
1.432 190.768 M(/* For some reason, in 2.2.3 current->uid gave me )S
1.432 179.968 M( * zero, not the real user ID. I tried to find what went )S
1.432 169.168 M( * wrong, but I couldn't do it in a short time, and )S
1.432 158.368 M( * I'm lazy - so I'll just use the system call to get the )S
1.432 147.568 M( * uid, the way a process would. )S
1.432 136.768 M( *)S
1.432 125.968 M( * For some reason, after I recompiled the kernel this )S
1.432 115.168 M( * problem went away. )S
1.432 104.368 M( */)S
1.432 93.568 M(asmlinkage int \(*getuid_call\)\(\);)S
1.432 50.368 M(/* The function we'll replace sys_open \(the function )S
1.432 39.568 M( * called when you call the open system call\) with. To )S
1.432 28.768 M( * find the exact prototype, with the number and type )S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 8. System Calls)S
474.768 0 M(48)S
GR
SP
%%Page: 49 54
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 687.568 M( * of arguments, we find the original function first )S
1.432 676.768 M( * \(it's at fs/open.c\). )S
1.432 665.968 M( *)S
1.432 655.168 M( * In theory, this means that we're tied to the )S
1.432 644.368 M( * current version of the kernel. In practice, the )S
1.432 633.568 M( * system calls almost never change \(it would wreck havoc )S
1.432 622.768 M( * and require programs to be recompiled, since the system)S
1.432 611.968 M( * calls are the interface between the kernel and the )S
1.432 601.168 M( * processes\).)S
1.432 590.368 M( */)S
1.432 579.568 M(asmlinkage int our_sys_open\(const char *filename, )S
1.432 568.768 M( int flags, )S
1.432 557.968 M( int mode\))S
1.432 547.168 M({)S
1.432 536.368 M( int i = 0;)S
1.432 525.568 M( char ch;)S
1.432 503.968 M( /* Check if this is the user we're spying on */)S
1.432 493.168 M( if \(uid == getuid_call\(\)\) { )S
1.432 482.368 M( /* getuid_call is the getuid system call, )S
1.432 471.568 M( * which gives the uid of the user who)S
1.432 460.768 M( * ran the process which called the system)S
1.432 449.968 M( * call we got */)S
1.432 428.368 M( /* Report the file, if relevant */)S
1.432 417.568 M( printk\("Opened file by %d: ", uid\); )S
1.432 406.768 M( do {)S
1.432 395.968 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 385.168 M( get_user\(ch, filename+i\);)S
1.432 374.368 M(#else)S
1.432 363.568 M( ch = get_user\(filename+i\);)S
1.432 352.768 M(#endif)S
1.432 341.968 M( i++;)S
1.432 331.168 M( printk\("%c", ch\);)S
1.432 320.368 M( } while \(ch != 0\);)S
1.432 309.568 M( printk\("\\n"\);)S
1.432 298.768 M( })S
1.432 277.168 M( /* Call the original sys_open - otherwise, we lose )S
1.432 266.368 M( * the ability to open files */)S
1.432 255.568 M( return original_call\(filename, flags, mode\);)S
1.432 244.768 M(})S
1.432 201.568 M(/* Initialize the module - replace the system call */)S
1.432 190.768 M(int init_module\(\))S
1.432 179.968 M({)S
1.432 169.168 M( /* Warning - too late for it now, but maybe for )S
1.432 158.368 M( * next time... */)S
1.432 147.568 M( printk\("I'm dangerous. I hope you did a "\);)S
1.432 136.768 M( printk\("sync before you insmod'ed me.\\n"\);)S
1.432 125.968 M( printk\("My counterpart, cleanup_module\(\), is even"\); )S
1.432 115.168 M( printk\("more dangerous. If\\n"\);)S
1.432 104.368 M( printk\("you value your file system, it will "\);)S
1.432 93.568 M( printk\("be \\"sync; rmmod\\" \\n"\);)S
1.432 82.768 M( printk\("when you remove this module.\\n"\);)S
1.432 61.168 M( /* Keep a pointer to the original function in )S
1.432 50.368 M( * original_call, and then replace the system call )S
1.432 39.568 M( * in the system call table with our_sys_open */)S
1.432 28.768 M( original_call = sys_call_table[__NR_open];)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 8. System Calls)S
474.768 0 M(49)S
GR
SP
%%Page: 50 55
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 403.536 M 487.0 294.5 F
0.00 0.00 0.00 C 0 394.936 M 487.0 2.0 F
9 FS/F0 SF 1.432 687.568 M( sys_call_table[__NR_open] = our_sys_open;)S
1.432 665.968 M( /* To get the address of the function for system )S
1.432 655.168 M( * call foo, go to sys_call_table[__NR_foo]. */)S
1.432 633.568 M( printk\("Spying on UID:%d\\n", uid\);)S
1.432 611.968 M( /* Get the system call for getuid */)S
1.432 601.168 M( getuid_call = sys_call_table[__NR_getuid];)S
1.432 579.568 M( return 0;)S
1.432 568.768 M(})S
1.432 536.368 M(/* Cleanup - unregister the appropriate file from /proc */)S
1.432 525.568 M(void cleanup_module\(\))S
1.432 514.768 M({)S
1.432 503.968 M( /* Return the system call back to normal */)S
1.432 493.168 M( if \(sys_call_table[__NR_open] != our_sys_open\) {)S
1.432 482.368 M( printk\("Somebody else also played with the "\);)S
1.432 471.568 M( printk\("open system call\\n"\);)S
1.432 460.768 M( printk\("The system may be left in "\);)S
1.432 449.968 M( printk\("an unstable state.\\n"\);)S
1.432 439.168 M( })S
1.432 417.568 M( sys_call_table[__NR_open] = original_call;)S
1.432 406.768 M(} )S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 8. System Calls)S
474.768 0 M(50)S
GR
SP
%%Page: 51 56
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0 635.4 M 487.0 2.0 F
0.88 0.88 0.88 C 0 22 M 487.0 92.0 F
0.00 0.00 0.00 C 20 FS/F9 SF 0 678 M(Chapter 9. Blocking Processes)S
14 FS/F9 SF 0 646.8 M(9.1. Blocking Processes)S
11 FS/F9 SF 0 617.8 M(9.1.1. Replacing )S
/F1 SF (printk)S
/F4 SF 0 591.4 M(What do you do when somebody asks you for something you can't do right away? If you're a human being and)S
0 578.2 M(you're bothered by a human being, the only thing you can say is: "Not right now, I'm busy.)S
/F6 SF ( Go away!)S
/F4 SF (". But if)S
0 565 M(you're a kernel module and you're bothered by a process, you have another possibility. You can put the)S
0 551.8 M(process to sleep until you can service it. After all, processes are being put to sleep by the kernel and woken up)S
0 538.6 M(all the time \(that's the way multiple processes appear to run on the same time on a single CPU\).)S
0 512.2 M(This kernel module is an example of this. The file \(called )S
/F0 SF (/proc/sleep)S
/F4 SF (\) can only be opened by a single)S
0 499 M(process at a time. If the file is already open, the kernel module calls)S
/F0 SF 0 485.8 M(module_interruptible_sleep_on)S
/F4 SF ([11]. This function changes the status of the task \(a task is the)S
0 472.6 M(kernel data structure which holds information about a process and the system call it's in, if any\) to)S
/Fa SF 0 459.4 M(TASK_INTERRUPTIBLE)S
/F4 SF (, which means that the task will not run until it is woken up somehow, and adds it)S
0 446.2 M(to )S
/F0 SF (WaitQ)S
/F4 SF (, the queue of tasks waiting to access the file. Then, the function calls the scheduler to context)S
0 433 M(switch to a different process, one which has some use for the CPU.)S
0 406.6 M(When a process is done with the file, it closes it, and )S
/F0 SF (module_close)S
/F4 SF ( is called. That function wakes up all)S
0 393.4 M(the processes in the queue \(there's no mechanism to only wake up one of them\). It then returns and the process)S
0 380.2 M(which just closed the file can continue to run. In time, the scheduler decides that that process has had enough)S
0 367 M(and gives control of the CPU to another process. Eventually, one of the processes which was in the queue will)S
0 353.8 M(be given control of the CPU by the scheduler. It starts at the point right after the call to)S
/F0 SF 0 340.6 M(module_interruptible_sleep_on)S
/F4 SF ([12]. It can then proceed to set a global variable to tell all the other)S
0 327.4 M(processes that the file is still open and go on with its life. When the other processes get a piece of the CPU,)S
0 314.2 M(they'll see that global variable and go back to sleep.)S
0 287.8 M(To make our life more interesting, )S
/F0 SF (module_close)S
/F4 SF ( doesn't have a monopoly on waking up the processes)S
0 274.6 M(which wait to access the file. A signal, such as)S
/F5 SF ( Ctrl)S
/F4 SF (+)S
/F5 SF (c)S
/F4 SF ( \()S
/Fa SF (SIGINT)S
/F4 SF (\) can also wake up a process.)S
( [13] In that case,)S
0 261.4 M(we want to return with)S
/Fa SF ( -EINTR)S
/F4 SF ( immediately. This is important so users can, for example, kill the process)S
0 248.2 M(before it receives the file.)S
0 221.8 M(There is one more point to remember. Some times processes don't want to sleep, they want either to get what)S
0 208.6 M(they want immediately, or to be told it cannot be done. Such processes use the)S
/Fa SF ( O_NONBLOCK)S
/F4 SF ( flag when)S
0 195.4 M(opening the file. The kernel is supposed to respond by returning with the error code)S
/Fa SF ( -EAGAIN)S
/F4 SF ( from)S
0 182.2 M(operations which would otherwise block, such as opening the file in this example. The program)S
/F5 SF ( cat_noblock)S
/F4 SF (,)S
0 169 M(available in the source directory for this chapter, can be used to open a file with)S
/Fa SF ( O_NONBLOCK)S
/F4 SF (.)S
/F5 SF 0 129.4 M(Example 9-1. sleep.c)S
9 FS/F0 SF 1.432 103.567 M(/* sleep.c - create a /proc file, and if several processes try to open it at)S
1.432 92.767 M( * the same time, put all but one to sleep)S
1.432 81.967 M( */)S
1.432 60.367 M(#include /* We're doing kernel work */)S
1.432 49.567 M(#include /* Specifically, a module */)S
1.432 27.967 M(/* Deal with CONFIG_MODVERSIONS */)S
11 FS/F8 SF 0 0 M(Chapter 9. Blocking Processes)S
474.768 0 M(51)S
GR
SP
%%Page: 52 57
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 687.568 M(#if CONFIG_MODVERSIONS==1)S
1.432 676.768 M(#define MODVERSIONS)S
1.432 665.968 M(#include )S
1.432 655.168 M(#endif )S
1.432 633.568 M(/* Necessary because we use proc fs */)S
1.432 622.768 M(#include )S
1.432 601.168 M(/* For putting processes to sleep and waking them up */)S
1.432 590.368 M(#include )S
1.432 579.568 M(#include )S
1.432 557.968 M(/* In 2.2.3 /usr/include/linux/version.h includes a macro for this, but 2.0.35)S
1.432 547.168 M( * doesn't - so I add it here if necessary.)S
1.432 536.368 M( */)S
1.432 525.568 M(#ifndef KERNEL_VERSION)S
1.432 514.768 M(#define KERNEL_VERSION\(a,b,c\) \(\(a\)*65536+\(b\)*256+\(c\)\))S
1.432 503.968 M(#endif)S
1.432 482.368 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 471.568 M(#include /* for get_user and put_user */)S
1.432 460.768 M(#endif)S
1.432 439.168 M(/* The module's file functions */)S
1.432 417.568 M(/* Here we keep the last message received, to prove that we can process our)S
1.432 406.768 M( * input)S
1.432 395.968 M( */)S
1.432 385.168 M(#define MESSAGE_LENGTH 80)S
1.432 374.368 M(static char Message[MESSAGE_LENGTH];)S
1.432 352.768 M(/* Since we use the file operations struct, we can't use the special proc)S
1.432 341.968 M( * output provisions - we have to use a standard read function, which is this)S
1.432 331.168 M( * function)S
1.432 320.368 M( */)S
1.432 309.568 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 298.768 M(static ssize_t module_output \()S
1.432 287.968 M( struct file *file, /* The file read */)S
1.432 277.168 M( char *buf, /* The buffer to put data to \(in the user segment\) */)S
1.432 266.368 M( size_t len, /* The length of the buffer */)S
1.432 255.568 M( loff_t *offset\) /* Offset in the file - ignore */)S
1.432 244.768 M(#else)S
1.432 233.968 M(static int module_output \()S
1.432 223.168 M( struct inode *inode, /* The inode read */)S
1.432 212.368 M( struct file *file, /* The file read */)S
1.432 201.568 M( char *buf, /* The buffer to put data to \(in the user segment\) */)S
1.432 190.768 M( int len\) /* The length of the buffer */)S
1.432 179.968 M(#endif)S
1.432 169.168 M({)S
1.432 158.368 M( static int finished = 0;)S
1.432 147.568 M( int i;)S
1.432 136.768 M( char message[MESSAGE_LENGTH+30];)S
1.432 115.168 M( /* Return 0 to signify end of file - that we have nothing more to say at this)S
1.432 104.368 M( * point.)S
1.432 93.568 M( */)S
1.432 82.768 M( if \(finished\) {)S
1.432 71.968 M( finished = 0;)S
1.432 61.168 M( return 0;)S
1.432 50.368 M( })S
1.432 28.768 M( /* If you don't understand this by now, you're hopeless as a kernel)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 9. Blocking Processes)S
474.768 0 M(52)S
GR
SP
%%Page: 53 58
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 687.568 M( * programmer.)S
1.432 676.768 M( */)S
1.432 665.968 M( sprintf\(message, "Last input:%s\\n", Message\);)S
1.432 655.168 M( for \(i = 0; i < len && message[i]; i++\) )S
1.432 644.368 M( put_user\(message[i], buf+i\);)S
1.432 622.768 M( finished = 1;)S
1.432 611.968 M( return i; /* Return the number of bytes "read" */)S
1.432 601.168 M(})S
1.432 579.568 M(/* This function receives input from the user when the user writes to the /proc)S
1.432 568.768 M( * file.)S
1.432 557.968 M( */)S
1.432 547.168 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 536.368 M(static ssize_t module_input \()S
1.432 525.568 M( struct file *file, /* The file itself */)S
1.432 514.768 M( const char *buf, /* The buffer with input */)S
1.432 503.968 M( size_t length, /* The buffer's length */)S
1.432 493.168 M( loff_t *offset\) /* offset to file - ignore */)S
1.432 482.368 M(#else)S
1.432 471.568 M(static int module_input \()S
1.432 460.768 M( struct inode *inode, /* The file's inode */)S
1.432 449.968 M( struct file *file, /* The file itself */)S
1.432 439.168 M( const char *buf, /* The buffer with the input */)S
1.432 428.368 M( int length\) /* The buffer's length */)S
1.432 417.568 M(#endif)S
1.432 406.768 M({)S
1.432 395.968 M( int i;)S
1.432 374.368 M( /* Put the input into Message, where module_output will later be able to use)S
1.432 363.568 M( * it)S
1.432 352.768 M( */)S
1.432 341.968 M( for\(i = 0; i < MESSAGE_LENGTH-1 && i < length; i++\))S
1.432 331.168 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 320.368 M( get_user\(Message[i], buf+i\);)S
1.432 309.568 M(#else)S
1.432 298.768 M( Message[i] = get_user\(buf+i\);)S
1.432 287.968 M(#endif)S
1.432 277.168 M( /* we want a standard, zero terminated string */)S
1.432 266.368 M( Message[i] = '\\0'; )S
1.432 244.768 M( /* We need to return the number of input characters used */)S
1.432 233.968 M( return i;)S
1.432 223.168 M(})S
1.432 201.568 M(/* 1 if the file is currently open by somebody */)S
1.432 190.768 M(int Already_Open = 0;)S
1.432 169.168 M(/* Queue of processes who want our file */)S
1.432 158.368 M(static struct wait_queue *WaitQ = NULL;)S
1.432 136.768 M(/* Called when the /proc file is opened */)S
1.432 125.968 M(static int module_open\(struct inode *inode, struct file *file\))S
1.432 115.168 M({)S
1.432 104.368 M( /* If the file's flags include O_NONBLOCK, it means the process doesn't want)S
1.432 93.568 M( * to wait for the file. In this case, if the file is already open, we)S
1.432 82.768 M( * should fail with -EAGAIN, meaning "you'll have to try again", instead of)S
1.432 71.968 M( * blocking a process which would rather stay awake.)S
1.432 61.168 M( */)S
1.432 50.368 M( if \(\(file->f_flags & O_NONBLOCK\) && Already_Open\) )S
1.432 39.568 M( return -EAGAIN;)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 9. Blocking Processes)S
474.768 0 M(53)S
GR
SP
%%Page: 54 59
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 687.568 M( /* This is the correct place for MOD_INC_USE_COUNT because if a process is)S
1.432 676.768 M( * in the loop, which is within the kernel module, the kernel module must)S
1.432 665.968 M( * not be removed.)S
1.432 655.168 M( */)S
1.432 644.368 M( MOD_INC_USE_COUNT;)S
1.432 622.768 M( /* If the file is already open, wait until it isn't */)S
1.432 611.968 M( while \(Already_Open\) )S
1.432 601.168 M( {)S
1.432 590.368 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 579.568 M( int i, is_sig = 0;)S
1.432 568.768 M(#endif)S
1.432 547.168 M( /* This function puts the current process, including any system calls,)S
1.432 536.368 M( * such as us, to sleep. Execution will be resumed right after the)S
1.432 525.568 M( * function call, either because somebody called wake_up\(&WaitQ\) \(only)S
1.432 514.768 M( * module_close does that, when the file is closed\) or when a signal,)S
1.432 503.968 M( * such as Ctrl-C, is sent to the process)S
1.432 493.168 M( */)S
1.432 482.368 M( module_interruptible_sleep_on\(&WaitQ\);)S
1.432 460.768 M( /* If we woke up because we got a signal we're not blocking, return)S
1.432 449.968 M( * -EINTR \(fail the system call\). This allows processes to be killed or)S
1.432 439.168 M( * stopped.)S
1.432 428.368 M( */)S
1.432 406.768 M(/*)S
1.432 395.968 M( * Emmanuel Papirakis:)S
1.432 385.168 M( *)S
1.432 374.368 M( * This is a little update to work with 2.2.*. Signals now are contained in)S
1.432 363.568 M( * two words \(64 bits\) and are stored in a structure that contains an array of)S
1.432 352.768 M( * two unsigned longs. We now have to make 2 checks in our if.)S
1.432 341.968 M( *)S
1.432 331.168 M( * Ori Pomerantz:)S
1.432 320.368 M( *)S
1.432 309.568 M( * Nobody promised me they'll never use more than 64 bits, or that this book)S
1.432 298.768 M( * won't be used for a version of Linux with a word size of 16 bits. This code)S
1.432 287.968 M( * would work in any case.)S
1.432 277.168 M( */ )S
1.432 266.368 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 255.568 M( for \(i = 0; i < _NSIG_WORDS && !is_sig; i++\))S
1.432 244.768 M( is_sig = current->signal.sig[i] & ~current->blocked.sig[i];)S
1.432 223.168 M( if \(is_sig\) {)S
1.432 212.368 M(#else)S
1.432 201.568 M( if \(current->signal & ~current->blocked\) {)S
1.432 190.768 M(#endif)S
1.432 179.968 M( /* It's important to put MOD_DEC_USE_COUNT here, because for processes)S
1.432 169.168 M( * where the open is interrupted there will never be a corresponding)S
1.432 158.368 M( * close. If we don't decrement the usage count here, we will be left)S
1.432 147.568 M( * with a positive usage count which we'll have no way to bring down)S
1.432 136.768 M( * to zero, giving us an immortal module, which can only be killed by)S
1.432 125.968 M( * rebooting the machine.)S
1.432 115.168 M( */)S
1.432 104.368 M( MOD_DEC_USE_COUNT;)S
1.432 93.568 M( return -EINTR;)S
1.432 82.768 M( })S
1.432 71.968 M( })S
1.432 50.368 M( /* If we got here, Already_Open must be zero */)S
1.432 28.768 M( /* Open the file */)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 9. Blocking Processes)S
474.768 0 M(54)S
GR
SP
%%Page: 55 60
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 687.568 M( Already_Open = 1;)S
1.432 676.768 M( return 0; /* Allow the access */)S
1.432 665.968 M(})S
1.432 644.368 M(/* Called when the /proc file is closed */)S
1.432 633.568 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 622.768 M(int module_close\(struct inode *inode, struct file *file\))S
1.432 611.968 M(#else)S
1.432 601.168 M(void module_close\(struct inode *inode, struct file *file\))S
1.432 590.368 M(#endif)S
1.432 579.568 M({)S
1.432 568.768 M( /* Set Already_Open to zero, so one of the processes in the WaitQ will be)S
1.432 557.968 M( * able to set Already_Open back to one and to open the file. All the other)S
1.432 547.168 M( * processes will be called when Already_Open is back to one, so they'll go)S
1.432 536.368 M( * back to sleep.)S
1.432 525.568 M( */)S
1.432 514.768 M( Already_Open = 0;)S
1.432 493.168 M( /* Wake up all the processes in WaitQ, so if anybody is waiting for the)S
1.432 482.368 M( * file, they can have it.)S
1.432 471.568 M( */)S
1.432 460.768 M( module_wake_up\(&WaitQ\);)S
1.432 439.168 M( MOD_DEC_USE_COUNT;)S
1.432 417.568 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 406.768 M( return 0; /* success */)S
1.432 395.968 M(#endif)S
1.432 385.168 M(})S
1.432 363.568 M(/* This function decides whether to allow an operation \(return zero\) or not)S
1.432 352.768 M( * allow it \(return a non-zero which indicates why it is not allowed\).)S
1.432 341.968 M( *)S
1.432 331.168 M( * The operation can be one of the following values:)S
1.432 320.368 M( * 0 - Execute \(run the "file" - meaningless in our case\))S
1.432 309.568 M( * 2 - Write \(input to the kernel module\))S
1.432 298.768 M( * 4 - Read \(output from the kernel module\))S
1.432 287.968 M( *)S
1.432 277.168 M( * This is the real function that checks file permissions. The permissions)S
1.432 266.368 M( * returned by ls -l are for referece only, and can be overridden here. )S
1.432 255.568 M( */)S
1.432 244.768 M(static int module_permission\(struct inode *inode, int op\))S
1.432 233.968 M({)S
1.432 223.168 M( /* We allow everybody to read from our module, but only root \(uid 0\) may)S
1.432 212.368 M( * write to it)S
1.432 201.568 M( */ )S
1.432 190.768 M( if \(op == 4 || \(op == 2 && current->euid == 0\)\))S
1.432 179.968 M( return 0; )S
1.432 158.368 M( /* If it's anything else, access is denied */)S
1.432 147.568 M( return -EACCES;)S
1.432 136.768 M(})S
1.432 115.168 M(/* Structures to register as the /proc file, with pointers to all the relevant)S
1.432 104.368 M( * functions. )S
1.432 93.568 M( */)S
1.432 71.968 M(/* File operations for our proc file. This is where we place pointers to all)S
1.432 61.168 M( * the functions called when somebody tries to do something to our file. NULL)S
1.432 50.368 M( * means we don't want to deal with something.)S
1.432 39.568 M( */)S
1.432 28.768 M(static struct file_operations File_Ops_4_Our_Proc_File = {)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 9. Blocking Processes)S
474.768 0 M(55)S
GR
SP
%%Page: 56 61
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 687.568 M( NULL, /* lseek */)S
1.432 676.768 M( module_output, /* "read" from the file */)S
1.432 665.968 M( module_input, /* "write" to the file */)S
1.432 655.168 M( NULL, /* readdir */)S
1.432 644.368 M( NULL, /* select */)S
1.432 633.568 M( NULL, /* ioctl */)S
1.432 622.768 M( NULL, /* mmap */)S
1.432 611.968 M( module_open, /* called when the /proc file is opened */)S
1.432 601.168 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 590.368 M( NULL, /* flush */)S
1.432 579.568 M(#endif)S
1.432 568.768 M( module_close}; /* called when it's classed */)S
1.432 547.168 M(/* Inode operations for our proc file. We need it so we'll have somewhere to)S
1.432 536.368 M( * specify the file operations structure we want to use, and the function we)S
1.432 525.568 M( * use for permissions. It's also possible to specify functions to be called)S
1.432 514.768 M( * for anything else which could be done to an inode \(although we don't bother,)S
1.432 503.968 M( * we just put NULL\).)S
1.432 493.168 M( */)S
1.432 482.368 M(static struct inode_operations Inode_Ops_4_Our_Proc_File = {)S
1.432 471.568 M( &File_Ops_4_Our_Proc_File,)S
1.432 460.768 M( NULL, /* create */)S
1.432 449.968 M( NULL, /* lookup */)S
1.432 439.168 M( NULL, /* link */)S
1.432 428.368 M( NULL, /* unlink */)S
1.432 417.568 M( NULL, /* symlink */)S
1.432 406.768 M( NULL, /* mkdir */)S
1.432 395.968 M( NULL, /* rmdir */)S
1.432 385.168 M( NULL, /* mknod */)S
1.432 374.368 M( NULL, /* rename */)S
1.432 363.568 M( NULL, /* readlink */)S
1.432 352.768 M( NULL, /* follow_link */)S
1.432 341.968 M( NULL, /* readpage */)S
1.432 331.168 M( NULL, /* writepage */)S
1.432 320.368 M( NULL, /* bmap */)S
1.432 309.568 M( NULL, /* truncate */)S
1.432 298.768 M( module_permission}; /* check for permissions */)S
1.432 277.168 M(/* Directory entry */)S
1.432 266.368 M(static struct proc_dir_entry Our_Proc_File = {)S
1.432 255.568 M( 0, /* Inode number - ignore, it will be filled by )S
1.432 244.768 M( * proc_register[_dynamic])S
1.432 233.968 M( */)S
1.432 223.168 M( 5, /* Length of the file name */)S
1.432 212.368 M( "sleep", /* The file name */)S
1.432 190.768 M( /* File mode - this is a regular file which can be read by its owner, its)S
1.432 179.968 M( * group, and everybody else. Also, its owner can write to it.)S
1.432 169.168 M( *)S
1.432 158.368 M( * Actually, this field is just for reference, it's module_permission that)S
1.432 147.568 M( * does the actual check. It could use this field, but in our)S
1.432 136.768 M( * implementation it doesn't, for simplicity.)S
1.432 125.968 M( */)S
1.432 115.168 M( S_IFREG | S_IRUGO | S_IWUSR, )S
1.432 104.368 M( 1, /* Number of links \(directories where the file is referenced\) */)S
1.432 93.568 M( 0, 0, /* The uid and gid for the file - we give it to root */)S
1.432 82.768 M( 80, /* The size of the file reported by ls. */)S
1.432 61.168 M( /* A pointer to the inode structure for the file, if we need it. In our)S
1.432 50.368 M( * case we do, because we need a write function.)S
1.432 39.568 M( */)S
1.432 28.768 M( &Inode_Ops_4_Our_Proc_File, )S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 9. Blocking Processes)S
474.768 0 M(56)S
GR
SP
%%Page: 57 62
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 349.536 M 487.0 348.5 F
0.00 0.00 0.00 C 0 340.936 M 487.0 2.0 F
9 FS/F0 SF 1.432 676.768 M( /* The read function for the file. Irrelevant, because we put it in the)S
1.432 665.968 M( * inode structure above)S
1.432 655.168 M( */)S
1.432 644.368 M( NULL}; )S
1.432 622.768 M(/* Module initialization and cleanup */)S
1.432 601.168 M(/* Initialize the module - register the proc file */)S
1.432 590.368 M(int init_module\(\))S
1.432 579.568 M({)S
1.432 568.768 M( /* Success if proc_register_dynamic is a success, failure otherwise */)S
1.432 557.968 M(#if LINUX_VERSION_CODE >= KERNEL_VERSION\(2,2,0\))S
1.432 547.168 M( return proc_register\(&proc_root, &Our_Proc_File\);)S
1.432 536.368 M(#else)S
1.432 525.568 M( return proc_register_dynamic\(&proc_root, &Our_Proc_File\);)S
1.432 514.768 M(#endif )S
1.432 493.168 M( /* proc_root is the root directory for the proc fs \(/proc\). This is where)S
1.432 482.368 M( * we want our file to be located. )S
1.432 471.568 M( */)S
1.432 460.768 M(})S
1.432 439.168 M(/* Cleanup - unregister our file from /proc. This could get dangerous if)S
1.432 428.368 M( * there are still processes waiting in WaitQ, because they are inside our)S
1.432 417.568 M( * open function, which will get unloaded. I'll explain how to avoid removal)S
1.432 406.768 M( * of a kernel module in such a case in chapter 10.)S
1.432 395.968 M( */)S
1.432 385.168 M(void cleanup_module\(\))S
1.432 374.368 M({)S
1.432 363.568 M( proc_unregister\(&proc_root, Our_Proc_File.low_ino\);)S
1.432 352.768 M(} )S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 9. Blocking Processes)S
474.768 0 M(57)S
GR
SP
%%Page: 58 63
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 463.6 F
0.00 0.00 0.00 C 20 FS/F9 SF 0 678 M(Chapter 10. Replacing Printks)S
14 FS/F9 SF 0 646.8 M(10.1. Replacing )S
/F1 SF (printk)S
11 FS/F4 SF 0 619.8 M(In Section 1.2.1.2, I said that X and kernel module programming don't mix. That's true for developing kernel)S
0 606.6 M(modules, but in actual use, you want to be able to send messages to whichever tty)S
([14] the command to load)S
0 593.4 M(the module came from.)S
0 567 M(The way this is done is by using)S
/Fa SF ( current)S
/F4 SF (, a pointer to the currently running task, to get the current task's )S
/F0 SF (tty)S
/F4 SF 0 553.8 M(structure. Then, we look inside that )S
/F0 SF (tty)S
/F4 SF ( structure to find a pointer to a string write function, which we use to)S
0 540.6 M(write a string to the tty.)S
/F5 SF 0 501 M(Example 10-1. print_string.c)S
9 FS/F0 SF 1.432 475.168 M(/* print_string.c - Send output to the tty you're running on, regardless of whether it's)S
1.432 464.368 M( * through X11, telnet, etc. We do this by printing the string to the tty associated)S
1.432 453.568 M( * with the current task.)S
1.432 442.768 M( */)S
1.432 431.968 M(#include )S
1.432 421.168 M(#include )S
1.432 410.368 M(#include // For current)S
1.432 399.568 M(#include // For the tty declarations)S
1.432 388.768 M(MODULE_LICENSE\("GPL"\);)S
1.432 377.968 M(MODULE_AUTHOR\("Peter Jay Salzman"\);)S
1.432 345.568 M(void print_string\(char *str\))S
1.432 334.768 M({)S
1.432 323.968 M( struct tty_struct *my_tty;)S
1.432 313.168 M( my_tty = current->tty; // The tty for the current task)S
1.432 291.568 M( /* If my_tty is NULL, the current task has no tty you can print to \(this is possible,)S
1.432 280.768 M( * for example, if it's a daemon\). If so, there's nothing we can do.)S
1.432 269.968 M( */)S
1.432 259.168 M( if \(my_tty != NULL\) { )S
1.432 237.568 M( /* my_tty->driver is a struct which holds the tty's functions, one of which \(write\))S
1.432 226.768 M( * is used to write strings to the tty. It can be used to take a string either)S
1.432 215.968 M( * from the user's memory segment or the kernel's memory segment.)S
1.432 205.168 M( *)S
1.432 194.368 M( * The function's 1st parameter is the tty to write to, because the same function)S
1.432 183.568 M( * would normally be used for all tty's of a certain type. The 2nd parameter)S
1.432 172.768 M( * controls whether the function receives a string from kernel memory \(false, 0\) or)S
1.432 161.968 M( * from user memory \(true, non zero\). The 3rd parameter is a pointer to a string.)S
1.432 151.168 M( * The 4th parameter is the length of the string.)S
1.432 140.368 M( */)S
1.432 129.568 M( \(*\(my_tty->driver\).write\)\()S
1.432 118.768 M( my_tty, // The tty itself)S
1.432 107.968 M( 0, // We don't take the string from user space)S
1.432 97.168 M( str, // String)S
1.432 86.368 M( strlen\(str\)\); // Length)S
1.432 64.768 M( /* ttys were originally hardware devices, which \(usually\) strictly followed the)S
1.432 53.968 M( * ASCII standard. In ASCII, to move to a new line you need two characters, a)S
1.432 43.168 M( * carriage return and a line feed. On Unix, the ASCII line feed is used for both)S
1.432 32.368 M( * purposes - so we can't just use \\n, because it wouldn't have a carriage return)S
11 FS/F8 SF 0 0 M(Chapter 10. Replacing Printks)S
474.768 0 M(58)S
GR
SP
%%Page: 59 64
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 414.336 M 487.0 283.7 F
0.00 0.00 0.00 C 0 405.736 M 487.0 2.0 F
9 FS/F0 SF 1.432 687.568 M( * and the next line will start at the column right after the line feed. )S
1.432 676.768 M( *)S
1.432 665.968 M( * BTW, this is why text files are different between Unix and MS Windows. In CP/M)S
1.432 655.168 M( * and its derivatives, like MS-DOS and MS Windows, the ASCII standard was strictly)S
1.432 644.368 M( * adhered to, and therefore a newline requirs both a LF and a CR.)S
1.432 633.568 M( */)S
1.432 622.768 M( \(*\(my_tty->driver\).write\)\(my_tty, 0, "\\015\\012", 2\);)S
1.432 611.968 M( })S
1.432 601.168 M(})S
1.432 568.768 M(int print_string_init\(void\))S
1.432 557.968 M({)S
1.432 547.168 M( print_string\("The module has been inserted. Hello world!"\);)S
1.432 536.368 M( return 0;)S
1.432 525.568 M(})S
1.432 493.168 M(void print_string_exit\(void\))S
1.432 482.368 M({)S
1.432 471.568 M( print_string\("The module has been removed. Farewell world!"\);)S
1.432 460.768 M(} )S
1.432 428.368 M(module_init\(print_string_init\);)S
1.432 417.568 M(module_exit\(print_string_exit\);)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 10. Replacing Printks)S
474.768 0 M(59)S
GR
SP
%%Page: 60 65
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 186.4 F
0.00 0.00 0.00 C 20 FS/F9 SF 0 678 M(Chapter 11. Scheduling Tasks)S
14 FS/F9 SF 0 646.8 M(11.1. Scheduling Tasks)S
11 FS/F4 SF 0 619.8 M(Very often, we have "housekeeping" tasks which have to be done at a certain time, or every so often. If the)S
0 606.6 M(task is to be done by a process, we do it by putting it in the )S
/F0 SF (crontab)S
/F4 SF ( file. If the task is to be done by a kernel)S
0 593.4 M(module, we have two possibilities. The first is to put a process in the )S
/F0 SF (crontab)S
/F4 SF ( file which will wake up the)S
0 580.2 M(module by a system call when necessary, for example by opening a file. This is terribly inefficient, however)S
0 567 M(-- we run a new process off of )S
/F0 SF (crontab)S
/F4 SF (, read a new executable to memory, and all this just to wake up a)S
0 553.8 M(kernel module which is in memory anyway.)S
0 527.4 M(Instead of doing that, we can create a function that will be called once for every timer interrupt. The way we)S
0 514.2 M(do this is we create a task, held in a )S
/F0 SF (tq_struct)S
/F4 SF ( structure, which will hold a pointer to the function. Then,)S
0 501 M(we use )S
/F0 SF (queue_task)S
/F4 SF ( to put that task on a task list called )S
/F0 SF (tq_timer)S
/F4 SF (, which is the list of tasks to be)S
0 487.8 M(executed on the next timer interrupt. Because we want the function to keep on being executed, we need to put)S
0 474.6 M(it back on )S
/F0 SF (tq_timer)S
/F4 SF ( whenever it is called, for the next timer interrupt.)S
0 448.2 M(There's one more point we need to remember here. When a module is removed by)S
/F5 SF ( rmmod)S
/F4 SF (, first its reference)S
0 435 M(count is checked. If it is zero, )S
/F0 SF (module_cleanup)S
/F4 SF ( is called. Then, the module is removed from memory with)S
0 421.8 M(all its functions. Nobody checks to see if the timer's task list happens to contain a pointer to one of those)S
0 408.6 M(functions, which will no longer be available. Ages later \(from the computer's perspective, from a human)S
0 395.4 M(perspective it's nothing, less than a hundredth of a second\), the kernel has a timer interrupt and tries to call the)S
0 382.2 M(function on the task list. Unfortunately, the function is no longer there. In most cases, the memory page where)S
0 369 M(it sat is unused, and you get an ugly error message. But if some other code is now sitting at the same memory)S
0 355.8 M(location, things could get)S
/F6 SF ( very)S
/F4 SF ( ugly. Unfortunately, we don't have an easy way to unregister a task from a task)S
0 342.6 M(list.)S
0 316.2 M(Since )S
/F0 SF (cleanup_module)S
/F4 SF ( can't return with an error code \(it's a void function\), the solution is to not let it)S
0 303 M(return at all. Instead, it calls )S
/F0 SF (sleep_on)S
/F4 SF ( or )S
/F0 SF (module_sleep_on)S
/F4 SF ([15] to put the)S
/F5 SF ( rmmod)S
/F4 SF ( process to sleep.)S
0 289.8 M(Before that, it informs the function called on the timer interrupt to stop attaching itself by setting a global)S
0 276.6 M(variable. Then, on the next timer interrupt, the)S
/F5 SF ( rmmod)S
/F4 SF ( process will be woken up, when our function is no)S
0 263.4 M(longer in the queue and it's safe to remove the module.)S
/F5 SF 0 223.8 M(Example 11-1. sched.c)S
9 FS/F0 SF 1.432 197.967 M(/* sched.c - scheduale a function to be called on every timer interrupt.)S
1.432 187.167 M( *)S
1.432 176.367 M( * Copyright \(C\) 2001 by Peter Jay Salzman)S
1.432 165.567 M( */)S
1.432 143.967 M(/* The necessary header files */)S
1.432 122.367 M(/* Standard in kernel modules */)S
1.432 111.567 M(#include /* We're doing kernel work */)S
1.432 100.767 M(#include /* Specifically, a module */)S
1.432 79.167 M(/* Deal with CONFIG_MODVERSIONS */)S
1.432 68.367 M(#if CONFIG_MODVERSIONS==1)S
1.432 57.567 M(#define MODVERSIONS)S
1.432 46.767 M(#include )S
1.432 35.967 M(#endif )S
11 FS/F8 SF 0 0 M(Chapter 11. Scheduling Tasks)S
474.768 0 M(60)S
GR
SP
%%Page: 61 66
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 687.568 M(/* Necessary because we use the proc fs */)S
1.432 676.768 M(#include )S
1.432 655.168 M(/* We scheduale tasks here */)S
1.432 644.368 M(#include )S
1.432 622.768 M(/* We also need the ability to put ourselves to sleep and wake up later */)S
1.432 611.968 M(#include )S
1.432 590.368 M(/* In 2.2.3 /usr/include/linux/version.h includes a macro for this, but)S
1.432 579.568 M( * 2.0.35 doesn't - so I add it here if necessary.)S
1.432 568.768 M( */)S
1.432 557.968 M(#ifndef KERNEL_VERSION)S
1.432 547.168 M(#define KERNEL_VERSION\(a,b,c\) \(\(a\)*65536+\(b\)*256+\(c\)\))S
1.432 536.368 M(#endif)S
1.432 514.768 M(/* The number of times the timer interrupt has been called so far */)S
1.432 503.968 M(static int TimerIntrpt = 0;)S
1.432 482.368 M(/* This is used by cleanup, to prevent the module from being unloaded while)S
1.432 471.568 M( * intrpt_routine is still in the task queue)S
1.432 460.768 M( */)S
1.432 449.968 M(static struct wait_queue *WaitQ = NULL;)S
1.432 428.368 M(static void intrpt_routine\(void *\);)S
1.432 406.768 M(/* The task queue structure for this task, from tqueue.h */)S
1.432 395.968 M(static struct tq_struct Task = {)S
1.432 385.168 M( NULL, /* Next item in list - queue_task will do this for us */)S
1.432 374.368 M( 0, /* A flag meaning we haven't been inserted into a task)S
1.432 363.568 M( * queue yet )S
1.432 352.768 M( */)S
1.432 341.968 M( intrpt_routine, /* The function to run */)S
1.432 331.168 M( NULL /* The void* parameter for that function */)S
1.432 320.368 M(};)S
1.432 298.768 M(/* This function will be called on every timer interrupt. Notice the void*)S
1.432 287.968 M( * pointer - task functions can be used for more than one purpose, each time )S
1.432 277.168 M( * getting a different parameter.)S
1.432 266.368 M( */)S
1.432 255.568 M(static void intrpt_routine\(void *irrelevant\))S
1.432 244.768 M({)S
1.432 233.968 M( /* Increment the counter */)S
1.432 223.168 M( TimerIntrpt++;)S
1.432 201.568 M( /* If cleanup wants us to die */)S
1.432 190.768 M( if \(WaitQ != NULL\) )S
1.432 179.968 M( wake_up\(&WaitQ\); /* Now cleanup_module can return */)S
1.432 169.168 M( else)S
1.432 158.368 M( /* Put ourselves back in the task queue */)S
1.432 147.568 M( queue_task\(&Task, &tq_timer\); )S
1.432 136.768 M(})S
1.432 115.168 M(/* Put data into the proc fs file. */)S
1.432 104.368 M(int procfile_read\(char *buffer, )S
1.432 93.568 M( char **buffer_location, off_t offset, )S
1.432 82.768 M( int buffer_length, int zero\))S
1.432 71.968 M({)S
1.432 61.168 M( int len; /* The number of bytes actually used */)S
1.432 39.568 M( /* It's static so it will still be in memory when we leave this function)S
1.432 28.768 M( */)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 11. Scheduling Tasks)S
474.768 0 M(61)S
GR
SP
%%Page: 62 67
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 687.568 M( static char my_buffer[80]; )S
1.432 665.968 M( static int count = 1;)S
1.432 644.368 M( /* We give all of our information in one go, so if the anybody asks us)S
1.432 633.568 M( * if we have more information the answer should always be no. )S
1.432 622.768 M( */)S
1.432 611.968 M( if \(offset > 0\))S
1.432 601.168 M( return 0;)S
1.432 579.568 M( /* Fill the buffer and get its length */)S
1.432 568.768 M( len = sprintf\(my_buffer, "Timer called %d times so far\\n", TimerIntrpt\);)S
1.432 557.968 M( count++;)S
1.432 536.368 M( /* Tell the function which called us where the buffer is */)S
1.432 525.568 M( *buffer_location = my_buffer;)S
1.432 503.968 M( /* Return the length */)S
1.432 493.168 M( return len;)S
1.432 482.368 M(})S
1.432 460.768 M(struct proc_dir_entry Our_Proc_File = {)S
1.432 449.968 M( 0, /* Inode number - ignore, it'll be filled by proc_register_dynamic */)S
1.432 439.168 M( 5, /* Length of the file name */)S
1.432 428.368 M( "sched", /* The file name */)S
1.432 417.568 M( S_IFREG | S_IRUGO, /* File mode - this is a regular file which can be)S
1.432 406.768 M( * read by its owner, its group, and everybody else)S
1.432 395.968 M( */)S
1.432 385.168 M( 1, /* Number of links \(directories where the file is referenced\) */)S
1.432 374.368 M( 0, 0, /* The uid and gid for the file - we give it to root */)S
1.432 363.568 M( 80, /* The size of the file reported by ls. */)S
1.432 352.768 M( NULL, /* functions which can be done on the inode \(linking, removing,)S
1.432 341.968 M( * etc\). - we don't * support any.)S
1.432 331.168 M( */)S
1.432 320.368 M( procfile_read, /* The read function for this file, the function called)S
1.432 309.568 M( * when somebody tries to read something from it.)S
1.432 298.768 M( */)S
1.432 287.968 M( NULL /* We could have here a function to fill the file's inode, to)S
1.432 277.168 M( * enable us to play with permissions, ownership, etc.)S
1.432 266.368 M( */)S
1.432 255.568 M( }; )S
1.432 233.968 M(/* Initialize the module - register the proc file */)S
1.432 223.168 M(int init_module\(\))S
1.432 212.368 M({)S
1.432 201.568 M( /* Put the task in the tq_timer task queue, so it will be executed at)S
1.432 190.768 M( * next timer interrupt)S
1.432 179.968 M( */)S
1.432 169.168 M( queue_task\(&Task, &tq_timer\);)S
1.432 147.568 M( /* Success if proc_register_dynamic is a success, failure otherwise */)S
1.432 136.768 M(#if LINUX_VERSION_CODE > KERNEL_VERSION\(2,2,0\))S
1.432 125.968 M( return proc_register\(&proc_root, &Our_Proc_File\);)S
1.432 115.168 M(#else)S
1.432 104.368 M( return proc_register_dynamic\(&proc_root, &Our_Proc_File\);)S
1.432 93.568 M(#endif)S
1.432 82.768 M(})S
1.432 61.168 M(/* Cleanup */)S
1.432 50.368 M(void cleanup_module\(\))S
1.432 39.568 M({)S
1.432 28.768 M( /* Unregister our /proc file */)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 11. Scheduling Tasks)S
474.768 0 M(62)S
GR
SP
%%Page: 63 68
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 565.535 M 487.0 132.5 F
0.00 0.00 0.00 C 0 556.935 M 487.0 2.0 F
9 FS/F0 SF 1.432 687.568 M( proc_unregister\(&proc_root, Our_Proc_File.low_ino\);)S
1.432 665.968 M( /* Sleep until intrpt_routine is called one last time. This is necessary,)S
1.432 655.168 M( * because otherwise we'll deallocate the memory holding intrpt_routine)S
1.432 644.368 M( * and Task while tq_timer still references them. Notice that here we)S
1.432 633.568 M( * don't allow signals to interrupt us. )S
1.432 622.768 M( *)S
1.432 611.968 M( * Since WaitQ is now not NULL, this automatically tells the interrupt)S
1.432 601.168 M( * routine it's time to die.)S
1.432 590.368 M( */)S
1.432 579.568 M( sleep_on\(&WaitQ\);)S
1.432 568.768 M(} )S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(Chapter 11. Scheduling Tasks)S
474.768 0 M(63)S
GR
SP
%%Page: 64 69
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0 635.4 M 487.0 2.0 F
0 65.8 M 487.0 2.0 F
20 FS/F9 SF 0 678 M(Chapter 12. Interrupt Handlers)S
14 FS/F9 SF 0 646.8 M(12.1. Interrupt Handlers)S
11 FS/F9 SF 0 617.8 M(12.1.1. Interrupt Handlers)S
/F4 SF 0 591.4 M(Except for the last chapter, everything we did in the kernel so far we've done as a response to a process asking)S
0 578.2 M(for it, either by dealing with a special file, sending an )S
/F0 SF (ioctl\(\))S
/F4 SF (, or issuing a system call. But the job of the)S
0 565 M(kernel isn't just to respond to process requests. Another job, which is every bit as important, is to speak to the)S
0 551.8 M(hardware connected to the machine.)S
0 525.4 M(There are two types of interaction between the CPU and the rest of the computer's hardware. The first type is)S
0 512.2 M(when the CPU gives orders to the hardware, the other is when the hardware needs to tell the CPU something.)S
0 499 M(The second, called interrupts, is much harder to implement because it has to be dealt with when convenient for)S
0 485.8 M(the hardware, not the CPU. Hardware devices typically have a very small amount of RAM, and if you don't)S
0 472.6 M(read their information when available, it is lost.)S
0 446.2 M(Under Linux, hardware interrupts are called IRQ's \()S
/F6 SF (I)S
/F4 SF (nterrupt)S
/F6 SF ( R)S
/F4 SF (e)S
/F6 SF (q)S
/F4 SF (uests\))S
([16]. There are two types of IRQ's,)S
0 433 M(short and long. A short IRQ is one which is expected to take a)S
/F6 SF ( very)S
/F4 SF ( short period of time, during which the rest)S
0 419.8 M(of the machine will be blocked and no other interrupts will be handled. A long IRQ is one which can take)S
0 406.6 M(longer, and during which other interrupts may occur \(but not interrupts from the same device\). If at all)S
0 393.4 M(possible, it's better to declare an interrupt handler to be long.)S
0 367 M(When the CPU receives an interrupt, it stops whatever it's doing \(unless it's processing a more important)S
0 353.8 M(interrupt, in which case it will deal with this one only when the more important one is done\), saves certain)S
0 340.6 M(parameters on the stack and calls the interrupt handler. This means that certain things are not allowed in the)S
0 327.4 M(interrupt handler itself, because the system is in an unknown state. The solution to this problem is for the)S
0 314.2 M(interrupt handler to do what needs to be done immediately, usually read something from the hardware or send)S
0 301 M(something to the hardware, and then schedule the handling of the new information at a later time \(this is called)S
0 287.8 M(the "bottom half"\) and return. The kernel is then guaranteed to call the bottom half as soon as possible -- and)S
0 274.6 M(when it does, everything allowed in kernel modules will be allowed.)S
0 248.2 M(The way to implement this is to call )S
/F0 SF (request_irq\(\))S
/F4 SF ( to get your interrupt handler called when the relevant)S
0 235 M(IRQ is received \(there are 15 of them, plus 1 which is used to cascade the interrupt controllers, on Intel)S
0 221.8 M(platforms\). This function receives the IRQ number, the name of the function, flags, a name for)S
/F0 SF 0 208.6 M(/proc/interrupts)S
/F4 SF ( and a parameter to pass to the interrupt handler. The flags can include)S
/Fa SF ( SA_SHIRQ)S
/F4 SF ( to)S
0 195.4 M(indicate you're willing to share the IRQ with other interrupt handlers \(usually because a number of hardware)S
0 182.2 M(devices sit on the same IRQ\) and)S
/Fa SF ( SA_INTERRUPT)S
/F4 SF ( to indicate this is a fast interrupt. This function will only)S
0 169 M(succeed if there isn't already a handler on this IRQ, or if you're both willing to share.)S
0 142.6 M(Then, from within the interrupt handler, we communicate with the hardware and then use)S
/F0 SF 0 129.4 M(queue_task_irq\(\))S
/F4 SF ( with )S
/F0 SF (tq_immediate\(\))S
/F4 SF ( and )S
/F0 SF (mark_bh\(BH_IMMEDIATE\))S
/F4 SF ( to schedule the bottom)S
0 116.2 M(half. The reason we can't use the standard )S
/F0 SF (queue_task)S
/F4 SF ( in version 2.0 is that the interrupt might happen)S
0 103 M(right in the middle of somebody else's )S
/F0 SF (queue_task)S
/F4 SF ([17]. We need )S
/F0 SF (mark_bh)S
/F4 SF ( because earlier versions of)S
0 89.8 M(Linux only had an array of 32 bottom halves, and now one of them \()S
/Fa SF (BH_IMMEDIATE)S
/F4 SF (\) is used for the linked)S
0 76.6 M(list of bottom halves for drivers which didn't get a bottom half entry assigned to them.)S
/F8 SF 0 0 M(Chapter 12. Interrupt Handlers)S
474.768 0 M(64)S
GR
SP
%%Page: 65 70
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 385.6 F
0.00 0.00 0.00 C 11 FS/F9 SF 0 687 M(12.1.2. Keyboards on the Intel Architecture)S
/F4 SF 0 660.6 M(The rest of this chapter is completely Intel specific. If you're not running on an Intel platform, it will not work.)S
0 647.4 M(Don't even try to compile the code here.)S
0 621 M(I had a problem with writing the sample code for this chapter. On one hand, for an example to be useful it has)S
0 607.8 M(to run on everybody's computer with meaningful results. On the other hand, the kernel already includes device)S
0 594.6 M(drivers for all of the common devices, and those device drivers won't coexist with what I'm going to write.)S
0 581.4 M(The solution I've found was to write something for the keyboard interrupt, and disable the regular keyboard)S
0 568.2 M(interrupt handler first. Since it is defined as a static symbol in the kernel source files \(specifically,)S
/F0 SF 0 555 M(drivers/char/keyboard.c)S
/F4 SF (\), there is no way to restore it. Before )S
/F1 SF (insmod)S
/F4 SF ('ing this code, do on another)S
0 541.8 M(terminal )S
/F1 SF (sleep 120 ; reboot)S
/F4 SF ( if you value your file system.)S
0 515.4 M(This code binds itself to IRQ 1, which is the IRQ of the keyboard controlled under Intel architectures. Then,)S
0 502.2 M(when it receives a keyboard interrupt, it reads the keyboard's status \(that's the purpose of the )S
/F1 SF (inb\(0x64\))S
/F4 SF (\))S
0 489 M(and the scan code, which is the value returned by the keyboard. Then, as soon as the kernel thinks it's feasible,)S
0 475.8 M(it runs )S
/F0 SF (got_char)S
/F4 SF ( which gives the code of the key used \(the first seven bits of the scan code\) and whether it)S
0 462.6 M(has been pressed \(if the 8th bit is zero\) or released \(if it's one\).)S
/F5 SF 0 423 M(Example 12-1. intrpt.c)S
9 FS/F0 SF 1.432 397.167 M(/* intrpt.c - An interrupt handler.)S
1.432 386.367 M( *)S
1.432 375.567 M( * Copyright \(C\) 2001 by Peter Jay Salzman)S
1.432 364.767 M( */)S
1.432 343.167 M(/* The necessary header files */)S
1.432 321.567 M(/* Standard in kernel modules */)S
1.432 310.767 M(#include /* We're doing kernel work */)S
1.432 299.967 M(#include /* Specifically, a module */)S
1.432 278.368 M(/* Deal with CONFIG_MODVERSIONS */)S
1.432 267.568 M(#if CONFIG_MODVERSIONS==1)S
1.432 256.768 M(#define MODVERSIONS)S
1.432 245.968 M(#include )S
1.432 235.168 M(#endif )S
1.432 213.568 M(#include )S
1.432 202.768 M(#include )S
1.432 181.168 M(/* We want an interrupt */)S
1.432 170.368 M(#include )S
1.432 148.768 M(#include )S
1.432 127.168 M(/* In 2.2.3 /usr/include/linux/version.h includes a macro for this, but)S
1.432 116.368 M( * 2.0.35 doesn't - so I add it here if necessary.)S
1.432 105.568 M( */)S
1.432 94.768 M(#ifndef KERNEL_VERSION)S
1.432 83.967 M(#define KERNEL_VERSION\(a,b,c\) \(\(a\)*65536+\(b\)*256+\(c\)\))S
1.432 73.167 M(#endif)S
1.432 51.567 M(/* Bottom Half - this will get called by the kernel as soon as it's safe)S
1.432 40.767 M( * to do everything normally allowed by kernel modules.)S
1.432 29.967 M( */)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(12.1. Interrupt Handlers)S
474.768 0 M(65)S
GR
SP
%%Page: 66 71
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 22 M 487.0 676.0 F
0.00 0.00 0.00 C 9 FS/F0 SF 1.432 687.568 M(static void got_char\(void *scancode\))S
1.432 676.768 M({)S
1.432 665.968 M( printk\("Scan Code %x %s.\\n",)S
1.432 655.168 M( \(int\) *\(\(char *\) scancode\) & 0x7F,)S
1.432 644.368 M( *\(\(char *\) scancode\) & 0x80 ? "Released" : "Pressed"\);)S
1.432 633.568 M(})S
1.432 611.968 M(/* This function services keyboard interrupts. It reads the relevant)S
1.432 601.168 M( * information from the keyboard and then scheduales the bottom half)S
1.432 590.368 M( * to run when the kernel considers it safe.)S
1.432 579.568 M( */)S
1.432 568.768 M(void irq_handler\(int irq, void *dev_id, struct pt_regs *regs\))S
1.432 557.968 M({)S
1.432 547.168 M( /* This variables are static because they need to be )S
1.432 536.368 M( * accessible \(through pointers\) to the bottom half routine.)S
1.432 525.568 M( */)S
1.432 514.768 M( static unsigned char scancode;)S
1.432 503.968 M( static struct tq_struct task = {NULL, 0, got_char, &scancode};)S
1.432 493.168 M( unsigned char status;)S
1.432 471.568 M( /* Read keyboard status */)S
1.432 460.768 M( status = inb\(0x64\);)S
1.432 449.968 M( scancode = inb\(0x60\);)S
1.432 428.368 M( /* Scheduale bottom half to run */)S
1.432 417.568 M(#if LINUX_VERSION_CODE > KERNEL_VERSION\(2,2,0\))S
1.432 406.768 M( queue_task\(&task, &tq_immediate\);)S
1.432 395.968 M(#else)S
1.432 385.168 M( queue_task_irq\(&task, &tq_immediate\);)S
1.432 374.368 M(#endif)S
1.432 363.568 M( mark_bh\(IMMEDIATE_BH\);)S
1.432 352.768 M(})S
1.432 331.168 M(/* Initialize the module - register the IRQ handler */)S
1.432 320.368 M(int init_module\(\))S
1.432 309.568 M({)S
1.432 298.768 M( /* Since the keyboard handler won't co-exist with another handler,)S
1.432 287.968 M( * such as us, we have to disable it \(free its IRQ\) before we do)S
1.432 277.168 M( * anything. Since we don't know where it is, there's no way to)S
1.432 266.368 M( * reinstate it later - so the computer will have to be rebooted)S
1.432 255.568 M( * when we're done.)S
1.432 244.768 M( */)S
1.432 233.968 M( free_irq\(1, NULL\);)S
1.432 212.368 M( /* Request IRQ 1, the keyboard IRQ, to go to our irq_handler.)S
1.432 201.568 M( * SA_SHIRQ means we're willing to have othe handlers on this IRQ.)S
1.432 190.768 M( * SA_INTERRUPT can be used to make the handler into a fast interrupt. )S
1.432 179.968 M( */)S
1.432 169.168 M( return request_irq\(1, /* The number of the keyboard IRQ on PCs */ )S
1.432 158.368 M( irq_handler, /* our handler */)S
1.432 147.568 M( SA_SHIRQ, )S
1.432 136.768 M( "test_keyboard_irq_handler", NULL\);)S
1.432 125.968 M(})S
1.432 104.368 M(/* Cleanup */)S
1.432 93.568 M(void cleanup_module\(\))S
1.432 82.768 M({)S
1.432 71.968 M( /* This is only here for completeness. It's totally irrelevant, since)S
1.432 61.168 M( * we don't have a way to restore the normal keyboard interrupt so the)S
1.432 50.368 M( * computer is completely useless and has to be rebooted.)S
1.432 39.568 M( */)S
1.432 28.768 M( free_irq\(1, NULL\);)S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(12.1. Interrupt Handlers)S
474.768 0 M(66)S
GR
SP
%%Page: 67 72
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0.88 0.88 0.88 C 0 684.335 M 487.0 13.7 F
0.00 0.00 0.00 C 0 675.735 M 487.0 2.0 F
9 FS/F0 SF 1.432 687.568 M(} )S
11 FS/F8 SF 131.624 709 M(The Linux Kernel Module Programming Guide)S
0 0 M(12.1. Interrupt Handlers)S
474.768 0 M(67)S
GR
SP
%%Page: 68 73
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0 318.6 M 487.0 2.0 F
20 FS/F9 SF 0 678 M(Chapter 13. Symmetric Multi Processing)S
14 FS/F9 SF 0 646.8 M(13.1. Symmetrical Multi-Processing)S
11 FS/F4 SF 0 619.8 M(One of the easiest and cheapest ways to improve hardware performance is to put more than one CPU on the)S
0 606.6 M(board. This can be done either making the different CPU's take on different jobs \(asymmetrical)S
0 593.4 M(multi-processing\) or by making them all run in parallel, doing the same job \(symmetrical multi-processing,)S
0 580.2 M(a.k.a. SMP\). Doing asymmetrical multi-processing effectively requires specialized knowledge about the tasks)S
0 567 M(the computer should do, which is unavailable in a general purpose operating system such as Linux. On the)S
0 553.8 M(other hand, symmetrical multi-processing is relatively easy to implement.)S
0 527.4 M(By relatively easy, I mean exactly that: not that it's)S
/F6 SF ( really)S
/F4 SF ( easy. In a symmetrical multi-processing)S
0 514.2 M(environment, the CPU's share the same memory, and as a result code running in one CPU can affect the)S
0 501 M(memory used by another. You can no longer be certain that a variable you've set to a certain value in the)S
0 487.8 M(previous line still has that value; the other CPU might have played with it while you weren't looking.)S
0 474.6 M(Obviously, it's impossible to program like this.)S
0 448.2 M(In the case of process programming this normally isn't an issue, because a process will normally only run on)S
0 435 M(one CPU at a time)S
([18]. The kernel, on the other hand, could be called by different processes running on)S
0 421.8 M(different CPU's.)S
0 395.4 M(In version 2.0.x, this isn't a problem because the entire kernel is in one big spinlock. This means that if one)S
0 382.2 M(CPU is in the kernel and another CPU wants to get in, for example because of a system call, it has to wait)S
0 369 M(until the first CPU is done. This makes Linux SMP safe)S
([19], but inefficient.)S
0 342.6 M(In version 2.2.x, several CPU's can be in the kernel at the same time. This is something module writers need)S
0 329.4 M(to be aware of.)S
/F8 SF 0 0 M(Chapter 13. Symmetric Multi Processing)S
474.768 0 M(68)S
GR
SP
%%Page: 69 74
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0 463.8 M 487.0 2.0 F
20 FS/F9 SF 0 678 M(Chapter 14. Common Pitfalls)S
14 FS/F9 SF 0 646.8 M(14.1. Common Pitfalls)S
11 FS/F4 SF 0 619.8 M(Before I send you on your way to go out into the world and write kernel modules, there are a few things I need)S
0 606.6 M(to warn you about. If I fail to warn you and something bad happens, please report the problem to me for a full)S
0 593.4 M(refund of the amount I was paid for your copy of the book.)S
/F6 SF 0 567 M(Using standard libraries)S
/F4 SF 36 553.8 M(You can't do that. In a kernel module you can only use kernel functions, which are the functions you)S
36 540.6 M(can see in )S
/F0 SF (/proc/ksyms)S
/F4 SF (.)S
/F6 SF 0 527.4 M(Disabling interrupts)S
/F4 SF 36 514.2 M(You might need to do this for a short time and that is OK, but if you don't enable them afterwards,)S
36 501 M(your system will be stuck and you'll have to power it off.)S
/F6 SF 0 487.8 M(Sticking your head inside a large carnivore)S
/F4 SF 36 474.6 M(I probably don't have to warn you about this, but I figured I will anyway, just in case.)S
/F8 SF 0 0 M(Chapter 14. Common Pitfalls)S
474.768 0 M(69)S
GR
SP
%%Page: 70 75
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0 635.4 M 487.0 2.0 F
0 105.4 M 487.0 2.0 F
20 FS/F9 SF 0 678 M(Appendix A. Changes: 2.0 To 2.2)S
14 FS/F9 SF 0 646.8 M(A.1. Changes between 2.0 and 2.2)S
11 FS/F9 SF 0 617.8 M(A.1.1. Changes between 2.0 and 2.2)S
/F4 SF 0 591.4 M(I don't know the entire kernel well enough do document all of the changes. In the course of converting the)S
0 578.2 M(examples \(or actually, adapting Emmanuel Papirakis's changes\) I came across the following differences. I)S
0 565 M(listed all of them here together to help module programmers, especially those who learned from previous)S
0 551.8 M(versions of this book and are most familiar with the techniques I use, convert to the new version.)S
0 525.4 M(An additional resource for people who wish to convert to 2.2 is located on Richard Gooch's site .)S
/F2 SF 0 499 M(asm/uaccess.h)S
/F4 SF 36 485.8 M(If you need )S
/F0 SF (put_user)S
/F4 SF ( or )S
/F0 SF (get_user)S
/F4 SF ( you have to )S
/F1 SF (#include)S
/F4 SF ( it.)S
/F2 SF 0 472.6 M(get_user)S
/F4 SF 36 459.4 M(In version 2.2, )S
/F0 SF (get_user)S
/F4 SF ( receives both the pointer into user memory and the variable in kernel)S
36 446.2 M(memory to fill with the information. The reason for this is that )S
/F0 SF (get_user)S
/F4 SF ( can now read two or four)S
36 433 M(bytes at a time if the variable we read is two or four bytes long.)S
/F2 SF 0 419.8 M(file_operations)S
/F4 SF 36 406.6 M(This structure now has a flush function between the )S
/F0 SF (open)S
/F4 SF ( and )S
/F0 SF (close)S
/F4 SF ( functions.)S
/F2 SF 0 393.4 M(close)S
/F6 SF ( in )S
/F2 SF (file_operations)S
/F4 SF 36 380.2 M(In version 2.2, the )S
/F0 SF (close)S
/F4 SF ( function returns an integer, so it's allowed to fail.)S
/F2 SF 0 367 M(read)S
/F6 SF (,)S
/F2 SF (write)S
/F6 SF ( in )S
/F2 SF (file_operations)S
/F4 SF 36 353.8 M(The headers for these functions changed. They now return )S
/F1 SF (ssize_t)S
/F4 SF ( instead of an integer, and their)S
36 340.6 M(parameter list is different. The inode is no longer a parameter, and on the other hand the offset into the)S
36 327.4 M(file is.)S
/F2 SF 0 314.2 M(proc_register_dynamic)S
/F4 SF 36 301 M(This function no longer exists. Instead, you call the regular )S
/F0 SF (proc_register)S
/F4 SF ( and put zero in the)S
36 287.8 M(inode field of the structure.)S
/F6 SF 0 274.6 M(Signals)S
/F4 SF 36 261.4 M(The signals in the task structure are no longer a 32 bit integer, but an array of)S
/Fa SF ( _NSIG_WORDS)S
/F4 SF 36 248.2 M(integers.)S
/F2 SF 0 235 M(queue_task_irq)S
/F4 SF 36 221.8 M(Even if you want to scheduale a task to happen from inside an interrupt handler, you use)S
/F0 SF 36 208.6 M(queue_task)S
/F4 SF (, not )S
/F0 SF (queue_task_irq)S
/F4 SF (.)S
/F6 SF 0 195.4 M(Module Parameters)S
/F4 SF 36 182.2 M(You no longer just declare module parameters as global variables. In 2.2 you have to also use)S
/Fa SF 36 169 M(MODULE_PARM)S
/F4 SF ( to declare their type. This is a big improvement, because it allows the module to)S
36 155.8 M(receive string parameters which start with a digits, for example, without getting confused.)S
/F6 SF 0 142.6 M(Symmetrical Multi-Processing)S
/F4 SF 36 129.4 M(The kernel is no longer inside one huge spinlock, which means that kernel modules have to be aware)S
36 116.2 M(of SMP.)S
/F8 SF 0 0 M(Appendix A. Changes: 2.0 To 2.2)S
474.768 0 M(70)S
GR
SP
%%Page: 71 76
%%PageBoundingBox: 72 36 559 756
GS
72 36 T
0 397.8 M 487.0 2.0 F
20 FS/F9 SF 0 678 M(Appendix B. Where To Go From Here)S
14 FS/F9 SF 0 646.8 M(B.1. Where From Here?)S
11 FS/F4 SF 0 619.8 M(I could easily have squeezed a few more chapters into this book. I could have added a chapter about creating)S
0 606.6 M(new file systems, or about adding new protocol stacks \(as if there's a need for that -- you'd have to dig)S
0 593.4 M(underground to find a protocol stack not supported by Linux\). I could have added explanations of the kernel)S
0 580.2 M(mechanisms we haven't touched upon, such as bootstrapping or the disk interface.)S
0 553.8 M(However, I chose not to. My purpose in writing this book was to provide initiation into the mysteries of kernel)S
0 540.6 M(module programming and to teach the common techniques for that purpose. For people seriously interested in)S
0 527.4 M(kernel programming, I recommend Juan-Mariano de Goyeneche's list of kernel resources . Also, as Linus)S
0 514.2 M(said, the best way to learn the kernel is to read the source code yourself.)S
0 487.8 M(If you're interested in more examples of short kernel modules, I recommend Phrack magazine. Even if you're)S
0 474.6 M(not interested in security, and as a programmer you should be, the kernel modules there are good examples of)S
0 461.4 M(what you can do inside the kernel, and they're short enough not to require too much effort to understand.)S
0 435 M(I hope I have helped you in your quest to become a better programmer, or at least to have fun through)S
0 421.8 M(technology. And, if you do write useful kernel modules, I hope you publish them under the GPL, so I can use)S
0 408.6 M(them too.)S
/F8 SF 0 0 M(Appendix B. Where To Go From Here)S
474.768 0 M(71)S
GR
SP
%%Trailer
%%EOF