The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/iokit/IOKit/IODMACommand.h

Version: -  FREEBSD  -  FREEBSD-13-STABLE  -  FREEBSD-13-0  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  l41  -  OPENBSD  -  linux-2.6  -  MK84  -  PLAN9  -  xnu-8792 
SearchContext: -  none  -  3  -  10 

    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 
   35 /**************************** class IODMACommand ***************************/
   36 
   37 /*!
   38     @class IODMACommand
   39     @abstract A mechanism to convert memory references to I/O bus addresses.
   40     @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.
   41 <br><br>
   42     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.
   43 <br><br>
   44     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.
   45 <br><br>
   46     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!
   47 */
   48 
   49 class IODMACommand : public IOCommand
   50 {
   51     OSDeclareDefaultStructors(IODMACommand);
   52 
   53 friend class IODMAEventSource;
   54 
   55 public:
   56 
   57 /*!
   58     @typedef Segment32
   59     @discussion A 32 bit I/O bus address/length pair
   60 */
   61     struct Segment32 {
   62         UInt32 fIOVMAddr, fLength;
   63     };
   64 
   65 /*!
   66     @typedef Segment64
   67     @discussion A 64 bit I/O bus address/length pair
   68 */
   69     struct Segment64 {
   70         UInt64 fIOVMAddr, fLength;
   71     };
   72 
   73 /*! @enum MappingOptions
   74     @abstract Mapping types to indicate the desired mapper type for translating memory descriptors into I/O DMA Bus addresses.
   75     @constant kNonCoherent      Used by drivers for non-coherent transfers, implies unmapped memmory
   76     @constant kMapped           Allow a driver to define addressing size
   77     @constant kBypassed         Allow drivers to bypass any mapper
   78     @constant kMaxMappingOptions        Internal use only
   79 */
   80     enum MappingOptions {
   81         kMapped       = 0x00000000,
   82         kBypassed     = 0x00000001,
   83         kNonCoherent  = 0x00000002,
   84         kTypeMask     = 0x0000000f,
   85 
   86         kNoCacheStore = 0x00000010,     // Memory in descriptor 
   87         kOnChip       = 0x00000020,     // Indicates DMA is on South Bridge
   88         kIterateOnly  = 0x00000040      // DMACommand will be used as a cursor only
   89     };
   90 
   91 /*! @enum SynchronizeOptions
   92     @abstract Options for the synchronize method.
   93     @constant kForceDoubleBuffer Copy the entire prepared range to a new page aligned buffer.
   94 */
   95     enum SynchronizeOptions {
   96         kForceDoubleBuffer = 0x01000000
   97     };
   98 
   99 /*!
  100     @typedef SegmentFunction
  101     @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.
  102     @param segment The 64Bit I/O bus address and length.
  103     @param segments Base of the output vector of DMA address length pairs.
  104     @param segmentIndex Index to output 'segment' in the 'segments' array.
  105     @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.
  106 */
  107     typedef bool (*SegmentFunction)(IODMACommand *target,
  108                                     Segment64 segment,
  109                                     void     *segments,
  110                                     UInt32    segmentIndex);
  111 
  112     // -------------- Preimplemented output functions ----------------
  113 
  114 /*! @function OutputHost32
  115     @abstract Output host natural Segment32 output segment function.
  116 */
  117     static bool OutputHost32(IODMACommand *target,
  118             Segment64 seg, void *segs, UInt32 ind);
  119 
  120 /*! @defined kIODMACommandOutputHost32
  121     @abstract Output host natural Segment32 output segment function.
  122  */
  123 #define kIODMACommandOutputHost32   (IODMACommand::OutputHost32)
  124 
  125 /*! @function OutputBig32
  126     @abstract Output big-endian Segment32 output segment function.
  127 */
  128     static bool OutputBig32(IODMACommand *target,
  129             Segment64 seg, void *segs, UInt32 ind);
  130 
  131 /*! @defined kIODMACommandOutputBig32
  132     @abstract Output big-endian Segment32 output segment function.
  133  */
  134 #define kIODMACommandOutputBig32    (IODMACommand::OutputBig32)
  135 
  136 /*! @function OutputLittle32
  137     @abstract Output little-endian Segment32 output segment function.
  138 */
  139     static bool OutputLittle32(IODMACommand *target,
  140             Segment64 seg, void *segs, UInt32 ind);
  141 
  142 /*! @defined kIODMACommandOutputLittle32
  143     @abstract Output little-endian Segment32 output segment function.
  144 */
  145 #define kIODMACommandOutputLittle32 (IODMACommand::OutputLittle32)
  146 
  147 /*! @function OutputHost64
  148     @abstract Output host natural Segment64 output segment function.
  149 */
  150     static bool OutputHost64(IODMACommand *target,
  151             Segment64 seg, void *segs, UInt32 ind);
  152 
  153 /*! @defined kIODMACommandOutputHost64
  154     @abstract Output host natural Segment64 output segment function.
  155 */
  156 #define kIODMACommandOutputHost64   (IODMACommand::OutputHost64)
  157 
  158 /*! @function OutputBig64
  159     @abstract Output big-endian Segment64 output segment function.
  160 */
  161     static bool OutputBig64(IODMACommand *target,
  162             Segment64 seg, void *segs, UInt32 ind);
  163 
  164 /*! @defined kIODMACommandOutputLittle64
  165     @abstract Output little-endian Segment64 output segment function.
  166 */
  167 #define kIODMACommandOutputBig64    (IODMACommand::OutputBig64)
  168 
  169 /*! @function OutputLittle64
  170     @abstract Output little-endian Segment64 output segment function.
  171 */
  172     static bool OutputLittle64(IODMACommand *target,
  173             Segment64 seg, void *segs, UInt32 ind);
  174 
  175 /*! @defined kIODMACommandOutputBig64
  176     @abstract Output big-endian Segment64 output segment function.
  177 */
  178 #define kIODMACommandOutputLittle64 (IODMACommand::OutputLittle64)
  179 
  180 /*! @function withSpecification
  181     @abstract Creates and initializes an IODMACommand in one operation.
  182     @discussion Factory function to create and initialize an IODMACommand in one operation.
  183     @param outSegFunc SegmentFunction to call to output one physical segment. A set of nine commonly required segment functions are provided.
  184     @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.
  185     @param maxSegmentSize Maximum allowable size for one segment.  If 0 is passed the maximum segment size is unlimited.
  186     @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.
  187     @param maxTransferSize Maximum size of an entire transfer.  Defaults to 0 indicating no maximum.
  188     @param alignment Alignment restriction, in bytes, on I/O bus addresses.  Defaults to single byte alignment.
  189     @param mapper For mapping types kMapped & kBypassed mapper is used to define the hardware that will perform the mapping, defaults to the system mapper.
  190     @result Returns a new memory cursor if successfully created and initialized, 0 otherwise.
  191 */
  192     static IODMACommand *
  193         withSpecification(SegmentFunction  outSegFunc,
  194                           UInt8            numAddressBits,
  195                           UInt64           maxSegmentSize,
  196                           MappingOptions   mappingOptions = kMapped,
  197                           UInt64           maxTransferSize = 0,
  198                           UInt32           alignment = 1,
  199                           IOMapper        *mapper = 0,
  200                           void            *refCon = 0);
  201 
  202 /*! @function weakWithSpecification
  203     @abstract Creates and initialises an IODMACommand in one operation if this version of the operating system supports it.
  204     @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.).
  205     @param newCommand Output reference variable of the newly created IODMACommand.
  206     @param outSegFunc SegmentFunction to call to output one physical segment. A set of nine commonly required segment functions are provided.
  207     @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.
  208     @param maxSegmentSize Maximum allowable size for one segment. Zero is treated as an unlimited segment size.
  209     @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.
  210     @param maxTransferSize Maximum size of an entire transfer.  Defaults to 0 indicating no maximum.
  211     @param alignment Alignment restriction, in bytes, on I/O bus addresses.  Defaults to single byte alignment.
  212     @param mapper For mapping types kMapped & kBypassed mapper is used to define the hardware that will perform the mapping, defaults to the system mapper.
  213     @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.
  214 */
  215     // Note that the function has the attribute always_inline.
  216     // The point of this function is to make a call into the kernel
  217     // without generating an undefined symbol.  If the client could call
  218     // the code as a function then the goal of no undefined symbols
  219     // would be lost thus defeating the purpose.
  220     static inline IOReturn weakWithSpecification
  221             (IODMACommand   **newCommand,
  222              SegmentFunction outSegFunc,
  223              UInt8           numAddressBits,
  224              UInt64          maxSegmentSize,
  225              MappingOptions  mapType = kMapped,
  226              UInt64          maxTransferSize = 0,
  227              UInt32          alignment = 1,
  228              IOMapper       *mapper = 0,
  229              void           *refCon = 0) __attribute__((always_inline));
  230 
  231 /*!
  232     @function cloneCommand
  233     @abstract Creates a new command based on the specification of the current one.
  234     @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.
  235     @result Returns a new memory cursor if successfully created and initialised, 0 otherwise.
  236 */
  237     virtual IODMACommand *cloneCommand(void *refCon = 0);
  238 
  239 /*! @function initWithSpecification
  240     @abstract Primary initializer for the IODMACommand class. 
  241     @param outSegFunc SegmentFunction to call to output one physical segment. A set of nine commonly required segment functions are provided.
  242     @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.
  243     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0 which means any size.
  244     @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.
  245     @param maxTransferSize Maximum size of an entire transfer.  Defaults to 0 indicating no maximum.
  246     @param alignment Alignment restriction, in bytes, on I/O bus addresses.  Defaults to single byte alignment.
  247     @param mapper For mapping types kMapped & kBypassed mapper is used to define the hardware that will perform the mapping, defaults to the system mapper.
  248     @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.
  249 */
  250     virtual bool initWithSpecification( SegmentFunction  outSegFunc,
  251                                         UInt8     numAddressBits,
  252                                         UInt64    maxSegmentSize,
  253                                         MappingOptions mappingOptions = kMapped,
  254                                         UInt64    maxTransferSize = 0,
  255                                         UInt32    alignment = 1,
  256                                         IOMapper *mapper = 0,
  257                                         void     *refCon = 0);
  258 
  259 /*! @function setMemoryDescriptor
  260     @abstract Sets and resets the DMACommand's current memory descriptor
  261     @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 memory descriptor 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.
  262     @param mem A pointer to the current I/Os memory descriptor.
  263     @param autoPrepare An optional boolean variable that will call the prepare() function automatically after the memory descriptor is processed. Defaults to true.
  264     @result Returns kIOReturnSuccess, kIOReturnBusy if currently prepared, kIOReturnNoSpace if the length(mem) >= Maximum Transfer Size or the error codes returned by prepare() (qv).
  265 */
  266     virtual IOReturn setMemoryDescriptor(const IOMemoryDescriptor *mem,
  267                                          bool autoPrepare = true);
  268 
  269 /*! @function clearMemoryDescriptor
  270     @abstract Clears the DMACommand's current memory descriptor
  271     @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.
  272     @param autoComplete An optional boolean variable that will call the complete() function automatically before the memory descriptor is processed. Defaults to true.
  273 */
  274     virtual IOReturn clearMemoryDescriptor(bool autoComplete = true);
  275 
  276 /*! @function getMemoryDescriptor
  277     @abstract Get the current memory descriptor
  278 */
  279     virtual const IOMemoryDescriptor *getMemoryDescriptor() const;
  280 
  281 /*! @function prepare
  282     @abstract Prepare the memory for an I/O transfer.
  283     @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.
  284     @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.
  285     @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.
  286     @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.
  287     @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.
  288     @result An IOReturn code. */
  289 
  290     virtual IOReturn prepare(UInt64 offset = 0, UInt64 length = 0, bool flushCache = true, bool synchronize = true);
  291 
  292 /*! @function complete
  293     @abstract Complete processing of DMA mappings after an I/O transfer is finished.
  294     @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
  295     @param invalidCache Invalidate the caches for the memory descriptor.  Defaults to true for kNonCoherent and is ignored by the other types.
  296     @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.
  297     @result kIOReturnNotReady if not prepared, kIOReturnSuccess otherwise. */
  298 
  299     virtual IOReturn complete(bool invalidateCache = true, bool synchronize = true);
  300 
  301 /*! @function synchronize
  302     @abstract Bring IOMemoryDescriptor and IODMACommand buffers into sync.
  303     @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.
  304     @param options Specifies the direction of the copy:
  305         kIODirectionOut copy IOMemoryDesciptor memory to any IODMACommand buffers. By default this action takes place automatically at prepare().
  306         kIODirectionIn copy any IODMACommand buffers back to the IOMemoryDescriptor. By default this action takes place automatically at complete().
  307         kForceDoubleBuffer copy the entire prepared range to a new page aligned buffer.
  308     @result kIOReturnNotReady if not prepared, kIOReturnBadArgument if invalid options are passed, kIOReturnSuccess otherwise. */
  309 
  310     virtual IOReturn synchronize(IOOptionBits options);
  311 
  312 /*! @function genIOVMSegments
  313     @abstract Generates a physical scatter/gather for the current DMA command
  314     @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.
  315     @param offset input/output parameter, defines the starting and ending offset in the memory descriptor, relative to any offset passed to the prepare() method.
  316     @param segments Void pointer to base of output physical scatter/gather list.  Always passed directly onto the SegmentFunction.
  317     @param numSegments Input/output parameter Number of segments that can fit in the segment array and returns number of segments generated.
  318     @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.
  319 */
  320     virtual IOReturn genIOVMSegments(UInt64 *offset,
  321                                      void   *segments,
  322                                      UInt32 *numSegments);
  323 
  324 private:
  325     virtual UInt64 transfer( IOOptionBits transferOp, UInt64 offset, void * buffer, UInt64 length );
  326 
  327 public:
  328 
  329 /*! @function writeBytes
  330     @abstract Copy data to the IODMACommand's buffer from the specified buffer.
  331     @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.
  332     @param offset A byte offset into the IODMACommand's memory, relative to the prepared offset.
  333     @param bytes The caller supplied buffer to copy the data from.
  334     @param length The length of the data to copy.
  335     @result The number of bytes copied, zero will be returned if the specified offset is beyond the prepared length of the IODMACommand. */
  336 
  337     UInt64 writeBytes(UInt64 offset, const void *bytes, UInt64 length);
  338 
  339 /*! @function readBytes
  340     @abstract Copy data from the IODMACommand's buffer to the specified buffer.
  341     @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.
  342     @param offset A byte offset into the IODMACommand's memory, relative to the prepared offset.
  343     @param bytes The caller supplied buffer to copy the data to.
  344     @param length The length of the data to copy.
  345     @result The number of bytes copied, zero will be returned if the specified offset is beyond the prepared length of the IODMACommand. */
  346 
  347     UInt64 readBytes(UInt64 offset, void *bytes, UInt64 length);
  348 
  349 /*! @function gen32IOVMSegments
  350     @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.
  351 */
  352     inline IOReturn gen32IOVMSegments(UInt64   *offset,
  353                                       Segment32 *segments,
  354                                       UInt32     *numSegments)
  355     { return genIOVMSegments(offset, segments, numSegments); };
  356 
  357 /*! @function gen64IOVMSegments
  358     @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.
  359 */
  360     inline IOReturn gen64IOVMSegments(UInt64    *offset,
  361                                       Segment64 *segments,
  362                                       UInt32    *numSegments)
  363     { return genIOVMSegments(offset, segments, numSegments); };
  364 
  365     virtual void free();
  366 
  367 private:
  368     typedef IOReturn (*InternalSegmentFunction)(
  369                                     void         *reference,
  370                                     IODMACommand *target,
  371                                     Segment64     segment,
  372                                     void         *segments,
  373                                     UInt32        segmentIndex);
  374 
  375     IOReturn genIOVMSegments(InternalSegmentFunction outSegFunc,
  376                                   void   *reference,
  377                                   UInt64 *offsetP,
  378                                   void   *segmentsP,
  379                                   UInt32 *numSegmentsP);
  380 
  381     static IOReturn clientOutputSegment(
  382             void *reference, IODMACommand *target,
  383             Segment64 segment, void *vSegList, UInt32 outSegIndex);
  384 
  385     static IOReturn segmentOp(
  386                         void         *reference,
  387                         IODMACommand *target,
  388                         Segment64     segment,
  389                         void         *segments,
  390                         UInt32        segmentIndex);
  391     IOReturn IODMACommand::walkAll(UInt8 op);
  392 
  393 public:
  394 
  395 /*! @function prepareWithSpecification
  396     @abstract Prepare the memory for an I/O transfer with a new specification.
  397     @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.
  398     @param outSegFunc SegmentFunction to call to output one physical segment. A set of nine commonly required segment functions are provided.
  399     @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.
  400     @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0 which means any size.
  401     @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.
  402     @param maxTransferSize Maximum size of an entire transfer.  Defaults to 0 indicating no maximum.
  403     @param alignment Alignment restriction, in bytes, on I/O bus addresses.  Defaults to single byte alignment.
  404     @param mapper For mapping types kMapped & kBypassed mapper is used to define the hardware that will perform the mapping, defaults to the system mapper.
  405     @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.
  406     @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.
  407     @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.
  408     @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.
  409     @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.
  410 */
  411 
  412     virtual IOReturn prepareWithSpecification(SegmentFunction   outSegFunc,
  413                                               UInt8             numAddressBits,
  414                                               UInt64            maxSegmentSize,
  415                                               MappingOptions    mappingOptions = kMapped,
  416                                               UInt64            maxTransferSize = 0,
  417                                               UInt32            alignment = 1,
  418                                               IOMapper          *mapper = 0,
  419                                               UInt64            offset = 0,
  420                                               UInt64            length = 0,
  421                                               bool              flushCache = true,
  422                                               bool              synchronize = true);
  423 
  424     static IOReturn transferSegment(
  425                         void         *reference,
  426                         IODMACommand *target,
  427                         Segment64     segment,
  428                         void         *segments,
  429                         UInt32        segmentIndex);
  430 
  431 private:
  432     OSMetaClassDeclareReservedUsed(IODMACommand,  0);
  433     OSMetaClassDeclareReservedUsed(IODMACommand,  1);
  434     OSMetaClassDeclareReservedUnused(IODMACommand,  2);
  435     OSMetaClassDeclareReservedUnused(IODMACommand,  3);
  436     OSMetaClassDeclareReservedUnused(IODMACommand,  4);
  437     OSMetaClassDeclareReservedUnused(IODMACommand,  5);
  438     OSMetaClassDeclareReservedUnused(IODMACommand,  6);
  439     OSMetaClassDeclareReservedUnused(IODMACommand,  7);
  440     OSMetaClassDeclareReservedUnused(IODMACommand,  8);
  441     OSMetaClassDeclareReservedUnused(IODMACommand,  9);
  442     OSMetaClassDeclareReservedUnused(IODMACommand, 10);
  443     OSMetaClassDeclareReservedUnused(IODMACommand, 11);
  444     OSMetaClassDeclareReservedUnused(IODMACommand, 12);
  445     OSMetaClassDeclareReservedUnused(IODMACommand, 13);
  446     OSMetaClassDeclareReservedUnused(IODMACommand, 14);
  447     OSMetaClassDeclareReservedUnused(IODMACommand, 15);
  448 
  449 public:
  450 /*! @var fRefCon Reference Constant, client defined publicly avialable */
  451     void *fRefCon;
  452 
  453 protected:
  454 
  455 /*! @var fMaxSegmentSize Maximum size of one segment in a scatter/gather list */
  456     UInt64  fMaxSegmentSize;
  457 
  458 /*! @var fMaxTransferSize
  459     Maximum size of a transfer that this memory cursor is allowed to generate */
  460     UInt64  fMaxTransferSize;
  461 
  462 /*! @var fBypassMask
  463     Mask to be ored into the address to bypass the given iommu's mapping. */
  464     UInt64  fBypassMask;
  465 
  466 /*! @var fMapper
  467     Client defined mapper. */
  468     IOMapper *fMapper;
  469 
  470 /*! @var fMemory
  471     memory descriptor for current I/O. */
  472     const IOMemoryDescriptor *fMemory;
  473 
  474 /*! @var fOutSeg The action method called when an event has been delivered */
  475     SegmentFunction fOutSeg;
  476 
  477 /*! @var fAlignMask
  478     Alignment restriction mask. */
  479     UInt32  fAlignMask;
  480 
  481 /*! @var fNumAddressBits
  482     Number of bits that the hardware can address */
  483     UInt32 fNumAddressBits;
  484 
  485 /*! @var fNumSegments
  486     Number of contiguous segments required for the current memory descriptor and desired mapping */
  487     UInt32  fNumSegments;
  488 
  489 /*! @var fMappingOptions
  490     What type of I/O virtual address mapping is required for this command */
  491     MappingOptions  fMappingOptions;
  492 
  493 /*! @var fActive
  494     fActive indicates that this DMA command is currently prepared and ready to go */
  495     UInt32 fActive;
  496 
  497 /*! @var reserved
  498     Reserved for future use.  (Internal use only)  */
  499     struct IODMACommandInternal * reserved;
  500 };
  501 
  502 IOReturn IODMACommand::
  503 weakWithSpecification(IODMACommand **newCommand,
  504                       SegmentFunction  outSegFunc,
  505                       UInt8     numAddressBits,
  506                       UInt64    maxSegmentSize,
  507                       MappingOptions mapType,
  508                       UInt64    maxTransferSize,
  509                       UInt32    alignment,
  510                       IOMapper *mapper,
  511                       void     *refCon) 
  512 {
  513     if (!newCommand)
  514         return kIOReturnBadArgument;
  515 
  516     IODMACommand *self = (IODMACommand *)
  517         OSMetaClass::allocClassWithName("IODMACommand");
  518     if (!self)
  519         return kIOReturnUnsupported;
  520 
  521     IOReturn ret;
  522     bool inited = self->
  523         initWithSpecification(outSegFunc,
  524                               numAddressBits, maxSegmentSize, mapType,
  525                               maxTransferSize, alignment, mapper, refCon);
  526     if (inited)
  527         ret =  kIOReturnSuccess;
  528     else {
  529         self->release();
  530         self = 0;
  531         ret = kIOReturnError;
  532     }
  533 
  534     *newCommand = self;
  535     return ret;
  536 };
  537 #endif /* !_IODMACOMMAND_H */
  538 

Cache object: d1a5d04904642d98c971092f493227b6


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.