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