1 /* 2 * Copyright (c) 1998-2000 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 #ifndef _IOBUFFERMEMORYDESCRIPTOR_H 29 #define _IOBUFFERMEMORYDESCRIPTOR_H 30 31 #include <IOKit/IOMemoryDescriptor.h> 32 33 enum { 34 kIOMemoryPhysicallyContiguous = 0x00000010, 35 kIOMemoryPageable = 0x00000020, 36 kIOMemoryPurgeable = 0x00000040, 37 kIOMemorySharingTypeMask = 0x000f0000, 38 kIOMemoryUnshared = 0x00000000, 39 kIOMemoryKernelUserShared = 0x00010000, 40 // shared IOMemoryDescriptor options for IOBufferMemoryDescriptor: 41 kIOBufferDescriptorMemoryFlags = kIOMemoryDirectionMask 42 #ifdef XNU_KERNEL_PRIVATE 43 | kIOMemoryAutoPrepare 44 #endif 45 | kIOMemoryThreadSafe 46 | kIOMemoryClearEncrypt 47 }; 48 49 #define _IOBUFFERMEMORYDESCRIPTOR_INTASKWITHOPTIONS_ 1 50 /*! 51 @class IOBufferMemoryDescriptor 52 @abstract Provides a simple memory descriptor that allocates its own buffer memory. 53 */ 54 55 class IOBufferMemoryDescriptor : public IOGeneralMemoryDescriptor 56 { 57 OSDeclareDefaultStructors(IOBufferMemoryDescriptor); 58 59 private: 60 /*! @struct ExpansionData 61 @discussion This structure will be used to expand the capablilties of this class in the future. 62 */ 63 struct ExpansionData { 64 IOMemoryMap * map; 65 }; 66 67 /*! @var reserved 68 Reserved for future use. (Internal use only) */ 69 ExpansionData * reserved; 70 71 protected: 72 void * _buffer; 73 vm_size_t _capacity; 74 vm_offset_t _alignment; 75 IOOptionBits _options; 76 private: 77 uintptr_t _internalReserved; 78 unsigned _internalFlags; 79 80 private: 81 #ifndef __LP64__ 82 virtual bool initWithOptions( 83 IOOptionBits options, 84 vm_size_t capacity, 85 vm_offset_t alignment, 86 task_t inTask) APPLE_KEXT_DEPRECATED; /* use withOptions() instead */ 87 #endif /* !__LP64__ */ 88 89 public: 90 virtual bool initWithPhysicalMask( 91 task_t inTask, 92 IOOptionBits options, 93 mach_vm_size_t capacity, 94 mach_vm_address_t alignment, 95 mach_vm_address_t physicalMask); 96 97 #ifdef __LP64__ 98 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 0); 99 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 1); 100 #else /* !__LP64__ */ 101 OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 0); 102 OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 1); 103 #endif /* !__LP64__ */ 104 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 2); 105 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 3); 106 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 4); 107 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 5); 108 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 6); 109 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 7); 110 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 8); 111 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 9); 112 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 10); 113 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 11); 114 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 12); 115 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 13); 116 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 14); 117 OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 15); 118 119 protected: 120 virtual void free(); 121 122 public: 123 124 /* 125 * withOptions: 126 * 127 * Returns a new IOBufferMemoryDescriptor with a buffer large enough to 128 * hold capacity bytes. The descriptor's length is initially set to the 129 * capacity. 130 */ 131 #ifndef __LP64__ 132 virtual bool initWithOptions( IOOptionBits options, 133 vm_size_t capacity, 134 vm_offset_t alignment) APPLE_KEXT_DEPRECATED; /* use withOptions() instead */ 135 #endif /* !__LP64__ */ 136 137 static IOBufferMemoryDescriptor * withOptions( IOOptionBits options, 138 vm_size_t capacity, 139 vm_offset_t alignment = 1); 140 141 /*! @function inTaskWithOptions 142 @abstract Creates a memory buffer with memory descriptor for that buffer. 143 @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. 144 @param inTask The task the buffer will be allocated in. 145 @param options Options for the allocation:<br> 146 kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br> 147 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> 148 kIOMemoryPageable - pass to request memory be non-wired - the default for kernel allocated memory is wired.<br> 149 kIOMemoryPurgeable - pass to request memory that may later have its purgeable state set with IOMemoryDescriptor::setPurgeable. Only supported for kIOMemoryPageable allocations.<br> 150 kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.<br> 151 kIOMapInhibitCache - allocate memory with inhibited cache setting. <br> 152 kIOMapWriteThruCache - allocate memory with writethru cache setting. <br> 153 kIOMapCopybackCache - allocate memory with copyback cache setting. <br> 154 kIOMapWriteCombineCache - allocate memory with writecombined cache setting. 155 @param capacity The number of bytes to allocate. 156 @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. 157 @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */ 158 159 static IOBufferMemoryDescriptor * inTaskWithOptions( 160 task_t inTask, 161 IOOptionBits options, 162 vm_size_t capacity, 163 vm_offset_t alignment = 1); 164 165 /*! @function inTaskWithPhysicalMask 166 @abstract Creates a memory buffer with memory descriptor for that buffer. 167 @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. 168 @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). 169 @param options Options for the allocation:<br> 170 kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br> 171 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> 172 kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.<br> 173 kIOMapInhibitCache - allocate memory with inhibited cache setting. <br> 174 kIOMapWriteThruCache - allocate memory with writethru cache setting. <br> 175 kIOMapCopybackCache - allocate memory with copyback cache setting. <br> 176 kIOMapWriteCombineCache - allocate memory with writecombined cache setting. 177 @param capacity The number of bytes to allocate. 178 @param mask 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. 179 @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */ 180 181 static IOBufferMemoryDescriptor * inTaskWithPhysicalMask( 182 task_t inTask, 183 IOOptionBits options, 184 mach_vm_size_t capacity, 185 mach_vm_address_t physicalMask); 186 187 /* 188 * withCapacity: 189 * 190 * Returns a new IOBufferMemoryDescriptor with a buffer large enough to 191 * hold capacity bytes. The descriptor's length is initially set to the 192 * capacity. 193 */ 194 static IOBufferMemoryDescriptor * withCapacity( 195 vm_size_t capacity, 196 IODirection withDirection, 197 bool withContiguousMemory = false); 198 #ifndef __LP64__ 199 virtual bool initWithBytes(const void * bytes, 200 vm_size_t withLength, 201 IODirection withDirection, 202 bool withContiguousMemory = false) APPLE_KEXT_DEPRECATED; /* use withBytes() instead */ 203 #endif /* !__LP64__ */ 204 205 /* 206 * withBytes: 207 * 208 * Returns a new IOBufferMemoryDescriptor preloaded with bytes (copied). 209 * The descriptor's length and capacity are set to the input buffer's size. 210 */ 211 static IOBufferMemoryDescriptor * withBytes( 212 const void * bytes, 213 vm_size_t withLength, 214 IODirection withDirection, 215 bool withContiguousMemory = false); 216 217 /* 218 * setLength: 219 * 220 * Change the buffer length of the memory descriptor. When a new buffer 221 * is created, the initial length of the buffer is set to be the same as 222 * the capacity. The length can be adjusted via setLength for a shorter 223 * transfer (there is no need to create more buffer descriptors when you 224 * can reuse an existing one, even for different transfer sizes). Note 225 * that the specified length must not exceed the capacity of the buffer. 226 */ 227 virtual void setLength(vm_size_t length); 228 229 /* 230 * setDirection: 231 * 232 * Change the direction of the transfer. This method allows one to redirect 233 * the descriptor's transfer direction. This eliminates the need to destroy 234 * and create new buffers when different transfer directions are needed. 235 */ 236 virtual void setDirection(IODirection direction); 237 238 /* 239 * getCapacity: 240 * 241 * Get the buffer capacity 242 */ 243 virtual vm_size_t getCapacity() const; 244 245 /* 246 * getBytesNoCopy: 247 * 248 * Return the virtual address of the beginning of the buffer 249 */ 250 virtual void *getBytesNoCopy(); 251 252 /* 253 * getBytesNoCopy: 254 * 255 * Return the virtual address of an offset from the beginning of the buffer 256 */ 257 virtual void *getBytesNoCopy(vm_size_t start, vm_size_t withLength); 258 259 /* 260 * appendBytes: 261 * 262 * Add some data to the end of the buffer. This method automatically 263 * maintains the memory descriptor buffer length. Note that appendBytes 264 * will not copy past the end of the memory descriptor's current capacity. 265 */ 266 virtual bool appendBytes(const void *bytes, vm_size_t withLength); 267 268 #ifndef __LP64__ 269 virtual void * getVirtualSegment(IOByteCount offset, 270 IOByteCount * length) APPLE_KEXT_DEPRECATED; /* use getBytesNoCopy() instead */ 271 #endif /* !__LP64__ */ 272 }; 273 274 #endif /* !_IOBUFFERMEMORYDESCRIPTOR_H */ 275