Novell Documentation: Storage Architecture Components (incl. Media Manager & NWPA) - CDM Architecture: Entry Points and Routines

4.1 CDM Architecture: Entry Points and Routines

This section provides prototypes for the entry points and routines required in a CDM by NetWare Peripheral Architecture (NWPA). A developer can use these prototypes to plumb the shell of a CDM. Detailed descriptions of the data structures and entry points can be found in Structures, and Functions.

To fit properly in the architecture, a CDM is required to provide the following:

Device control and I/O routines are mentioned here because they are crucial to the CDM architecture. However, this developer's guide does not attempt any specifications on these routines, because they are manufacturer specific. Prototypes and definitions of these routines are the responsibility of CDM developers.

Complete functional specifications of the entry points can be found in Functions, and descriptions of the CDM messages can be found in CDM Message Control Functions and CDM Message I/O Functions.

Naming each entry point is left to the CDM developer; however, each entry point must provide the functionality described in this guide.

For consistency in referring to these entry points and routines within the text and in code examples, this guide gives each a generic name with a CDM_ prefix. Whenever an entry point or function with this prefix is encountered, it indicates that the routine is CDM specific. The italic typeface indicates that the name is arbitrary.

4.1.1 NLM Load/Unload-Time Entry Points

A CDM must provide three standard NLM entry points for the OS. These entry points are made visible to the OS through a definition (.def) file that is processed by a NetWare compatible linker utility. The prototypes of these entry points, along with their generic names, are as follows:

CDM_Load is the CDM's load-time entry point. CDM_Load is called on a blocking thread. Through this entry point, a CDM receives its OS-generated resource handle (loadHandle), an ID to the LOAD console screen, and a pointer to the LOAD command line string that contains load options associated with the module. For a CDM, these options set the operational states of the program module. They do not apply to hardware resources.
CDM_Load is responsible for allocating any resources needed to make the CDM operational, for configuring the CDM based on the load options specified on the LOAD command line, and for registering the CDM and its I/O entry points with NWPA.
```
    LONG CDM_Load (
       LONG   loadHandle, 
       LONG   screenID, 
       BYTE  *commandLine 
    );
    
```
CDM_Unload_Check is the CDM's initial unload-time entry point. The entry point gets called when an UNLOAD command is issued on the CDM. CDM_Unload_Check is called on a blocking thread. CDM_Unload_Check is responsible for checking to see if any of the CDM's devices are currently being used by an NLM application and return use status. To do this, CDM_Unload_Check returns the use-status returned by NPA_Unload_Module_Check. From this return value, the OS can determine if any of the devices managed by the CDM are in use. If any devices are in use, the OS displays a message at the console listing the devices to be deactivated and the corresponding NetWare volumes that will be dismounted if the action is continued. The user then has the option to either continue or abort the unload.
```
    LONG CDM_Unload_Check (LONG screenID);
    
```
CDM_Unload is the CDM's final unload-time entry point, meaning that the unload thread already called CDM_Unload_Check and the systems operator chose to continue. Thus, the unload thread was allowed to continue and make a call to CDM_Unload. CDM_Unload unregisters the CDM from NWPA and returns allocated resources back to the system. After the CDM is unloaded, all devices it was managing are inaccessible.
```
    void CDM_Unload (void);
    
```

4.1.2 CDM Entry Points

A CDM must provide additional entry points for NWPA. The prototypes of these entry points, along with their generic names, are as follows:

