]> git.saurik.com Git - apple/xnu.git/blobdiff - iokit/IOKit/IOMemoryCursor.h
projects / apple / xnu.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
xnu-7195.101.1.tar.gz
[apple/xnu.git] / iokit / IOKit / IOMemoryCursor.h
diff --git a/iokit/IOKit/IOMemoryCursor.h b/iokit/IOKit/IOMemoryCursor.h
index 048cdf5845308ba626647a6144307db19666ec54..22eea326e19bb9e62eacedd9502df1cc20183f84 100644 (file)
--- a/iokit/IOKit/IOMemoryCursor.h
+++ b/iokit/IOKit/IOMemoryCursor.h
@@ -1,8 +1,8 @@
 /*
 /*
- * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
+ * Copyright (c) 1998-2019 Apple Inc. All rights reserved.
  *
  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
  *
  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
- * 
+ *
  * This file contains Original Code and/or Modifications of Original Code
  * as defined in and that are subject to the Apple Public Source License
  * Version 2.0 (the 'License'). You may not use this file except in
  * This file contains Original Code and/or Modifications of Original Code
  * as defined in and that are subject to the Apple Public Source License
  * Version 2.0 (the 'License'). You may not use this file except in
@@ -11,10 +11,10 @@
  * unlawful or unlicensed copies of an Apple operating system, or to
  * circumvent, violate, or enable the circumvention or violation of, any
  * terms of an Apple operating system software license agreement.
  * unlawful or unlicensed copies of an Apple operating system, or to
  * circumvent, violate, or enable the circumvention or violation of, any
  * terms of an Apple operating system software license agreement.
- * 
+ *
  * Please obtain a copy of the License at
  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  * Please obtain a copy of the License at
  * http://www.opensource.apple.com/apsl/ and read it before using this file.
- * 
+ *
  * The Original Code and all software distributed under the License are
  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  * The Original Code and all software distributed under the License are
  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
@@ -22,13 +22,14 @@
  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  * Please see the License for the specific language governing rights and
  * limitations under the License.
  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  * Please see the License for the specific language governing rights and
  * limitations under the License.
- * 
+ *
  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  */
 #ifndef _IOMEMORYCURSOR_H
 #define _IOMEMORYCURSOR_H
 
 #include <libkern/c++/OSObject.h>
  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  */
 #ifndef _IOMEMORYCURSOR_H
 #define _IOMEMORYCURSOR_H
 
 #include <libkern/c++/OSObject.h>
+#include <libkern/c++/OSPtr.h>
 #include <IOKit/IOTypes.h>
 
 class IOMemoryDescriptor;
 #include <IOKit/IOTypes.h>
 
 class IOMemoryDescriptor;
