5.1 Making CDMs and HAMs NetWare Loadable Modules

Device drivers must be converted from source modules into NetWare Loadable Modules (NLM) applications before they can be loaded and installed in a NetWare operating system. Developer Services can provide a list of compilers that can be used to create object modules from driver source modules. The object modules must be processed by the NetWare linker NLMLINKX. The linker requires a developer-created definition file (.def) that provides configuration information needed to produce the NLM, including the NetWare internal variables and routines the driver will access once loaded.

This section covers the following topics:

The NLMLINKX command syntax is as follows:

    nlmlinkx drivername <Enter>

Where drivername is the name of the definition file for the desired driver. (It is not necessary to enter the .def extension in this command).

NLMLINKX finds all the required information and directives in the definition file, including the names of all object modules that must be linked to form the driver (see Sample Definition File). NLMLINKX produces an output file (with a .ham or .cdm extension) that is the NLM form of the driver module, ready to load into an active NetWare environment. The Sample Definition File shows a sample definition file that directs NLMLINKX to find sample.obj, link it, and produce the output file sample.ham.

5.1.1 Required Header Files

There are four header files that Novell® created to provide the necessary definition statements for HAMs and CDMs. These are:

  • NPA.H - Required for HAMs and CDMs. This must be included first.
  • NBI.H - Required for NBI-aware HAMs. If used, this must be included before NPA_HAM.H. Also, a Novell assigned compiler environment variable for the target platform must be declared. Currently, IAPX386 (for Intel platforms) is the only defined environment variable. NBI.H has an imbedded include statement that is associated with a platform-specific .h file based on this environment variable. This file contains all of the programs associated with the target platform for the specific compiler. Contact Developer Services for a current list of supported platforms and their associated environment variables and .H files. For IAPX386, the file NBIEXP.H must be located in your include path.
  • NPA_HAM.H - Required for HAMs.
  • NPA_CDM.H - Required for CDMs.
  • NWPA.H - Can be used in place of all the above-referenced header files for both HAMs and CDMs.

The nwpaload.nlm file a required module that must be loaded prior to your HAM or CDM being loaded. This is done by the inclusion of the module NWPALOAD.NLM line in the example definition file.

Include these files in your modules and in the include path defined for your compiler.

Do not import public symbols that are not defined in this specification. We also recommend including the debug keyword in the definition file to facilitate debugging (even for certification).

5.1.2 Sample Definition File

    # SAMPLE.DEF example file
    
    description "Novell Sample HAM" 
    type        8 
    input       sample
    output      sample
    debug       
    start       HAM_Load 
    check       HAM_Unload_Check 
    exit        HAM_Unload 
    map 
    module      NWPALOAD.NLM 
    reentrant 
    copyright   "Copyright 2002 Novell, Inc."
    version    xx, yy, zz (see keyword description for details)
    flag_on    0x04000000
    xdcdata    NWPA.XDC 
    import 
       CCmpB 
       CMovB 
       CSetB 
       CStrLen 
       DisableAndRetFlags 
       Enable 
       HAI_Activate_Bus 
       HAI_Complete_HACB 
       HAI_Deactivate_Bus 
       InvertLong 
       NPA_Add_Option 
       NPA_Allocate_Memory 
       NPA_Cancel_Thread 
       NPA_Dec
       NPA_Delay_Thread 
       NPA_Exchange_Message 
       NPA_Inc
       NPA_Interrupt_Control 
       NPA_Micro_Delay 
       NPA_Parse_Options 
       NPA_Register_HAM_Module 
       NPA_Register_Options 
       NPA_Return_Bus_Type 
       NPA_Return_Memory 
       NPA_Spawn_Thread 
       NPA_Spinlock
       NPA_SpinlockInit
       NPA_SpinUnlock
       NPA_System_Alert 
       NPA_Unload_Module_Check 
       NPA_Unregister_Module 
       NPA_Unregister_Options 
       NPAB_Get_Card_Config_Info 
       OutputToScreen 
       MapDataOffsetToAbsoluteAddress 
       SetFlags

Definition File Keywords

The .def file keywords can occur in any order, and the required keywords are indicated. The following keywords are defined for use in the definition file to direct NLMLINKX in creating NLM device drivers:

type
(Required) Specifies the type of loadable module, and implicitly determines the extension to append on the output file:
  • 1 = LAN Driver (.lan)
  • 3 = Name space module (.nam)
  • 4 = Utility (.nlm)
  • 8 = HAM
  • 9 = CDM
description
(Required) Specifies a string that describes the loadable module to be created. The console command MODULES outputs this string to describe this module. The description can be 1-127 bytes long, must be enclosed in double quotes, and cannot include a null, double quote, carriage return, or new-line. The description should contain the indicated fields in the following order format: company or product name, description.
output
(Required) Specifies the name of the output file (the extension is added by the linker as specified above).
input
(Required) Specifies the name of the input files. An .obj extension is assumed; .lib files are not accepted.
start
(Required) Specifies the name of the loadable module's initialization procedure. When the file server supervisor uses the LOAD console command to load the module, NetWare calls this procedure.
exit
(Required) Specifies the name of the loadable module's exit procedure. This procedure is called when the file server supervisor enters the UNLOAD console command.
check
(Required) Specifies the name of the loadable module's check procedure. The UNLOAD console command calls an NLM's check procedure (if it exists) before unloading the module. The check procedure is required for disk drivers because it must indicate to the OS if any disks are locked (that is, the module cannot be safely unloaded).
copyright
(Required) Inserts the Novell default copyright or the copyright for a third-party developer. Usage:

copyright " " is the Novell default copyright "company" is the third-party copyright message

version
(Required) Version XX,YY,ZZ as follows:
  • XX - Major version number (0 to 2147483647)
  • YY - Minor version number (0 to 99)
  • ZZ - Revision number (0 to 26)
reentrant
(Usually optional. Required for modules that support Software Hot Replacement.) Specifies that the loadable module is reentrant (that is, two or more processes can use the code at the same time). This keyword is mutually exclusive (both cannot be specified) with the keyword multiple.
multiple
(Optional) Specifies that more than one code image of the loadable module can be loaded into file server memory. This keyword is mutually exclusive (both cannot be specified) with the keyword reentrant.
flag_on
(Optional) Specifies flags to be set for the NLM. For a module that supports Software Hot Replacement and uses the same module name for the existing and replacement modules, use the following string (see also Section 3.6, Software Hot Replacement):

flag_on 0x04000000

map
(Optional) Directs the linker to create a map file.
import
(Required) Specifies that a list following the keyword contains variable and procedure names that are external to the object files. These variables and procedures are case sensitive NWPA and NetWare operating system variables and procedures (or variables and procedures from other loadable modules that must have been previously loaded) to be linked to the module after it has been loaded and before it begins initialization.
module
(Required for HAMs and CDMs) Specifies loadable modules that must be loaded before the current loadable module is loaded. The loader attempts to find and load any modules not already in the server memory. If it cannot, the current module is not loaded. HAMs and CDMs must use this option to require loading nwpaload.nlm prior to their loading.
debug
(Optional) Specifies that the linker includes debug information in the output file.
@
(Optional) Specifies a filename that can be used with the Input, Import, and Export directives. The @ operator indicates that the list is to be read from a file, and can be nested. The file specifier, including path, must immediately follow the @ operator.
import
@file.txt
#
(Optional) Identical to the "//" comment indicator in the C programming language. All text on the same line following the # operator is ignored by the linker.