iokit/IOKit/IOMemoryCursor.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25 #ifndef _IOMEMORYCURSOR_H
  26 #define _IOMEMORYCURSOR_H
  27
  28 #include <libkern/c++/OSObject.h>
  29 #include <IOKit/IOTypes.h>
  30
  31 class IOMemoryDescriptor;
  32
  33 /**************************** class IOMemoryCursor ***************************/
  34
  35 /*!
  36     @class IOMemoryCursor : public OSObject
  37     @abstract A mechanism to convert memory references to physical addresses.
  38     @discussion The IOMemoryCursor declares the super class that all
  39 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.
  40 <br><br>
  41     A driver is expected to create a memory cursor and configure it to the limitations of it's DMA hardware; for instance the memory cursor used by the firewire SBP2 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.
  42 <br><br>
  43 Below is the simplest example of a SegmentFunction:-
  44 void IONaturalMemoryCursor::outputSegment(PhysicalSegment segment,
  45                                           void *          outSegments,
  46                                           UInt32          outSegmentIndex)
  47 {
  48     ((PhysicalSegment *) outSegments)[outSegmentIndex] = segment;
  49 }
  50
  51 */
  52 class IOMemoryCursor : public OSObject
  53 {
  54     OSDeclareDefaultStructors(IOMemoryCursor)
  55
  56 public:
  57 /*!
  58     @typedef PhysicalSegment
  59     @discussion A physical address/length pair.
  60 */
  61     struct PhysicalSegment
  62     {
  63         IOPhysicalAddress location;
  64         IOPhysicalLength  length;
  65     };
  66
  67 /*! @defined IOPhysicalSegment
  68     @discussion Backward compatibilty define for the old non-class scoped type definition.  See $link IOMemoryCursor::PhysicalSegment */
  69 #define IOPhysicalSegment IOMemoryCursor::PhysicalSegment
  70
  71 /*!
  72     @typedef SegmentFunction
  73     @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.
  74     @param segment The physical address and length that is next to be output.
  75     @param segments Base of the output vector of DMA address length pairs.
  76     @param segmentIndex Index to output 'segment' in the 'segments' array.
  77 */
  78     typedef void (*SegmentFunction)(PhysicalSegment segment,
  79                                     void *          segments,
  80                                     UInt32          segmentIndex);
  81
  82 /*! @defined OutputSegmentFunc
  83     @discussion Backward compatibilty define for the old non-class scoped type definition.  See $link IOMemoryCursor::SegmentFunction */
  84 #define OutputSegmentFunc IOMemoryCursor::SegmentFunction
  85
  86 protected:
  87 /*! @var outSeg The action method called when an event has been delivered */
  88     SegmentFunction outSeg;
  89
  90 /*! @var maxSegmentSize Maximum size of one segment in a scatter/gather list */
  91     IOPhysicalLength  maxSegmentSize;
  92
  93 /*! @var maxTransferSize
  94     Maximum size of a transfer that this memory cursor is allowed to generate */
  95     IOPhysicalLength  maxTransferSize;
  96
  97 /*! @var alignMask
  98     Currently unused.  Reserved for automated aligment restriction code. */
  99     IOPhysicalLength  alignMask;
 100
 101 public:
 102 /*! @function withSpecification
 103     @abstract Factory function to create and initialise an IOMemoryCursor in one operation, see $link 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.  Default to 0 indicating no maximum.
 107     @param alignment Alligment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
 108     @result A new memory cursor if successfully created and initialised, 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 initialiser 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.  Default to 0 indicating no maximum.
 121     @param alignment Alligment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
 122     @result true if the inherited classes and this instance initialise
 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 Generate 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 a IOByteCount variable that can contain the total size of the transfer being described.  Default 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 : public IOMemoryCursor
 155     @abstract A $link 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 /*! @funtion outputSegment
 164     @abstract Output 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 compatibilty define for the old global function definition.  See $link IONaturalMemoryCursor::outputSegment */
 175 #define naturalOutputSegment IONaturalMemoryCursor::outputSegment
 176
 177 /*! @function withSpecification
 178     @abstract Factory function to create and initialise an IONaturalMemoryCursor in one operation, see $link IONaturalMemoryCursor::initWithSpecification.
 179     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
 180     @param maxTransferSize Maximum size of an entire transfer.  Default to 0 indicating no maximum.
 181     @param alignment Alligment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
 182     @result A new memory cursor if successfully created and initialised, 0 otherwise.
 183 */
 184     static IONaturalMemoryCursor *
 185         withSpecification(IOPhysicalLength maxSegmentSize,
 186                           IOPhysicalLength maxTransferSize,
 187                           IOPhysicalLength alignment = 1);
 188
 189 /*! @function initWithSpecification
 190     @abstract Primary initialiser for the IONaturalMemoryCursor class.
 191     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
 192     @param maxTransferSize Maximum size of an entire transfer.  Default to 0 indicating no maximum.
 193     @param alignment Alligment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
 194     @result true if the inherited classes and this instance initialise
 195 successfully.
 196 */
 197     virtual bool initWithSpecification(IOPhysicalLength  maxSegmentSize,
 198                                        IOPhysicalLength  maxTransferSize,
 199                                        IOPhysicalLength  alignment = 1);
 200
 201
 202 /*! @function getPhysicalSegments
 203     @abstract Generate 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 $link 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 $link 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 a IOByteCount variable that can contain the total size of the transfer being described.  Default 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 : public IOMemoryCursor
 229     @abstract A $link 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 /*! @funtion outputSegment
 238     @abstract Output 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 compatibilty define for the old global function definition.  See $link IOBigMemoryCursor::outputSegment */
 249 #define bigOutputSegment IOBigMemoryCursor::outputSegment
 250
 251 /*! @function withSpecification
 252     @abstract Factory function to create and initialise an IOBigMemoryCursor in one operation, see $link IOBigMemoryCursor::initWithSpecification.
 253     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
 254     @param maxTransferSize Maximum size of an entire transfer.  Default to 0 indicating no maximum.
 255     @param alignment Alligment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
 256     @result A new memory cursor if successfully created and initialised, 0 otherwise.
 257 */
 258     static IOBigMemoryCursor *
 259         withSpecification(IOPhysicalLength maxSegmentSize,
 260                           IOPhysicalLength maxTransferSize,
 261                           IOPhysicalLength alignment = 1);
 262
 263 /*! @function initWithSpecification
 264     @abstract Primary initialiser for the IOBigMemoryCursor class.
 265     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
 266     @param maxTransferSize Maximum size of an entire transfer.  Default to 0 indicating no maximum.
 267     @param alignment Alligment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
 268     @result true if the inherited classes and this instance initialise
 269 successfully.
 270 */
 271     virtual bool initWithSpecification(IOPhysicalLength  maxSegmentSize,
 272                                        IOPhysicalLength  maxTransferSize,
 273                                        IOPhysicalLength  alignment = 1);
 274
 275
 276 /*! @function getPhysicalSegments
 277     @abstract Generate a big endian physical scatter/gather list given a memory descriptor.
 278     @discussion Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor.  Wraps $link IOMemoryCursor::genPhysicalSegments.
 279     @param descriptor IOMemoryDescriptor that describes the data associated with an I/O request.
 280     @param fromPosition Starting location of the I/O within a memory descriptor.
 281     @param segments Pointer to an array of $link IOMemoryCursor::PhysicalSegments for the output physical scatter/gather list.
 282     @param maxSegments Maximum number of segments that can be written to segments array.
 283     @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.
 284     @param transferSize Pointer to a IOByteCount variable that can contain the total size of the transfer being described.  Default to 0 indicating that no transfer size need be returned.
 285     @result If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.
 286 */
 287     virtual UInt32 getPhysicalSegments(IOMemoryDescriptor * descriptor,
 288                                        IOByteCount          fromPosition,
 289                                        PhysicalSegment *    segments,
 290                                        UInt32               maxSegments,
 291                                        UInt32               maxTransferSize = 0,
 292                                        IOByteCount       *  transferSize = 0)
 293     {
 294         return genPhysicalSegments(descriptor, fromPosition, segments,
 295                                 maxSegments, maxTransferSize, transferSize);
 296     }
 297 };
 298
 299 /************************* class IOLittleMemoryCursor ************************/
 300
 301 /*!
 302     @class IOLittleMemoryCursor : public IOMemoryCursor
 303     @abstract A $link IOMemoryCursor subclass that outputs a vector of PhysicalSegments in the little endian byte order.
 304     @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.
 305 */
 306 class IOLittleMemoryCursor : public IOMemoryCursor
 307 {
 308     OSDeclareDefaultStructors(IOLittleMemoryCursor)
 309
 310 public:
 311 /*! @funtion outputSegment
 312     @abstract Output the given segment into the output segments array in little endian byte order.
 313     @param segment The physical address and length that is next to be output.
 314     @param segments Base of the output vector of DMA address length pairs.
 315     @param segmentIndex Index to output 'segment' in the 'segments' array.
 316 */
 317     static void outputSegment(PhysicalSegment segment,
 318                               void *          segments,
 319                               UInt32          segmentIndex);
 320
 321 /*! @defined littleOutputSegment
 322     @discussion Backward compatibilty define for the old global function definition.  See $link IOLittleMemoryCursor::outputSegment */
 323 #define littleOutputSegment IOLittleMemoryCursor::outputSegment
 324
 325 /*! @function withSpecification
 326     @abstract Factory function to create and initialise an IOLittleMemoryCursor in one operation, see $link IOLittleMemoryCursor::initWithSpecification.
 327     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
 328     @param maxTransferSize Maximum size of an entire transfer.  Default to 0 indicating no maximum.
 329     @param alignment Alligment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
 330     @result A new memory cursor if successfully created and initialised, 0 otherwise.
 331 */
 332     static IOLittleMemoryCursor *
 333         withSpecification(IOPhysicalLength maxSegmentSize,
 334                           IOPhysicalLength maxTransferSize,
 335                           IOPhysicalLength alignment = 1);
 336
 337 /*! @function initWithSpecification
 338     @abstract Primary initialiser for the IOLittleMemoryCursor class.
 339     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
 340     @param maxTransferSize Maximum size of an entire transfer.  Default to 0 indicating no maximum.
 341     @param alignment Alligment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
 342     @result true if the inherited classes and this instance initialise
 343 successfully.
 344 */
 345     virtual bool initWithSpecification(IOPhysicalLength  maxSegmentSize,
 346                                        IOPhysicalLength  maxTransferSize,
 347                                        IOPhysicalLength  alignment = 1);
 348
 349
 350 /*! @function getPhysicalSegments
 351     @abstract Generate a little endian physical scatter/gather list given a memory descriptor.
 352     @discussion Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor.  Wraps $link IOMemoryCursor::genPhysicalSegments.
 353     @param descriptor IOMemoryDescriptor that describes the data associated with an I/O request.
 354     @param fromPosition Starting location of the I/O within a memory descriptor.
 355     @param segments Pointer to an array of $link IOMemoryCursor::PhysicalSegments for the output physical scatter/gather list.
 356     @param maxSegments Maximum number of segments that can be written to segments array.
 357     @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.
 358     @param transferSize Pointer to a IOByteCount variable that can contain the total size of the transfer being described.  Default to 0 indicating that no transfer size need be returned.
 359     @result If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.
 360 */
 361     virtual UInt32 getPhysicalSegments(IOMemoryDescriptor * descriptor,
 362                                        IOByteCount          fromPosition,
 363                                        PhysicalSegment *    segments,
 364                                        UInt32               maxSegments,
 365                                        UInt32               maxTransferSize = 0,
 366                                        IOByteCount       *  transferSize = 0)
 367     {
 368         return genPhysicalSegments(descriptor, fromPosition, segments,
 369                                 maxSegments, maxTransferSize, transferSize);
 370     }
 371 };
 372
 373 /************************* class IODBDMAMemoryCursor *************************/
 374
 375 #if defined(__ppc__)
 376
 377 struct IODBDMADescriptor;
 378
 379 /*!
 380     @class IODBDMAMemoryCursor : public IOMemoryCursor
 381     @abstract A $link IOMemoryCursor subclass that outputs a vector of DBDMA descriptors where the address and length are filled in.
 382     @discussion The IODBDMAMemoryCursor would be used when the DBDMA hardware is available for the device for that will use an instance of this cursor.
 383 */
 384 class IODBDMAMemoryCursor : public IOMemoryCursor
 385 {
 386     OSDeclareDefaultStructors(IODBDMAMemoryCursor)
 387
 388 public:
 389 /*! @funtion outputSegment
 390     @abstract Output the given segment into the output segments array in address and length fields of an DBDMA descriptor.
 391     @param segment The physical address and length that is next to be output.
 392     @param segments Base of the output vector of DMA address length pairs.
 393     @param segmentIndex Index to output 'segment' in the 'segments' array.
 394 */
 395     static void outputSegment(PhysicalSegment segment,
 396                               void *          segments,
 397                               UInt32          segmentIndex);
 398
 399 /*! @defined dbdmaOutputSegment
 400     @discussion Backward compatibilty define for the old global function definition.  See $link IODBDMAMemoryCursor::outputSegment */
 401 #define dbdmaOutputSegment IODBDMAMemoryCursor::outputSegment
 402
 403 /*! @function withSpecification
 404     @abstract Factory function to create and initialise an IODBDMAMemoryCursor in one operation, see $link IODBDMAMemoryCursor::initWithSpecification.
 405     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
 406     @param maxTransferSize Maximum size of an entire transfer.  Default to 0 indicating no maximum.
 407     @param alignment Alligment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
 408     @result A new memory cursor if successfully created and initialised, 0 otherwise.
 409 */
 410     static IODBDMAMemoryCursor *
 411         withSpecification(IOPhysicalLength maxSegmentSize,
 412                           IOPhysicalLength maxTransferSize,
 413                           IOPhysicalLength alignment = 1);
 414
 415 /*! @function initWithSpecification
 416     @abstract Primary initialiser for the IODBDMAMemoryCursor class.
 417     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
 418     @param maxTransferSize Maximum size of an entire transfer.  Default to 0 indicating no maximum.
 419     @param alignment Alligment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
 420     @result true if the inherited classes and this instance initialise
 421 successfully.
 422 */
 423     virtual bool initWithSpecification(IOPhysicalLength  maxSegmentSize,
 424                                        IOPhysicalLength  maxTransferSize,
 425                                        IOPhysicalLength  alignment = 1);
 426
 427
 428 /*! @function getPhysicalSegments
 429     @abstract Generate a DBDMA physical scatter/gather list given a memory descriptor.
 430     @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 teh DBDMA descriptor as is appropriate for their particular hardware.  Wraps $link IOMemoryCursor::genPhysicalSegments.
 431     @param descriptor IOMemoryDescriptor that describes the data associated with an I/O request.
 432     @param fromPosition Starting location of the I/O within a memory descriptor.
 433     @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.
 434     @param maxSegments Maximum number of segments that can be written to the dbdma descriptor table.
 435     @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.
 436     @param transferSize Pointer to a IOByteCount variable that can contain the total size of the transfer being described.  Default to 0 indicating that no transfer size need be returned.
 437     @result If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.
 438 */
 439     virtual UInt32 getPhysicalSegments(IOMemoryDescriptor * descriptor,
 440                                        IOByteCount          fromPosition,
 441                                        IODBDMADescriptor *  segments,
 442                                        UInt32               maxSegments,
 443                                        UInt32               maxTransferSize = 0,
 444                                        IOByteCount       *  transferSize = 0)
 445     {
 446         return genPhysicalSegments(descriptor, fromPosition, segments,
 447                                 maxSegments, maxTransferSize, transferSize);
 448     }
 449 };
 450
 451 #endif /* defined(__ppc__) */
 452
 453 #endif /* !_IOMEMORYCURSOR_H */
 454