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