Chameleon

Chameleon Svn Source Tree

Root/branches/mozodojo/i386/include/libkern/OSKextLib.h

1/*
2 * Copyright (c) 2008 Apple Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28
29#ifndef _LIBKERN_OSKEXTLIB_H
30#define _LIBKERN_OSKEXTLIB_H
31
32#include <sys/cdefs.h>
33__BEGIN_DECLS
34
35#include <stdint.h>
36#include <mach/kmod.h>
37#include <mach/vm_types.h>
38
39#include <CoreFoundation/CoreFoundation.h>
40#include <System/libkern/OSReturn.h>
41
42/*!
43 * @header
44 *
45 * Declares functions, basic return values, and other constants
46 * related to kernel extensions (kexts).
47 */
48
49#if PRAGMA_MARK
50#pragma mark -
51/********************************************************************/
52#pragma mark OSReturn Values for Kernel Extensions
53/********************************************************************/
54#endif
55/*!
56 * @group OSReturn Values for Kernel Extensions
57 * Many kext-related functions return these values,
58 * as well as those defined under
59 * <code>@link //apple_ref/c/tdef/OSReturn OSReturn@/link</code>
60 * and other variants of <code>kern_return_t</code>.
61 */
62
63
64#define sub_libkern_kext err_sub(2)
65#define libkern_kext_err(code) (sys_libkern|sub_libkern_kext|(code))
66
67
68/*!
69 * @define kOSKextReturnInternalError
70 * @abstract An internal error in the kext library.
71 * Contrast with <code>@link //apple_ref/c/econst/OSReturnError
72 * OSReturnError@/link</code>.
73 */
74#define kOSKextReturnInternalError libkern_kext_err(0x1)
75
76/*!
77 * @define kOSKextReturnNoMemory
78 * @abstract Memory allocation failed.
79 */
80#define kOSKextReturnNoMemory libkern_kext_err(0x2)
81
82/*!
83 * @define kOSKextReturnNoResources
84 * @abstract Some resource other than memory (such as available load tags)
85 * is exhausted.
86 */
87#define kOSKextReturnNoResources libkern_kext_err(0x3)
88
89/*!
90 * @define kOSKextReturnNotPrivileged
91 * @abstract The caller lacks privileges to perform the requested operation.
92 */
93#define kOSKextReturnNotPrivileged libkern_kext_err(0x4)
94
95/*!
96 * @define kOSKextReturnInvalidArgument
97 * @abstract Invalid argument.
98 */
99#define kOSKextReturnInvalidArgument libkern_kext_err(0x5)
100
101/*!
102 * @define kOSKextReturnNotFound
103 * @abstract Search item not found.
104 */
105#define kOSKextReturnNotFound libkern_kext_err(0x6)
106
107/*!
108 * @define kOSKextReturnBadData
109 * @abstract Malformed data (not used for XML).
110 */
111#define kOSKextReturnBadData libkern_kext_err(0x7)
112
113/*!
114 * @define kOSKextReturnSerialization
115 * @abstract Error converting or (un)serializing URL, string, or XML.
116 */
117#define kOSKextReturnSerialization libkern_kext_err(0x8)
118
119/*!
120 * @define kOSKextReturnUnsupported
121 * @abstract Operation is no longer or not yet supported.
122 */
123#define kOSKextReturnUnsupported libkern_kext_err(0x9)
124
125/*!
126 * @define kOSKextReturnDisabled
127 * @abstract Operation is currently disabled.
128 */
129#define kOSKextReturnDisabled libkern_kext_err(0xa)
130
131/*!
132 * @define kOSKextReturnNotAKext
133 * @abstract Bundle is not a kernel extension.
134 */
135#define kOSKextReturnNotAKext libkern_kext_err(0xb)
136
137/*!
138 * @define kOSKextReturnValidation
139 * @abstract Validation failures encountered; check diagnostics for details.
140 */
141#define kOSKextReturnValidation libkern_kext_err(0xc)
142
143/*!
144 * @define kOSKextReturnAuthentication
145 * @abstract Authetication failures encountered; check diagnostics for details.
146 */
147#define kOSKextReturnAuthentication libkern_kext_err(0xd)
148
149/*!
150 * @define kOSKextReturnDependencies
151 * @abstract Dependency resolution failures encountered; check diagnostics for details.
152 */
153#define kOSKextReturnDependencies libkern_kext_err(0xe)
154
155/*!
156 * @define kOSKextReturnArchNotFound
157 * @abstract Kext does not contain code for the requested architecture.
158 */
159#define kOSKextReturnArchNotFound libkern_kext_err(0xf)
160
161/*!
162 * @define kOSKextReturnCache
163 * @abstract An error occurred processing a system kext cache.
164 */
165#define kOSKextReturnCache libkern_kext_err(0x10)
166
167/*!
168 * @define kOSKextReturnDeferred
169 * @abstract Operation has been posted asynchronously to user space (kernel only).
170 */
171#define kOSKextReturnDeferred libkern_kext_err(0x11)
172
173/*!
174 * @define kOSKextReturnBootLevel
175 * @abstract Kext not loadable or operation not allowed at current boot level.
176 */
177#define kOSKextReturnBootLevel libkern_kext_err(0x12)
178
179/*!
180 * @define kOSKextReturnNotLoadable
181 * @abstract Kext cannot be loaded; check diagnostics for details.
182 */
183#define kOSKextReturnNotLoadable libkern_kext_err(0x13)
184
185/*!
186 * @define kOSKextReturnLoadedVersionDiffers
187 * @abstract A different version (or executable UUID, or executable by checksum)
188 * of the requested kext is already loaded.
189 */
190#define kOSKextReturnLoadedVersionDiffers libkern_kext_err(0x14)
191
192/*!
193 * @define kOSKextReturnDependencyLoadError
194 * @abstract A load error occurred on a dependency of the kext being loaded.
195 */
196#define kOSKextReturnDependencyLoadError libkern_kext_err(0x15)
197
198/*!
199 * @define kOSKextReturnLinkError
200 * @abstract A link failure occured with this kext or a dependency.
201 */
202#define kOSKextReturnLinkError libkern_kext_err(0x16)
203
204/*!
205 * @define kOSKextReturnStartStopError
206 * @abstract The kext start or stop routine returned an error.
207 */
208#define kOSKextReturnStartStopError libkern_kext_err(0x17)
209
210/*!
211 * @define kOSKextReturnInUse
212 * @abstract The kext is currently in use or has outstanding references,
213 * and cannot be unloaded.
214 */
215#define kOSKextReturnInUse libkern_kext_err(0x18)
216
217/*!
218 * @define kOSKextReturnTimeout
219 * @abstract A kext request has timed out.
220 */
221#define kOSKextReturnTimeout libkern_kext_err(0x19)
222
223/*!
224 * @define kOSKextReturnStopping
225 * @abstract The kext is in the process of stopping; requests cannot be made.
226 */
227#define kOSKextReturnStopping libkern_kext_err(0x1a)
228
229#if PRAGMA_MARK
230#pragma mark -
231/********************************************************************/
232#pragma mark Kext/OSBundle Property List Keys
233/********************************************************************/
234#endif
235/*!
236 * @group Kext Property List Keys
237 * These constants cover CFBundle properties defined for kernel extensions.
238 * Because they are used in the kernel, if you want to use one with
239 * CFBundle APIs you'll need to wrap it in a <code>CFSTR()</code> macro.
240 */
241
242
243/*!
244 * @define kOSBundleCompatibleVersionKey
245 * @abstract A string giving the backwards-compatible version of a library kext
246 * in extended Mac OS 'vers' format (####.##.##s{1-255} where 's'
247 * is a build stage 'd', 'a', 'b', 'f' or 'fc').
248 */
249#define kOSBundleCompatibleVersionKey "OSBundleCompatibleVersion"
250
251/*!
252 * @define kOSBundleEnableKextLoggingKey
253 * @abstract Set to true to have the kernel kext logging spec applied
254 * to the kext.
255 * See <code>@link //apple_ref/c/econst/OSKextLogSpec
256 * OSKextLogSpec@/link</code>.
257 */
258#define kOSBundleEnableKextLoggingKey "OSBundleEnableKextLogging"
259
260/*!
261 * @define kOSBundleIsInterfaceKey
262 * @abstract A boolean value indicating whether the kext executable
263 * contains only symbol references.
264 */
265#define kOSBundleIsInterfaceKey "OSBundleIsInterface"
266
267/*!
268 * @define kOSBundleLibrariesKey
269 * @abstract A dictionary listing link dependencies for this kext.
270 * Keys are bundle identifiers, values are version strings.
271 */
272#define kOSBundleLibrariesKey "OSBundleLibraries"
273
274/*!
275 * @define kOSBundleRequiredKey
276 * @abstract A string indicating in which kinds of startup this kext
277 * may need to load during early startup (before
278 * <code>@link //apple_ref/doc/man/8/kextd kextcache(8)@/link</code>).
279 * @discussion
280 * The value is one of:
281 * <ul>
282 * <li>@link kOSBundleRequiredRoot "OSBundleRequiredRoot"@/link</li>
283 * <li>@link kOSBundleRequiredLocalRoot "OSBundleRequiredLocalRoot"@/link</li>
284 * <li>@link kOSBundleRequiredNetworkRoot "OSBundleRequiredNetworkRoot"@/link</li>
285 * <li>@link kOSBundleRequiredSafeBoot "OSBundleRequiredSafeBoot"@/link</li>
286 * <li>@link kOSBundleRequiredConsole "OSBundleRequiredConsole"@/link</li>
287 * </ul>
288 *
289 * Use this property judiciously.
290 * Every kext that declares a value other than "OSBundleRequiredSafeBoot"
291 * increases startup time, as the booter must read it into memory,
292 * or startup kext caches must include it.
293 */
294#define kOSBundleRequiredKey "OSBundleRequired"
295
296/*!
297 * @define kOSBundleAllowUserLoadKey
298 * @abstract A boolean value indicating whether
299 * <code>@link //apple_ref/doc/man/8/kextd kextcache(8)@/link</code>
300 * will honor a non-root process's request to load a kext.
301 * @discussion
302 * See <code>@link //apple_ref/doc/compositePage/c/func/KextManagerLoadKextWithURL
303 * KextManagerLoadKextWithURL@/link</code>
304 * and <code>@link //apple_ref/doc/compositePage/c/func/KextManagerLoadKextWithIdentifier
305 * KextManagerLoadKextWithIdentifier@/link</code>.
306 */
307#define kOSBundleAllowUserLoadKey "OSBundleAllowUserLoad"
308
309/*!
310 * @define kOSKernelResourceKey
311 * @abstract A boolean value indicating whether the kext represents a built-in
312 * component of the kernel.
313 */
314#define kOSKernelResourceKey "OSKernelResource"
315
316/*!
317 * @define kIOKitPersonalitiesKey
318 * @abstract A dictionary of dictionaries used in matching for I/O Kit drivers.
319 */
320#define kIOKitPersonalitiesKey "IOKitPersonalities"
321
322/*
323 * @define kIOPersonalityPublisherKey
324 * @abstract Used in personalities sent to the I/O Kit,
325 * contains the CFBundleIdentifier of the kext
326 * that the personality originated in.
327 */
328#define kIOPersonalityPublisherKey "IOPersonalityPublisher"
329
330
331#if PRAGMA_MARK
332/********************************************************************/
333#pragma mark Kext/OSBundle Property Deprecated Keys
334/********************************************************************/
335#endif
336/*
337 * @define kOSBundleDebugLevelKey
338 * @abstract
339 * Deprecated (used on some releases of Mac OS X prior to 10.6 Snow Leopard).
340 * Value is an integer from 1-6, corresponding to the verbose levels
341 * of kext tools on those releases.
342 * On 10.6 Snow Leopard, use <code>@link OSKextEnableKextLogging
343 * OSKextEnableKextLogging@/link</code>.
344 */
345#define kOSBundleDebugLevelKey "OSBundleDebugLevel"
346
347/*!
348 * @define kOSBundleSharedExecutableIdentifierKey
349 * @abstract Deprecated (used on some releases of Mac OS X
350 * prior to 10.6 Snow Leopard).
351 * Value is the bundle identifier of the pseudokext
352 * that contains an executable shared by this kext.
353 */
354#define kOSBundleSharedExecutableIdentifierKey "OSBundleSharedExecutableIdentifier"
355
356
357#if PRAGMA_MARK
358/********************************************************************/
359#pragma mark Kext/OSBundle Property List Values
360/********************************************************************/
361#endif
362
363/*!
364 * @group Kext Property List Values
365 * These constants encompass established values
366 * for kernel extension bundle properties.
367 */
368
369/*!
370* @define kOSKextKernelIdentifier
371* @abstract
372* This is the CFBundleIdentifier user for the kernel itself.
373*/
374#define kOSKextKernelIdentifier "__kernel__"
375
376/*!
377* @define kOSBundleRequiredRoot
378* @abstract
379* This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code>
380* value indicates that the kext may be needed to mount the root filesystem
381* whether starting from a local or a network volume.
382*/
383#define kOSBundleRequiredRoot "Root"
384
385/*!
386* @define kOSBundleRequiredLocalRoot
387* @abstract
388* This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code>
389* value indicates that the kext may be needed to mount the root filesystem
390* when starting from a local disk.
391*/
392#define kOSBundleRequiredLocalRoot "Local-Root"
393
394/*!
395* @define kOSBundleRequiredNetworkRoot
396* @abstract
397* This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code>
398* value indicates that the kext may be needed to mount the root filesystem
399* when starting over a network connection.
400*/
401#define kOSBundleRequiredNetworkRoot "Network-Root"
402
403/*!
404* @define kOSBundleRequiredSafeBoot
405* @abstract
406* This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code>
407* value indicates that the kext can be loaded during a safe startup.
408* This value does not normally cause the kext to be read by the booter
409* or included in startup kext caches.
410*/
411#define kOSBundleRequiredSafeBoot "Safe Boot"
412
413/*!
414* @define kOSBundleRequiredConsole
415* @abstract
416* This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code>
417* value indicates that the kext may be needed for console access
418* (specifically in a single-user startup when
419* <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code>.
420* does not run)
421* and should be loaded during early startup.
422*/
423#define kOSBundleRequiredConsole "Console"
424
425
426#if PRAGMA_MARK
427#pragma mark -
428/********************************************************************/
429#pragma mark Kext Information
430/********************************************************************/
431#endif
432/*!
433 * @group Kext Information
434 * Types, constants, and macros providing a kext with information
435 * about itself.
436 */
437
438/*!
439 * @typedef OSKextLoadTag
440 *
441 * @abstract
442 * A unique identifier assigned to a loaded instanace of a kext.
443 *
444 * @discussion
445 * If a kext is unloaded and later reloaded, the new instance
446 * has a different load tag.
447 *
448 * A kext can get its own load tag in the <code>kmod_info_t</code>
449 * structure passed into its module start routine, as the
450 * <code>id</code> field (cast to this type).
451 * You can use the load tag with the functions
452 * <code>@link OSKextRetainKextWithLoadTag
453 * OSKextRetainKextWithLoadTag@/link</code> and
454 * <code>@link OSKextReleaseKextWithLoadTag
455 * OSKextReleaseKextWithLoadTag@/link</code>.
456 */
457typedef uint32_t OSKextLoadTag;
458
459/*!
460 * @define kOSKextInvalidLoadTag
461 *
462 * @abstract
463 * A load tag value that will never be used for a loaded kext;
464 * indicates kext not found.
465 */
466#define kOSKextInvalidLoadTag ((OSKextLoadTag)(-1))
467
468
469
470__END_DECLS
471
472#endif /* _LIBKERN_OSKEXTLIB_H */
473

Archive Download this file

Revision: 1232