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