1/*
2 * Copyright (c) 2000-2016 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/*
29Copyright (c) 1998 Apple Computer, Inc. All rights reserved.
30HISTORY
31 1998-10-30 Godfrey van der Linden(gvdl)
32 Created
33*/
34#ifndef _LIBKERN_OSOBJECT_H
35#define _LIBKERN_OSOBJECT_H
36
37#include <libkern/c++/OSMetaClass.h>
38
39#if defined(__clang__)
40#pragma clang diagnostic ignored "-Woverloaded-virtual"
41#endif
42
43class OSSymbol;
44class OSString;
45
46
47/*!
48 * @header
49 *
50 * @abstract
51 * This header declares the OSObject class,
52 * which is the concrete root of the Libkern C++ class hierarchy.
53 */
54
55
56/*!
57 * @class OSObject
58 *
59 * @abstract
60 * OSObject is the concrete root class
61 * of the Libkern and I/O Kit C++ class hierarchy.
62 *
63 * @discussion
64 * OSObject defines the minimal functionality
65 * required of Libkern and I/O Kit C++ classes:
66 * tie-in to the run-time type information facility,
67 * the dynamic allocation/initialization paradigm,
68 * and reference counting.
69 * While kernel extensions are free to use their own C++ classes internally,
70 * any interaction they have with Libkern or the I/O Kit will require
71 * classes ultimately derived from OSObject.
72 *
73 * <b>Run-Time Type Information</b>
74 *
75 * OSObject is derived from the abstract root class
76 * @link //apple_ref/doc/class/OSMetaClassBase OSMetaClassBase@/link,
77 * which declares (and defines many of) the primitives
78 * on which the run-time type information facility is based.
79 * A parallel inheritance hierarchy of metaclass objects
80 * provides run-time introspection, including access to class names,
81 * inheritance, and safe type-casting.
82 * See @link //apple_ref/doc/class/OSMetaClass OSMetaClass@/link
83 * for more information.
84 *
85 * <b>Dynamic Allocation/Initialization</b>
86 *
87 * The kernel-resident C++ runtime does not support exceptions,
88 * so Libkern classes cannot use standard C++ object
89 * constructors and destructors,
90 * which use exceptions to report errors.
91 * To support error-handling during instance creation, then,
92 * OSObject separates object allocation from initialization.
93 * You can create a new OSObject-derived instance
94 * with the <code>new</code> operator,
95 * but this does nothing more than allocate memory
96 * and initialize the reference count to 1.
97 * Following this, you must call a designated initialization function
98 * and check its <code>bool</code> return value.
99 * If the initialization fails,
100 * you must immediately call
101 * <code>@link
102 * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
103 * release@/link</code>
104 * on the instance and handle the failure in whatever way is appropriate.
105 * Many Libkern and I/O Kit classes define static instance-creation functions
106 * (beginning with the word "with")
107 * to make construction a one-step process for clients.
108 *
109 * <b>Reference Counting</b>
110 *
111 * OSObject provides reference counting services using the
112 * <code>@link
113 * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/()
114 * retain@/link</code>,
115 * <code>@link
116 * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
117 * release()@/link</code>,
118 * <code>@link
119 * //apple_ref/cpp/instm/OSObject/release/virtualvoid/(int)
120 * release(int freeWhen)@/link</code>
121 * and
122 *<code> @link
123 * //apple_ref/cpp/instm/OSObject/free/virtualvoid/()
124 * free@/link</code>
125 * functions.
126 * The public interface to the reference counting is
127 * <code>@link
128 * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/()
129 * retain@/link</code>,
130 * and
131 * <code>@link
132 * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
133 * release@/link</code>;
134 * <code>@link
135 * //apple_ref/cpp/instm/OSObject/release/virtualvoid/(int)
136 * release(int freeWhen)@/link</code>
137 * is provided
138 * for objects that have internal retain cycles.
139 *
140 * In general, a subclass is expected to only override
141 * <code>@link
142 * //apple_ref/cpp/instm/OSObject/free/virtualvoid/()
143 * free@/link</code>.
144 * It may also choose to override
145 * <code>@link
146 * //apple_ref/cpp/instm/OSObject/release/virtualvoid/(int)
147 * release(int freeWhen)@/link</code>
148 * if the object has a circular retain count, as noted above.
149 *
150 * <b>Use Restrictions</b>
151 *
152 * With very few exceptions in the I/O Kit, all Libkern-based C++
153 * classes, functions, and macros are <b>unsafe</b>
154 * to use in a primary interrupt context.
155 * Consult the I/O Kit documentation related to primary interrupts
156 * for more information.
157 *
158 * <b>Concurrency Protection</b>
159 *
160 * The basic features of OSObject are thread-safe.
161 * Most Libkern subclasses are not, and require locking or other protection
162 * if instances are shared between threads.
163 * I/O Kit driver objects are either designed for use within thread-safe contexts
164 * or designed to inherently be thread-safe.
165 * Always check the individual class documentation to see what
166 * steps are necessary for concurrent use of instances.
167 */
168class OSObject : public OSMetaClassBase
169{
170 OSDeclareAbstractStructors(OSObject)
171#if IOKITSTATS
172 friend class IOStatistics;
173#endif
174
175private:
176 /* Not to be included in headerdoc.
177 *
178 * @var retainCount Number of references held on this instance.
179 */
180 mutable int retainCount;
181
182protected:
183
184// xx-review: seems not to be used, should we deprecate?
185
186 /*!
187 * @function release
188 *
189 * @abstract
190 * Releases a reference to an object,
191 * freeing it immediately if the reference count
192 * drops below the specified threshold.
193 *
194 * @param freeWhen If decrementing the reference count makes it
195 * >= <code>freeWhen</code>, the object is immediately freed.
196 *
197 * @discussion
198 * If the receiver has <code>freeWhen</code> or fewer references
199 * after its reference count is decremented,
200 * it is immediately freed.
201 *
202 * This version of <code>release</code>
203 * can be used to break certain retain cycles in object graphs.
204 * In general, however, it should be avoided.
205 */
206 virtual void release(int freeWhen) const APPLE_KEXT_OVERRIDE;
207
208 /*!
209 * @function taggedRelease
210 *
211 * @abstract
212 * Releases a tagged reference to an object,
213 * freeing it immediately if the reference count
214 * drops below the specified threshold.
215 *
216 * @param tag Used for tracking collection references.
217 * @param freeWhen If decrementing the reference count makes it
218 * >= <code>freeWhen</code>, the object is immediately freed.
219 *
220 * @discussion
221 * Kernel extensions should not use this function.
222 * It is for use by OSCollection and subclasses to track
223 * inclusion in collections.
224 *
225 * If the receiver has <code>freeWhen</code> or fewer references
226 * after its reference count is decremented,
227 * it is immediately freed.
228 *
229 * This version of <code>release</code>
230 * can be used to break certain retain cycles in object graphs.
231 * In general, however, it should be avoided.
232 */
233 virtual void taggedRelease(const void * tag, const int freeWhen) const APPLE_KEXT_OVERRIDE;
234
235
236 /*!
237 * @function init
238 *
239 * @abstract
240 * Initializes a newly-allocated object.
241 *
242 * @result
243 * <code>true</code> on success, <code>false</code> on failure.
244 *
245 * @discussion
246 * Classes derived from OSObject must override the primary init method
247 * of their parent.
248 * In general most implementations call
249 * <code><i>super</i>::init()</code>
250 * before doing local initialisation.
251 * If the superclass call fails then return <code>false</code> immediately.
252 * If the subclass encounters a failure then it should return <code>false</code>.
253 */
254 virtual bool init();
255
256
257 /*!
258 * @function free
259 *
260 * @abstract
261 * Deallocates/releases resources held by the object.
262 *
263 * @discussion
264 * Classes derived from OSObject should override this function
265 * to deallocate or release all dynamic resources held by the instance,
266 * then call the superclass's implementation.
267 *
268 * <b>Caution:</b>
269 * <ol>
270 * <li>You can not assume that you have completed initialization
271 * before <code>free</code> is called,
272 * so be very careful in your implementation.</li>
273 * <li>OSObject's implementation performs the C++ <code>delete</code>
274 * of the instance, so be sure that you call the superclass
275 * implementation <i>last</i> in your implementation.</li>
276 * <li><code>free</code> must not fail;
277 * all resources must be deallocated or released on completion.</li>
278 * </ol>
279 */
280 virtual void free();
281
282
283 /*!
284 * @function operator delete
285 *
286 * @abstract
287 * Frees the memory of the object itself.
288 *
289 * @param mem A pointer to the object's memory.
290 * @param size The size of the object's block of memory.
291 *
292 * @discussion
293 * Never use <code>delete</code> on objects derived from OSObject;
294 * use
295 * <code>@link
296 * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
297 * release@/link</code>
298 * instead.
299 */
300 static void operator delete(void * mem, size_t size);
301
302public:
303
304 /*!
305 * @function operator new
306 *
307 * @abstract
308 * Allocates memory for an instance of the class.
309 *
310 * @param size The number of bytes to allocate
311 *
312 * @result
313 * A pointer to block of memory if available, <code>NULL</code> otherwise.
314 */
315 static void * operator new(size_t size);
316
317
318 /*!
319 * @function getRetainCount
320 *
321 * @abstract
322 * Returns the reference count of the object.
323 *
324 * @result
325 * The reference count of the object.
326 */
327 virtual int getRetainCount() const APPLE_KEXT_OVERRIDE;
328
329
330 /*!
331 * @function retain
332 *
333 * @abstract
334 * Retains a reference to the object.
335 *
336 * @discussion
337 * This function increments the reference count of the receiver by 1.
338 * If you need to maintain a reference to an object
339 * outside the context in which you received it,
340 * you should always retain it immediately.
341 */
342 virtual void retain() const APPLE_KEXT_OVERRIDE;
343
344
345 /*!
346 * @function release
347 *
348 * @abstract
349 * Releases a reference to the object,
350 * freeing it immediately if the reference count drops to zero.
351 *
352 * @discussion
353 * This function decrements the reference count of the receiver by 1.
354 * If the reference count drops to zero,
355 * the object is immediately freed using
356 * <code>@link
357 * //apple_ref/cpp/instm/OSObject/free/virtualvoid/()
358 * free@/link</code>.
359 */
360 virtual void release() const APPLE_KEXT_OVERRIDE;
361
362
363 /*!
364 * @function taggedRetain
365 *
366 * @abstract
367 * Retains a reference to the object with an optional
368 * tag used for reference-tracking.
369 *
370 * @param tag Used for tracking collection references.
371 *
372 * @discussion
373 * Kernel extensions should not use this function.
374 * It is for use by OSCollection and subclasses to track
375 * inclusion in collections.
376 *
377 * If you need to maintain a reference to an object
378 * outside the context in which you received it,
379 * you should always retain it immediately.
380 */
381 virtual void taggedRetain(const void * tag = 0) const APPLE_KEXT_OVERRIDE;
382
383
384 /*!
385 * @function taggedRelease
386 *
387 * @abstract
388 * Releases a tagged reference to an object,
389 * freeing it immediately if the reference count
390 * drops to zero.
391 *
392 * @param tag Used for tracking collection references.
393 *
394 * @discussion
395 * Kernel extensions should not use this function.
396 * It is for use by OSCollection and subclasses to track
397 * inclusion in collections.
398 */
399 virtual void taggedRelease(const void * tag = 0) const APPLE_KEXT_OVERRIDE;
400 // xx-review: used to say, "Remove a reference on this object with this tag, if an attempt is made to remove a reference that isn't associated with this tag the kernel will panic immediately", but I don't see that in the implementation
401
402
403 /*!
404 * @function serialize
405 *
406 * @abstract
407 * Overridden by subclasses to archive the receiver into the provided
408 * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link object.
409 *
410 * @param serializer The OSSerialize object.
411 *
412 * @result
413 * <code>true</code> if serialization succeeds, <code>false</code> if not.
414 *
415 * @discussion
416 * OSObject's implementation writes a string indicating that
417 * the class of the object receiving the function call
418 * is not serializable.
419 * Subclasses that can meaningfully encode themselves
420 * in I/O Kit-style property list XML can override this function to do so.
421 * See
422 * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link
423 * for more information.
424 */
425 virtual bool serialize(OSSerialize * serializer) const APPLE_KEXT_OVERRIDE;
426
427#ifdef XNU_KERNEL_PRIVATE
428#if IOTRACKING
429 void trackingAccumSize(size_t size);
430#endif
431#endif
432
433 // Unused Padding
434 OSMetaClassDeclareReservedUnused(OSObject, 0);
435 OSMetaClassDeclareReservedUnused(OSObject, 1);
436 OSMetaClassDeclareReservedUnused(OSObject, 2);
437 OSMetaClassDeclareReservedUnused(OSObject, 3);
438 OSMetaClassDeclareReservedUnused(OSObject, 4);
439 OSMetaClassDeclareReservedUnused(OSObject, 5);
440 OSMetaClassDeclareReservedUnused(OSObject, 6);
441 OSMetaClassDeclareReservedUnused(OSObject, 7);
442 OSMetaClassDeclareReservedUnused(OSObject, 8);
443 OSMetaClassDeclareReservedUnused(OSObject, 9);
444 OSMetaClassDeclareReservedUnused(OSObject, 10);
445 OSMetaClassDeclareReservedUnused(OSObject, 11);
446 OSMetaClassDeclareReservedUnused(OSObject, 12);
447 OSMetaClassDeclareReservedUnused(OSObject, 13);
448 OSMetaClassDeclareReservedUnused(OSObject, 14);
449 OSMetaClassDeclareReservedUnused(OSObject, 15);
450
451};
452
453#endif /* !_LIBKERN_OSOBJECT_H */
454