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     kIOMemoryDirectionMask              = 0x0000000f,
  29     kIOMemoryPhysicallyContiguous       = 0x00000010,
  30     kIOMemoryPageable                   = 0x00000020,
  31     kIOMemorySharingTypeMask            = 0x000f0000,
  32     kIOMemoryUnshared                   = 0x00000000,
  33     kIOMemoryKernelUserShared           = 0x00010000,
  34 };
  35
  36 #define _IOBUFFERMEMORYDESCRIPTOR_INTASKWITHOPTIONS_    1
  37
  38 class IOBufferMemoryDescriptor : public IOGeneralMemoryDescriptor
  39 {
  40     OSDeclareDefaultStructors(IOBufferMemoryDescriptor);
  41
  42 protected:
  43 /*! @struct ExpansionData
  44     @discussion This structure will be used to expand the capablilties of this class in the future.
  45     */
  46     struct ExpansionData {
  47         vm_map_t        map;
  48     };
  49
  50 /*! @var reserved
  51     Reserved for future use.  (Internal use only)  */
  52     ExpansionData * reserved;
  53
  54 protected:
  55     void *               _buffer;
  56     vm_size_t            _capacity;
  57     vm_offset_t          _alignment;
  58     IOOptionBits         _options;
  59     IOPhysicalAddress *  _physAddrs;
  60     unsigned             _physSegCount;
  61
  62 private:
  63     virtual bool initWithOptions(
  64                                IOOptionBits options,
  65                                vm_size_t    capacity,
  66                                vm_offset_t  alignment,
  67                                task_t       inTask);
  68
  69     OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 0);
  70     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 1);
  71     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 2);
  72     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 3);
  73     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 4);
  74     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 5);
  75     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 6);
  76     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 7);
  77     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 8);
  78     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 9);
  79     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 10);
  80     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 11);
  81     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 12);
  82     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 13);
  83     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 14);
  84     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 15);
  85
  86 protected:
  87     virtual void free();
  88
  89     virtual bool initWithAddress( void *      address,       /* not supported */
  90                                   IOByteCount withLength,
  91                                   IODirection withDirection );
  92
  93     virtual bool initWithAddress( vm_address_t address,      /* not supported */
  94                                   IOByteCount  withLength,
  95                                   IODirection  withDirection,
  96                                   task_t       withTask );
  97
  98     virtual bool initWithPhysicalAddress(
  99                                   IOPhysicalAddress address, /* not supported */
 100                                   IOByteCount       withLength,
 101                                   IODirection       withDirection );
 102
 103     virtual bool initWithPhysicalRanges(
 104                                   IOPhysicalRange * ranges,  /* not supported */
 105                                   UInt32            withCount,
 106                                   IODirection       withDirection,
 107                                   bool              asReference = false );
 108
 109     virtual bool initWithRanges(  IOVirtualRange * ranges,   /* not supported */
 110                                   UInt32           withCount,
 111                                   IODirection      withDirection,
 112                                   task_t           withTask,
 113                                   bool             asReference = false );
 114
 115     IOGeneralMemoryDescriptor::withAddress;                  /* not supported */
 116     IOGeneralMemoryDescriptor::withPhysicalAddress;          /* not supported */
 117     IOGeneralMemoryDescriptor::withPhysicalRanges;           /* not supported */
 118     IOGeneralMemoryDescriptor::withRanges;                   /* not supported */
 119     IOGeneralMemoryDescriptor::withSubRange;                 /* not supported */
 120
 121 public:
 122
 123     /*
 124      * withOptions:
 125      *
 126      * Returns a new IOBufferMemoryDescriptor with a buffer large enough to
 127      * hold capacity bytes.  The descriptor's length is initially set to the
 128      * capacity.
 129      */
 130     virtual bool initWithOptions(   IOOptionBits options,
 131                                     vm_size_t    capacity,
 132                                     vm_offset_t  alignment);
 133
 134     static IOBufferMemoryDescriptor * withOptions(  IOOptionBits options,
 135                                                     vm_size_t    capacity,
 136                                                     vm_offset_t  alignment = 1);
 137
 138 /*! @function inTaskWithOptions
 139     @abstract Create a memory buffer with memory descriptor for that buffer. Added in Mac OS X 10.2.
 140     @discussion 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 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.
 141     @param inTask The task the buffer will be allocated in.
 142     @param options Options for the allocation:
 143     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.
 144     kIOMemoryPageable - pass to request memory be non-wired - the default for kernel allocated memory is wired.
 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 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     /*
 157      * withCapacity:
 158      *
 159      * Returns a new IOBufferMemoryDescriptor with a buffer large enough to
 160      * hold capacity bytes.  The descriptor's length is initially set to the
 161      * capacity.
 162      */
 163     static IOBufferMemoryDescriptor * withCapacity(
 164                                      vm_size_t    capacity,
 165                                      IODirection  withDirection,
 166                                      bool         withContiguousMemory = false);
 167     /*
 168      * initWithBytes:
 169      *
 170      * Initialize a new IOBufferMemoryDescriptor preloaded with bytes (copied).
 171      * The descriptor's length and capacity are set to the input buffer's size.
 172      */
 173     virtual bool initWithBytes(const void * bytes,
 174                                vm_size_t    withLength,
 175                                IODirection  withDirection,
 176                                bool         withContiguousMemory = false);
 177
 178     /*
 179      * withBytes:
 180      *
 181      * Returns a new IOBufferMemoryDescriptor preloaded with bytes (copied).
 182      * The descriptor's length and capacity are set to the input buffer's size.
 183      */
 184     static IOBufferMemoryDescriptor * withBytes(
 185                                      const void * bytes,
 186                                      vm_size_t    withLength,
 187                                      IODirection  withDirection,
 188                                      bool         withContiguousMemory = false);
 189
 190     /*
 191      * setLength:
 192      *
 193      * Change the buffer length of the memory descriptor.  When a new buffer
 194      * is created, the initial length of the buffer is set to be the same as
 195      * the capacity.  The length can be adjusted via setLength for a shorter
 196      * transfer (there is no need to create more buffer descriptors when you
 197      * can reuse an existing one, even for different transfer sizes).   Note
 198      * that the specified length must not exceed the capacity of the buffer.
 199      */
 200     virtual void setLength(vm_size_t length);
 201
 202     /*
 203      * setDirection:
 204      *
 205      * Change the direction of the transfer.  This method allows one to redirect
 206      * the descriptor's transfer direction.  This eliminates the need to destroy
 207      * and create new buffers when different transfer directions are needed.
 208      */
 209     virtual void setDirection(IODirection direction);
 210
 211     /*
 212      * getCapacity:
 213      *
 214      * Get the buffer capacity
 215      */
 216     virtual vm_size_t getCapacity() const;
 217
 218     /*
 219      * getBytesNoCopy:
 220      *
 221      * Return the virtual address of the beginning of the buffer
 222      */
 223     virtual void *getBytesNoCopy();
 224
 225     /*
 226      * getBytesNoCopy:
 227      *
 228      * Return the virtual address of an offset from the beginning of the buffer
 229      */
 230     virtual void *getBytesNoCopy(vm_size_t start, vm_size_t withLength);
 231
 232     /*
 233      * appendBytes:
 234      *
 235      * Add some data to the end of the buffer.  This method automatically
 236      * maintains the memory descriptor buffer length.  Note that appendBytes
 237      * will not copy past the end of the memory descriptor's current capacity.
 238      */
 239     virtual bool appendBytes(const void *bytes, vm_size_t withLength);
 240
 241     /*
 242      * getPhysicalSegment:
 243      *
 244      * Get the physical address of the buffer, relative to the current position.
 245      * If the current position is at the end of the buffer, a zero is returned.
 246      */
 247     virtual IOPhysicalAddress getPhysicalSegment(IOByteCount offset,
 248                                                  IOByteCount * length);
 249 };
 250
 251 #endif /* !_IOBUFFERMEMORYDESCRIPTOR_H */