PATH
If insufficient resources are available to prepare the whole range of memory that is specified, PrepareMemoryForIO will prepare as much as possible, indicate to the driver how much memory was prepared, clear the kIOStateDone bit in tableState, and return noErr. This is called a partial preparation.
Examples of resources that may limit the preparation are insufficient physical page frames to make the buffer resident, mapping table size too small, and not enough operating-system pool space. Because not all of these resources are under the control of the driver, every driver that calls PrepareMemoryForIO must be written to handle a partial preparation. One possibility is to make the terminating CheckpointIO call to deallocate the preparation's resources and return an error to the client. Another possibility is to perform the transfer as a series of partial transfers.
The firstPrepared, lengthPrepared, and granularity fields of the IOPreparationTable structure (shown in Figure 11-1 ) control partial preparations. When calling PrepareMemoryForIO the first time, specify 0 for firstPrepared. If the resulting tableState value does not indicate kIOStateDone, a partial preparation was performed, and lengthPrepared indicates how much memory was successfully prepared. After the data transfer and final call to CheckpointIO, another PrepareMemoryForIO call can be made to prepare as much as possible of the ranges that remain. This time, firstPrepared should be the sum of the current firstPrepared and lengthPrepared. This sequence prepare, transfer, and final checkpoint can be repeated until IOPreparationState indicates kIOStateDone.
The granularity field gives a hint to PrepareMemoryForIO for partial preparation. It is useful for transfers with devices that operate on fixed-length buffers. The length prepared will be 0 (with an error status returned) or a multiple of granularity rounded up to the next greatest page alignment. This prevents preparing more memory than the driver is willing to use. A value of 0 for granularity specifies no granularity. No check is made for whether the specified range lengths are multiples of granularity.