iokit/IOKit/IOBufferMemoryDescriptor.h

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