iokit/IOKit/IOMemoryCursor.h

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