PATH
OSStatus
PrepareMemoryForIO (IOPreparationTable *theIOPreparationTable);
PrepareMemoryForIO coordinates data transfers between devices and one or more memory ranges with the operating system, the main processor caches, and other data buffers. Preparation includes ensuring that physical memory remains assigned to the memory ranges until CheckpointIO relinquishes it. Depending on the I/O direction and data path coherence that are specified, Mac OS manipulates the contents of the processor's caches, if any, and may make parts of the ranges noncacheable.
A native driver can call PrepareMemoryForIO from its DoDriverIO handler. The DoDriverIO entry point is discussed in DoDriverIO Entry Point.
The driver or other software must perform I/O preparation before permitting data movement. For operations with block-oriented devices, preparation is best done just before moving the data, typically by the driver. For operations upon buffers such as memory shared between the main processor and a coprocessor, frame buffers, or buffers internal to a driver, preparation is best performed when the buffer is allocated. This technique is discussed more fully in Multiple Transfers. The PCI Card Device Driver Kit contains code samples that use PrepareMemoryForIO.
Calls to PrepareMemoryForIO should be matched with calls to CheckpointIO, even if the I/O operation was aborted. In addition to applying finishing operations to the memory range, CheckpointIO deallocates resources used in preparing the range.
The IOPreparationTable must remain allocated until the last CheckPointIO is called.
PrepareMemoryForIO may be called only at task level from a driver's DoDriverIO routine or from a subroutine called by DoDriverIO.