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