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