iokit/IOKit/IOMemoryCursor.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_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. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23 #ifndef _IOMEMORYCURSOR_H
  24 #define _IOMEMORYCURSOR_H
  25
  26 #include <libkern/c++/OSObject.h>
  27 #include <IOKit/IOTypes.h>
  28
  29 class IOMemoryDescriptor;
  30
  31 /**************************** class IOMemoryCursor ***************************/
  32
  33 /*!
  34     @class IOMemoryCursor
  35     @abstract A mechanism to convert memory references to physical addresses.
  36     @discussion The IOMemoryCursor declares the super class that all
  37 specific memory cursors must inherit from, but a memory cursor can be created without a specific format subclass by just providing a segment function to the initializers.  This class does the difficult stuff of dividing a memory descriptor into a physical scatter/gather list appropriate for the target hardware.
  38 <br><br>
  39     A driver is expected to create a memory cursor and configure it to the limitations of its DMA hardware; for instance the memory cursor used by the FireWire SBP-2 protocol has a maximum physical segment size of 2^16 - 1 but the actual transfer size is unlimited.  Thus it would create a cursor with a maxSegmentSize of 65535 and a maxTransfer size of UINT_MAX.   It would also provide a SegmentFunction that can output a pagelist entry.
  40 <br><br>
  41 Below is the simplest example of a SegmentFunction:<br>
  42 void IONaturalMemoryCursor::outputSegment(PhysicalSegment segment,<br>
  43                                           void *          outSegments,<br>
  44                                           UInt32          outSegmentIndex)<br>
  45 {<br>
  46     ((PhysicalSegment *) outSegments)[outSegmentIndex] = segment;<br>
  47 }
  48
  49 */
  50 class IOMemoryCursor : public OSObject
  51 {
  52     OSDeclareDefaultStructors(IOMemoryCursor)
  53
  54 public:
  55 /*!
  56     @typedef PhysicalSegment
  57     @discussion A physical address/length pair.
  58 */
  59     struct PhysicalSegment
  60     {
  61         IOPhysicalAddress location;
  62         IOPhysicalLength  length;
  63     };
  64
  65 /*! @defined IOPhysicalSegment
  66     @discussion Backward compatibility define for the old non-class scoped type definition.  See IOMemoryCursor::PhysicalSegment
  67 */
  68 #define IOPhysicalSegment IOMemoryCursor::PhysicalSegment
  69
  70 /*!
  71     @typedef SegmentFunction
  72     @discussion Pointer to a C function that outputs a single physical segment to an element in the array as defined by the segments and segmentIndex parameters.
  73     @param segment The physical address and length that is next to be output.
  74     @param segments Base of the output vector of DMA address length pairs.
  75     @param segmentIndex Index to output 'segment' in the 'segments' array.
  76 */
  77     typedef void (*SegmentFunction)(PhysicalSegment segment,
  78                                     void *          segments,
  79                                     UInt32          segmentIndex);
  80
  81 /*! @defined OutputSegmentFunc
  82     @discussion Backward compatibility define for the old non-class scoped type definition.  See IOMemoryCursor::SegmentFunction */
  83 #define OutputSegmentFunc IOMemoryCursor::SegmentFunction
  84
  85 protected:
  86 /*! @var outSeg The action method called when an event has been delivered */
  87     SegmentFunction outSeg;
  88
  89 /*! @var maxSegmentSize Maximum size of one segment in a scatter/gather list */
  90     IOPhysicalLength  maxSegmentSize;
  91
  92 /*! @var maxTransferSize
  93     Maximum size of a transfer that this memory cursor is allowed to generate */
  94     IOPhysicalLength  maxTransferSize;
  95
  96 /*! @var alignMask
  97     Currently unused.  Reserved for automated aligment restriction code. */
  98     IOPhysicalLength  alignMask;
  99
 100 public:
 101 /*! @function withSpecification
 102     @abstract Creates and initializes an IOMemoryCursor in one operation.
 103     @discussion Factory function to create and initialize an IOMemoryCursor in one operation.  For more information, see IOMemoryCursor::initWithSpecification.
 104     @param outSegFunc SegmentFunction to call to output one physical segment.
 105     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
 106     @param maxTransferSize Maximum size of an entire transfer.  Defaults to 0 indicating no maximum.
 107     @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
 108     @result Returns a new memory cursor if successfully created and initialized, 0 otherwise.
 109 */
 110     static IOMemoryCursor *
 111         withSpecification(SegmentFunction  outSegFunc,
 112                           IOPhysicalLength maxSegmentSize = 0,
 113                           IOPhysicalLength maxTransferSize = 0,
 114                           IOPhysicalLength alignment = 1);
 115
 116 /*! @function initWithSpecification
 117     @abstract Primary initializer for the IOMemoryCursor class.
 118     @param outSegFunc SegmentFunction to call to output one physical segment.
 119     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
 120     @param maxTransferSize Maximum size of an entire transfer.  Defaults to 0 indicating no maximum.
 121     @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
 122     @result Returns true if the inherited classes and this instance initialize
 123 successfully.
 124 */
 125     virtual bool initWithSpecification(SegmentFunction  outSegFunc,
 126                                        IOPhysicalLength maxSegmentSize = 0,
 127                                        IOPhysicalLength maxTransferSize = 0,
 128                                        IOPhysicalLength alignment = 1);
 129
 130 /*! @function genPhysicalSegments
 131     @abstract Generates a physical scatter/gather list given a memory descriptor.
 132     @discussion Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor.
 133     @param descriptor IOMemoryDescriptor that describes the data associated with an I/O request.
 134     @param fromPosition Starting location of the I/O within a memory descriptor.
 135     @param segments Void pointer to base of output physical scatter/gather list.  Always passed directly onto the SegmentFunction without interpretation by the cursor.
 136     @param maxSegments Maximum number of segments that can be written to segments array.
 137     @param maxTransferSize Maximum transfer size is limited to that many bytes, otherwise it defaults to the maximum transfer size specified when the memory cursor was initialized.
 138     @param transferSize Pointer to an IOByteCount variable that can contain the total size of the transfer being described.  Defaults to 0 indicating that no transfer size need be returned.
 139     @result If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.
 140 */
 141     virtual UInt32 genPhysicalSegments(
 142                                       IOMemoryDescriptor *descriptor,
 143                                       IOByteCount         fromPosition,
 144                                       void *              segments,
 145                                       UInt32              maxSegments,
 146                                       UInt32              maxTransferSize = 0,
 147                                       IOByteCount        *transferSize = 0);
 148 };
 149
 150 /************************ class IONaturalMemoryCursor ************************/
 151
 152
 153 /*!
 154     @class IONaturalMemoryCursor
 155     @abstract An IOMemoryCursor subclass that outputs a vector of PhysicalSegments in the natural byte orientation for the CPU.
 156     @discussion The IONaturalMemoryCursor would be used when it is too difficult to safely describe a SegmentFunction that is more appropriate for your hardware.  This cursor just outputs an array of PhysicalSegments.
 157 */
 158 class IONaturalMemoryCursor : public IOMemoryCursor
 159 {
 160     OSDeclareDefaultStructors(IONaturalMemoryCursor)
 161
 162 public:
 163 /*! @function outputSegment
 164     @abstract Outputs the given segment into the output segments array in natural byte order.
 165     @param segment The physical address and length that is next to be output.
 166     @param segments Base of the output vector of DMA address length pairs.
 167     @param segmentIndex Index to output 'segment' in the 'segments' array.
 168 */
 169     static void outputSegment(PhysicalSegment segment,
 170                               void *          segments,
 171                               UInt32          segmentIndex);
 172
 173 /*! @defined naturalOutputSegment
 174     @discussion Backward compatibility define for the old global function definition.  See IONaturalMemoryCursor::outputSegment.
 175 */
 176 #define naturalOutputSegment IONaturalMemoryCursor::outputSegment
 177
 178 /*! @function withSpecification
 179     @abstract Creates and initializes an IONaturalMemoryCursor in one operation.
 180     @discussion Factory function to create and initialize an IONaturalMemoryCursor in one operation.  For more information, see IONaturalMemoryCursor::initWithSpecification.
 181     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
 182     @param maxTransferSize Maximum size of an entire transfer.  Defaults to 0 indicating no maximum.
 183     @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
 184     @result Returns a new memory cursor if successfully created and initialized, 0 otherwise.
 185 */
 186     static IONaturalMemoryCursor *
 187         withSpecification(IOPhysicalLength maxSegmentSize,
 188                           IOPhysicalLength maxTransferSize,
 189                           IOPhysicalLength alignment = 1);
 190
 191 /*! @function initWithSpecification
 192     @abstract Primary initializer for the IONaturalMemoryCursor class.
 193     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
 194     @param maxTransferSize Maximum size of an entire transfer.  Defaults to 0 indicating no maximum.
 195     @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
 196     @result Returns true if the inherited classes and this instance initialize successfully.
 197 */
 198     virtual bool initWithSpecification(IOPhysicalLength  maxSegmentSize,
 199                                        IOPhysicalLength  maxTransferSize,
 200                                        IOPhysicalLength  alignment = 1);
 201
 202
 203 /*! @function getPhysicalSegments
 204     @abstract Generates a CPU natural physical scatter/gather list given a memory descriptor.
 205     @discussion Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor.  Wraps IOMemoryCursor::genPhysicalSegments.
 206     @param descriptor IOMemoryDescriptor that describes the data associated with an I/O request.
 207     @param fromPosition Starting location of the I/O within a memory descriptor.
 208     @param segments Pointer to an array of IOMemoryCursor::PhysicalSegments for the output physical scatter/gather list.
 209     @param maxSegments Maximum number of segments that can be written to segments array.
 210     @param maxTransferSize Maximum transfer size is limited to that many bytes, otherwise it defaults to the maximum transfer size specified when the memory cursor was initialized.
 211     @param transferSize Pointer to an IOByteCount variable that can contain the total size of the transfer being described.  Defaults to 0 indicating that no transfer size need be returned.
 212     @result If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.
 213 */
 214     virtual UInt32 getPhysicalSegments(IOMemoryDescriptor *descriptor,
 215                                        IOByteCount         fromPosition,
 216                                        PhysicalSegment    *segments,
 217                                        UInt32              maxSegments,
 218                                        UInt32              maxTransferSize = 0,
 219                                        IOByteCount        *transferSize = 0)
 220     {
 221         return genPhysicalSegments(descriptor, fromPosition, segments,
 222                                 maxSegments, maxTransferSize, transferSize);
 223     }
 224 };
 225
 226 /************************** class IOBigMemoryCursor **************************/
 227
 228 /*!
 229     @class IOBigMemoryCursor
 230     @abstract An IOMemoryCursor subclass that outputs a vector of PhysicalSegments in the big endian byte order.
 231     @discussion The IOBigMemoryCursor would be used when the DMA hardware requires a big endian address and length pair.  This cursor outputs an array of PhysicalSegments that are encoded in big-endian format.
 232 */
 233 class IOBigMemoryCursor : public IOMemoryCursor
 234 {
 235     OSDeclareDefaultStructors(IOBigMemoryCursor)
 236
 237 public:
 238 /*! @function outputSegment
 239     @abstract Outputs the given segment into the output segments array in big endian byte order.
 240     @param segment The physical address and length that is next to be output.
 241     @param segments Base of the output vector of DMA address length pairs.
 242     @param segmentIndex Index to output 'segment' in the 'segments' array.
 243 */
 244     static void outputSegment(PhysicalSegment segment,
 245                               void *          segments,
 246                               UInt32          segmentIndex);
 247
 248 /*! @defined bigOutputSegment
 249     @discussion Backward compatibility define for the old global function definition.  See IOBigMemoryCursor::outputSegment
 250 */
 251 #define bigOutputSegment IOBigMemoryCursor::outputSegment
 252
 253 /*! @function withSpecification
 254     @abstract Creates and initializes an IOBigMemoryCursor in one operation.
 255     @discussion Factory function to create and initialize an IOBigMemoryCursor in one operation.  See also IOBigMemoryCursor::initWithSpecification.
 256     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
 257     @param maxTransferSize Maximum size of an entire transfer.  Defaults to 0 indicating no maximum.
 258     @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
 259     @result Returns a new memory cursor if successfully created and initialized, 0 otherwise.
 260 */
 261     static IOBigMemoryCursor *
 262         withSpecification(IOPhysicalLength maxSegmentSize,
 263                           IOPhysicalLength maxTransferSize,
 264                           IOPhysicalLength alignment = 1);
 265
 266 /*! @function initWithSpecification
 267     @abstract Primary initializer for the IOBigMemoryCursor class.
 268     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
 269     @param maxTransferSize Maximum size of an entire transfer.  Defaults to 0 indicating no maximum.
 270     @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
 271     @result Returns true if the inherited classes and this instance initialize
 272 successfully.
 273 */
 274     virtual bool initWithSpecification(IOPhysicalLength  maxSegmentSize,
 275                                        IOPhysicalLength  maxTransferSize,
 276                                        IOPhysicalLength  alignment = 1);
 277
 278
 279 /*! @function getPhysicalSegments
 280     @abstract Generates a big endian physical scatter/gather list given a memory descriptor.
 281     @discussion Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor.  Wraps IOMemoryCursor::genPhysicalSegments.
 282     @param descriptor IOMemoryDescriptor that describes the data associated with an I/O request.
 283     @param fromPosition Starting location of the I/O within a memory descriptor.
 284     @param segments Pointer to an array of IOMemoryCursor::PhysicalSegments for the output physical scatter/gather list.
 285     @param maxSegments Maximum number of segments that can be written to segments array.
 286     @param maxTransferSize Maximum transfer size is limited to that many bytes, otherwise it defaults to the maximum transfer size specified when the memory cursor was initialized.
 287     @param transferSize Pointer to an IOByteCount variable that can contain the total size of the transfer being described.  Defaults to 0 indicating that no transfer size need be returned.
 288     @result If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.
 289 */
 290     virtual UInt32 getPhysicalSegments(IOMemoryDescriptor * descriptor,
 291                                        IOByteCount          fromPosition,
 292                                        PhysicalSegment *    segments,
 293                                        UInt32               maxSegments,
 294                                        UInt32               maxTransferSize = 0,
 295                                        IOByteCount       *  transferSize = 0)
 296     {
 297         return genPhysicalSegments(descriptor, fromPosition, segments,
 298                                 maxSegments, maxTransferSize, transferSize);
 299     }
 300 };
 301
 302 /************************* class IOLittleMemoryCursor ************************/
 303
 304 /*!
 305     @class IOLittleMemoryCursor
 306     @abstract An IOMemoryCursor subclass that outputs a vector of PhysicalSegments in the little endian byte order.
 307     @discussion The IOLittleMemoryCursor would be used when the DMA hardware requires a little endian address and length pair.  This cursor outputs an array of PhysicalSegments that are encoded in little endian format.
 308 */
 309 class IOLittleMemoryCursor : public IOMemoryCursor
 310 {
 311     OSDeclareDefaultStructors(IOLittleMemoryCursor)
 312
 313 public:
 314 /*! @function outputSegment
 315     @abstract Outputs the given segment into the output segments array in little endian byte order.
 316     @param segment The physical address and length that is next to be output.
 317     @param segments Base of the output vector of DMA address length pairs.
 318     @param segmentIndex Index to output 'segment' in the 'segments' array.
 319 */
 320     static void outputSegment(PhysicalSegment segment,
 321                               void *          segments,
 322                               UInt32          segmentIndex);
 323
 324 /*! @defined littleOutputSegment
 325     @discussion Backward compatibility define for the old global function definition.  See also IOLittleMemoryCursor::outputSegment. */
 326 #define littleOutputSegment IOLittleMemoryCursor::outputSegment
 327
 328 /*! @function withSpecification
 329     @abstract Creates and initializes an IOLittleMemoryCursor in one operation.
 330     @discussion Factory function to create and initialize an IOLittleMemoryCursor in one operation.  See also IOLittleMemoryCursor::initWithSpecification.
 331     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
 332     @param maxTransferSize Maximum size of an entire transfer.  Defaults to 0 indicating no maximum.
 333     @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
 334     @result Returns a new memory cursor if successfully created and initialized, 0 otherwise.
 335 */
 336     static IOLittleMemoryCursor *
 337         withSpecification(IOPhysicalLength maxSegmentSize,
 338                           IOPhysicalLength maxTransferSize,
 339                           IOPhysicalLength alignment = 1);
 340
 341 /*! @function initWithSpecification
 342     @abstract Primary initializer for the IOLittleMemoryCursor class.
 343     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
 344     @param maxTransferSize Maximum size of an entire transfer.  Defaults to 0 indicating no maximum.
 345     @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
 346     @result Returns true if the inherited classes and this instance initialize successfully.
 347 */
 348     virtual bool initWithSpecification(IOPhysicalLength  maxSegmentSize,
 349                                        IOPhysicalLength  maxTransferSize,
 350                                        IOPhysicalLength  alignment = 1);
 351
 352
 353 /*! @function getPhysicalSegments
 354     @abstract Generates a little endian physical scatter/gather list given a memory descriptor.
 355     @discussion Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor.  Wraps IOMemoryCursor::genPhysicalSegments.
 356     @param descriptor IOMemoryDescriptor that describes the data associated with an I/O request.
 357     @param fromPosition Starting location of the I/O within a memory descriptor.
 358     @param segments Pointer to an array of IOMemoryCursor::PhysicalSegments for the output physical scatter/gather list.
 359     @param maxSegments Maximum number of segments that can be written to segments array.
 360     @param maxTransferSize Maximum transfer size is limited to that many bytes, otherwise it defaults to the maximum transfer size specified when the memory cursor was initialized.
 361     @param transferSize Pointer to an IOByteCount variable that can contain the total size of the transfer being described.  Defaults to 0 indicating that no transfer size need be returned.
 362     @result If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.
 363 */
 364     virtual UInt32 getPhysicalSegments(IOMemoryDescriptor * descriptor,
 365                                        IOByteCount          fromPosition,
 366                                        PhysicalSegment *    segments,
 367                                        UInt32               maxSegments,
 368                                        UInt32               maxTransferSize = 0,
 369                                        IOByteCount       *  transferSize = 0)
 370     {
 371         return genPhysicalSegments(descriptor, fromPosition, segments,
 372                                 maxSegments, maxTransferSize, transferSize);
 373     }
 374 };
 375
 376 /************************* class IODBDMAMemoryCursor *************************/
 377
 378 #if defined(__ppc__)
 379
 380 struct IODBDMADescriptor;
 381
 382 /*!
 383     @class IODBDMAMemoryCursor
 384     @abstract An IOMemoryCursor subclass that outputs a vector of DBDMA descriptors where the address and length are filled in.
 385     @discussion The IODBDMAMemoryCursor would be used when the DBDMA hardware is available for the device for that will use an instance of this cursor.
 386 */
 387 class IODBDMAMemoryCursor : public IOMemoryCursor
 388 {
 389     OSDeclareDefaultStructors(IODBDMAMemoryCursor)
 390
 391 public:
 392 /*! @function outputSegment
 393     @abstract Outpust the given segment into the output segments array in address and length fields of an DBDMA descriptor.
 394     @param segment The physical address and length that is next to be output.
 395     @param segments Base of the output vector of DMA address length pairs.
 396     @param segmentIndex Index to output 'segment' in the 'segments' array.
 397 */
 398     static void outputSegment(PhysicalSegment segment,
 399                               void *          segments,
 400                               UInt32          segmentIndex);
 401
 402 /*! @defined dbdmaOutputSegment
 403     @discussion Backward compatibility define for the old global function definition.  See IODBDMAMemoryCursor::outputSegment. */
 404 #define dbdmaOutputSegment IODBDMAMemoryCursor::outputSegment
 405
 406 /*! @function withSpecification
 407     @abstract Creates and initializes an IODBDMAMemoryCursor in one operation.
 408     @discussion Factory function to create and initialize an IODBDMAMemoryCursor in one operation.  See also IODBDMAMemoryCursor::initWithSpecification.
 409     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
 410     @param maxTransferSize Maximum size of an entire transfer.  Defaults to 0 indicating no maximum.
 411     @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
 412     @result Returns a new memory cursor if successfully created and initialized, 0 otherwise.
 413 */
 414     static IODBDMAMemoryCursor *
 415         withSpecification(IOPhysicalLength maxSegmentSize,
 416                           IOPhysicalLength maxTransferSize,
 417                           IOPhysicalLength alignment = 1);
 418
 419 /*! @function initWithSpecification
 420     @abstract Primary initializer for the IODBDMAMemoryCursor class.
 421     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
 422     @param maxTransferSize Maximum size of an entire transfer.  Defaults to 0 indicating no maximum.
 423     @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
 424     @result Returns true if the inherited classes and this instance initialize successfully.
 425 */
 426     virtual bool initWithSpecification(IOPhysicalLength  maxSegmentSize,
 427                                        IOPhysicalLength  maxTransferSize,
 428                                        IOPhysicalLength  alignment = 1);
 429
 430
 431 /*! @function getPhysicalSegments
 432     @abstract Generates a DBDMA physical scatter/gather list given a memory descriptor.
 433     @discussion Generates a list of DBDMA descriptors where the address and length fields are filled in appropriately.  But the client is expected to fill in the rest of the DBDMA descriptor as is appropriate for their particular hardware.  Wraps IOMemoryCursor::genPhysicalSegments.
 434     @param descriptor IOMemoryDescriptor that describes the data associated with an I/O request.
 435     @param fromPosition Starting location of the I/O within a memory descriptor.
 436     @param segments Pointer to an array of DBDMA descriptors for the output physical scatter/gather list.  Be warned no room is left for a preamble in the output array.  'segments' should point to the first memory description slot in a DBDMA command.
 437     @param maxSegments Maximum number of segments that can be written to the DBDMA descriptor table.
 438     @param maxTransferSize Maximum transfer size is limited to that many bytes, otherwise it defaults to the maximum transfer size specified when the memory cursor was initialized.
 439     @param transferSize Pointer to an IOByteCount variable that can contain the total size of the transfer being described.  Defaults to 0 indicating that no transfer size need be returned.
 440     @result If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.
 441 */
 442     virtual UInt32 getPhysicalSegments(IOMemoryDescriptor * descriptor,
 443                                        IOByteCount          fromPosition,
 444                                        IODBDMADescriptor *  segments,
 445                                        UInt32               maxSegments,
 446                                        UInt32               maxTransferSize = 0,
 447                                        IOByteCount       *  transferSize = 0)
 448     {
 449         return genPhysicalSegments(descriptor, fromPosition, segments,
 450                                 maxSegments, maxTransferSize, transferSize);
 451     }
 452 };
 453
 454 #endif /* defined(__ppc__) */
 455
 456 #endif /* !_IOMEMORYCURSOR_H */
 457