- @abstract Creates and initialises an IODMACommand in one operation if this version of the operating system supports it.
- @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.).
- @param newCommand Output reference variable of the newly created IODMACommand.
- @param outSegFunc SegmentFunction to call to output one physical segment. A set of nine commonly required segment functions are provided.
- @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.
- @param maxSegmentSize Maximum allowable size for one segment. Zero is treated as an unlimited segment size.
- @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.
- @param maxTransferSize Maximum size of an entire transfer. Defaults to 0 indicating no maximum.
- @param alignment Alignment restriction, in bytes, on I/O bus addresses. Defaults to single byte alignment.
- @param mapper For mapping types kMapped & kBypassed mapper is used to define the hardware that will perform the mapping, defaults to the system mapper.
- @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.
-*/
- // Note that the function has the attribute always_inline.
- // The point of this function is to make a call into the kernel
- // without generating an undefined symbol. If the client could call
- // the code as a function then the goal of no undefined symbols
- // would be lost thus defeating the purpose.
- static inline IOReturn weakWithSpecification
- (IODMACommand **newCommand,
- SegmentFunction outSegFunc,
- UInt8 numAddressBits,
- UInt64 maxSegmentSize,
- MappingOptions mapType = kMapped,
- UInt64 maxTransferSize = 0,
- UInt32 alignment = 1,
- IOMapper *mapper = 0,
- void *refCon = 0) __attribute__((always_inline));
+ * @abstract Creates and initialises an IODMACommand in one operation if this version of the operating system supports it.
+ * @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.).
+ * @param newCommand Output reference variable of the newly created IODMACommand.
+ * @param outSegFunc SegmentFunction to call to output one physical segment. A set of nine commonly required segment functions are provided.
+ * @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.
+ * @param maxSegmentSize Maximum allowable size for one segment. Zero is treated as an unlimited segment size.
+ * @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.
+ * @param maxTransferSize Maximum size of an entire transfer. Defaults to 0 indicating no maximum.
+ * @param alignment Alignment restriction, in bytes, on I/O bus addresses. Defaults to single byte alignment.
+ * @param mapper For mapping types kMapped & kBypassed mapper is used to define the hardware that will perform the mapping, defaults to the system mapper.
+ * @param refCon Reference Constant
+ * @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.
+ */
+// Note that the function has the attribute always_inline.
+// The point of this function is to make a call into the kernel
+// without generating an undefined symbol. If the client could call
+// the code as a function then the goal of no undefined symbols
+// would be lost thus defeating the purpose.
+ static inline IOReturn weakWithSpecification
+ (IODMACommand **newCommand,
+ SegmentFunction outSegFunc,
+ UInt8 numAddressBits,
+ UInt64 maxSegmentSize,
+ MappingOptions mapType = kMapped,
+ UInt64 maxTransferSize = 0,
+ UInt32 alignment = 1,
+ IOMapper *mapper = NULL,
+ void *refCon = NULL) __attribute__((always_inline));
+
+ static IODMACommand *
+ withSpecification(SegmentFunction outSegFunc,
+ const SegmentOptions * segmentOptions,
+ uint32_t mappingOptions,
+ IOMapper * mapper,
+ void * refCon);
+
+
+/*! @function withRefCon
+ * @abstract Creates and initializes an unspecified IODMACommand.
+ * @discussion Factory function to create and initialize an unspecified IODMACommand. prepareWithSpecification() must be used to prepare the IODMACommand before use.
+ * @param refCon Reference Constant
+ * @result Returns a new IODMACommand if successfully created and initialized, 0 otherwise.
+ */
+ static IODMACommand * withRefCon(void * refCon);
projects / apple / xnu.git / blobdiff