PrepareMemoryForIO Data Structures

The PrepareMemoryForIO function has a single parameter, a pointer to an IOPreparationTable structure.

Some fields of the IOPreparationTable structure contain pointers to subsidiary structures. There are three types of subsidiary structures:

The IOPreparationTable structure and its subsidiary structures are diagrammed in Figure 11-1.

Note

In Figure 11-1, gray areas are filled in by the PrepareMemoryForIO function and white areas are filled in by the calling software. The preparationID field is used both ways.

The IOPreparationTable structure is defined as follows:



 
struct IOPreparationTable

{

    IOPreparationOptions            options;

    IOPreparationState              state;

    IOPreparationID                 preparationID;

    AddressSpaceID                  addressSpace;

    ByteCount                       granularity;

    ByteCount                       firstPrepared;

    ByteCount                       lengthPrepared;

    ItemCount                       mappingEntryCount;

    LogicalMappingTablePtr          logicalMapping;

    PhysicalMappingTablePtr         physicalMapping;

    union

    {

    AddressRange                    range;

    MultipleAddressRange            multipleRanges;

    }                               rangeInfo;

};



 
typedef struct IOPreparationTable IOPreparationTable;



 
typedef OptionBits IOPreparationOptions;

enum {

    kIOMultipleRanges                   = 0x00000001,

    kIOLogicalRanges                    = 0x00000002,

    kIOMinimalLogicalMapping            = 0x00000004,

    kIOShareMappingTables               = 0x00000008,

    kIOIsInput                          = 0x00000010,

    kIOIsOutput                         = 0x00000020,

    kIOCoherentDataPath                 = 0x00000040,

    kIOClientIsUserMode                 = 0x00000080

};

Figure 11-1 IOPreparationTable structure



 
typedef OptionBits IOPreparationState;

enum {

    kIOStateDone                        = 0x00000001

};



 
typedef struct MultipleAddressRange MultipleAddressRange;



 
struct MultipleAddressRange

{

    ItemCount                       entryCount;

    AddressRangeTablePtr            rangeTable;

};

The IOPreparationTable structure specifies the buffer to be prepared and provides storage for the mapping and other information that are returned. Its fields contain the following information:

options: Optional characteristics of the IOPreparationTable structure and the transfer process. Possible values in this field are discussed in IOPreparationTable Options.
state: Filled in by PrepareMemoryForIO to indicate the state of the IOPreparationTable structure. The kIOStateDone flag indicates that the buffer has been prepared up to the end of the specified range. See Partial Preparation.
preparationID: Filled in by PrepareMemoryForIO to indicate the identifier that represents the I/O transaction. When the I/O operation is completed or abandoned, the IOPreparationID value is used to finish the transaction, as described in Finishing I/O Transactions.
addressSpace: The address space containing the buffer to be prepared. Current versions of the Mac OS provide only one address space, which it automatically passes to native drivers through DoDriverIO. In general, a driver should always pass the address space it received as a parameter to its DoDriverIO routine in this field. Otherwise, this field must be specified as kCurrentAddressSpaceID.
granularity: Information to reduce the memory usage of partial preparations. See Partial Preparation.
firstPrepared: The byte offset into the buffer at which to begin preparation. See Partial Preparation.
lengthPrepared: Filled in by PrepareMemoryForIO to indicate how much of the buffer was successfully prepared, beginning at firstPrepared. See Partial Preparation.
mappingEntryCount: Number of entries in the logical and physical mapping tables supplied. Normally, the driver should allocate as many entries as there are pages in the buffer. The number of pages in a memory range can be calculated from the range's base address and length. If there are not enough entries, a partial preparation is performed within the limit of the tables. See Partial Preparation.
logicalMapping: The address of an array of LogicalAddress values. PrepareMemoryForIO fills the logical mapping table with the static logical mappings for the specified buffer. This table is optional. Mapping tables are discussed in Mapping Tables.
physicalMapping: The address of an array of PhysicalAddress values. PrepareMemoryForIO fills the physical mapping table with the physical addresses corresponding to the specified buffer. This table is optional. Mapping tables are discussed in Mapping Tables.
rangeInfo: The buffer to prepare. A simple buffer is represented by a single AddressRange value. A scatter-gather buffer is specified by a MultipleAddressRange structure. If the kIOMultipleRanges flag is omitted from options, rangeInfo is interpreted as an AddressRange value named range. If kIOMultipleRanges is specified in options, rangeInfo is interpreted as a MultipleAddressRange structure named multipleRanges. Scatter-gather buffers are discussed in Scatter-Gather Client Buffers. Because there might be insufficient resources to prepare the entire buffer, the buffer can be prepared in pieces. This procedure is discussed in Partial Preparation.