iokit/IOKit/IOBufferMemoryDescriptor.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22 #ifndef _IOBUFFERMEMORYDESCRIPTOR_H
  23 #define _IOBUFFERMEMORYDESCRIPTOR_H
  24
  25 #include <IOKit/IOMemoryDescriptor.h>
  26
  27 enum {
  28     kIOMemoryPhysicallyContiguous       = 0x00000010,
  29     kIOMemoryPageable                   = 0x00000020,
  30     kIOMemoryPurgeable                  = 0x00000040,
  31     kIOMemorySharingTypeMask            = 0x000f0000,
  32     kIOMemoryUnshared                   = 0x00000000,
  33     kIOMemoryKernelUserShared           = 0x00010000
  34 };
  35
  36 #define _IOBUFFERMEMORYDESCRIPTOR_INTASKWITHOPTIONS_    1
  37 /*!
  38     @class IOBufferMemoryDescriptor
  39     @abstract Provides a simple memory descriptor that allocates its own buffer memory.
  40 */
  41
  42 class IOBufferMemoryDescriptor : public IOGeneralMemoryDescriptor
  43 {
  44     OSDeclareDefaultStructors(IOBufferMemoryDescriptor);
  45
  46 protected:
  47 /*! @struct ExpansionData
  48     @discussion This structure will be used to expand the capablilties of this class in the future.
  49     */
  50     struct ExpansionData {
  51         vm_map_t        map;
  52     };
  53
  54 /*! @var reserved
  55     Reserved for future use.  (Internal use only)  */
  56     ExpansionData * reserved;
  57
  58 protected:
  59     void *               _buffer;
  60     vm_size_t            _capacity;
  61     vm_offset_t          _alignment;
  62     IOOptionBits         _options;
  63     IOPhysicalAddress *  _physAddrs;
  64     unsigned             _physSegCount;
  65
  66 private:
  67     virtual bool initWithOptions(
  68                                IOOptionBits options,
  69                                vm_size_t    capacity,
  70                                vm_offset_t  alignment,
  71                                task_t       inTask);
  72     OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 0);
  73
  74 #if !(defined(__ppc__) && defined(KPI_10_4_0_PPC_COMPAT))
  75     virtual bool initWithPhysicalMask(
  76                                 task_t            inTask,
  77                                 IOOptionBits      options,
  78                                 mach_vm_size_t    capacity,
  79                                 mach_vm_address_t alignment,
  80                                 mach_vm_address_t physicalMask);
  81     OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 1);
  82 #else
  83     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 1);
  84 #endif
  85     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 2);
  86     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 3);
  87     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 4);
  88     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 5);
  89     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 6);
  90     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 7);
  91     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 8);
  92     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 9);
  93     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 10);
  94     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 11);
  95     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 12);
  96     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 13);
  97     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 14);
  98     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 15);
  99
 100 protected:
 101     virtual void free();
 102
 103     virtual bool initWithAddress( void *      address,       /* not supported */
 104                                   IOByteCount withLength,
 105                                   IODirection withDirection );
 106
 107     virtual bool initWithAddress( vm_address_t address,      /* not supported */
 108                                   IOByteCount  withLength,
 109                                   IODirection  withDirection,
 110                                   task_t       withTask );
 111
 112     virtual bool initWithPhysicalAddress(
 113                                   IOPhysicalAddress address, /* not supported */
 114                                   IOByteCount       withLength,
 115                                   IODirection       withDirection );
 116
 117     virtual bool initWithPhysicalRanges(
 118                                   IOPhysicalRange * ranges,  /* not supported */
 119                                   UInt32            withCount,
 120                                   IODirection       withDirection,
 121                                   bool              asReference = false );
 122
 123     virtual bool initWithRanges(  IOVirtualRange * ranges,   /* not supported */
 124                                   UInt32           withCount,
 125                                   IODirection      withDirection,
 126                                   task_t           withTask,
 127                                   bool             asReference = false );
 128
 129     IOGeneralMemoryDescriptor::withAddress;                  /* not supported */
 130     IOGeneralMemoryDescriptor::withPhysicalAddress;          /* not supported */
 131     IOGeneralMemoryDescriptor::withPhysicalRanges;           /* not supported */
 132     IOGeneralMemoryDescriptor::withRanges;                   /* not supported */
 133     IOGeneralMemoryDescriptor::withSubRange;                 /* not supported */
 134
 135 public:
 136
 137     /*
 138      * withOptions:
 139      *
 140      * Returns a new IOBufferMemoryDescriptor with a buffer large enough to
 141      * hold capacity bytes.  The descriptor's length is initially set to the
 142      * capacity.
 143      */
 144     virtual bool initWithOptions(   IOOptionBits options,
 145                                     vm_size_t    capacity,
 146                                     vm_offset_t  alignment);
 147
 148     static IOBufferMemoryDescriptor * withOptions(  IOOptionBits options,
 149                                                     vm_size_t    capacity,
 150                                                     vm_offset_t  alignment = 1);
 151
 152 /*! @function inTaskWithOptions
 153     @abstract Creates a memory buffer with memory descriptor for that buffer.
 154     @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.
 155     @param inTask The task the buffer will be allocated in.
 156     @param options Options for the allocation:<br>
 157     kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br>
 158     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>
 159     kIOMemoryPageable - pass to request memory be non-wired - the default for kernel allocated memory is wired.<br>
 160     kIOMemoryPurgeable - pass to request memory that may later have its purgeable state set with IOMemoryDescriptor::setPurgeable. Only supported for kIOMemoryPageable allocations.<br>
 161     kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.
 162     @param capacity The number of bytes to allocate.
 163     @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.
 164     @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */
 165
 166     static IOBufferMemoryDescriptor * inTaskWithOptions(
 167                                             task_t       inTask,
 168                                             IOOptionBits options,
 169                                             vm_size_t    capacity,
 170                                             vm_offset_t  alignment = 1);
 171
 172 #if !(defined(__ppc__) && defined(KPI_10_4_0_PPC_COMPAT))
 173 /*! @function inTaskWithPhysicalMask
 174     @abstract Creates a memory buffer with memory descriptor for that buffer.
 175     @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.
 176     @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).
 177     @param options Options for the allocation:<br>
 178     kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br>
 179     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>
 180     kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.
 181     @param capacity The number of bytes to allocate.
 182     @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.
 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 #endif
 191
 192     /*
 193      * withCapacity:
 194      *
 195      * Returns a new IOBufferMemoryDescriptor with a buffer large enough to
 196      * hold capacity bytes.  The descriptor's length is initially set to the
 197      * capacity.
 198      */
 199     static IOBufferMemoryDescriptor * withCapacity(
 200                                      vm_size_t    capacity,
 201                                      IODirection  withDirection,
 202                                      bool         withContiguousMemory = false);
 203     /*
 204      * initWithBytes:
 205      *
 206      * Initialize a new IOBufferMemoryDescriptor preloaded with bytes (copied).
 207      * The descriptor's length and capacity are set to the input buffer's size.
 208      */
 209     virtual bool initWithBytes(const void * bytes,
 210                                vm_size_t    withLength,
 211                                IODirection  withDirection,
 212                                bool         withContiguousMemory = false);
 213
 214     /*
 215      * withBytes:
 216      *
 217      * Returns a new IOBufferMemoryDescriptor preloaded with bytes (copied).
 218      * The descriptor's length and capacity are set to the input buffer's size.
 219      */
 220     static IOBufferMemoryDescriptor * withBytes(
 221                                      const void * bytes,
 222                                      vm_size_t    withLength,
 223                                      IODirection  withDirection,
 224                                      bool         withContiguousMemory = false);
 225
 226     /*
 227      * setLength:
 228      *
 229      * Change the buffer length of the memory descriptor.  When a new buffer
 230      * is created, the initial length of the buffer is set to be the same as
 231      * the capacity.  The length can be adjusted via setLength for a shorter
 232      * transfer (there is no need to create more buffer descriptors when you
 233      * can reuse an existing one, even for different transfer sizes).   Note
 234      * that the specified length must not exceed the capacity of the buffer.
 235      */
 236     virtual void setLength(vm_size_t length);
 237
 238     /*
 239      * setDirection:
 240      *
 241      * Change the direction of the transfer.  This method allows one to redirect
 242      * the descriptor's transfer direction.  This eliminates the need to destroy
 243      * and create new buffers when different transfer directions are needed.
 244      */
 245     virtual void setDirection(IODirection direction);
 246
 247     /*
 248      * getCapacity:
 249      *
 250      * Get the buffer capacity
 251      */
 252     virtual vm_size_t getCapacity() const;
 253
 254     /*
 255      * getBytesNoCopy:
 256      *
 257      * Return the virtual address of the beginning of the buffer
 258      */
 259     virtual void *getBytesNoCopy();
 260
 261     /*
 262      * getBytesNoCopy:
 263      *
 264      * Return the virtual address of an offset from the beginning of the buffer
 265      */
 266     virtual void *getBytesNoCopy(vm_size_t start, vm_size_t withLength);
 267
 268     /*
 269      * appendBytes:
 270      *
 271      * Add some data to the end of the buffer.  This method automatically
 272      * maintains the memory descriptor buffer length.  Note that appendBytes
 273      * will not copy past the end of the memory descriptor's current capacity.
 274      */
 275     virtual bool appendBytes(const void *bytes, vm_size_t withLength);
 276
 277 #if !(defined(__ppc__) && defined(KPI_10_4_0_PPC_COMPAT))
 278     /* DEPRECATED */ virtual void * getVirtualSegment(IOByteCount offset,
 279     /* DEPRECATED */                                    IOByteCount * length);
 280 #endif
 281 };
 282
 283 #endif /* !_IOBUFFERMEMORYDESCRIPTOR_H */