iokit/IOKit/IODMACommand.h

   1 /*
   2  * Copyright (c) 2005 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 _IODMACOMMAND_H
  29 #define _IODMACOMMAND_H
  30
  31 #include <IOKit/IOCommand.h>
  32 #include <IOKit/IOMemoryDescriptor.h>
  33 class IOMapper;
  34 class IOBufferMemoryDescriptor;
  35
  36 /**************************** class IODMACommand ***************************/
  37
  38 /*!
  39     @class IODMACommand
  40     @abstract A mechanism to convert memory references to I/O bus addresses.
  41     @discussion The IODMACommand is supersedes the IOMemoryCursor and greatly enhances the functionality and power of it.  The command can be specified to output 64 bit physical addresses and also allows driver writers bypass mapping hardware or get addresses suitable for non-snooped DMA.
  42 <br><br>
  43     The command is designed to be very easily subclassable.  Most driver writers need to associate some DMA operations with their memory descriptor and usually use a C structure for that purpose.  This structure is often kept in a linked list.  This IODMACommand has built it <kern/queue.h> linkage and can be derived and 'public:' variables added, giving the developer a structure that can associate a memory descriptor with a particular dma command but will also allow the developer to generate that command and keep the state necessary for tracking it.
  44 <br><br>
  45     It is envisaged that a pool of IODMACommands will be created at driver initialisation and each command will be kept in an IOCommandPool while not in use.  However if developers wishes to maintain their own free lists that is certainly possible.  See the <kern/queue.h> and <xnu/iokit/Kernel/IOCommandPool> for sample code on manipulating the command's doubly linked list entries.
  46 <br><br>
  47     The IODMACommand can be used in a 'weak-linked' manner.  To do this you must avoid using any static member functions.  Use the, much slower but safe, weakWithSpecification function.  On success a dma command instance will be returned.  This instance can then be used to clone as many commands as is needed.  Remember deriving from this class can not be done weakly, that is no weak subclassing!
  48 */
  49
  50
  51 enum
  52 {
  53     kIODMAMapOptionMapped       = 0x00000000,
  54     kIODMAMapOptionBypassed     = 0x00000001,
  55     kIODMAMapOptionNonCoherent  = 0x00000002,
  56     kIODMAMapOptionUnmapped     = 0x00000003,
  57     kIODMAMapOptionTypeMask     = 0x0000000f,
  58
  59     kIODMAMapOptionNoCacheStore = 0x00000010,   // Memory in descriptor
  60     kIODMAMapOptionOnChip       = 0x00000020,   // Indicates DMA is on South Bridge
  61     kIODMAMapOptionIterateOnly  = 0x00000040    // DMACommand will be used as a cursor only
  62 };
  63
  64 class IODMACommand : public IOCommand
  65 {
  66     OSDeclareDefaultStructors(IODMACommand);
  67
  68 friend class IODMAEventSource;
  69
  70 public:
  71
  72 /*!
  73     @typedef Segment32
  74     @discussion A 32 bit I/O bus address/length pair
  75 */
  76     struct Segment32 {
  77         UInt32 fIOVMAddr, fLength;
  78     };
  79
  80 /*!
  81     @typedef Segment64
  82     @discussion A 64 bit I/O bus address/length pair
  83 */
  84     struct Segment64 {
  85         UInt64 fIOVMAddr, fLength;
  86     };
  87
  88 /*! @enum MappingOptions
  89     @abstract Mapping types to indicate the desired mapper type for translating memory descriptors into I/O DMA Bus addresses.
  90     @constant kNonCoherent      Used by drivers for non-coherent transfers, implies unmapped memmory
  91     @constant kMapped           Allow a driver to define addressing size
  92     @constant kBypassed         Allow drivers to bypass any mapper
  93     @constant kMaxMappingOptions        Internal use only
  94 */
  95     enum MappingOptions {
  96         kMapped       = kIODMAMapOptionMapped,
  97         kBypassed     = kIODMAMapOptionBypassed,
  98         kNonCoherent  = kIODMAMapOptionNonCoherent,
  99         kUnmapped     = kIODMAMapOptionUnmapped,
 100         kTypeMask     = kIODMAMapOptionTypeMask,
 101
 102         kNoCacheStore = kIODMAMapOptionNoCacheStore,    // Memory in descriptor
 103         kOnChip       = kIODMAMapOptionOnChip,          // Indicates DMA is on South Bridge
 104         kIterateOnly  = kIODMAMapOptionIterateOnly      // DMACommand will be used as a cursor only
 105     };
 106
 107     struct SegmentOptions {
 108         uint8_t  fStructSize;
 109         uint8_t  fNumAddressBits;
 110         uint64_t fMaxSegmentSize;
 111         uint64_t fMaxTransferSize;
 112         uint32_t fAlignment;
 113         uint32_t fAlignmentLength;
 114         uint32_t fAlignmentInternalSegments;
 115     };
 116
 117 /*! @enum SynchronizeOptions
 118     @abstract Options for the synchronize method.
 119     @constant kForceDoubleBuffer Copy the entire prepared range to a new page aligned buffer.
 120 */
 121     enum SynchronizeOptions {
 122         kForceDoubleBuffer = 0x01000000
 123     };
 124
 125 /*!
 126     @typedef SegmentFunction
 127     @discussion Pointer to a C function that translates a 64 segment and outputs a single desired segment to the array at the requested index. There are a group of pre-implemented SegmentFunctions that may be usefull to the developer below.
 128     @param segment The 64Bit I/O bus address and length.
 129     @param segments Base of the output vector of DMA address length pairs.
 130     @param segmentIndex Index to output 'segment' in the 'segments' array.
 131     @result Returns true if segment encoding succeeded.  false may be returned if the current segment does not fit in an output segment, i.e. a 38bit address wont fit into a 32 encoding.
 132 */
 133     typedef bool (*SegmentFunction)(IODMACommand *target,
 134                                     Segment64 segment,
 135                                     void     *segments,
 136                                     UInt32    segmentIndex);
 137
 138     // -------------- Preimplemented output functions ----------------
 139
 140 /*! @function OutputHost32
 141     @abstract Output host natural Segment32 output segment function.
 142 */
 143     static bool OutputHost32(IODMACommand *target,
 144             Segment64 seg, void *segs, UInt32 ind);
 145
 146 /*! @defined kIODMACommandOutputHost32
 147     @abstract Output host natural Segment32 output segment function.
 148  */
 149 #define kIODMACommandOutputHost32   (IODMACommand::OutputHost32)
 150
 151 /*! @function OutputBig32
 152     @abstract Output big-endian Segment32 output segment function.
 153 */
 154     static bool OutputBig32(IODMACommand *target,
 155             Segment64 seg, void *segs, UInt32 ind);
 156
 157 /*! @defined kIODMACommandOutputBig32
 158     @abstract Output big-endian Segment32 output segment function.
 159  */
 160 #define kIODMACommandOutputBig32    (IODMACommand::OutputBig32)
 161
 162 /*! @function OutputLittle32
 163     @abstract Output little-endian Segment32 output segment function.
 164 */
 165     static bool OutputLittle32(IODMACommand *target,
 166             Segment64 seg, void *segs, UInt32 ind);
 167
 168 /*! @defined kIODMACommandOutputLittle32
 169     @abstract Output little-endian Segment32 output segment function.
 170 */
 171 #define kIODMACommandOutputLittle32 (IODMACommand::OutputLittle32)
 172
 173 /*! @function OutputHost64
 174     @abstract Output host natural Segment64 output segment function.
 175 */
 176     static bool OutputHost64(IODMACommand *target,
 177             Segment64 seg, void *segs, UInt32 ind);
 178
 179 /*! @defined kIODMACommandOutputHost64
 180     @abstract Output host natural Segment64 output segment function.
 181 */
 182 #define kIODMACommandOutputHost64   (IODMACommand::OutputHost64)
 183
 184 /*! @function OutputBig64
 185     @abstract Output big-endian Segment64 output segment function.
 186 */
 187     static bool OutputBig64(IODMACommand *target,
 188             Segment64 seg, void *segs, UInt32 ind);
 189
 190 /*! @defined kIODMACommandOutputBig64
 191     @abstract Output big-endian Segment64 output segment function.
 192 */
 193 #define kIODMACommandOutputBig64    (IODMACommand::OutputBig64)
 194
 195 /*! @function OutputLittle64
 196     @abstract Output little-endian Segment64 output segment function.
 197 */
 198     static bool OutputLittle64(IODMACommand *target,
 199             Segment64 seg, void *segs, UInt32 ind);
 200
 201 /*! @defined kIODMACommandOutputLittle64
 202     @abstract Output little-endian Segment64 output segment function.
 203 */
 204 #define kIODMACommandOutputLittle64 (IODMACommand::OutputLittle64)
 205
 206 /*! @function withSpecification
 207     @abstract Creates and initializes an IODMACommand in one operation.
 208     @discussion Factory function to create and initialize an IODMACommand in one operation.
 209     @param outSegFunc SegmentFunction to call to output one physical segment. A set of nine commonly required segment functions are provided.
 210     @param numAddressBits Number of bits that the hardware uses on its internal address bus. Typically 32 but may be more on modern hardware.  A 0 implies no-restriction other than that implied by the output segment function.
 211     @param maxSegmentSize Maximum allowable size for one segment.  If 0 is passed the maximum segment size is unlimited.
 212     @param mappingOptions is the type of mapping that is required to translate an IOMemoryDescriptor into the desired number of bits.  For instance if your hardware only supports 32 bits but must run on machines with > 4G of RAM some mapping will be required.  Number of bits will be specified in numAddressBits, see below.This parameter can take 3 values:- kNonCoherent - used for non-coherent hardware transfers, Mapped - Validate that all I/O bus generated addresses are within the number of addressing bits specified, Bypassed indicates that bypassed addressing is required, this is used when the hardware transferes are into coherent memory but no mapping is required.  See also prepare() for failure cases.
 213     @param maxTransferSize Maximum size of an entire transfer.  Defaults to 0 indicating no maximum.
 214     @param alignment Alignment restriction, in bytes, on I/O bus addresses.  Defaults to single byte alignment.
 215     @param mapper For mapping types kMapped & kBypassed mapper is used to define the hardware that will perform the mapping, defaults to the system mapper.
 216     @param refCon Reference Constant
 217     @result Returns a new IODMACommand if successfully created and initialized, 0 otherwise.
 218 */
 219     static IODMACommand *
 220         withSpecification(SegmentFunction  outSegFunc,
 221                           UInt8            numAddressBits,
 222                           UInt64           maxSegmentSize,
 223                           MappingOptions   mappingOptions = kMapped,
 224                           UInt64           maxTransferSize = 0,
 225                           UInt32           alignment = 1,
 226                           IOMapper        *mapper = 0,
 227                           void            *refCon = 0);
 228
 229 /*! @function weakWithSpecification
 230     @abstract Creates and initialises an IODMACommand in one operation if this version of the operating system supports it.
 231     @discussion Factory function to create and initialise an IODMACommand in one operation.  The function allows a developer to 'weak' link with IODMACommand.  This function will return kIOReturnUnsupported if the IODMACommand is unavailable.  This function is actually fairly slow so it will be better to call it once then clone the successfully create command using cloneCommand (q.v.).
 232     @param newCommand Output reference variable of the newly created IODMACommand.
 233     @param outSegFunc SegmentFunction to call to output one physical segment. A set of nine commonly required segment functions are provided.
 234     @param numAddressBits Number of bits that the hardware uses on its internal address bus. Typically 32 but may be more on modern hardware.  A 0 implies no-restriction other than that implied by the output segment function.
 235     @param maxSegmentSize Maximum allowable size for one segment. Zero is treated as an unlimited segment size.
 236     @param mapType is the type of mapping that is required to translate an IOMemoryDescriptor into the desired number of bits.  For instance if your hardware only supports 32 bits but must run on machines with > 4G of RAM some mapping will be required.  Number of bits will be specified in numAddressBits, see below.  This parameter can take 3 values:- kNonCoherent - used for non-coherent hardware transfers, Mapped - Validate that all I/O bus generated addresses are within the number of addressing bits specified, Bypassed indicates that bypassed addressing is required, this is used when the hardware transfers are into coherent memory but no mapping is required.  See also prepare() for failure cases.
 237     @param maxTransferSize Maximum size of an entire transfer.  Defaults to 0 indicating no maximum.
 238     @param alignment Alignment restriction, in bytes, on I/O bus addresses.  Defaults to single byte alignment.
 239     @param mapper For mapping types kMapped & kBypassed mapper is used to define the hardware that will perform the mapping, defaults to the system mapper.
 240     @param refCon Reference Constant
 241     @result kIOReturnSuccess if everything is OK, otherwise kIOReturnBadArgument if newCommand is NULL, kIOReturnUnsupported if the kernel doesn't export IODMACommand or IOReturnError if the new command fails to init, q.v. initWithSpecification.
 242 */
 243     // Note that the function has the attribute always_inline.
 244     // The point of this function is to make a call into the kernel
 245     // without generating an undefined symbol.  If the client could call
 246     // the code as a function then the goal of no undefined symbols
 247     // would be lost thus defeating the purpose.
 248     static inline IOReturn weakWithSpecification
 249             (IODMACommand   **newCommand,
 250              SegmentFunction outSegFunc,
 251              UInt8           numAddressBits,
 252              UInt64          maxSegmentSize,
 253              MappingOptions  mapType = kMapped,
 254              UInt64          maxTransferSize = 0,
 255              UInt32          alignment = 1,
 256              IOMapper       *mapper = 0,
 257              void           *refCon = 0) __attribute__((always_inline));
 258
 259     static IODMACommand *
 260         withSpecification(SegmentFunction        outSegFunc,
 261                           const SegmentOptions * segmentOptions,
 262                           uint32_t               mappingOptions,
 263                           IOMapper             * mapper,
 264                           void                 * refCon);
 265
 266
 267 /*! @function withRefCon
 268     @abstract Creates and initializes an unspecified IODMACommand.
 269     @discussion Factory function to create and initialize an unspecified IODMACommand. prepareWithSpecification() must be used to prepare the IODMACommand before use.
 270     @param refCon Reference Constant
 271     @result Returns a new IODMACommand if successfully created and initialized, 0 otherwise.
 272 */
 273     static IODMACommand * withRefCon(void * refCon);
 274
 275 /*!
 276     @function cloneCommand
 277     @abstract Creates a new command based on the specification of the current one.
 278     @discussion Factory function to create and initialise an IODMACommand in one operation.  The current command's specification will be duplicated in the new object, but however none of its state will be duplicated.  This means that it is safe to clone a command even if it is currently active and running, however you must be certain that the command to be duplicated does have a valid reference for the duration.
 279     @result Returns a new IODMACommand if successfully created and initialised, 0 otherwise.
 280 */
 281     virtual IODMACommand *cloneCommand(void *refCon = 0);
 282
 283 /*! @function initWithSpecification
 284     @abstract Primary initializer for the IODMACommand class.
 285     @param outSegFunc SegmentFunction to call to output one physical segment. A set of nine commonly required segment functions are provided.
 286     @param numAddressBits Number of bits that the hardware uses on its internal address bus. Typically 32 but may be more on modern hardware.  A 0 implies no-restriction other than that implied by the output segment function.
 287     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0 which means any size.
 288     @param mappingOptions is the type of mapping that is required to translate an IOMemoryDescriptor into the desired number of bits.  For instance if your hardware only supports 32 bits but must run on machines with > 4G of RAM some mapping will be required.  Number of bits will be specified in numAddressBits, see below.This parameter can take 3 values:- kNonCoherent - used for non-coherent hardware transfers, Mapped - Validate that all I/O bus generated addresses are within the number of addressing bits specified, Bypassed indicates that bypassed addressing is required, this is used when the hardware transferes are into coherent memory but no mapping is required.  See also prepare() for failure cases.
 289     @param maxTransferSize Maximum size of an entire transfer.  Defaults to 0 indicating no maximum.
 290     @param alignment Alignment restriction, in bytes, on I/O bus addresses.  Defaults to single byte alignment.
 291     @param mapper For mapping types kMapped & kBypassed mapper is used to define the hardware that will perform the mapping, defaults to the system mapper.
 292     @param refCon Reference Constant
 293     @result Can fail if the mapping type is not recognised, if one of the 3 mandatory parameters are set to 0, if a 32 bit output function is selected when more than 32 bits of address is required or, if kBypassed is requested on a machine that doesn't support bypassing.  Returns true otherwise.
 294 */
 295     virtual bool initWithSpecification( SegmentFunction  outSegFunc,
 296                                         UInt8     numAddressBits,
 297                                         UInt64    maxSegmentSize,
 298                                         MappingOptions mappingOptions = kMapped,
 299                                         UInt64    maxTransferSize = 0,
 300                                         UInt32    alignment = 1,
 301                                         IOMapper *mapper = 0,
 302                                         void     *refCon = 0);
 303
 304 /*! @function setMemoryDescriptor
 305     @abstract Sets and resets the DMACommand's current memory descriptor
 306     @discussion The DMA command will configure itself based on the information that it finds in the memory descriptor.  It looks for things like the direction of the memory descriptor and whether the current memory descriptor is already mapped into some IOMMU.  As a programmer convenience it can also prepare the DMA command immediately.  See prepare().  Note the IODMACommand is designed to used multiple times with a succession of memory descriptors, making the pooling of commands possible.  It is an error though to attempt to reset a currently prepared() DMA command.  Warning: This routine may block so never try to autoprepare an IODMACommand while in a gated context, i.e. one of the WorkLoops action call outs.
 307     @param mem A pointer to the current I/Os memory descriptor.
 308     @param autoPrepare An optional boolean variable that will call the prepare() function automatically after the memory descriptor is processed. Defaults to true.
 309     @result Returns kIOReturnSuccess, kIOReturnBusy if currently prepared, kIOReturnNoSpace if the length(mem) >= Maximum Transfer Size or the error codes returned by prepare() (qv).
 310 */
 311     virtual IOReturn setMemoryDescriptor(const IOMemoryDescriptor *mem,
 312                                          bool autoPrepare = true);
 313
 314 /*! @function clearMemoryDescriptor
 315     @abstract Clears the DMACommand's current memory descriptor
 316     @discussion completes and invalidates the cache if the DMA command is currently active, copies all data from bounce buffers if necessary and releases all resources acquired during setMemoryDescriptor.
 317     @param autoComplete An optional boolean variable that will call the complete() function automatically before the memory descriptor is processed. Defaults to true.
 318 */
 319     virtual IOReturn clearMemoryDescriptor(bool autoComplete = true);
 320
 321 /*! @function getMemoryDescriptor
 322     @abstract Get the current memory descriptor
 323 */
 324     virtual const IOMemoryDescriptor *getMemoryDescriptor() const;
 325
 326 /*! @function getIOMemoryDescriptor
 327     @abstract Get the memory descriptor to be used for DMA
 328 */
 329     IOMemoryDescriptor * getIOMemoryDescriptor() const;
 330
 331 /*! @function prepare
 332     @abstract Prepare the memory for an I/O transfer.
 333     @discussion Allocate the mapping resources neccessary for this transfer, specifying a sub range of the IOMemoryDescriptor that will be the target of the I/O.  The complete() method frees these resources.  Data may be copied to buffers for kIODirectionOut memory descriptors, depending on hardware mapping resource availabilty or alignment restrictions.  It should be noted that the this function may block and should only be called on the clients context, i.e never call this routine while gated; also the call itself is not thread safe though this should be an issue as each IODMACommand is independant.
 334     @param offset defines the starting offset in the memory descriptor the DMA command will operate on. genIOVMSegments will produce its results based on the offset and length passed to the prepare method.
 335     @param length defines the ending position in the memory descriptor the DMA command will operate on. genIOVMSegments will produce its results based on the offset and length passed to the prepare method.
 336     @param flushCache Flush the caches for the memory descriptor and make certain that the memory cycles are complete.  Defaults to true for kNonCoherent and is ignored by the other types.
 337     @param synchronize Copy any buffered data back from the target IOMemoryDescriptor.  Defaults to true, if synchronize() is being used to explicitly copy data, passing false may avoid an unneeded copy.
 338     @result An IOReturn code. */
 339
 340     virtual IOReturn prepare(UInt64 offset = 0, UInt64 length = 0, bool flushCache = true, bool synchronize = true);
 341
 342 /*! @function complete
 343     @abstract Complete processing of DMA mappings after an I/O transfer is finished.
 344     @discussion This method should not be called unless a prepare was previously issued; the prepare() and complete() must occur in pairs, before and after an I/O transfer
 345     @param invalidCache Invalidate the caches for the memory descriptor.  Defaults to true for kNonCoherent and is ignored by the other types.
 346     @param synchronize Copy any buffered data back to the target IOMemoryDescriptor.  Defaults to true, if synchronize() is being used to explicitly copy data, passing false may avoid an unneeded copy.
 347     @result kIOReturnNotReady if not prepared, kIOReturnSuccess otherwise. */
 348
 349     virtual IOReturn complete(bool invalidateCache = true, bool synchronize = true);
 350
 351 /*! @function synchronize
 352     @abstract Bring IOMemoryDescriptor and IODMACommand buffers into sync.
 353     @discussion This method should not be called unless a prepare was previously issued. If needed a caller may synchronize any IODMACommand buffers with the original IOMemoryDescriptor buffers.
 354     @param options Specifies the direction of the copy:
 355         kIODirectionOut copy IOMemoryDesciptor memory to any IODMACommand buffers. By default this action takes place automatically at prepare().
 356         kIODirectionIn copy any IODMACommand buffers back to the IOMemoryDescriptor. By default this action takes place automatically at complete().
 357         kForceDoubleBuffer copy the entire prepared range to a new page aligned buffer.
 358     @result kIOReturnNotReady if not prepared, kIOReturnBadArgument if invalid options are passed, kIOReturnSuccess otherwise. */
 359
 360     virtual IOReturn synchronize(IOOptionBits options);
 361
 362 /*! @function genIOVMSegments
 363     @abstract Generates a physical scatter/gather for the current DMA command
 364     @discussion Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor.  The constraints that are set during initialisation will be respected. This function maintains the state across multiple calls for efficiency.  However the state is discarded if the new offset is not the expected one.
 365     @param offset input/output parameter, defines the starting and ending offset in the memory descriptor, relative to any offset passed to the prepare() method.
 366     @param segments Void pointer to base of output physical scatter/gather list.  Always passed directly onto the SegmentFunction.
 367     @param numSegments Input/output parameter Number of segments that can fit in the segment array and returns number of segments generated.
 368     @result kIOReturnSuccess on success, kIOReturnOverrun if the memory descriptor is exhausted, kIOReturnMessageTooLarge if the output segment function's address bits has insufficient resolution for a segment, kIOReturnNotReady if the DMA command has not be prepared, kIOReturnBadArgument if the DMA command doesn't have a memory descriptor yet or some of the parameters are NULL and kIOReturnNotReady if the DMA command is not prepared.
 369 */
 370     virtual IOReturn genIOVMSegments(UInt64 *offset,
 371                                      void   *segments,
 372                                      UInt32 *numSegments);
 373
 374 private:
 375     virtual UInt64 transfer( IOOptionBits transferOp, UInt64 offset, void * buffer, UInt64 length );
 376
 377 public:
 378
 379 /*! @function writeBytes
 380     @abstract Copy data to the IODMACommand's buffer from the specified buffer.
 381     @discussion This method copies data to the IODMACommand's memory at the given offset, from the caller's buffer. The IODMACommand must be prepared, and the offset is relative to the prepared offset.
 382     @param offset A byte offset into the IODMACommand's memory, relative to the prepared offset.
 383     @param bytes The caller supplied buffer to copy the data from.
 384     @param length The length of the data to copy.
 385     @result The number of bytes copied, zero will be returned if the specified offset is beyond the prepared length of the IODMACommand. */
 386
 387     UInt64 writeBytes(UInt64 offset, const void *bytes, UInt64 length);
 388
 389 /*! @function readBytes
 390     @abstract Copy data from the IODMACommand's buffer to the specified buffer.
 391     @discussion This method copies data from the IODMACommand's memory at the given offset, to the caller's buffer. The IODMACommand must be prepared, and the offset is relative to the prepared offset.
 392     @param offset A byte offset into the IODMACommand's memory, relative to the prepared offset.
 393     @param bytes The caller supplied buffer to copy the data to.
 394     @param length The length of the data to copy.
 395     @result The number of bytes copied, zero will be returned if the specified offset is beyond the prepared length of the IODMACommand. */
 396
 397     UInt64 readBytes(UInt64 offset, void *bytes, UInt64 length);
 398
 399 /*! @function gen32IOVMSegments
 400     @abstract Helper function for a type checked call to genIOVMSegments(qv), for use with an IODMACommand set up with the output function kIODMACommandOutputHost32, kIODMACommandOutputBig32, or kIODMACommandOutputLittle32. If the output function of the IODMACommand is not a 32 bit function, results will be incorrect.
 401 */
 402     inline IOReturn gen32IOVMSegments(UInt64   *offset,
 403                                       Segment32 *segments,
 404                                       UInt32     *numSegments)
 405     { return genIOVMSegments(offset, segments, numSegments); };
 406
 407 /*! @function gen64IOVMSegments
 408     @abstract Helper function for a type checked call to genIOVMSegments(qv), for use with an IODMACommand set up with the output function kIODMACommandOutputHost64, kIODMACommandOutputBig64, or kIODMACommandOutputLittle64. If the output function of the IODMACommand is not a 64 bit function, results will be incorrect.
 409 */
 410     inline IOReturn gen64IOVMSegments(UInt64    *offset,
 411                                       Segment64 *segments,
 412                                       UInt32    *numSegments)
 413     { return genIOVMSegments(offset, segments, numSegments); };
 414
 415     IOReturn
 416     genIOVMSegments(SegmentFunction segmentFunction,
 417                     UInt64 *offsetP,
 418                     void   *segmentsP,
 419                     UInt32 *numSegmentsP);
 420
 421     virtual void free() APPLE_KEXT_OVERRIDE;
 422
 423 private:
 424     IOReturn setSpecification(SegmentFunction        outSegFunc,
 425                               const SegmentOptions * segmentOptions,
 426                               uint32_t               mappingOptions,
 427                               IOMapper             * mapper);
 428
 429     typedef IOReturn (*InternalSegmentFunction)(
 430                                     void         *reference,
 431                                     IODMACommand *target,
 432                                     Segment64     segment,
 433                                     void         *segments,
 434                                     UInt32        segmentIndex);
 435
 436     IOReturn genIOVMSegments(uint32_t op,
 437                                   InternalSegmentFunction outSegFunc,
 438                                   void   *reference,
 439                                   UInt64 *offsetP,
 440                                   void   *segmentsP,
 441                                   UInt32 *numSegmentsP);
 442
 443     static IOReturn clientOutputSegment(
 444             void *reference, IODMACommand *target,
 445             Segment64 segment, void *vSegList, UInt32 outSegIndex);
 446
 447     static IOReturn segmentOp(
 448                         void         *reference,
 449                         IODMACommand *target,
 450                         Segment64     segment,
 451                         void         *segments,
 452                         UInt32        segmentIndex);
 453     IOReturn walkAll(UInt8 op);
 454
 455 public:
 456
 457 /*! @function prepareWithSpecification
 458     @abstract Prepare the memory for an I/O transfer with a new specification.
 459     @discussion Allocate the mapping resources neccessary for this transfer, specifying a sub range of the IOMemoryDescriptor that will be the target of the I/O.  The complete() method frees these resources.  Data may be copied to buffers for kIODirectionOut memory descriptors, depending on hardware mapping resource availabilty or alignment restrictions.  It should be noted that the this function may block and should only be called on the clients context, i.e never call this routine while gated; also the call itself is not thread safe though this should be an issue as each IODMACommand is independant.
 460     @param outSegFunc SegmentFunction to call to output one physical segment. A set of nine commonly required segment functions are provided.
 461     @param numAddressBits Number of bits that the hardware uses on its internal address bus. Typically 32 but may be more on modern hardware.  A 0 implies no-restriction other than that implied by the output segment function.
 462     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0 which means any size.
 463     @param mappingOptions is the type of mapping that is required to translate an IOMemoryDescriptor into the desired number of bits.  For instance if your hardware only supports 32 bits but must run on machines with > 4G of RAM some mapping will be required.  Number of bits will be specified in numAddressBits, see below.This parameter can take 3 values:- kNonCoherent - used for non-coherent hardware transfers, Mapped - Validate that all I/O bus generated addresses are within the number of addressing bits specified, Bypassed indicates that bypassed addressing is required, this is used when the hardware transferes are into coherent memory but no mapping is required.  See also prepare() for failure cases.
 464     @param maxTransferSize Maximum size of an entire transfer.  Defaults to 0 indicating no maximum.
 465     @param alignment Alignment restriction, in bytes, on I/O bus addresses.  Defaults to single byte alignment.
 466     @param mapper For mapping types kMapped & kBypassed mapper is used to define the hardware that will perform the mapping, defaults to the system mapper.
 467     @param offset defines the starting offset in the memory descriptor the DMA command will operate on. genIOVMSegments will produce its results based on the offset and length passed to the prepare method.
 468     @param length defines the ending position in the memory descriptor the DMA command will operate on. genIOVMSegments will produce its results based on the offset and length passed to the prepare method.
 469     @param flushCache Flush the caches for the memory descriptor and make certain that the memory cycles are complete.  Defaults to true for kNonCoherent and is ignored by the other types.
 470     @param synchronize Copy any buffered data back from the target IOMemoryDescriptor.  Defaults to true, if synchronize() is being used to explicitly copy data, passing false may avoid an unneeded copy.
 471     @result An IOReturn code. Can fail if the mapping type is not recognised, if one of the 3 mandatory parameters are set to 0, if a 32 bit output function is selected when more than 32 bits of address is required or, if kBypassed is requested on a machine that doesn't support bypassing.
 472 */
 473
 474     virtual IOReturn prepareWithSpecification(SegmentFunction   outSegFunc,
 475                                               UInt8             numAddressBits,
 476                                               UInt64            maxSegmentSize,
 477                                               MappingOptions    mappingOptions = kMapped,
 478                                               UInt64            maxTransferSize = 0,
 479                                               UInt32            alignment = 1,
 480                                               IOMapper          *mapper = 0,
 481                                               UInt64            offset = 0,
 482                                               UInt64            length = 0,
 483                                               bool              flushCache = true,
 484                                               bool              synchronize = true);
 485
 486     static IOReturn transferSegment(void         *reference,
 487                                     IODMACommand *target,
 488                                     Segment64     segment,
 489                                     void         *segments,
 490                                     UInt32        segmentIndex);
 491
 492 /*! @function getPreparedOffsetAndLength
 493     @abstract Returns the offset and length into the target IOMemoryDescriptor of a prepared IODDMACommand.
 494     @discussion If successfully prepared, returns the offset and length into the IOMemoryDescriptor. Will fail for an unprepared IODMACommand.
 495     @param offset returns the starting offset in the memory descriptor the DMA command was prepared with. Pass NULL for don't care.
 496     @param length returns the length in the memory descriptor the DMA command was prepared with. Pass NULL for don't care.
 497     @result An IOReturn code. kIOReturnNotReady if the IODMACommand is not prepared. */
 498
 499     virtual IOReturn getPreparedOffsetAndLength(UInt64 * offset, UInt64 * length);
 500
 501     UInt8    getNumAddressBits(void);
 502     UInt32   getAlignment(void);
 503     uint32_t getAlignmentLength(void);
 504     uint32_t getAlignmentInternalSegments(void);
 505
 506
 507 /*! @function initWithRefCon
 508     @abstract Secondary initializer for the IODMACommand class.
 509     @param refCon Reference Constant
 510     @result Can fail if super init fails.  Returns true otherwise.
 511 */
 512
 513     virtual
 514     bool initWithRefCon(void * refCon = 0);
 515
 516     virtual
 517     bool initWithSpecification(SegmentFunction        outSegFunc,
 518                                const SegmentOptions * segmentOptions,
 519                                uint32_t               mappingOptions,
 520                                IOMapper             * mapper,
 521                                void                 * refCon);
 522
 523     virtual
 524     IOReturn prepareWithSpecification(SegmentFunction        outSegFunc,
 525                                       const SegmentOptions * segmentOptions,
 526                                       uint32_t               mappingOptions,
 527                                       IOMapper             * mapper,
 528                                       uint64_t               offset,
 529                                       uint64_t               length,
 530                                       bool                   flushCache = true,
 531                                       bool                   synchronize = true);
 532
 533     virtual
 534     IOBufferMemoryDescriptor * createCopyBuffer(IODirection direction, UInt64 length);
 535
 536 private:
 537     OSMetaClassDeclareReservedUsed(IODMACommand,  0);
 538     OSMetaClassDeclareReservedUsed(IODMACommand,  1);
 539     OSMetaClassDeclareReservedUsed(IODMACommand,  2);
 540     OSMetaClassDeclareReservedUsed(IODMACommand,  3);
 541     OSMetaClassDeclareReservedUsed(IODMACommand,  4);
 542     OSMetaClassDeclareReservedUsed(IODMACommand,  5);
 543     OSMetaClassDeclareReservedUsed(IODMACommand,  6);
 544     OSMetaClassDeclareReservedUnused(IODMACommand,  7);
 545     OSMetaClassDeclareReservedUnused(IODMACommand,  8);
 546     OSMetaClassDeclareReservedUnused(IODMACommand,  9);
 547     OSMetaClassDeclareReservedUnused(IODMACommand, 10);
 548     OSMetaClassDeclareReservedUnused(IODMACommand, 11);
 549     OSMetaClassDeclareReservedUnused(IODMACommand, 12);
 550     OSMetaClassDeclareReservedUnused(IODMACommand, 13);
 551     OSMetaClassDeclareReservedUnused(IODMACommand, 14);
 552     OSMetaClassDeclareReservedUnused(IODMACommand, 15);
 553
 554 public:
 555 /*! @var fRefCon Reference Constant, client defined publicly avialable */
 556     void *fRefCon;
 557
 558 protected:
 559
 560 /*! @var fMaxSegmentSize Maximum size of one segment in a scatter/gather list */
 561     UInt64  fMaxSegmentSize;
 562
 563 /*! @var fMaxTransferSize
 564     Maximum size of a transfer that this memory cursor is allowed to generate */
 565     UInt64  fMaxTransferSize;
 566
 567     UInt32  fAlignMaskLength;
 568     UInt32  fAlignMaskInternalSegments;
 569
 570 /*! @var fMapper
 571     Client defined mapper. */
 572     IOMapper *fMapper;
 573
 574 /*! @var fMemory
 575     memory descriptor for current I/O. */
 576     const IOMemoryDescriptor *fMemory;
 577
 578 /*! @var fOutSeg The action method called when an event has been delivered */
 579     SegmentFunction fOutSeg;
 580
 581 /*! @var fAlignMask
 582     Alignment restriction mask. */
 583     UInt32  fAlignMask;
 584
 585 /*! @var fNumAddressBits
 586     Number of bits that the hardware can address */
 587     UInt32 fNumAddressBits;
 588
 589 /*! @var fNumSegments
 590     Number of contiguous segments required for the current memory descriptor and desired mapping */
 591     UInt32  fNumSegments;
 592
 593 /*! @var fMappingOptions
 594     What type of I/O virtual address mapping is required for this command */
 595     uint32_t  fMappingOptions;
 596
 597 /*! @var fActive
 598     fActive indicates that this DMA command is currently prepared and ready to go */
 599     UInt32 fActive;
 600
 601 /*! @var reserved
 602     Reserved for future use.  (Internal use only)  */
 603     struct IODMACommandInternal * reserved;
 604 };
 605
 606 IOReturn IODMACommand::
 607 weakWithSpecification(IODMACommand **newCommand,
 608                       SegmentFunction  outSegFunc,
 609                       UInt8     numAddressBits,
 610                       UInt64    maxSegmentSize,
 611                       MappingOptions mapType,
 612                       UInt64    maxTransferSize,
 613                       UInt32    alignment,
 614                       IOMapper *mapper,
 615                       void     *refCon)
 616 {
 617     if (!newCommand)
 618         return kIOReturnBadArgument;
 619
 620     IODMACommand *self = (IODMACommand *)
 621         OSMetaClass::allocClassWithName("IODMACommand");
 622     if (!self)
 623         return kIOReturnUnsupported;
 624
 625     IOReturn ret;
 626     bool inited = self->
 627         initWithSpecification(outSegFunc,
 628                               numAddressBits, maxSegmentSize, mapType,
 629                               maxTransferSize, alignment, mapper, refCon);
 630     if (inited)
 631         ret =  kIOReturnSuccess;
 632     else {
 633         self->release();
 634         self = 0;
 635         ret = kIOReturnError;
 636     }
 637
 638     *newCommand = self;
 639     return ret;
 640 };
 641 #endif /* !_IODMACOMMAND_H */
 642