CDM_Abort_CDMMessage is an entry point that the CDM must provide if it internally queues CDM messages. Each time a CDM queues a message as opposed to immediately building a HACB and initiating its execution, the CDM must call CDI_Queue_Message. For each message it queues, the CDM must pass the address of an abort routine as an input argument to CDI_Queue_Message. This is the routine that NWPA calls if an abort is issued on its corresponding message.
```
    LONG CDM_Abort_CDMMessage (LONG parameter);
    
```
As in the case of CDM_Callback, the CDM can define multiple abort routines. The term CDM_Abort_CDMMessage is used to generically refer to one or multiple CDM abort routines.
CDM_Callback is a callback entry point so NWPA can inform the CDM of the completion of a non-blocking execution cycle. A non-blocking execution cycle of a HACB is initiated when the CDM calls CDI_Execute_HACB. The address of the callback routine is an input parameter to CDI_Execute_HACB; thus, a callback is registered with NWPA for each call of CDI_Execute_HACB. Because the callback link is on a per execution basis, the CDM can either have one global callback, or it can define multiple callback routines, and link the one appropriate to the HACB request being executed. In this manual, the term CDM_Callback generically refers to either of these cases.
```
    LONG CDM_Callback (
       struct SuperHACBStruct *superHACB, 
       LONG                    npaCompletionCode); 
    
    
```
CDM_Check_Option is the CDM's entry point for receiving and verifying command line options. The entry point is called during two separate NWPA processes: once during the command line parsing phase of CDM initialization and again during the actual registration of options. The CDM invokes these two NWPA processes at different points in its load-time entry point, CDM_Load. This entry point is made visible to the system when the CDM registers itself with NWPA using NPA_Register_CDM_Module.
This entry point is optional. The only reason a CDM would need to provide this routine is if it supports load options and intends to parse the LOAD command line for these options.
```
    LONG CDM_Check_Option ( 
       struct NPAOptionStruct  *Option, 
       LONG                     instance 
       LONG                     flag); 
    
    
```
CDM_Execute_CDMMessage is the CDM's entry point for fielding CDM message requests. This routine uses a jump table (or some other form of routing) so that the CDM can route the message to the local control or I/O routine designed to field the current message type. The local routine is required to build the appropriate SuperHACB to accomplish the request. This entry point is made visible to the system when the CDM registers with NWPA using NPA_Register_CDM_Module.
```
    LONG CDM_Execute_CDMMessage (
       LONG                     cdmBindHandle, 
       struct CDMMessageStruct  *Msg); 
    
    
```
CDM_Get_Attribute is the entry point from which NWPA can retrieve registered device attribute information for an NLM application. This entry point gets registered with NWPA when the CDM registers the attribute by calling CDI_Register_Object_Attribute.
```
    LONG CDM_Get_Attribute (
       LONG   cdmBindHandle, 
       void  *infoBuffer, 
       LONG   infoBufferLength, 
       LONG   attributeID); 
    
    
```
The CDM registers a get-attribute routine by calling CDI_Register_Object_Attribute. Therefore, the CDM can implement either one routine to handle all get-attribute calls, or distribute the calls through multiple routines. This developer's guide calls CDM_Get_Attribute generically to refer to either case.
CDM_Inquiry is the entry point where NWPA passes the CDM information about either an existing device or a device that just came online with a type that matches the device type for which the CDM registered. This entry point is registered with the system when the CDM registers itself with NWPA using NPA_Register_CDM_Module. It is during the context of this entry point that the CDM can issue passive requests (see note below) to the device to determine if it wants to field I/O requests for the device. If the CDM decides to field requests for the device, it informs NWPA by binding to the device.
During the context of this entry point the CDM must not issue any commands that change the state or mode of the device. Passive requests are those such as the SCSI MODE SENSE command.
```
    LONG CDM_Inquiry (
       LONG                      npaDeviceID, 
       LONG                      npaBusID, 
       struct DeviceInfoStruct  *DeviceInfo, 
       LONG                     flags, 
       LONG                     cdmHandle); 
    
    
```
CDM_Set_Attribute is the entry point by which NWPA can set a registered device attribute for an NLM application. This entry point gets registered with NWPA when the CDM registers the attribute by calling CDI_Register_Object_Attribute.
The CDM registers a set-attribute routine with each call to CDI_Register_Object_Attribute. Therefore, the CDM can implement either one routine to handle all set-attribute calls, or distribute the calls through multiple routines. This developer's guide uses CDM_Set_Attribute generically to refer to either case.
```
    LONG CDM_Set_Attribute (
       LONG   cdmBindHandle, 
       void  *infoBuffer, 
       LONG   infoBufferLength, 
       LONG   attributeID); 
    
    
```

4.1.3 Device Control and I/O Routines

A CDM must provide routines that translate CDM messages containing NWPA functions into HACB requests. Some of these NWPA functions deal with device control, and some deal with I/O. Control functions typically modify the state of devices or media objects such as activating a device or formatting media. I/O functions typically handle the movement of data to and from media such as reads and writes. The appropriate CDM routine to field an incoming CDM message gets called through the routing mechanism the CDM implements in CDM_Execute_CDMMessage.