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