iokit/IOKit/IOBufferMemoryDescriptor.h

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