1 /* 2 * Copyright (c) 1998-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 #ifndef _IOBUFFERMEMORYDESCRIPTOR_H 29 #define _IOBUFFERMEMORYDESCRIPTOR_H 30 31 #include <libkern/c++/OSPtr.h> 32 #include <IOKit/IOMemoryDescriptor.h> 33 #include <DriverKit/IOBufferMemoryDescriptor.h> 34 35 enum { 36 kIOMemoryPhysicallyContiguous = 0x00000010, 37 kIOMemoryPageable = 0x00000020, 38 kIOMemoryPurgeable = 0x00000040, 39 kIOMemoryHostPhysicallyContiguous = 0x00000080, 40 kIOMemorySharingTypeMask = 0x000f0000, 41 kIOMemoryUnshared = 0x00000000, 42 kIOMemoryKernelUserShared = 0x00010000, 43 // shared IOMemoryDescriptor options for IOBufferMemoryDescriptor: 44 kIOBufferDescriptorMemoryFlags = kIOMemoryDirectionMask 45 #ifdef XNU_KERNEL_PRIVATE 46 | kIOMemoryAutoPrepare 47 #endif 48 | kIOMemoryThreadSafe 49 | kIOMemoryClearEncrypt 50 | kIOMemoryMapperNone 51 | kIOMemoryUseReserve 52 }; 53 54 #define _IOBUFFERMEMORYDESCRIPTOR_INTASKWITHOPTIONS_ 1 55 #define _IOBUFFERMEMORYDESCRIPTOR_HOSTPHYSICALLYCONTIGUOUS_ 1 56 #define IOBUFFERMEMORYDESCRIPTOR_SUPPORTS_INTASKWITHOPTIONS_TAGS 1 57 /*! 58 * @class IOBufferMemoryDescriptor 59 * @abstract Provides a simple memory descriptor that allocates its own buffer memory. 60 */ 61 62 class IOBufferMemoryDescriptor : public IOGeneralMemoryDescriptor 63 { 64 OSDeclareDefaultStructorsWithDispatch(IOBufferMemoryDescriptor); 65 66 private: 67 /*! @struct ExpansionData 68 * @discussion This structure will be used to expand the capablilties of this class in the future. 69 */ 70 struct ExpansionData { 71 IOMemoryMap * map; 72 }; 73 74 /*! @var reserved 75 * Reserved for future use. (Internal use only) */ 76 APPLE_KEXT_WSHADOW_PUSH; 77 ExpansionData * reserved; 78 79 protected: 80 void * _buffer; 81 vm_size_t _capacity; 82 vm_offset_t _alignment; 83 IOOptionBits _options; 84 private: 85 uintptr_t _internalReserved; 86 unsigned _internalFlags; 87 APPLE_KEXT_WSHADOW_POP; 88 89 private: 90 #ifndef __LP64__ 91 virtual bool initWithOptions( 92 IOOptionBits options, 93 vm_size_t capacity, 94 vm_offset_t alignment, 95 task_t inTask) APPLE_KEXT_DEPRECATED; /* use withOptions() instead */ 96 #endif /* !__LP64__ */ 97 98 public: 99 virtual bool initWithPhysicalMask( 100 task_t inTask, 101 IOOptionBits options, 102 mach_vm_size_t capacity, 103 mach_vm_address_t alignment, 104 mach_vm_address_t physicalMask); 105 106 #ifdef XNU_KERNEL_PRIVATE 107 /* 108 * By default the buffer allocated in IOBufferMemoryDescriptor is 109 * considered to contain "pure data" and no kernel pointers. It 110 * is therefore colocated with other data buffers. 111 * 112 * This API allows to create a buffer that contains pointers and 113 * will not be redirected to the data heap/map. 114 */ 115 bool initControlWithPhysicalMask( 116 task_t inTask, 117 IOOptionBits options, 118 mach_vm_size_t capacity, 119 mach_vm_address_t alignment, 120 mach_vm_address_t physicalMask); 121 #endif 122 123 #ifdef KERNEL_PRIVATE 124 /* 125 * Create an IOBufferMemoryDescriptor with guard pages on each side of the buffer allocation. 126 * @param inTask The task the buffer will be allocated in. 127 * @param options Options for the IOBufferMemoryDescriptor. See inTaskWithOptions for a description of available options. 128 * Some options are not available when using guard pages. Specifically, physically contiguous memory and pageable memory 129 * options are not supported. If these options are used, this will fail to create the memory descriptor and return NULL. 130 * @param capacity The number of bytes to allocate. Due to how memory with guard pages is allocated, this will be rounded up to page size. 131 * The buffer will also always be aligned to the page size. 132 * @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory descriptor and associated buffer. 133 */ 134 static OSPtr<IOBufferMemoryDescriptor> inTaskWithGuardPages( 135 task_t inTask, 136 IOOptionBits options, 137 mach_vm_size_t capacity); 138 139 bool initWithGuardPages( 140 task_t inTask, 141 IOOptionBits options, 142 mach_vm_size_t capacity); 143 #endif 144 145 #ifdef __LP64__ 146 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 0); 147 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 1); 148 #else /* !__LP64__ */ 149 OSMetaClassDeclareReservedUsedX86(IOBufferMemoryDescriptor, 0); 150 OSMetaClassDeclareReservedUsedX86(IOBufferMemoryDescriptor, 1); 151 #endif /* !__LP64__ */ 152 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 2); 153 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 3); 154 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 4); 155 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 5); 156 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 6); 157 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 7); 158 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 8); 159 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 9); 160 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 10); 161 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 11); 162 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 12); 163 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 13); 164 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 14); 165 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 15); 166 167 protected: 168 virtual void free() APPLE_KEXT_OVERRIDE; 169 170 public: 171 172 /* 173 * withOptions: 174 * 175 * Returns a new IOBufferMemoryDescriptor with a buffer large enough to 176 * hold capacity bytes. The descriptor's length is initially set to the 177 * capacity. 178 */ 179 #ifndef __LP64__ 180 virtual bool initWithOptions( IOOptionBits options, 181 vm_size_t capacity, 182 vm_offset_t alignment) APPLE_KEXT_DEPRECATED; /* use withOptions() instead */ 183 #endif /* !__LP64__ */ 184 185 static OSPtr<IOBufferMemoryDescriptor> withCopy( 186 task_t inTask, 187 IOOptionBits options, 188 vm_map_t sourceMap, 189 mach_vm_address_t source, 190 mach_vm_size_t size); 191 192 static OSPtr<IOBufferMemoryDescriptor> withOptions( IOOptionBits options, 193 vm_size_t capacity, 194 vm_offset_t alignment = 1); 195 196 /*! @function inTaskWithOptions 197 * @abstract Creates a memory buffer with memory descriptor for that buffer. 198 * @discussion Added in Mac OS X 10.2, this method allocates a memory buffer with a given size and alignment in the task's address space specified, and returns a memory descriptor instance representing the memory. It is recommended that memory allocated for I/O or sharing via mapping be created via IOBufferMemoryDescriptor. Options passed with the request specify the kind of memory to be allocated - pageablity and sharing are specified with option bits. This function may block and so should not be called from interrupt level or while a simple lock is held. 199 * @param inTask The task the buffer will be allocated in. 200 * @param options Options for the allocation:<br> 201 * kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br> 202 * kIOMemoryPhysicallyContiguous - pass to request memory be physically contiguous. This option is heavily discouraged. The request may fail if memory is fragmented, may cause large amounts of paging activity, and may take a very long time to execute.<br> 203 * kIOMemoryPageable - pass to request memory be non-wired - the default for kernel allocated memory is wired.<br> 204 * kIOMemoryPurgeable - pass to request memory that may later have its purgeable state set with IOMemoryDescriptor::setPurgeable. Only supported for kIOMemoryPageable allocations.<br> 205 * kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.<br> 206 * kIOMapInhibitCache - allocate memory with inhibited cache setting. <br> 207 * kIOMapWriteThruCache - allocate memory with writethru cache setting. <br> 208 * kIOMapCopybackCache - allocate memory with copyback cache setting. <br> 209 * kIOMapWriteCombineCache - allocate memory with writecombined cache setting. 210 * @param capacity The number of bytes to allocate. 211 * @param alignment The minimum required alignment of the buffer in bytes - 1 is the default for no required alignment. For example, pass 256 to get memory allocated at an address with bits 0-7 zero. 212 * @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */ 213 214 static OSPtr<IOBufferMemoryDescriptor> inTaskWithOptions( 215 task_t inTask, 216 IOOptionBits options, 217 vm_size_t capacity, 218 vm_offset_t alignment = 1); 219 220 /*! @function inTaskWithOptions 221 * @abstract Creates a memory buffer with memory descriptor for that buffer. 222 * @discussion Added in Mac OS X 10.2, this method allocates a memory buffer with a given size and alignment in the task's address space specified, and returns a memory descriptor instance representing the memory. It is recommended that memory allocated for I/O or sharing via mapping be created via IOBufferMemoryDescriptor. Options passed with the request specify the kind of memory to be allocated - pageablity and sharing are specified with option bits. This function may block and so should not be called from interrupt level or while a simple lock is held. 223 * @param inTask The task the buffer will be allocated in. 224 * @param options Options for the allocation:<br> 225 * kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br> 226 * kIOMemoryPhysicallyContiguous - pass to request memory be physically contiguous. This option is heavily discouraged. The request may fail if memory is fragmented, may cause large amounts of paging activity, and may take a very long time to execute.<br> 227 * kIOMemoryPageable - pass to request memory be non-wired - the default for kernel allocated memory is wired.<br> 228 * kIOMemoryPurgeable - pass to request memory that may later have its purgeable state set with IOMemoryDescriptor::setPurgeable. Only supported for kIOMemoryPageable allocations.<br> 229 * kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.<br> 230 * kIOMapInhibitCache - allocate memory with inhibited cache setting. <br> 231 * kIOMapWriteThruCache - allocate memory with writethru cache setting. <br> 232 * kIOMapCopybackCache - allocate memory with copyback cache setting. <br> 233 * kIOMapWriteCombineCache - allocate memory with writecombined cache setting. 234 * @param capacity The number of bytes to allocate. 235 * @param alignment The minimum required alignment of the buffer in bytes - 1 is the default for no required alignment. For example, pass 256 to get memory allocated at an address with bits 0-7 zero. 236 * @param kernTag The kernel memory tag 237 * @param userTag The user memory tag 238 * @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */ 239 240 static OSPtr<IOBufferMemoryDescriptor> inTaskWithOptions( 241 task_t inTask, 242 IOOptionBits options, 243 vm_size_t capacity, 244 vm_offset_t alignment, 245 uint32_t kernTag, 246 uint32_t userTag); 247 248 /*! @function inTaskWithPhysicalMask 249 * @abstract Creates a memory buffer with memory descriptor for that buffer. 250 * @discussion Added in Mac OS X 10.5, this method allocates a memory buffer with a given size and alignment in the task's address space specified, and returns a memory descriptor instance representing the memory. It is recommended that memory allocated for I/O or sharing via mapping be created via IOBufferMemoryDescriptor. Options passed with the request specify the kind of memory to be allocated - pageablity and sharing are specified with option bits. This function may block and so should not be called from interrupt level or while a simple lock is held. 251 * @param inTask The task the buffer will be mapped in. Pass NULL to create memory unmapped in any task (eg. for use as a DMA buffer). 252 * @param options Options for the allocation:<br> 253 * kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br> 254 * kIOMemoryPhysicallyContiguous - pass to request memory be physically contiguous. This option is heavily discouraged. The request may fail if memory is fragmented, may cause large amounts of paging activity, and may take a very long time to execute.<br> 255 * kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.<br> 256 * kIOMapInhibitCache - allocate memory with inhibited cache setting. <br> 257 * kIOMapWriteThruCache - allocate memory with writethru cache setting. <br> 258 * kIOMapCopybackCache - allocate memory with copyback cache setting. <br> 259 * kIOMapWriteCombineCache - allocate memory with writecombined cache setting. 260 * @param capacity The number of bytes to allocate. 261 * @param physicalMask The buffer will be allocated with pages such that physical addresses will only have bits set present in physicalMask. For example, pass 0x00000000FFFFFFFFULL for a buffer to be accessed by hardware that has 32 address bits. 262 * @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */ 263 264 static OSPtr<IOBufferMemoryDescriptor> inTaskWithPhysicalMask( 265 task_t inTask, 266 IOOptionBits options, 267 mach_vm_size_t capacity, 268 mach_vm_address_t physicalMask); 269 270 /* 271 * withCapacity: 272 * 273 * Returns a new IOBufferMemoryDescriptor with a buffer large enough to 274 * hold capacity bytes. The descriptor's length is initially set to the 275 * capacity. 276 */ 277 static OSPtr<IOBufferMemoryDescriptor> withCapacity( 278 vm_size_t capacity __xnu_data_size, 279 IODirection withDirection, 280 bool withContiguousMemory = false); 281 #ifndef __LP64__ 282 virtual bool initWithBytes(const void * bytes, 283 vm_size_t withLength, 284 IODirection withDirection, 285 bool withContiguousMemory = false) APPLE_KEXT_DEPRECATED; /* use withBytes() instead */ 286 #endif /* !__LP64__ */ 287 288 /* 289 * withBytes: 290 * 291 * Returns a new IOBufferMemoryDescriptor preloaded with bytes (copied). 292 * The descriptor's length and capacity are set to the input buffer's size. 293 */ 294 static OSPtr<IOBufferMemoryDescriptor> withBytes( 295 const void * bytes, 296 vm_size_t withLength __xnu_data_size, 297 IODirection withDirection, 298 bool withContiguousMemory = false); 299 300 /* 301 * setLength: 302 * 303 * Change the buffer length of the memory descriptor. When a new buffer 304 * is created, the initial length of the buffer is set to be the same as 305 * the capacity. The length can be adjusted via setLength for a shorter 306 * transfer (there is no need to create more buffer descriptors when you 307 * can reuse an existing one, even for different transfer sizes). Note 308 * that the specified length must not exceed the capacity of the buffer. 309 */ 310 virtual void setLength(vm_size_t length); 311 312 /* 313 * setDirection: 314 * 315 * Change the direction of the transfer. This method allows one to redirect 316 * the descriptor's transfer direction. This eliminates the need to destroy 317 * and create new buffers when different transfer directions are needed. 318 */ 319 virtual void setDirection(IODirection direction); 320 321 /* 322 * getCapacity: 323 * 324 * Get the buffer capacity 325 */ 326 virtual vm_size_t getCapacity() const; 327 328 /* 329 * getBytesNoCopy: 330 * 331 * Return the virtual address of the beginning of the buffer 332 */ 333 __xnu_returns_data_pointer 334 virtual void *getBytesNoCopy(); 335 336 /* 337 * getBytesNoCopy: 338 * 339 * Return the virtual address of an offset from the beginning of the buffer 340 */ 341 __xnu_returns_data_pointer 342 virtual void *getBytesNoCopy(vm_size_t start, vm_size_t withLength); 343 344 /* 345 * appendBytes: 346 * 347 * Add some data to the end of the buffer. This method automatically 348 * maintains the memory descriptor buffer length. Note that appendBytes 349 * will not copy past the end of the memory descriptor's current capacity. 350 */ 351 virtual bool appendBytes(const void *bytes, vm_size_t withLength __xnu_data_size); 352 353 #ifndef __LP64__ 354 virtual void * getVirtualSegment(IOByteCount offset, 355 IOByteCount * length) APPLE_KEXT_OVERRIDE APPLE_KEXT_DEPRECATED; /* use getBytesNoCopy() instead */ 356 #endif /* !__LP64__ */ 357 }; 358 359 #endif /* !_IOBUFFERMEMORYDESCRIPTOR_H */ 360