@@ -36,347 +37,348 @@ class IOMemoryDescriptor;
 /**************************** class IOMemoryCursor ***************************/
 
 /*!
 /**************************** class IOMemoryCursor ***************************/
 
 /*!
-    @class IOMemoryCursor
-    @abstract A mechanism to convert memory references to physical addresses.
-    @discussion The IOMemoryCursor declares the super class that all
-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.
-<br><br>
-    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.
-<br><br>
-Below is the simplest example of a SegmentFunction:<br>
-void IONaturalMemoryCursor::outputSegment(PhysicalSegment segment,<br>
-                                         void *          outSegments,<br>
-                                         UInt32          outSegmentIndex)<br>
-{<br>
-    ((PhysicalSegment *) outSegments)[outSegmentIndex] = segment;<br>
-}
-
-*/
+ *   @class IOMemoryCursor
+ *   @abstract A mechanism to convert memory references to physical addresses.
+ *   @discussion The IOMemoryCursor declares the super class that all
+ *  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.
+ *  <br><br>
+ *   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.
+ *  <br><br>
+ *  Below is the simplest example of a SegmentFunction:<br>
+ *  void IONaturalMemoryCursor::outputSegment(PhysicalSegment segment,<br>
+ *                                         void *        outSegments,<br>
+ *                                         UInt32        outSegmentIndex)<br>
+ *  {<br>
+ *   ((PhysicalSegment *) outSegments)[outSegmentIndex] = segment;<br>
+ *  }
+ *
+ */
 class IOMemoryCursor : public OSObject
 {
 class IOMemoryCursor : public OSObject
 {
-    OSDeclareDefaultStructors(IOMemoryCursor)
+       OSDeclareDefaultStructors(IOMemoryCursor);
 
 public:
 /*!
 
 public:
 /*!
-    @typedef PhysicalSegment
-    @discussion A physical address/length pair.
-*/
-    struct PhysicalSegment
-    {
-       IOPhysicalAddress location;
-       IOPhysicalLength  length;
-    };
+ *   @typedef PhysicalSegment
+ *   @discussion A physical address/length pair.
+ */
+       struct PhysicalSegment {
+               IOPhysicalAddress location;
+               IOPhysicalLength  length;
+       };
 
 /*! @defined IOPhysicalSegment
 
 /*! @defined IOPhysicalSegment
-    @discussion Backward compatibility define for the old non-class scoped type definition.  See IOMemoryCursor::PhysicalSegment 
-*/
+ *   @discussion Backward compatibility define for the old non-class scoped type definition.  See IOMemoryCursor::PhysicalSegment
+ */
 #define IOPhysicalSegment IOMemoryCursor::PhysicalSegment
 
 /*!
 #define IOPhysicalSegment IOMemoryCursor::PhysicalSegment
 
 /*!
-    @typedef SegmentFunction
-    @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.
-    @param segment The physical address and length that is next to be output.
-    @param segments Base of the output vector of DMA address length pairs.
-    @param segmentIndex Index to output 'segment' in the 'segments' array.
-*/
-    typedef void (*SegmentFunction)(PhysicalSegment segment,
-                                   void *          segments,
-                                   UInt32          segmentIndex);
+ *   @typedef SegmentFunction
+ *   @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.
+ *   @param segment The physical address and length that is next to be output.
+ *   @param segments Base of the output vector of DMA address length pairs.
+ *   @param segmentIndex Index to output 'segment' in the 'segments' array.
+ */
+       typedef void (*SegmentFunction)(PhysicalSegment segment,
+           void *          segments,
+           UInt32          segmentIndex);
 
 /*! @defined OutputSegmentFunc
 
 /*! @defined OutputSegmentFunc
-    @discussion Backward compatibility define for the old non-class scoped type definition.  See IOMemoryCursor::SegmentFunction */
+ *   @discussion Backward compatibility define for the old non-class scoped type definition.  See IOMemoryCursor::SegmentFunction */
 #define OutputSegmentFunc IOMemoryCursor::SegmentFunction
 
 protected:
 /*! @var outSeg The action method called when an event has been delivered */
 #define OutputSegmentFunc IOMemoryCursor::SegmentFunction
 
 protected:
 /*! @var outSeg The action method called when an event has been delivered */
-    SegmentFunction outSeg;
+       SegmentFunction outSeg;
 
 /*! @var maxSegmentSize Maximum size of one segment in a scatter/gather list */
 
 /*! @var maxSegmentSize Maximum size of one segment in a scatter/gather list */
-    IOPhysicalLength  maxSegmentSize;
+       IOPhysicalLength  maxSegmentSize;
 
 /*! @var maxTransferSize
 
 /*! @var maxTransferSize
-    Maximum size of a transfer that this memory cursor is allowed to generate */
-    IOPhysicalLength  maxTransferSize;
+ *   Maximum size of a transfer that this memory cursor is allowed to generate */
+       IOPhysicalLength  maxTransferSize;
 
 /*! @var alignMask
 
 /*! @var alignMask
-    Currently unused.  Reserved for automated aligment restriction code. */
-    IOPhysicalLength  alignMask;
+ *   Currently unused.  Reserved for automated aligment restriction code. */
+       IOPhysicalLength  alignMask;
 
 public:
 /*! @function withSpecification
 
 public:
 /*! @function withSpecification
-    @abstract Creates and initializes an IOMemoryCursor in one operation.
-    @discussion Factory function to create and initialize an IOMemoryCursor in one operation.  For more information, see IOMemoryCursor::initWithSpecification.
-    @param outSegFunc SegmentFunction to call to output one physical segment.
-    @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
-    @param maxTransferSize Maximum size of an entire transfer. Defaults to 0 indicating no maximum.
-    @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
-    @result Returns a new memory cursor if successfully created and initialized, 0 otherwise.
-*/
-    static IOMemoryCursor *
+ *   @abstract Creates and initializes an IOMemoryCursor in one operation.
+ *   @discussion Factory function to create and initialize an IOMemoryCursor in one operation.  For more information, see IOMemoryCursor::initWithSpecification.
+ *   @param outSegFunc SegmentFunction to call to output one physical segment.
+ *   @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
+ *   @param maxTransferSize Maximum size of an entire transfer.        Defaults to 0 indicating no maximum.
+ *   @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
+ *   @result Returns a new memory cursor if successfully created and initialized, 0 otherwise.
+ */
+       static OSPtr<IOMemoryCursor>
        withSpecification(SegmentFunction  outSegFunc,
        withSpecification(SegmentFunction  outSegFunc,
-                         IOPhysicalLength maxSegmentSize = 0,
-                         IOPhysicalLength maxTransferSize = 0,
-                         IOPhysicalLength alignment = 1);
+           IOPhysicalLength maxSegmentSize = 0,
+           IOPhysicalLength maxTransferSize = 0,
+           IOPhysicalLength alignment = 1);
 
 /*! @function initWithSpecification
 
 /*! @function initWithSpecification
-    @abstract Primary initializer for the IOMemoryCursor class.
-    @param outSegFunc SegmentFunction to call to output one physical segment.
-    @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
-    @param maxTransferSize Maximum size of an entire transfer. Defaults to 0 indicating no maximum.
-    @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
-    @result Returns true if the inherited classes and this instance initialize
-successfully.
-*/
-    virtual bool initWithSpecification(SegmentFunction outSegFunc,
-                                      IOPhysicalLength maxSegmentSize = 0,
-                                      IOPhysicalLength maxTransferSize = 0,
-                                      IOPhysicalLength alignment = 1);
+ *   @abstract Primary initializer for the IOMemoryCursor class.
+ *   @param outSegFunc SegmentFunction to call to output one physical segment.
+ *   @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
+ *   @param maxTransferSize Maximum size of an entire transfer.        Defaults to 0 indicating no maximum.
+ *   @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
+ *   @result Returns true if the inherited classes and this instance initialize
+ *  successfully.
+ */
+       virtual bool initWithSpecification(SegmentFunction  outSegFunc,
+           IOPhysicalLength maxSegmentSize = 0,
+           IOPhysicalLength maxTransferSize = 0,
+           IOPhysicalLength alignment = 1);
 
 /*! @function genPhysicalSegments
 
 /*! @function genPhysicalSegments
-    @abstract Generates a physical scatter/gather list given a memory descriptor.
-    @discussion Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor.
-    @param descriptor IOMemoryDescriptor that describes the data associated with an I/O request. 
-    @param fromPosition Starting location of the I/O within a memory descriptor. 
-    @param segments Void pointer to base of output physical scatter/gather list.  Always passed directly onto the SegmentFunction without interpretation by the cursor. 
-    @param maxSegments Maximum number of segments that can be written to segments array.
-    @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.
-    @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. 
-    @result If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.
-*/
-    virtual UInt32 genPhysicalSegments(
-                                     IOMemoryDescriptor *descriptor,
-                                     IOByteCount         fromPosition,
-                                     void *              segments,
-                                     UInt32              maxSegments,
-                                     UInt32              maxTransferSize = 0,
-                                     IOByteCount        *transferSize = 0);
+ *   @abstract Generates a physical scatter/gather list given a memory descriptor.
+ *   @discussion Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor.
+ *   @param descriptor IOMemoryDescriptor that describes the data associated with an I/O request.
+ *   @param fromPosition Starting location of the I/O within a memory descriptor.
+ *   @param segments Void pointer to base of output physical scatter/gather list.  Always passed directly onto the SegmentFunction without interpretation by the cursor.
+ *   @param maxSegments Maximum number of segments that can be written to segments array.
+ *   @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.
+ *   @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.
+ *   @result If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.
+ */
+       virtual UInt32 genPhysicalSegments(
+               IOMemoryDescriptor *descriptor,
+               IOByteCount         fromPosition,
+               void *              segments,
+               UInt32              maxSegments,
+               UInt32              maxTransferSize = 0,
+               IOByteCount        *transferSize = NULL);
 };
 
 /************************ class IONaturalMemoryCursor ************************/
 
 
 /*!
 };
 
 /************************ class IONaturalMemoryCursor ************************/
 
 
 /*!
-    @class IONaturalMemoryCursor
-    @abstract An IOMemoryCursor subclass that outputs a vector of PhysicalSegments in the natural byte orientation for the CPU.  
-    @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.
-*/
+ *   @class IONaturalMemoryCursor
+ *   @abstract An IOMemoryCursor subclass that outputs a vector of PhysicalSegments in the natural byte orientation for the CPU.
+ *   @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.
+ */
 class IONaturalMemoryCursor : public IOMemoryCursor
 {
 class IONaturalMemoryCursor : public IOMemoryCursor
 {
-    OSDeclareDefaultStructors(IONaturalMemoryCursor)
+       OSDeclareDefaultStructors(IONaturalMemoryCursor);
 
 public:
 /*! @function outputSegment
 
 public:
 /*! @function outputSegment
-    @abstract Outputs the given segment into the output segments array in natural byte order.
-    @param segment The physical address and length that is next to be output.
-    @param segments Base of the output vector of DMA address length pairs.
-    @param segmentIndex Index to output 'segment' in the 'segments' array.
-*/
-    static void outputSegment(PhysicalSegment segment,
-                             void *          segments,
-                             UInt32          segmentIndex);
+ *   @abstract Outputs the given segment into the output segments array in natural byte order.
+ *   @param segment The physical address and length that is next to be output.
+ *   @param segments Base of the output vector of DMA address length pairs.
+ *   @param segmentIndex Index to output 'segment' in the 'segments' array.
+ */
+       static void outputSegment(PhysicalSegment segment,
+           void *          segments,
+           UInt32          segmentIndex);
 
 /*! @defined naturalOutputSegment
 
 /*! @defined naturalOutputSegment
-    @discussion Backward compatibility define for the old global function definition.  See IONaturalMemoryCursor::outputSegment.
-*/
+ *   @discussion Backward compatibility define for the old global function definition.  See IONaturalMemoryCursor::outputSegment.
+ */
 #define naturalOutputSegment IONaturalMemoryCursor::outputSegment
 
 /*! @function withSpecification
 #define naturalOutputSegment IONaturalMemoryCursor::outputSegment
 
 /*! @function withSpecification
-    @abstract Creates and initializes an IONaturalMemoryCursor in one operation.
-    @discussion Factory function to create and initialize an IONaturalMemoryCursor in one operation.  For more information, see IONaturalMemoryCursor::initWithSpecification.
-    @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
-    @param maxTransferSize Maximum size of an entire transfer. Defaults to 0 indicating no maximum.
-    @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
-    @result Returns a new memory cursor if successfully created and initialized, 0 otherwise.
-*/
-    static IONaturalMemoryCursor * 
+ *   @abstract Creates and initializes an IONaturalMemoryCursor in one operation.
+ *   @discussion Factory function to create and initialize an IONaturalMemoryCursor in one operation.  For more information, see IONaturalMemoryCursor::initWithSpecification.
+ *   @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
+ *   @param maxTransferSize Maximum size of an entire transfer.        Defaults to 0 indicating no maximum.
+ *   @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
+ *   @result Returns a new memory cursor if successfully created and initialized, 0 otherwise.
+ */
+       static OSPtr<IONaturalMemoryCursor>
        withSpecification(IOPhysicalLength maxSegmentSize,
        withSpecification(IOPhysicalLength maxSegmentSize,
-                         IOPhysicalLength maxTransferSize,
-                         IOPhysicalLength alignment = 1);
+           IOPhysicalLength maxTransferSize,
+           IOPhysicalLength alignment = 1);
 
 /*! @function initWithSpecification
 
 /*! @function initWithSpecification
-    @abstract Primary initializer for the IONaturalMemoryCursor class.
-    @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
-    @param maxTransferSize Maximum size of an entire transfer. Defaults to 0 indicating no maximum.
-    @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
-    @result Returns true if the inherited classes and this instance initialize successfully.
-*/
-    virtual bool initWithSpecification(IOPhysicalLength         maxSegmentSize,
-                                      IOPhysicalLength  maxTransferSize,
-                                      IOPhysicalLength  alignment = 1);
+ *   @abstract Primary initializer for the IONaturalMemoryCursor class.
+ *   @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
+ *   @param maxTransferSize Maximum size of an entire transfer.        Defaults to 0 indicating no maximum.
+ *   @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
+ *   @result Returns true if the inherited classes and this instance initialize successfully.
+ */
+       virtual bool initWithSpecification(IOPhysicalLength  maxSegmentSize,
+           IOPhysicalLength  maxTransferSize,
+           IOPhysicalLength  alignment = 1);
 
 
 /*! @function getPhysicalSegments
 
 
 /*! @function getPhysicalSegments
-    @abstract Generates a CPU natural physical scatter/gather list given a memory descriptor.
-    @discussion Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor.  Wraps IOMemoryCursor::genPhysicalSegments.
-    @param descriptor IOMemoryDescriptor that describes the data associated with an I/O request. 
-    @param fromPosition Starting location of the I/O within a memory descriptor. 
-    @param segments Pointer to an array of IOMemoryCursor::PhysicalSegments for the output physical scatter/gather list.
-    @param maxSegments Maximum number of segments that can be written to segments array.
-    @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.
-    @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. 
-    @result If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.
-*/
-    virtual UInt32 getPhysicalSegments(IOMemoryDescriptor *descriptor,
-                                      IOByteCount         fromPosition,
-                                      PhysicalSegment    *segments,
-                                      UInt32              maxSegments,
-                                      UInt32              inMaxTransferSize = 0,
-                                      IOByteCount        *transferSize = 0)
-    {
-       return genPhysicalSegments(descriptor, fromPosition, segments,
-                               maxSegments, inMaxTransferSize, transferSize);
-    }
+ *   @abstract Generates a CPU natural physical scatter/gather list given a memory descriptor.
+ *   @discussion Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor.  Wraps IOMemoryCursor::genPhysicalSegments.
+ *   @param descriptor IOMemoryDescriptor that describes the data associated with an I/O request.
+ *   @param fromPosition Starting location of the I/O within a memory descriptor.
+ *   @param segments Pointer to an array of IOMemoryCursor::PhysicalSegments for the output physical scatter/gather list.
+ *   @param maxSegments Maximum number of segments that can be written to segments array.
+ *   @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.
+ *   @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.
+ *   @result If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.
+ */
+       virtual UInt32
+       getPhysicalSegments(IOMemoryDescriptor *descriptor,
+           IOByteCount         fromPosition,
+           PhysicalSegment    *segments,
+           UInt32              maxSegments,
+           UInt32              inMaxTransferSize = 0,
+           IOByteCount        *transferSize = NULL)
+       {
+               return genPhysicalSegments(descriptor, fromPosition, segments,
+                          maxSegments, inMaxTransferSize, transferSize);
+       }
 };
 
 /************************** class IOBigMemoryCursor **************************/
 
 /*!
 };
 
 /************************** class IOBigMemoryCursor **************************/
 
 /*!
-    @class IOBigMemoryCursor
-    @abstract An IOMemoryCursor subclass that outputs a vector of PhysicalSegments in the big endian byte order.  
-    @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.
-*/
+ *   @class IOBigMemoryCursor
+ *   @abstract An IOMemoryCursor subclass that outputs a vector of PhysicalSegments in the big endian byte order.
+ *   @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.
+ */
 class IOBigMemoryCursor : public IOMemoryCursor
 {
 class IOBigMemoryCursor : public IOMemoryCursor
 {
-    OSDeclareDefaultStructors(IOBigMemoryCursor)
+       OSDeclareDefaultStructors(IOBigMemoryCursor);
 
 public:
 /*! @function outputSegment
 
 public:
 /*! @function outputSegment
-    @abstract Outputs the given segment into the output segments array in big endian byte order.
-    @param segment The physical address and length that is next to be output.
-    @param segments Base of the output vector of DMA address length pairs.
-    @param segmentIndex Index to output 'segment' in the 'segments' array.
-*/
-    static void outputSegment(PhysicalSegment segment,
-                             void *          segments,
-                             UInt32          segmentIndex);
+ *   @abstract Outputs the given segment into the output segments array in big endian byte order.
+ *   @param segment The physical address and length that is next to be output.
+ *   @param segments Base of the output vector of DMA address length pairs.
+ *   @param segmentIndex Index to output 'segment' in the 'segments' array.
+ */
+       static void outputSegment(PhysicalSegment segment,
+           void *          segments,
+           UInt32          segmentIndex);
 
 /*! @defined bigOutputSegment
 
 /*! @defined bigOutputSegment
-    @discussion Backward compatibility define for the old global function definition.  See IOBigMemoryCursor::outputSegment 
-*/
+ *   @discussion Backward compatibility define for the old global function definition.  See IOBigMemoryCursor::outputSegment
+ */
 #define bigOutputSegment IOBigMemoryCursor::outputSegment
 
 /*! @function withSpecification
 #define bigOutputSegment IOBigMemoryCursor::outputSegment
 
 /*! @function withSpecification
-    @abstract Creates and initializes an IOBigMemoryCursor in one operation.
-    @discussion Factory function to create and initialize an IOBigMemoryCursor in one operation.  See also IOBigMemoryCursor::initWithSpecification.
-    @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
-    @param maxTransferSize Maximum size of an entire transfer. Defaults to 0 indicating no maximum.
-    @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
-    @result Returns a new memory cursor if successfully created and initialized, 0 otherwise.
-*/
-    static IOBigMemoryCursor *
+ *   @abstract Creates and initializes an IOBigMemoryCursor in one operation.
+ *   @discussion Factory function to create and initialize an IOBigMemoryCursor in one operation.  See also IOBigMemoryCursor::initWithSpecification.
+ *   @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
+ *   @param maxTransferSize Maximum size of an entire transfer.        Defaults to 0 indicating no maximum.
+ *   @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
+ *   @result Returns a new memory cursor if successfully created and initialized, 0 otherwise.
+ */
+       static OSPtr<IOBigMemoryCursor>
        withSpecification(IOPhysicalLength maxSegmentSize,
        withSpecification(IOPhysicalLength maxSegmentSize,
-                         IOPhysicalLength maxTransferSize,
-                         IOPhysicalLength alignment = 1);
+           IOPhysicalLength maxTransferSize,
+           IOPhysicalLength alignment = 1);
 
 /*! @function initWithSpecification
 
 /*! @function initWithSpecification
-    @abstract Primary initializer for the IOBigMemoryCursor class.
-    @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
-    @param maxTransferSize Maximum size of an entire transfer. Defaults to 0 indicating no maximum.
-    @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
-    @result Returns true if the inherited classes and this instance initialize
-successfully.
-*/
-    virtual bool initWithSpecification(IOPhysicalLength         maxSegmentSize,
-                                      IOPhysicalLength  maxTransferSize,
-                                      IOPhysicalLength  alignment = 1);
+ *   @abstract Primary initializer for the IOBigMemoryCursor class.
+ *   @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
+ *   @param maxTransferSize Maximum size of an entire transfer.        Defaults to 0 indicating no maximum.
+ *   @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
+ *   @result Returns true if the inherited classes and this instance initialize
+ *  successfully.
+ */
+       virtual bool initWithSpecification(IOPhysicalLength  maxSegmentSize,
+           IOPhysicalLength  maxTransferSize,
+           IOPhysicalLength  alignment = 1);
 
 
 /*! @function getPhysicalSegments
 
 
 /*! @function getPhysicalSegments
-    @abstract Generates a big endian physical scatter/gather list given a memory descriptor.
-    @discussion Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor.  Wraps IOMemoryCursor::genPhysicalSegments.
-    @param descriptor IOMemoryDescriptor that describes the data associated with an I/O request. 
-    @param fromPosition Starting location of the I/O within a memory descriptor. 
-    @param segments Pointer to an array of IOMemoryCursor::PhysicalSegments for the output physical scatter/gather list.
-    @param maxSegments Maximum number of segments that can be written to segments array.
-    @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.
-    @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. 
-    @result If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.
-*/
-    virtual UInt32 getPhysicalSegments(IOMemoryDescriptor * descriptor,
-                                      IOByteCount          fromPosition,
-                                      PhysicalSegment *    segments,
-                                      UInt32               maxSegments,
-                                      UInt32               inMaxTransferSize = 0,
-                                      IOByteCount       *  transferSize = 0)
-    {
-       return genPhysicalSegments(descriptor, fromPosition, segments,
-                               maxSegments, inMaxTransferSize, transferSize);
-    }
+ *   @abstract Generates a big endian physical scatter/gather list given a memory descriptor.
+ *   @discussion Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor.  Wraps IOMemoryCursor::genPhysicalSegments.
+ *   @param descriptor IOMemoryDescriptor that describes the data associated with an I/O request.
+ *   @param fromPosition Starting location of the I/O within a memory descriptor.
+ *   @param segments Pointer to an array of IOMemoryCursor::PhysicalSegments for the output physical scatter/gather list.
+ *   @param maxSegments Maximum number of segments that can be written to segments array.
+ *   @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.
+ *   @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.
+ *   @result If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.
+ */
+       virtual UInt32
+       getPhysicalSegments(IOMemoryDescriptor * descriptor,
+           IOByteCount          fromPosition,
+           PhysicalSegment *    segments,
+           UInt32               maxSegments,
+           UInt32               inMaxTransferSize = 0,
+           IOByteCount       *  transferSize = NULL)
+       {
+               return genPhysicalSegments(descriptor, fromPosition, segments,
+                          maxSegments, inMaxTransferSize, transferSize);
+       }
 };
 
 /************************* class IOLittleMemoryCursor ************************/
 
 /*!
 };
 
 /************************* class IOLittleMemoryCursor ************************/
 
 /*!
-    @class IOLittleMemoryCursor
-    @abstract An IOMemoryCursor subclass that outputs a vector of PhysicalSegments in the little endian byte order.  
-    @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.
-*/
+ *   @class IOLittleMemoryCursor
+ *   @abstract An IOMemoryCursor subclass that outputs a vector of PhysicalSegments in the little endian byte order.
+ *   @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.
+ */
 class IOLittleMemoryCursor : public IOMemoryCursor
 {
 class IOLittleMemoryCursor : public IOMemoryCursor
 {
-    OSDeclareDefaultStructors(IOLittleMemoryCursor)
+       OSDeclareDefaultStructors(IOLittleMemoryCursor);
 
 public:
 /*! @function outputSegment
 
 public:
 /*! @function outputSegment
-    @abstract Outputs the given segment into the output segments array in little endian byte order.
-    @param segment The physical address and length that is next to be output.
-    @param segments Base of the output vector of DMA address length pairs.
-    @param segmentIndex Index to output 'segment' in the 'segments' array.
-*/
-    static void outputSegment(PhysicalSegment segment,
-                             void *          segments,
-                             UInt32          segmentIndex);
+ *   @abstract Outputs the given segment into the output segments array in little endian byte order.
+ *   @param segment The physical address and length that is next to be output.
+ *   @param segments Base of the output vector of DMA address length pairs.
+ *   @param segmentIndex Index to output 'segment' in the 'segments' array.
+ */
+       static void outputSegment(PhysicalSegment segment,
+           void *          segments,
+           UInt32          segmentIndex);
 
 /*! @defined littleOutputSegment
 
 /*! @defined littleOutputSegment
-    @discussion Backward compatibility define for the old global function definition.  See also IOLittleMemoryCursor::outputSegment. */
+ *   @discussion Backward compatibility define for the old global function definition.  See also IOLittleMemoryCursor::outputSegment. */
 #define littleOutputSegment IOLittleMemoryCursor::outputSegment
 
 /*! @function withSpecification
 #define littleOutputSegment IOLittleMemoryCursor::outputSegment
 
 /*! @function withSpecification
-    @abstract Creates and initializes an IOLittleMemoryCursor in one operation.
-    @discussion Factory function to create and initialize an IOLittleMemoryCursor in one operation.  See also IOLittleMemoryCursor::initWithSpecification.
-    @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
-    @param maxTransferSize Maximum size of an entire transfer. Defaults to 0 indicating no maximum.
-    @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
-    @result Returns a new memory cursor if successfully created and initialized, 0 otherwise.
-*/
-    static IOLittleMemoryCursor *
+ *   @abstract Creates and initializes an IOLittleMemoryCursor in one operation.
+ *   @discussion Factory function to create and initialize an IOLittleMemoryCursor in one operation.  See also IOLittleMemoryCursor::initWithSpecification.
+ *   @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
+ *   @param maxTransferSize Maximum size of an entire transfer.        Defaults to 0 indicating no maximum.
+ *   @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
+ *   @result Returns a new memory cursor if successfully created and initialized, 0 otherwise.
+ */
+       static OSPtr<IOLittleMemoryCursor>
        withSpecification(IOPhysicalLength maxSegmentSize,
        withSpecification(IOPhysicalLength maxSegmentSize,
-                         IOPhysicalLength maxTransferSize,
-                         IOPhysicalLength alignment = 1);
+           IOPhysicalLength maxTransferSize,
+           IOPhysicalLength alignment = 1);
 
 /*! @function initWithSpecification
 
 /*! @function initWithSpecification
-    @abstract Primary initializer for the IOLittleMemoryCursor class.
-    @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
-    @param maxTransferSize Maximum size of an entire transfer. Defaults to 0 indicating no maximum.
-    @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
-    @result Returns true if the inherited classes and this instance initialize successfully.
-*/
-    virtual bool initWithSpecification(IOPhysicalLength         maxSegmentSize,
-                                      IOPhysicalLength  maxTransferSize,
-                                      IOPhysicalLength  alignment = 1);
+ *   @abstract Primary initializer for the IOLittleMemoryCursor class.
+ *   @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
+ *   @param maxTransferSize Maximum size of an entire transfer.        Defaults to 0 indicating no maximum.
+ *   @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
+ *   @result Returns true if the inherited classes and this instance initialize successfully.
+ */
+       virtual bool initWithSpecification(IOPhysicalLength  maxSegmentSize,
+           IOPhysicalLength  maxTransferSize,
+           IOPhysicalLength  alignment = 1);
 
 
 /*! @function getPhysicalSegments
 
 
 /*! @function getPhysicalSegments
-    @abstract Generates a little endian physical scatter/gather list given a memory descriptor.
-    @discussion Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor.  Wraps IOMemoryCursor::genPhysicalSegments.
-    @param descriptor IOMemoryDescriptor that describes the data associated with an I/O request. 
-    @param fromPosition Starting location of the I/O within a memory descriptor. 
-    @param segments Pointer to an array of IOMemoryCursor::PhysicalSegments for the output physical scatter/gather list.
-    @param maxSegments Maximum number of segments that can be written to segments array.
-    @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.
-    @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. 
-    @result If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.
-*/
-    virtual UInt32 getPhysicalSegments(IOMemoryDescriptor * descriptor,
-                                      IOByteCount          fromPosition,
-                                      PhysicalSegment *    segments,
-                                      UInt32               maxSegments,
-                                      UInt32               inMaxTransferSize = 0,
-                                      IOByteCount       *  transferSize = 0)
-    {
-       return genPhysicalSegments(descriptor, fromPosition, segments,
-                               maxSegments, inMaxTransferSize, transferSize);
-    }
+ *   @abstract Generates a little endian physical scatter/gather list given a memory descriptor.
+ *   @discussion Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor.  Wraps IOMemoryCursor::genPhysicalSegments.
+ *   @param descriptor IOMemoryDescriptor that describes the data associated with an I/O request.
+ *   @param fromPosition Starting location of the I/O within a memory descriptor.
+ *   @param segments Pointer to an array of IOMemoryCursor::PhysicalSegments for the output physical scatter/gather list.
+ *   @param maxSegments Maximum number of segments that can be written to segments array.
+ *   @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.
+ *   @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.
+ *   @result If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.
+ */
+       virtual UInt32
+       getPhysicalSegments(IOMemoryDescriptor * descriptor,
+           IOByteCount          fromPosition,
+           PhysicalSegment *    segments,
+           UInt32               maxSegments,
+           UInt32               inMaxTransferSize = 0,
+           IOByteCount       *  transferSize = NULL)
+       {
+               return genPhysicalSegments(descriptor, fromPosition, segments,
+                          maxSegments, inMaxTransferSize, transferSize);
+       }
 };
 
 #endif /* !_IOMEMORYCURSOR_H */
 };
 
 #endif /* !_IOMEMORYCURSOR_H */
-
mirror of XNU