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.