iokit/IOKit/IODMACommand.h

35 /**************************** class IODMACommand ***************************/
38     @class IODMACommand
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.
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.
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!
49 class IODMACommand : public IOCommand
51     OSDeclareDefaultStructors(IODMACommand);
107     typedef bool (*SegmentFunction)(IODMACommand *target,
117     static bool OutputHost32(IODMACommand *target,
123 #define kIODMACommandOutputHost32   (IODMACommand::OutputHost32)
128     static bool OutputBig32(IODMACommand *target,
134 #define kIODMACommandOutputBig32    (IODMACommand::OutputBig32)
139     static bool OutputLittle32(IODMACommand *target,
145 #define kIODMACommandOutputLittle32 (IODMACommand::OutputLittle32)
150     static bool OutputHost64(IODMACommand *target,
156 #define kIODMACommandOutputHost64   (IODMACommand::OutputHost64)
161     static bool OutputBig64(IODMACommand *target,
167 #define kIODMACommandOutputBig64    (IODMACommand::OutputBig64)
172     static bool OutputLittle64(IODMACommand *target,
178 #define kIODMACommandOutputLittle64 (IODMACommand::OutputLittle64)
181     @abstract Creates and initializes an IODMACommand in one operation.
182     @discussion Factory function to create and initialize an IODMACommand in one operation.
192     static IODMACommand *
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.
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.
221 	    (IODMACommand   **newCommand,
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.
237     virtual IODMACommand *cloneCommand(void *refCon = 0);
240     @abstract Primary initializer for the IODMACommand class.
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 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.
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.
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.
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().
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.
335     @result The number of bytes copied, zero will be returned if the specified offset is beyond the prepared length of the IODMACommand. */
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.
345     @result The number of bytes copied, zero will be returned if the specified offset is beyond the prepared length of the IODMACommand. */
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.
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.
376 				    IODMACommand *target,
389 	    void *reference, IODMACommand *target,
394 			IODMACommand *target,
404     @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.
433 			IODMACommand *target,
440     @discussion If successfully prepared, returns the offset and length into the IOMemoryDescriptor. Will fail for an unprepared IODMACommand.
443     @result An IOReturn code. kIOReturnNotReady if the IODMACommand is not prepared. */
451     OSMetaClassDeclareReservedUsed(IODMACommand,  0);
452     OSMetaClassDeclareReservedUsed(IODMACommand,  1);
453     OSMetaClassDeclareReservedUsed(IODMACommand,  2);
454     OSMetaClassDeclareReservedUnused(IODMACommand,  3);
455     OSMetaClassDeclareReservedUnused(IODMACommand,  4);
456     OSMetaClassDeclareReservedUnused(IODMACommand,  5);
457     OSMetaClassDeclareReservedUnused(IODMACommand,  6);
458     OSMetaClassDeclareReservedUnused(IODMACommand,  7);
459     OSMetaClassDeclareReservedUnused(IODMACommand,  8);
460     OSMetaClassDeclareReservedUnused(IODMACommand,  9);
461     OSMetaClassDeclareReservedUnused(IODMACommand, 10);
462     OSMetaClassDeclareReservedUnused(IODMACommand, 11);
463     OSMetaClassDeclareReservedUnused(IODMACommand, 12);
464     OSMetaClassDeclareReservedUnused(IODMACommand, 13);
465     OSMetaClassDeclareReservedUnused(IODMACommand, 14);
466     OSMetaClassDeclareReservedUnused(IODMACommand, 15);
521 IOReturn IODMACommand::
522 weakWithSpecification(IODMACommand **newCommand,
535     IODMACommand *self = (IODMACommand *)
536 	OSMetaClass::allocClassWithName("IODMACommand");