iokit/IOKit/IOBufferMemoryDescriptor.h

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