iokit/IOKit/IOBufferMemoryDescriptor.h

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