forked from cellularmitosis/ADC-reference-library-2009-july
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathlisting5.html
executable file
·481 lines (378 loc) · 15 KB
/
listing5.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html>
<head>
<!-- BEGIN META TAG INFO -->
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<link rel="home" href="http://developer.apple.com/">
<link rel="find" href="http://developer.apple.com/search/">
<link rel="stylesheet" type="text/css" href="../../documentation/css/adcstyle.css" title="fonts">
<script language="JavaScript" src="../../documentation/js/adc.js" type="text/javascript"></script>
<!-- END META TAG INFO -->
<!-- BEGIN TITLE -->
<title>IOKitWithLibrary - /Read Me.txt</title>
<!-- END TITLE -->
<script language="JavaScript">
function JumpToNewPage() {
window.location=document.scpopupmenu.gotop.value;
return true;
}
</script>
</head>
<!-- BEGIN BODY OPEN -->
<body>
<!--END BODY OPEN -->
<!-- START CENTER OPEN -->
<center>
<!-- END CENTER OPEN -->
<!-- BEGIN LOGO AND SEARCH -->
<!--#include virtual="/includes/adcnavbar"-->
<!-- END LOGO AND SEARCH -->
<!-- START BREADCRUMB -->
<div id="breadcrumb">
<table width="680" border="0" cellpadding="0" cellspacing="0">
<tr>
<td scope="row"><img width="340" height="10" src="images/1dot.gif" alt=""></td>
<td><img width="340" height="10" src="images/1dot.gif" alt=""></td>
</tr>
<tr valign="middle">
<td align="left" colspan="2">
<a href="http://developer.apple.com/">ADC Home</a> > <a href="../../referencelibrary/index.html">Reference Library</a> > <a href="../../samplecode/index.html">Sample Code</a> > <a href="../../samplecode/Darwin/index.html">Darwin</a> > <a href="../../samplecode/Darwin/idxHardwareDrivers-date.html">Hardware & Drivers</a> > <A HREF="javascript:location.replace('index.html');">IOKitWithLibrary</A> >
</td>
</tr>
<tr>
<td colspan="2" scope="row"><img width="680" height="35" src="images/1dot.gif" alt=""></td>
</tr>
</table>
</div>
<!-- END BREADCRUMB -->
<!-- START MAIN CONTENT -->
<!-- START TITLE GRAPHIC AND INTRO-->
<table width="680" border="0" cellpadding="0" cellspacing="0">
<tr align="left" valign="top">
<td><h1><div id="pagehead">IOKitWithLibrary</div></h1></td>
</tr>
</table>
<!-- END TITLE GRAPHIC AND INTRO -->
<!-- START WIDE COLUMN -->
<table width="680" border="0" cellpadding="0" cellspacing="0">
<tr align="left" valign="top">
<td id="scdetails">
<h2>/Read Me.txt</h2>
<form name="scpopupmenu" onSubmit="return false;" method=post>
<p><strong>View Source Code:</strong>
<select name="gotop" onChange="JumpToNewPage();" style="width:340px"><option selected value="ingnore">Select File</option>
<option value="listing1.html">/IOKitPart.cpp</option>
<option value="listing2.html">/IOKitPart.h</option>
<option value="listing3.html">/LibraryPart.c</option>
<option value="listing4.html">/LibraryPart.h</option>
<option value="listing5.html">/Read Me.txt</option></select>
</p>
</form>
<p><strong><a href="IOKitWithLibrary.zip">Download Sample</a></strong> (“IOKitWithLibrary.zip”, 61.2K)<BR>
<strong><a href="IOKitWithLibrary.dmg">Download Sample</a></strong> (“IOKitWithLibrary.dmg”, 121.2K)</p>
<!--
<p><strong><a href="#">Download Sample</a></strong> (“filename.sit”, 500K)</p>
-->
</td>
</tr>
<tr>
<td scope="row"><img width="680" height="10" src="images/1dot.gif" alt=""><br>
<img height="1" width="680" src="images/1dot_919699.gif" alt=""><br>
<img width="680" height="20" src="images/1dot.gif" alt=""></td>
</tr>
<tr>
<td scope="row">
<!--googleon: index -->
<pre class="sourcecodebox">Read Me About IOKitWithLibrary1.0IOKitWithLibrary is a trivial I/O Kit
sample that shows how an I/O Kit driver can link with a C library that resides
in a separate kernel extension. Some developers find this technique useful
because it allows them to share some core functionality between many different
I/O Kit drivers.The sample should work on all versions of Mac OS X, but has
only been tested on Mac OS X 10.2.x.Packing ListThe sample contains the
following items:* Read Me About IOKitWithLibrary \xD1 This document.*
IOKitWithLibrary.pbproj \xD1 A Project Builder project for the sample.* build \xD1 A
folder containing pre-built versions of the I/O Kit driver and, embedded within
it, the library KEXT.* English.lproj \xD1 Localised resources.* IOKitPart.h \xD1
Interface to the I/O Kit driver.* IOKitPart.cpp \xD1 Implementation of the I/O
Kit driver.* LibraryPart.h \xD1 Interface to the library KEXT.* LibraryPart.c \xD1
Implementation of the library KEXT.Using the SampleTo use the sample, you
have to first install the I/O Kit driver. To start, change into the directory
containing the sample\xC9[guy-smiley:~] quinn% cd PathToSample\xC9 then change
into the build directory.[guy-smiley:IOKitWithLibrary] quinn% cd buildYou
can now copy the I/O Kit driver into the Extensions folder.[guy-smiley:build]
quinn% sudo cp -r IOKitWithLibrary.kext /System/Library/ExtensionsPassword:
********At this point, it's possible to load the I/O Kit driver and have the
system automatically load the library it depends on. The -t flag causes
kextload to validate the KEXT before it loads it.[guy-smiley:build] quinn%
sudo kextload -t /System/Library/Extensions/IOKitWithLibrary.kextkextload:
extension /System/Library/Extensions/IOKitWithLibrary.kext appears to be
validkextload: notice: extension
/System/Library/Extensions/IOKitWithLibrary.kext has debug properties
setkextload: /System/Library/Extensions/IOKitWithLibrary.kext loaded
successfullyIf you look at the end of the system log file, you'll see that
the I/O Kit driver is actually linked to the library and can call functions
within the library (for example, the log entry "LibraryFunction" is printed by
code in the library).[guy-smiley:build] quinn% tail /var/log/system.logAug
7 16:56:45 mr-hoots sshd[439]: Accepted password for quinn from 10.0.40.2 port
56692 ssh2Aug 7 16:57:09 mr-hoots sudo: quinn : TTY=ttyp1 ;
PWD=/Users/quinn ; USER=root ; COMMAND=/bin/cp -r IOKitPart.kext
/System/Library/ExtensionsAug 7 16:57:19 mr-hoots sudo: quinn : TTY=ttyp1
; PWD=/Users/quinn ; USER=root ; COMMAND=/bin/cp -r IOKitWithLibrary.kext
/System/Library/ExtensionsAug 7 16:57:44 mr-hoots sudo: quinn : TTY=ttyp1
; PWD=/Users/quinn ; USER=root ; COMMAND=/sbin/kextload -t
/System/Library/Extensions/IOKitWithLibrary.kextAug 7 16:57:48 mr-hoots
mach_kernel: Matching service count = 1Aug 7 16:57:48 mr-hoots mach_kernel:
Calling library functionAug 7 16:57:48 mr-hoots mach_kernel:
LibraryFunctionAug 7 16:57:48 mr-hoots mach_kernel: Returned from libraryAug
7 16:57:48 mr-hoots mach_kernel:
com_apple_dts_driver_IOKitWithLibrary::probe(IOResources)Aug 7 16:57:48
mr-hoots mach_kernel: com_apple_dts_driver_IOKitWithLibrary::start(IOResources)
<1>Finally, you can unload the I/O Kit driver and the library
KEXT\xC9[guy-smiley:build] quinn% sudo kextunload
/System/Library/Extensions/IOKitWithLibrary.kextunload kext
/System/Library/Extensions/IOKitWithLibrary.kext succeeded (any personalities
also unloaded)[guy-smiley:build] quinn% sudo kextunload -b
com.apple.dts.library.IOKitWithLibraryunload id
com.apple.dts.library.IOKitWithLibrary succeeded (any personalities also
unloaded)\xC9 and delete the I/O Kit driver from the Extensions
folder.[guy-smiley:build] quinn% sudo rm -r
/System/Library/Extensions/IOKitWithLibrary.kextBuilding the SampleThe
sample was built on Mac OS X version 10.2.6 using Project Builder 2.1 from the
Dec 2002 developer tools. To build the project, open the project, make sure
that the "IOKitWithLibrary" target is selected, and choose Build from the Build
menu.The project contains two targets, "IOKitLibrary" and "LibraryPart".
Building the first target also builds the second and runs a "copy" build phase
to copy the "LibraryPart.kext" KEXT into the "PlugIns" folder within
"IOKitWithLibrary.kext". The end result is that the library KEXT is embedded
within the driver KEXT. This guarantees that the driver and library will never
be separated, which has a number of advantages.* It guarantees that the
library will never be missing when the driver is loaded.* It guarantees that
the library and driver will always be in sync.* It makes the KEXT easier to
install and remove.This technique may not be approach for all projects, but
we encourage you to use it when it is.How it WorksThe kernel has a single
level namespace, so the process of linking between one KEXT and another is very
simple: just declare a function in a common header, defined the function in one
KEXT, and call it in another.On the other hand, setting up the KEXT packaging
so that one KEXT declares a dependency on another can be tricky. The following
is a list of items that I had to get right in order for IOKitLibrary to work
properly.Source CodeCheck that I/O Kit driver header and source have the
correct class name (com_apple_dts_driver_IOKitWithLibrary), and that it matches
the class name in the IOKitPersonalities entry within the plist.Check that
functions exported from the library aren't going to collide with other kernel
symbols. In this example I used the name
com_apple_dts_library_IOKitWithLibrary_LibraryFunction. Remember that the
kernel has a single-level namespace, so if you export a function and the kernel
or some other KEXT exports a function of the same name, bad things will happen.
The best way to avoid this problem is to use reverse DNS notation for your
function names, as shown in this example. For more information about this
issue, see the "Standard C Naming Conventions" section of "Inside Mac OS X:
Kernel
Programming".<http://developer.apple.com/documentation/Darwin/Conceptual/KernelProgramming/index.html>Check
that the library start and stop routines are uniquely named
(com_apple_dts_library_IOKitWithLibrary_start,
com_apple_dts_library_IOKitWithLibrary_stop).For C exports, make sure the
exports are bracketed with the following guards, otherwise C++ code won't be
able to access the symbols because the C++ compiler will mangle the
names.#ifdef __cplusplus extern "C" {#endif// your declarations
here#ifdef __cplusplus }#endifLibraryPart target, Settings, Expert
ViewCheck that KERNEL_MODULE is defined to YES.Check that MODULE_IOKIT is
not defined.Check that MODULE_NAME matches the name in CFBundleIdentifier in
the plist (com.apple.dts.library.IOKitWithLibrary).Check that MODULE_START
and MODULE_STOP match the names used in the source
(com_apple_dts_library_IOKitWithLibrary_start,
com_apple_dts_library_IOKitWithLibrary_stop).Check that MODULE_VERSION
matches CFBundleVersion in plist (1.0).Check that PRODUCT_NAME reflects the
name of the bundle in the file system and that it matches CFBundleExecutable in
the plist (LibraryPart).Check that WRAPPER_EXTENSION is kext.LibraryPart
target, Info.plist, Expert ViewCheck that CFBundleExecutable matches
PRODUCT_NAME in settings (LibraryPart).Check that CFBundleIdentifier matches
MODULE_NAME in settings (com.apple.dts.library.IOKitWithLibrary).Check that
CFBundlePackageType is KEXT.Check that CFBundleVersion matches MODULE_VERSION
in settings (1.0).Check that OSBundleCompatibleVersion is present and correct
(1.0).Check that OSBundleLibraries reflects correct dependencies.
com.apple.kernel.iokit = 1.1 com.apple.kernel.libkern = 1.1
com.apple.kernel.mach = 1.1IOKitWithLibrary target, Settings, Expert
ViewCheck that KERNEL_MODULE is defined to YES.Check that MODULE_IOKIT is
defined to YES.Check that MODULE_NAME matches the name in CFBundleIdentifier
in the plist (com.apple.dts.driver.IOKitWithLibrary).Check that MODULE_START
and MODULE_STOP are not defined.Check that MODULE_VERSION matches
CFBundleVersion in plist (1.0).Check that PRODUCT_NAME reflects name of the
bundle in the file system and that it matches CFBundleExecutable in plist
(IOKitWithLibrary).Check that WRAPPER_EXTENSION is kext.IOKitWithLibrary
target, Info.plist, Expert ViewCheck that CFBundleExecutable matches
PRODUCT_NAME in settings (IOKitWithLibrary).Check that CFBundleIdentifier
matches MODULE_NAME in settings (com.apple.dts.driver.IOKitWithLibrary).Check
that CFBundlePackageType is KEXT.Check that CFBundleVersion matches
MODULE_VERSION in settings (1.0).Check that IOKitPersonalities is set
correctly. There should be at least one entry, named by a suitably mnemonic
key. Check the following within that entry.* Check that CFBundleIdentifier
matches identifier in plist (com.apple.dts.driver.IOKitWithLibrary).*\xCACheck
that IOClass matches class name in source
(com_apple_dts_driver_IOKitWithLibrary).* If debugging, set IOKitDebug to the
number 65535.* Set IOProviderClass to class of your provider
(IOResources).*\xCASet other matching properties. IOMatchCategory =
IOKitWithLibrary IOResourceMatch = IOKitCheck that OSBundleLibraries
reflects correct dependencies. com.apple.dts.library.IOKitWithLibrary = 1.0
com.apple.kernel.iokit = 1.1 com.apple.kernel.libkern
= 1.1 com.apple.kernel.mach = 1.1Clean All Targets
and RebuildProject Builder does not correctly update all dependencies when
you change the above settings, so make sure that you clean all targets and
rebuild after you change them.Credits and Version HistoryIf you find any
problems with this sample, mail <[email protected]> and I'll try to fix them
up.1.0 (Aug 2003) was the first shipping version.Share and Enjoy.Apple
Developer Technical SupportNetworking, Communications, Hardware14 Aug 2003</pre>
<!--googleoff: index -->
</td>
</tr>
</table>
<!-- END WIDE COLUMN -->
<!-- END MAIN CONTENT -->
<table width="680" border="0" cellpadding="0" cellspacing="0">
<tr>
<td><div style="width: 100%; height: 1px; background-color: #919699; margin-top: 5px; margin-bottom: 15px"></div></td>
</tr>
<tr>
<td align="center"><br/>
<table border="0" cellpadding="0" cellspacing="0" class="graybox">
<tr>
<th>Did this document help you?</th>
</tr>
<tr>
<td>
<div style="margin-bottom: 8px"><a href="http://developer.apple.com/feedback/?v=1&url=/samplecode/IOKitWithLibrary/listing5.html%3Fid%3DDTS10000446-1.0&media=dvd" target=_new>Yes</a>: Tell us what works for you.</div>
<div style="margin-bottom: 8px"><a href="http://developer.apple.com/feedback/?v=2&url=/samplecode/IOKitWithLibrary/listing5.html%3Fid%3DDTS10000446-1.0&media=dvd" target=_new>It’s good, but:</a> Report typos, inaccuracies, and so forth.</div>
<div><a href="http://developer.apple.com/feedback/?v=3&url=/samplecode/IOKitWithLibrary/listing5.html%3Fid%3DDTS10000446-1.0&media=dvd" target=_new>It wasn’t helpful</a>: Tell us what would have helped.</div>
</td>
</tr>
</table>
</td>
</tr>
</table>
<!-- START BOTTOM APPLE NAVIGATION -->
<!--#include virtual="/includes/footer"-->
<!-- END BOTTOM APPLE NAVIGATION -->
<!-- START CENTER CLOSE -->
</center>
<!-- END CENTER CLOSE -->
</body>
</html>