1 /*
2 * Copyright (c) 1998-2016 Apple Computer, 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 * Copyright (c) 1998 Apple Computer, Inc. All rights reserved.
30 *
31 * HISTORY
32 *
33 */
34
35 #ifndef __IOKIT_IOLIB_H
36 #define __IOKIT_IOLIB_H
37
38 #ifndef KERNEL
39 #error IOLib.h is for kernel use only
40 #endif
41
42 #include <stdarg.h>
43 #include <sys/cdefs.h>
44 #include <os/overflow.h>
45 #include <os/alloc_util.h>
46
47 #include <sys/appleapiopts.h>
48
49 #include <IOKit/system.h>
50
51 #include <IOKit/IOReturn.h>
52 #include <IOKit/IOTypes.h>
53 #include <IOKit/IOLocks.h>
54
55 #include <libkern/OSAtomic.h>
56
57 __BEGIN_DECLS
58
59 #include <kern/thread_call.h>
60 #include <kern/clock.h>
61 #ifdef KERNEL_PRIVATE
62 #include <kern/kalloc.h>
63 #include <kern/assert.h>
64 #endif
65
66 /*
67 * min/max macros.
68 */
69
70 #define min(a, b) ((a) < (b) ? (a) : (b))
71 #define max(a, b) ((a) > (b) ? (a) : (b))
72
73 /*
74 * Safe functions to compute array sizes (saturate to a size that can't be
75 * allocated ever and will cause the allocation to return NULL always).
76 */
77
78 static inline vm_size_t
IOMallocArraySize(vm_size_t hdr_size,vm_size_t elem_size,vm_size_t elem_count)79 IOMallocArraySize(vm_size_t hdr_size, vm_size_t elem_size, vm_size_t elem_count)
80 {
81 /* IOMalloc() will reject this size before even asking the VM */
82 const vm_size_t limit = 1ull << (8 * sizeof(vm_size_t) - 1);
83 vm_size_t s = hdr_size;
84
85 if (os_mul_and_add_overflow(elem_size, elem_count, s, &s) || (s & limit)) {
86 return limit;
87 }
88 return s;
89 }
90
91 /*
92 * These are opaque to the user.
93 */
94 typedef thread_t IOThread;
95 typedef void (*IOThreadFunc)(void *argument);
96
97 /*
98 * Memory allocation functions.
99 */
100 #if XNU_KERNEL_PRIVATE
101
102 /*
103 * IOMalloc_internal allocates memory from the specifed kalloc heap, which can be:
104 * - KHEAP_DATA_BUFFERS: Should be used for data buffers
105 * - KHEAP_DEFAULT: Should be used for allocations that aren't data buffers.
106 *
107 * For more details on kalloc_heaps see kalloc.h
108 */
109
110 extern void *
111 IOMalloc_internal(
112 struct kalloc_heap * kalloc_heap_cfg,
113 vm_size_t size,
114 zalloc_flags_t flags);
115
116 __attribute__((alloc_size(2)))
117 static inline void *
__IOMalloc_internal(struct kalloc_heap * kalloc_heap_cfg,vm_size_t size,zalloc_flags_t flags)118 __IOMalloc_internal(
119 struct kalloc_heap * kalloc_heap_cfg,
120 vm_size_t size,
121 zalloc_flags_t flags)
122 {
123 void *addr = (IOMalloc_internal)(kalloc_heap_cfg, size, flags);
124 if (flags & Z_NOFAIL) {
125 __builtin_assume(addr != NULL);
126 }
127 return addr;
128 }
129
130 #define IOMalloc(size) __IOMalloc_internal(KHEAP_DEFAULT, size, Z_WAITOK)
131 #define IOMallocZero(size) __IOMalloc_internal(KHEAP_DEFAULT, size, Z_ZERO)
132
133 #else /* XNU_KERNEL_PRIVATE */
134
135 /*! @function IOMalloc
136 * @abstract Allocates general purpose, wired memory in the kernel map.
137 * @discussion This is a general purpose utility to allocate memory in the kernel. There are no alignment guarantees given on the returned memory, and alignment may vary depending on the kernel configuration. This function may block and so should not be called from interrupt level or while a simple lock is held.
138 * @param size Size of the memory requested.
139 * @result Pointer to the allocated memory, or zero on failure. */
140
141 void * IOMalloc(vm_size_t size) __attribute__((alloc_size(1)));
142 void * IOMallocZero(vm_size_t size) __attribute__((alloc_size(1)));
143
144 /*! @function IOFree
145 * @abstract Frees memory allocated with IOMalloc.
146 * @discussion This function frees memory allocated with IOMalloc, it may block and so should not be called from interrupt level or while a simple lock is held.
147 * @param address Pointer to the allocated memory. Must be identical to result
148 * @of a prior IOMalloc.
149 * @param size Size of the memory allocated. Must be identical to size of
150 * @the corresponding IOMalloc */
151
152 #endif /* XNU_KERNEL_PRIVATE */
153
154 #if XNU_KERNEL_PRIVATE
155
156 /*
157 * IOFree_internal allows specifying the kalloc heap to free the allocation
158 * to
159 */
160
161 extern void
162 IOFree_internal(
163 struct kalloc_heap * kalloc_heap_cfg,
164 void * inAddress,
165 vm_size_t size);
166
167 #endif /* XNU_KERNEL_PRIVATE */
168
169 void IOFree(void * address, vm_size_t size);
170
171 /*! @function IOMallocAligned
172 * @abstract Allocates wired memory in the kernel map, with an alignment restriction.
173 * @discussion This is a utility to allocate memory in the kernel, with an alignment restriction which is specified as a byte count. This function may block and so should not be called from interrupt level or while a simple lock is held.
174 * @param size Size of the memory requested.
175 * @param alignment Byte count of the alignment for the memory. For example, pass 256 to get memory allocated at an address with bit 0-7 zero.
176 * @result Pointer to the allocated memory, or zero on failure. */
177
178 #if XNU_KERNEL_PRIVATE
179
180 extern void *
181 IOMallocAligned_internal(
182 struct kalloc_heap * kalloc_heap_cfg,
183 vm_size_t size,
184 vm_size_t alignment,
185 zalloc_flags_t flags);
186
187 __attribute__((alloc_size(2)))
188 static inline void *
__IOMallocAligned_internal(struct kalloc_heap * kalloc_heap_cfg,vm_size_t size,vm_size_t alignment,zalloc_flags_t flags)189 __IOMallocAligned_internal(
190 struct kalloc_heap * kalloc_heap_cfg,
191 vm_size_t size,
192 vm_size_t alignment,
193 zalloc_flags_t flags)
194 {
195 void *addr = (IOMallocAligned_internal)(kalloc_heap_cfg, size, alignment, flags);
196 if (flags & Z_NOFAIL) {
197 __builtin_assume(addr != NULL);
198 }
199 return addr;
200 }
201
202 #define IOMallocAligned(size, alignment) \
203 __IOMallocAligned_internal(KHEAP_DATA_BUFFERS, size, alignment, Z_WAITOK)
204
205 #else /* XNU_KERNEL_PRIVATE */
206
207 void * IOMallocAligned(vm_size_t size, vm_offset_t alignment) __attribute__((alloc_size(1)));
208
209 #endif /* !XNU_KERNEL_PRIVATE */
210
211
212 /*! @function IOFreeAligned
213 * @abstract Frees memory allocated with IOMallocAligned.
214 * @discussion This function frees memory allocated with IOMallocAligned, it may block and so should not be called from interrupt level or while a simple lock is held.
215 * @param address Pointer to the allocated memory.
216 * @param size Size of the memory allocated. */
217
218 #if XNU_KERNEL_PRIVATE
219
220 /*
221 * IOFreeAligned_internal allows specifying the kalloc heap to free the
222 * allocation to
223 */
224
225 extern void
226 IOFreeAligned_internal(
227 struct kalloc_heap * kalloc_heap_cfg,
228 void * address,
229 vm_size_t size);
230
231 #endif /* XNU_KERNEL_PRIVATE */
232
233 void IOFreeAligned(void * address, vm_size_t size);
234
235 /*! @function IOMallocContiguous
236 * @abstract Deprecated - use IOBufferMemoryDescriptor. Allocates wired memory in the kernel map, with an alignment restriction and physically contiguous.
237 * @discussion This is a utility to allocate memory in the kernel, with an alignment restriction which is specified as a byte count, and will allocate only physically contiguous memory. The request may fail if memory is fragmented, and may cause large amounts of paging activity. This function may block and so should not be called from interrupt level or while a simple lock is held.
238 * @param size Size of the memory requested.
239 * @param alignment Byte count of the alignment for the memory. For example, pass 256 to get memory allocated at an address with bits 0-7 zero.
240 * @param physicalAddress IOMallocContiguous returns the physical address of the allocated memory here, if physicalAddress is a non-zero pointer. The physicalAddress argument is deprecated and should be passed as NULL. To obtain the physical address for a memory buffer, use the IODMACommand class in conjunction with the IOMemoryDescriptor or IOBufferMemoryDescriptor classes.
241 * @result Virtual address of the allocated memory, or zero on failure. */
242
243 void * IOMallocContiguous(vm_size_t size, vm_size_t alignment,
244 IOPhysicalAddress * physicalAddress) __attribute__((deprecated)) __attribute__((alloc_size(1)));
245
246 /*! @function IOFreeContiguous
247 * @abstract Deprecated - use IOBufferMemoryDescriptor. Frees memory allocated with IOMallocContiguous.
248 * @discussion This function frees memory allocated with IOMallocContiguous, it may block and so should not be called from interrupt level or while a simple lock is held.
249 * @param address Virtual address of the allocated memory.
250 * @param size Size of the memory allocated. */
251
252 void IOFreeContiguous(void * address, vm_size_t size) __attribute__((deprecated));
253
254
255 /*! @function IOMallocPageable
256 * @abstract Allocates pageable memory in the kernel map.
257 * @discussion This is a utility to allocate pageable memory in the kernel. This function may block and so should not be called from interrupt level or while a simple lock is held.
258 * @param size Size of the memory requested.
259 * @param alignment Byte count of the alignment for the memory. For example, pass 256 to get memory allocated at an address with bits 0-7 zero.
260 * @result Pointer to the allocated memory, or zero on failure. */
261
262 void * IOMallocPageable(vm_size_t size, vm_size_t alignment) __attribute__((alloc_size(1)));
263
264 /*! @function IOMallocPageableZero
265 * @abstract Allocates pageable, zeroed memory in the kernel map.
266 * @discussion Same as IOMallocPageable but guarantees the returned memory will be zeroed.
267 * @param size Size of the memory requested.
268 * @param alignment Byte count of the alignment for the memory. For example, pass 256 to get memory allocated at an address with bits 0-7 zero.
269 * @result Pointer to the allocated memory, or zero on failure. */
270
271 void * IOMallocPageableZero(vm_size_t size, vm_size_t alignment) __attribute__((alloc_size(1)));
272
273 /*! @function IOFreePageable
274 * @abstract Frees memory allocated with IOMallocPageable.
275 * @discussion This function frees memory allocated with IOMallocPageable, it may block and so should not be called from interrupt level or while a simple lock is held.
276 * @param address Virtual address of the allocated memory.
277 * @param size Size of the memory allocated. */
278
279 void IOFreePageable(void * address, vm_size_t size);
280
281 #if XNU_KERNEL_PRIVATE
282
283 #define IOMallocData(size) __IOMalloc_internal(KHEAP_DATA_BUFFERS, size, Z_WAITOK)
284 #define IOMallocZeroData(size) __IOMalloc_internal(KHEAP_DATA_BUFFERS, size, Z_ZERO)
285
286 #elif KERNEL_PRIVATE /* XNU_KERNEL_PRIVATE */
287
288 /*! @function IOMallocData
289 * @abstract Allocates wired memory in the kernel map, from a separate section meant for pure data.
290 * @discussion Same as IOMalloc except that this function should be used for allocating pure data.
291 * @param size Size of the memory requested.
292 * @result Pointer to the allocated memory, or zero on failure. */
293 void * IOMallocData(vm_size_t size) __attribute__((alloc_size(1)));
294
295 /*! @function IOMallocZeroData
296 * @abstract Allocates wired memory in the kernel map, from a separate section meant for pure data bytes that don't contain pointers.
297 * @discussion Same as IOMallocData except that the memory returned is zeroed.
298 * @param size Size of the memory requested.
299 * @result Pointer to the allocated memory, or zero on failure. */
300 void * IOMallocZeroData(vm_size_t size) __attribute__((alloc_size(1)));
301
302 #endif /* KERNEL_PRIVATE */
303
304 #if KERNEL_PRIVATE
305
306 /*! @function IOFreeData
307 * @abstract Frees memory allocated with IOMallocData or IOMallocZeroData.
308 * @discussion This function frees memory allocated with IOMallocData/IOMallocZeroData, it may block and so should not be called from interrupt level or while a simple lock is held.
309 * @param address Virtual address of the allocated memory. Passing NULL here is acceptable.
310 * @param size Size of the memory allocated. It is acceptable to pass 0 size for a NULL address. */
311 void IOFreeData(void * address, vm_size_t size);
312
313 /*
314 * Typed memory allocation macros. All may block.
315 */
316
317 /*
318 * Use IOMallocType to allocate a single typed object.
319 *
320 * If you use IONew with count 1, please use IOMallocType
321 * instead. For arrays of typed objects use IONew.
322 *
323 * IOMallocType returns zeroed memory. It will not
324 * fail to allocate memory for sizes less than:
325 * - 16K (macos)
326 * - 8K (embedded 32-bit)
327 * - 32K (embedded 64-bit)
328 */
329 #define IOMallocType(type) ({ \
330 static _KALLOC_TYPE_DEFINE(kt_view_var, type, \
331 KT_SHARED_ACCT); \
332 (type *) IOMallocTypeImpl(kt_view_var); \
333 })
334
335 #define IOFreeType(elem, type) ({ \
336 static _KALLOC_TYPE_DEFINE(kt_view_var, type, \
337 KT_SHARED_ACCT); \
338 IOFREETYPE_ASSERT_COMPATIBLE_POINTER(elem, type); \
339 IOFreeTypeImpl(kt_view_var, \
340 os_ptr_load_and_erase(elem)); \
341 })
342
343 #define IONewData(type, count) \
344 ((type *)IOMallocData(IOMallocArraySize(0, sizeof(type), count)))
345
346 #define IONewZeroData(type, count) \
347 ((type *)IOMallocZeroData(IOMallocArraySize(0, sizeof(type), count)))
348
349 #define IODeleteData(ptr, type, count) ({ \
350 vm_size_t __count = (vm_size_t)(count); \
351 KALLOC_TYPE_ASSERT_COMPATIBLE_POINTER(ptr, type); \
352 IOFreeData(os_ptr_load_and_erase(ptr), \
353 IOMallocArraySize(0, sizeof(type), __count)); \
354 })
355
356 /*
357 * Versioning macro for the typed allocator APIs.
358 */
359 #define IO_TYPED_ALLOCATOR_VERSION 1
360
361 #endif /* KERNEL_PRIVATE */
362
363 /*
364 * IONew/IONewZero/IODelete/IOSafeDeleteNULL
365 *
366 * Those functions come in 2 variants:
367 *
368 * 1. IONew(element_type, count)
369 * IONewZero(element_type, count)
370 * IODelete(ptr, element_type, count)
371 * IOSafeDeleteNULL(ptr, element_type, count)
372 *
373 * Those allocate/free arrays of `count` elements of type `element_type`.
374 *
375 * 2. IONew(hdr_type, element_type, count)
376 * IONewZero(hdr_type, element_type, count)
377 * IODelete(ptr, hdr_type, element_type, count)
378 * IOSafeDeleteNULL(ptr, hdr_type, element_type, count)
379 *
380 * Those allocate/free arrays with `count` elements of type `element_type`,
381 * prefixed with a header of type `hdr_type`, like this:
382 *
383 * Those perform safe math with the sizes, checking for overflow.
384 * An overflow in the sizes will cause the allocation to return NULL.
385 */
386 #define IONew(...) __IOKIT_DISPATCH(IONew, ##__VA_ARGS__)
387 #define IONewZero(...) __IOKIT_DISPATCH(IONewZero, ##__VA_ARGS__)
388 #define IODelete(...) __IOKIT_DISPATCH(IODelete, ##__VA_ARGS__)
389 #if KERNEL_PRIVATE
390 #define IOSafeDeleteNULL(...) __IOKIT_DISPATCH(IODelete, ##__VA_ARGS__)
391 #else
392 #define IOSafeDeleteNULL(...) __IOKIT_DISPATCH(IOSafeDeleteNULL, ##__VA_ARGS__)
393 #endif
394
395 #if KERNEL_PRIVATE
396 #define IONew_2(e_ty, count) ({ \
397 static KALLOC_TYPE_VAR_DEFINE(kt_view_var, e_ty, KT_SHARED_ACCT); \
398 (e_ty *) IOMallocTypeVarImpl(kt_view_var, \
399 IOMallocArraySize(0, sizeof(e_ty), count)); \
400 })
401
402 #define IONew_3(h_ty, e_ty, count) ({ \
403 static KALLOC_TYPE_VAR_DEFINE(kt_view_var, h_ty, e_ty, KT_SHARED_ACCT); \
404 (h_ty *) IOMallocTypeVarImpl(kt_view_var, \
405 IOMallocArraySize(sizeof(h_ty), sizeof(e_ty), count)); \
406 })
407
408 #define IONewZero_2(e_ty, count) \
409 IONew_2(e_ty, count)
410
411 #define IONewZero_3(h_ty, e_ty, count) \
412 IONew_3(h_ty, e_ty, count)
413
414 #else /* KERNEL_PRIVATE */
415 #define IONew_2(e_ty, count) \
416 ((e_ty *)IOMalloc(IOMallocArraySize(0, sizeof(e_ty), count)))
417
418 #define IONew_3(h_ty, e_ty, count) \
419 ((h_ty *)IOMalloc(IOMallocArraySize(sizeof(h_ty), sizeof(e_ty), count)))
420
421 #define IONewZero_2(e_ty, count) \
422 ((e_ty *)IOMallocZero(IOMallocArraySize(0, sizeof(e_ty), count)))
423
424 #define IONewZero_3(h_ty, e_ty, count) \
425 ((h_ty *)IOMallocZero(IOMallocArraySize(sizeof(h_ty), sizeof(e_ty), count)))
426 #endif /* !KERNEL_PRIVATE */
427
428 #if KERNEL_PRIVATE
429 #define IODelete_3(ptr, e_ty, count) ({ \
430 vm_size_t __s = IOMallocArraySize(0, sizeof(e_ty), count); \
431 KALLOC_TYPE_ASSERT_COMPATIBLE_POINTER(ptr, e_ty); \
432 static KALLOC_TYPE_VAR_DEFINE(kt_view_var, e_ty, KT_SHARED_ACCT); \
433 IOFreeTypeVarImpl(kt_view_var, os_ptr_load_and_erase(ptr), __s); \
434 })
435
436 #define IODelete_4(ptr, h_ty, e_ty, count) ({ \
437 vm_size_t __s = IOMallocArraySize(sizeof(h_ty), sizeof(e_ty), count); \
438 KALLOC_TYPE_ASSERT_COMPATIBLE_POINTER(ptr, h_ty); \
439 static KALLOC_TYPE_VAR_DEFINE(kt_view_var, h_ty, e_ty, KT_SHARED_ACCT); \
440 IOFreeTypeVarImpl(kt_view_var, os_ptr_load_and_erase(ptr), __s); \
441 })
442
443 #else /* KERNEL_PRIVATE */
444 #define IODelete_3(ptr, e_ty, count) \
445 IOFree(ptr, IOMallocArraySize(0, sizeof(e_ty), count));
446
447 #define IODelete_4(ptr, h_ty, e_ty, count) \
448 IOFree(ptr, IOMallocArraySize(sizeof(h_ty), sizeof(e_ty), count));
449
450 #define IOSafeDeleteNULL_3(ptr, e_ty, count) ({ \
451 vm_size_t __s = IOMallocArraySize(0, sizeof(e_ty), count); \
452 IOFree(os_ptr_load_and_erase(ptr), __s); \
453 })
454
455 #define IOSafeDeleteNULL_4(ptr, h_ty, e_ty, count) ({ \
456 vm_size_t __s = IOMallocArraySize(sizeof(h_ty), sizeof(e_ty), count); \
457 IOFree(os_ptr_load_and_erase(ptr), __s); \
458 })
459 #endif /* !KERNEL_PRIVATE */
460
461 /////////////////////////////////////////////////////////////////////////////
462 //
463 //
464 // These functions are now implemented in IOMapper.cpp
465 //
466 //
467 /////////////////////////////////////////////////////////////////////////////
468
469 /*! @function IOMappedRead8
470 * @abstract Read one byte from the desired "Physical" IOSpace address.
471 * @discussion Read one byte from the desired "Physical" IOSpace address. This function allows the developer to read an address returned from any memory descriptor's getPhysicalSegment routine. It can then be used by segmenting a physical page slightly to tag the physical page with its kernel space virtual address.
472 * @param address The desired address, as returned by IOMemoryDescriptor::getPhysicalSegment.
473 * @result Data contained at that location */
474
475 UInt8 IOMappedRead8(IOPhysicalAddress address);
476
477 /*! @function IOMappedRead16
478 * @abstract Read two bytes from the desired "Physical" IOSpace address.
479 * @discussion Read two bytes from the desired "Physical" IOSpace address. This function allows the developer to read an address returned from any memory descriptor's getPhysicalSegment routine. It can then be used by segmenting a physical page slightly to tag the physical page with its kernel space virtual address.
480 * @param address The desired address, as returned by IOMemoryDescriptor::getPhysicalSegment.
481 * @result Data contained at that location */
482
483 UInt16 IOMappedRead16(IOPhysicalAddress address);
484
485 /*! @function IOMappedRead32
486 * @abstract Read four bytes from the desired "Physical" IOSpace address.
487 * @discussion Read four bytes from the desired "Physical" IOSpace address. This function allows the developer to read an address returned from any memory descriptor's getPhysicalSegment routine. It can then be used by segmenting a physical page slightly to tag the physical page with its kernel space virtual address.
488 * @param address The desired address, as returned by IOMemoryDescriptor::getPhysicalSegment.
489 * @result Data contained at that location */
490
491 UInt32 IOMappedRead32(IOPhysicalAddress address);
492
493 /*! @function IOMappedRead64
494 * @abstract Read eight bytes from the desired "Physical" IOSpace address.
495 * @discussion Read eight bytes from the desired "Physical" IOSpace address. This function allows the developer to read an address returned from any memory descriptor's getPhysicalSegment routine. It can then be used by segmenting a physical page slightly to tag the physical page with its kernel space virtual address.
496 * @param address The desired address, as returned by IOMemoryDescriptor::getPhysicalSegment.
497 * @result Data contained at that location */
498
499 UInt64 IOMappedRead64(IOPhysicalAddress address);
500
501 /*! @function IOMappedWrite8
502 * @abstract Write one byte to the desired "Physical" IOSpace address.
503 * @discussion Write one byte to the desired "Physical" IOSpace address. This function allows the developer to write to an address returned from any memory descriptor's getPhysicalSegment routine.
504 * @param address The desired address, as returned by IOMemoryDescriptor::getPhysicalSegment.
505 * @param value Data to be writen to the desired location */
506
507 void IOMappedWrite8(IOPhysicalAddress address, UInt8 value);
508
509 /*! @function IOMappedWrite16
510 * @abstract Write two bytes to the desired "Physical" IOSpace address.
511 * @discussion Write two bytes to the desired "Physical" IOSpace address. This function allows the developer to write to an address returned from any memory descriptor's getPhysicalSegment routine.
512 * @param address The desired address, as returned by IOMemoryDescriptor::getPhysicalSegment.
513 * @param value Data to be writen to the desired location */
514
515 void IOMappedWrite16(IOPhysicalAddress address, UInt16 value);
516
517 /*! @function IOMappedWrite32
518 * @abstract Write four bytes to the desired "Physical" IOSpace address.
519 * @discussion Write four bytes to the desired "Physical" IOSpace address. This function allows the developer to write to an address returned from any memory descriptor's getPhysicalSegment routine.
520 * @param address The desired address, as returned by IOMemoryDescriptor::getPhysicalSegment.
521 * @param value Data to be writen to the desired location */
522
523 void IOMappedWrite32(IOPhysicalAddress address, UInt32 value);
524
525 /*! @function IOMappedWrite64
526 * @abstract Write eight bytes to the desired "Physical" IOSpace address.
527 * @discussion Write eight bytes to the desired "Physical" IOSpace address. This function allows the developer to write to an address returned from any memory descriptor's getPhysicalSegment routine.
528 * @param address The desired address, as returned by IOMemoryDescriptor::getPhysicalSegment.
529 * @param value Data to be writen to the desired location */
530
531 void IOMappedWrite64(IOPhysicalAddress address, UInt64 value);
532
533 /* This function is deprecated. Cache settings may be set for allocated memory with the IOBufferMemoryDescriptor api. */
534
535 IOReturn IOSetProcessorCacheMode( task_t task, IOVirtualAddress address,
536 IOByteCount length, IOOptionBits cacheMode ) __attribute__((deprecated));
537
538 /*! @function IOFlushProcessorCache
539 * @abstract Flushes the processor cache for mapped memory.
540 * @discussion This function flushes the processor cache of an already mapped memory range. Note in most cases it is preferable to use IOMemoryDescriptor::prepare and complete to manage cache coherency since they are aware of the architecture's requirements. Flushing the processor cache is not required for coherency in most situations.
541 * @param task Task the memory is mapped into.
542 * @param address Virtual address of the memory.
543 * @param length Length of the range to set.
544 * @result An IOReturn code. */
545
546 IOReturn IOFlushProcessorCache( task_t task, IOVirtualAddress address,
547 IOByteCount length );
548
549 /*! @function IOThreadSelf
550 * @abstract Returns the osfmk identifier for the currently running thread.
551 * @discussion This function returns the current thread (a pointer to the currently active osfmk thread_shuttle). */
552
553 #define IOThreadSelf() (current_thread())
554
555 /*! @function IOCreateThread
556 * @abstract Deprecated function - use kernel_thread_start(). Create a kernel thread.
557 * @discussion This function creates a kernel thread, and passes the caller supplied argument to the new thread. Warning: the value returned by this function is not 100% reliable. There is a race condition where it is possible that the new thread has already terminated before this call returns. Under that circumstance the IOThread returned will be invalid. In general there is little that can be done with this value except compare it against 0. The thread itself can call IOThreadSelf() 100% reliably and that is the prefered mechanism to manipulate the IOThreads state.
558 * @param function A C-function pointer where the thread will begin execution.
559 * @param argument Caller specified data to be passed to the new thread.
560 * @result An IOThread identifier for the new thread, equivalent to an osfmk thread_t. */
561
562 IOThread IOCreateThread(IOThreadFunc function, void *argument) __attribute__((deprecated));
563
564 /*! @function IOExitThread
565 * @abstract Deprecated function - use thread_terminate(). Terminate execution of current thread.
566 * @discussion This function destroys the currently running thread, and does not return. */
567
568 void IOExitThread(void) __attribute__((deprecated));
569
570 /*! @function IOSleep
571 * @abstract Sleep the calling thread for a number of milliseconds.
572 * @discussion This function blocks the calling thread for at least the number of specified milliseconds, giving time to other processes.
573 * @param milliseconds The integer number of milliseconds to wait. */
574
575 void IOSleep(unsigned milliseconds);
576
577 /*! @function IOSleepWithLeeway
578 * @abstract Sleep the calling thread for a number of milliseconds, with a specified leeway the kernel may use for timer coalescing.
579 * @discussion This function blocks the calling thread for at least the number of specified milliseconds, giving time to other processes. The kernel may also coalesce any timers involved in the delay, using the leeway given as a guideline.
580 * @param intervalMilliseconds The integer number of milliseconds to wait.
581 * @param leewayMilliseconds The integer number of milliseconds to use as a timer coalescing guideline. */
582
583 void IOSleepWithLeeway(unsigned intervalMilliseconds, unsigned leewayMilliseconds);
584
585 /*! @function IODelay
586 * @abstract Spin delay for a number of microseconds.
587 * @discussion This function spins to delay for at least the number of specified microseconds. Since the CPU is busy spinning no time is made available to other processes; this method of delay should be used only for short periods. Also, the AbsoluteTime based APIs of kern/clock.h provide finer grained and lower cost delays.
588 * @param microseconds The integer number of microseconds to spin wait. */
589
590 void IODelay(unsigned microseconds);
591
592 /*! @function IOPause
593 * @abstract Spin delay for a number of nanoseconds.
594 * @discussion This function spins to delay for at least the number of specified nanoseconds. Since the CPU is busy spinning no time is made available to other processes; this method of delay should be used only for short periods.
595 * @param nanoseconds The integer number of nanoseconds to spin wait. */
596
597 void IOPause(unsigned nanoseconds);
598
599 /*! @function IOLog
600 * @abstract Log a message to console in text mode, and /var/log/system.log.
601 * @discussion This function allows a driver to log diagnostic information to the screen during verbose boots, and to a log file found at /var/log/system.log. IOLog should not be called from interrupt context.
602 * @param format A printf() style format string (see printf(3) documentation).
603 */
604
605 void IOLog(const char *format, ...)
606 __attribute__((format(printf, 1, 2)));
607
608 /*! @function IOLogv
609 * @abstract Log a message to console in text mode, and /var/log/system.log.
610 * @discussion This function allows a driver to log diagnostic information to the screen during verbose boots, and to a log file found at /var/log/system.log. IOLogv should not be called from interrupt context.
611 * @param format A printf() style format string (see printf(3) documentation).
612 * @param ap stdarg(3) style variable arguments. */
613
614 void IOLogv(const char *format, va_list ap)
615 __attribute__((format(printf, 1, 0)));
616
617 #ifndef _FN_KPRINTF
618 #define _FN_KPRINTF
619 void kprintf(const char *format, ...) __printflike(1, 2);
620 #endif
621 #ifndef _FN_KPRINTF_DECLARED
622 #define _FN_KPRINTF_DECLARED
623 #endif
624
625 /*
626 * Convert a integer constant (typically a #define or enum) to a string
627 * via an array of IONamedValue.
628 */
629 const char *IOFindNameForValue(int value,
630 const IONamedValue *namedValueArray);
631
632 /*
633 * Convert a string to an int via an array of IONamedValue. Returns
634 * kIOReturnSuccess of string found, else returns kIOReturnBadArgument.
635 */
636 IOReturn IOFindValueForName(const char *string,
637 const IONamedValue *regValueArray,
638 int *value); /* RETURNED */
639
640 /*! @function Debugger
641 * @abstract Enter the kernel debugger.
642 * @discussion This function freezes the kernel and enters the builtin debugger. It may not be possible to exit the debugger without a second machine.
643 * @param reason A C-string to describe why the debugger is being entered. */
644
645 void Debugger(const char * reason);
646 #if __LP64__
647 #define IOPanic(reason) panic("%s", reason)
648 #else
649 void IOPanic(const char *reason) __attribute__((deprecated)) __abortlike;
650 #endif
651
652 #ifdef __cplusplus
653 class OSDictionary;
654 #endif
655
656 #ifdef __cplusplus
657 OSDictionary *
658 #else
659 struct OSDictionary *
660 #endif
661 IOBSDNameMatching( const char * name );
662
663 #ifdef __cplusplus
664 OSDictionary *
665 #else
666 struct OSDictionary *
667 #endif
668 IOOFPathMatching( const char * path, char * buf, int maxLen ) __attribute__((deprecated));
669
670 /*
671 * Convert between size and a power-of-two alignment.
672 */
673 IOAlignment IOSizeToAlignment(unsigned int size);
674 unsigned int IOAlignmentToSize(IOAlignment align);
675
676 /*
677 * Multiply and divide routines for IOFixed datatype.
678 */
679
680 static inline IOFixed
IOFixedMultiply(IOFixed a,IOFixed b)681 IOFixedMultiply(IOFixed a, IOFixed b)
682 {
683 return (IOFixed)((((SInt64) a) * ((SInt64) b)) >> 16);
684 }
685
686 static inline IOFixed
IOFixedDivide(IOFixed a,IOFixed b)687 IOFixedDivide(IOFixed a, IOFixed b)
688 {
689 return (IOFixed)((((SInt64) a) << 16) / ((SInt64) b));
690 }
691
692 /*
693 * IORound and IOTrunc convenience functions, in the spirit
694 * of vm's round_page() and trunc_page().
695 */
696 #define IORound(value, multiple) \
697 ((((value) + (multiple) - 1) / (multiple)) * (multiple))
698
699 #define IOTrunc(value, multiple) \
700 (((value) / (multiple)) * (multiple));
701
702
703 #if defined(__APPLE_API_OBSOLETE)
704
705 /* The following API is deprecated */
706
707 /* The API exported by kern/clock.h
708 * should be used for high resolution timing. */
709
710 void IOGetTime( mach_timespec_t * clock_time) __attribute__((deprecated));
711
712 #if !defined(__LP64__)
713
714 #undef eieio
715 #define eieio() \
716 OSSynchronizeIO()
717
718 extern mach_timespec_t IOZeroTvalspec;
719
720 #endif /* !defined(__LP64__) */
721
722 #endif /* __APPLE_API_OBSOLETE */
723
724 #if XNU_KERNEL_PRIVATE
725 vm_tag_t
726 IOMemoryTag(vm_map_t map);
727
728 vm_size_t
729 log2up(vm_size_t size);
730 #endif
731
732 /*
733 * Implementation details
734 */
735 #define __IOKIT_COUNT_ARGS1(a0, a1, a2, a3, a4, a5, a6, a7, a8, a9, N, ...) N
736 #define __IOKIT_COUNT_ARGS(...) \
737 __IOKIT_COUNT_ARGS1(, ##__VA_ARGS__, _9, _8, _7, _6, _5, _4, _3, _2, _1, _0)
738 #define __IOKIT_DISPATCH1(base, N, ...) __CONCAT(base, N)(__VA_ARGS__)
739 #define __IOKIT_DISPATCH(base, ...) \
740 __IOKIT_DISPATCH1(base, __IOKIT_COUNT_ARGS(__VA_ARGS__), ##__VA_ARGS__)
741
742
743 #ifdef XNU_KERNEL_PRIVATE
744
745 #define IOFREETYPE_ASSERT_COMPATIBLE_POINTER(ptr, type) \
746 KALLOC_TYPE_ASSERT_COMPATIBLE_POINTER(ptr, type)
747
748 #else /* XNU_KERNEL_PRIVATE */
749
750 #define IOFREETYPE_ASSERT_COMPATIBLE_POINTER(ptr, type) do {} while (0)
751
752 #endif /* XNU_KERNEL_PRIVATE */
753
754 #if KERNEL_PRIVATE
755 /*
756 * Implementation functions for IOMallocType/IOFreeType.
757 * Not intended to be used on their own.
758 */
759 void *
760 IOMallocTypeImpl(kalloc_type_view_t kt_view);
761
762 void
763 IOFreeTypeImpl(kalloc_type_view_t kt_view, void * address);
764
765 void *
766 IOMallocTypeVarImpl(kalloc_type_var_view_t kt_view, vm_size_t size);
767
768 void
769 IOFreeTypeVarImpl(kalloc_type_var_view_t kt_view, void * address, vm_size_t size);
770 #endif
771
772 #if KERNEL_PRIVATE
773 #if __cplusplus
774
775 #if __has_feature(cxx_deleted_functions)
776 #define __IODeleteArrayOperators() \
777 _Pragma("clang diagnostic push") \
778 _Pragma("clang diagnostic ignored \"-Wc++98-compat\"") \
779 void *operator new[](size_t) = delete; \
780 void operator delete[](void *) = delete; \
781 void operator delete[](void *, size_t) = delete; \
782 _Pragma("clang diagnostic pop")
783 #else /* __has_feature(cxx_deleted_functions) */
784 #define __IODeleteArrayOperators()
785 #endif /* __has_feature(cxx_deleted_functions) */
786
787 #define __IOAddOperatorsSentinel(name, type) \
788 static void __CONCAT(name, type) (void) __unused
789
790 #define __IOAddTypedOperatorsSentinel(type) \
791 __IOAddOperatorsSentinel(__kt_typed_operators_, type)
792
793 #define __IOAddTypedArrayOperatorsSentinel(type) \
794 __IOAddOperatorsSentinel(__kt_typed_array_operators_, type)
795
796 #define __IODeclareTypedOperators(type) \
797 void *operator new(size_t size __unused); \
798 void operator delete(void *mem, size_t size __unused); \
799 __IOAddTypedOperatorsSentinel(type)
800
801 #define __IODeclareTypedArrayOperators(type) \
802 void *operator new[](size_t __unused); \
803 void operator delete[](void *ptr); \
804 __IOAddTypedArrayOperatorsSentinel(type)
805
806
807 #define __IODefineTypedOperators(type) \
808 void *type::operator new(size_t size __unused) \
809 { \
810 return IOMallocType(type); \
811 } \
812 void type::operator delete(void *mem, size_t size __unused) \
813 { \
814 IOFreeType(mem, type); \
815 }
816
817
818 extern "C++" {
819 template<typename T>
820 struct __IOTypedOperatorsArrayHeader {
821 size_t alloc_size;
822 _Alignas(T) char array[];
823 };
824
825 #define __IOTypedOperatorNewArrayImpl(type, count) \
826 { \
827 typedef __IOTypedOperatorsArrayHeader<type> hdr_ty; \
828 static KALLOC_TYPE_VAR_DEFINE(kt_view_var, \
829 hdr_ty, type, KT_SHARED_ACCT); \
830 hdr_ty *hdr; \
831 const size_t __s = sizeof(hdr_ty) + count; \
832 hdr = reinterpret_cast<hdr_ty *>( \
833 IOMallocTypeVarImpl(kt_view_var, __s)); \
834 if (hdr) { \
835 hdr->alloc_size = __s; \
836 return reinterpret_cast<void *>(&hdr->array); \
837 } \
838 _Pragma("clang diagnostic push") \
839 _Pragma("clang diagnostic ignored \"-Wnew-returns-null\"") \
840 return NULL; \
841 _Pragma("clang diagnostic pop") \
842 }
843
844 #define __IOTypedOperatorDeleteArrayImpl(type, ptr) \
845 { \
846 typedef __IOTypedOperatorsArrayHeader<type> hdr_ty; \
847 static KALLOC_TYPE_VAR_DEFINE(kt_view_var, \
848 hdr_ty, type, KT_SHARED_ACCT); \
849 hdr_ty *hdr = reinterpret_cast<hdr_ty *>( \
850 reinterpret_cast<uintptr_t>(ptr) - sizeof(*hdr)); \
851 IOFreeTypeVarImpl(kt_view_var, \
852 reinterpret_cast<void *>(hdr), hdr->alloc_size); \
853 }
854
855 #define __IODefineTypedArrayOperators(type) \
856 void *type::operator new[](size_t count) \
857 __IOTypedOperatorNewArrayImpl(type, count) \
858 void type::operator delete[](void *ptr) \
859 __IOTypedOperatorDeleteArrayImpl(type, ptr)
860
861
862 #define __IOOverrideTypedOperators(type) \
863 void *operator new(size_t size __unused) \
864 { \
865 return IOMallocType(type); \
866 } \
867 void operator delete(void *mem, size_t size __unused) \
868 { \
869 IOFreeType(mem, type); \
870 } \
871 __IOAddTypedOperatorsSentinel(type)
872
873 #define __IOOverrideTypedArrayOperators(type) \
874 void *operator new[](size_t count) \
875 __IOTypedOperatorNewArrayImpl(type, count) \
876 void operator delete[](void *ptr) \
877 __IOTypedOperatorDeleteArrayImpl(type, ptr) \
878 __IOAddTypedArrayOperatorsSentinel(type)
879
880 /*!
881 * @macro IODeclareTypedOperators
882 *
883 * @abstract
884 * Declare operator new/delete to adopt the typed allocator
885 * API for a given class/struct. It must be paired with
886 * @c IODefineTypedOperators.
887 *
888 * @discussion
889 * Use this macro within a class/struct declaration to declare
890 * @c operator new and @c operator delete to use the typed
891 * allocator API as the backing storage for this type.
892 *
893 * @note The default variant deletes the declaration of the
894 * array operators. Please see doc/allocators/api-basics.md for
895 * more details regarding their usage.
896 *
897 * @param type The type which the declarations are being provided for.
898 */
899 #define IODeclareTypedOperatorsSupportingArrayOperators(type) \
900 __IODeclareTypedArrayOperators(type); \
901 __IODeclareTypedOperators(type)
902 #define IODeclareTypedOperators(type) \
903 __IODeleteArrayOperators() \
904 __IODeclareTypedOperators(type)
905
906 /*!
907 * @macro IODefineTypedOperators
908 *
909 * @abstract
910 * Define (out of line) operator new/delete to adopt the typed
911 * allocator API for a given class/struct. It must be paired
912 * with @c IODeclareTypedOperators.
913 *
914 * @discussion
915 * Use this macro to provide an out of line definition of
916 * @c operator new and @c operator delete for a given type
917 * to use the typed allocator API as its backing storage.
918 *
919 * @param type The type which the overrides are being provided for.
920 */
921 #define IODefineTypedOperatorsSupportingArrayOperators(type) \
922 __IODefineTypedOperators(type) \
923 __IODefineTypedArrayOperators(type)
924 #define IODefineTypedOperators(type) \
925 __IODefineTypedOperators(type)
926
927 /*!
928 * @macro IOOverrideTypedOperators
929 *
930 * @abstract
931 * Override operator new/delete to use @c kalloc_type.
932 *
933 * @discussion
934 * Use this macro within a class/struct declaration to override
935 * @c operator new and @c operator delete to use the typed
936 * allocator API as the backing storage for this type.
937 *
938 * @note The default variant deletes the implementation of the
939 * array operators. Please see doc/allocators/api-basics.md for
940 * more details regarding their usage.
941 *
942 * @param type The type which the overrides are being provided for.
943 */
944 #define IOOverrideTypedOperators(type) \
945 __IODeleteArrayOperators() \
946 __IOOverrideTypedOperators(type)
947
948 #define IOOverrideTypedOperatorsSupportingArrayOperators(type) \
949 __IOOverrideTypedArrayOperators(type); \
950 __IOOverrideTypedOperators(type)
951
952
953 /*!
954 * @template IOTypedOperatorsMixin
955 *
956 * @abstract
957 * Mixin that implements @c operator new and @c operator delete
958 * using the typed allocator API.
959 *
960 * @discussion
961 * Inherit from this struct in order to adopt the typed allocator
962 * API on a struct/class for @c operator new and @c operator delete.
963 *
964 * The type passed as as a template parameter must be the type
965 * which is inheriting from the struct itself.
966 *
967 * @note See doc/allocators/api-basics.md for more details
968 * regarding the usage of the mixin.
969 *
970 * @example
971 *
972 * class C : public IOTypedOperatorsMixin<C> {
973 * ...
974 * }
975 * C *obj = new C;
976 *
977 */
978 template<class T>
979 struct IOTypedOperatorsMixin {
980 IOOverrideTypedOperators(T);
981 };
982
983 template<class T>
984 struct IOTypedOperatorsMixinSupportingArrayOperators {
985 IOOverrideTypedOperatorsSupportingArrayOperators(T);
986 };
987 } // extern "C++"
988
989
990 #endif /* __cplusplus */
991 #endif /* KERNEL_PRIVATE */
992
993 __END_DECLS
994
995 #endif /* !__IOKIT_IOLIB_H */
996