| 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 | ␊ |
| 463 | |
