Syntax

    struct CDMMessageStruct
    { 
       LONG   msgPutHandle;
       LONG   function;
       LONG   parameter0;
       LONG   parameter1;
       LONG   parameter2;
       LONG   bufferLength;
       void   *buffer;
       LONG   cdmSpace[2];
    };
    

Fields

msgPutHandle

A 4-byte field containing a handle to the current I/O request issued by the Media Manager. The Media Manger generates this value and uses it to track a request through different execution stages. This field value is needed as an argument for many of the APIs described in this manual, and it should never be altered.

function

A 1 LONG field. The upper WORD contains control attributes set by the Media Manager for the I/O request, and the lower WORD contains a Media Manager function code set by an application.

For processor independence reasons, the CDM can use the GET_MSW and GET_LSW macros to extract information from this field. These macros are defined as follows:

    #define GET_MSW (function) ((function >> 16) & 0xFFFF)
    

    #define GET_LSW (function) (function & 0xFFFF)
    

Media Manager control and I/O requests are equated to unique hexadecimal function codes (0x0000 - 0x0047). A Media Manager application makes an I/O request by calling a Media Manager API. The application selects a desired I/O action by passing one of the Media Manager function codes as an input parameter. In turn, the Media Manager packages the request into a CDM message [see CDMMessageStruct] by placing the function code in the lower WORD of this field, and then issues the CDM message to the target CDM.

The CDM maps this code into a call to one of its locally-implemented control or I/O routines designed to build the corresponding SuperHACB request.

A list of CDM message types, their corresponding Media Manager function codes, and their corresponding request descriptions can be found in CDM Message Control Functions and CDM Message I/O Functions.

As previously mentioned, in building the CDM message, the Media Manager places control attributes associated with the request in the upper WORD of this field. Most of these attributes have meaning only to the Media Manager and OS. The attributes that do have meaning to a CDM are defined as follows:

    #define SCATTER_GATHER_ON_BIT  0x0080
    

Indicates that the request is in NWPA's scatter/gather format. To inform the HAM, the CDM must set the Scatter_Gather_Bit in the corresponding HACB.

    #define HARDWARE_VERIFY_BIT  0x0100
    

Tells CDMs that they must set the verify bit for all write commands.

    #define CACHE_OKAY_BIT  0x8000
    

Indicates that controller and/or device level caching is okay. If this bit is not set, all write commands must write-through any controller/device caches.

parameter0

parameter1

parameter2

The content of these three LONGs depends on the function executed or message being sent. See CDM Message I/O Functions and CDM Message Control Functions for examples.

bufferLength

A 1-LONG field. Typically, its value indicates the size of the buffer field. However, its content depends on whether or not the request is in scatter/gather format. If it is in scatter/gather format, this field contains the number of entries in the scatter/gather request list. If it is not in scatter/gather format, this field contains the length, in bytes, of the data buffer. This field is set to zero for requests that do not require the movement of data.

buffer

A 4-byte field of type pointer to void. Typically, the pointer points to the CDM message's data buffer. However, the structure of the buffer it points to depends on whether or not the request is in scatter/gather format. If it is in scatter/gather format, this field contains the virtual starting address of the scatter/gather request list. The scatter/gather list is generated by NWPA or a Media Manager application. If the request is not in scatter/gather request, this field contains the virtual address to the data buffer, in which case if the operation is a read, this buffer is where the data is read to. If the operation is a write, this buffer is where the data is read from. This field is set to zero for requests that do not require the movement of data.

For information about the format of a scatter/gather list, refer to Scatter/Gather List .

cdmSpace

A 2-LONG field for the private use of the CDM that queues the current CDM Message using CDI_Queue_Message. The intended use of this field is to allow the CDM to create links between the queued, current message and other CDM messages or HACBs. If the CDM did not explicitly queue the message, it cannot expect the value it placed in this field to persist.

Remarks

CDMMessageStruct is identical to the Media Manager internal message structure. The fields in CDMMessageStruct contain the pertinent information required to build a control or I/O request. A pointer to this structure is then passed to the CDM which processes the CDMMessageStruct and converts it into a HACB request that is compatible with the adapter supporting the desired device.