Disclaimer	Novell, Inc. makes no representations or warranties with respect to the contents or use of this
manual, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc. reserves the right to revise this publication and to make changes to its content at any time, without obligation to notify any person or entity of such revisions or changes.

Further, Novell, Inc. makes no representations or warranties with respect to any NetWare software, and specifically disclaims any express or implied warranties of merchantability or fitness for any purpose. Further, Novell, Inc. reserves the right to make changes to any and all parts of NetWare software, at any time, without obligation to notify any person or entity of such changes.

Trademarks	Novell, Inc. has made every effort to supply trademark information about company names, products, and services mentioned in this document. Trademarks indicated below were derived from various sources.

Novell, NetWare, and the N-Design are registered trademarks of Novell, Inc.. The NetWare Logotype (teeth) is a trademark of Novell, Inc.

Copyright	© Copyright 1993, 1994, 1995 Novell, Inc. All rights reserved

This work is subject to U.S. and international copyright laws and treaties. No part of this publication may be practiced, performed, copied, distributed, revised, modified, translated, abridged, condensed, expanded, collected, or adapted without the express prior written consent of Novell, Inc. Any use or exploitation of this work without authorization could subject the perpetrator to criminal and civil liability.

Novell, Inc.

122 East 1700 South

Provo, Utah 84606 U.S.A.

Version 2.1d

September1995 Edition

Contents

Figures	v

Tables	v

Preface	vii

Revision History	viii

Chapter 1 About This Guide	1-1

1.1 Audience	1-1

1.2 Presentation Format	1-1

1.3 Synopsis of Sections and Chapters	1-2

1.4 Printing Conventions	1-4

Chapter 2 NetWare Peripheral Architecture Overview	2-1

2.1 Advantages	2-1

2.2 Conceptual Overview	2-2

2.2.1 NWPA Components	2-2

2.2.2 General Flow of Events	2-4

2.3 NetWare OS Environment	2-6

2.3.1 Operating Mode	2-6

2.3.2 Multitasking and Process Levels	2-6

Chapter 3 Host Adapter Control Block (HACB)	3-1

3.1 Overview	3-1

3.2 Super Host Adapter Control Block (SHACB)	3-1

3.2.1 Structure Definition	3-1

3.2.2 Field Descriptions	3-2

3.3 HACB Structure	3-2

3.3.1 Structure Definition	3-2

3.3.2 Field Descriptions	3-3

3.4 Scatter/Gather List	3-13

Chapter 4 Host Adapter Module (HAM)	4-1

4.1 HAM Architecture: Entry Points, Functions, and Routines	4-1

4.1.1 NLM Load/Unload-Time Entry Points	4-2

4.1.2 NWPA I/O Entry Points	4-3

4.1.3 Timeout Routine	4-5

4.1.4 HACB Type Zero Functions	4-5

4.1.5 Host Adapter Interface Routines	4-7

4.2 Operational Overview	4-8

4.2.2 Processing HACB I/O Requests	4-16

4.2.3 Aborting a HACB Request	4-19

4.2.4 Unload-time Deregistration	4-22

4.3 Special Topics	4-24

4.3.1 HAM Device Queues	4-24

4.3.2 Asynchronous Event Notification	4-28

4.3.3 Reentrance	4-29

4.3.4 Hot Software Replacement	4-29

4.3.5 Diagnostics	4-34

4.3.6 Error Handling and Auto Error Sense	4-35

4.3.7 Scanning Specific Target IDs and LUNs	4-36

4.3.8 Automatic Hardware Detection and Driver Configuration	4-38

4.3.9 Elevator Queuing	4-38

4.3.10 Vendor-Pass Through API for HAMs	4-39

Chapter 5 Custom Device Module (CDM)	5-1

5.1 CDM Architecture: Entry Points and Routines	5-1

5.1.1 NLM Load/Unload-Time Entry Points	5-2

5.1.2 CDM Entry Points	5-3

5.1.3 Device Control and I/O Routines	5-6

5.2 Operational Overview	5-7

5.2.1 Load-time Initialization and Registration	5-7

5.2.2 Inquiring and Binding to a Device	5-10

5.2.3 Processing CDM Messages	5-13

5.2.5 Registering Device Attributes	5-17

5.2.6 Unload-time Deregistration	5-19

5.3 Special Topics	5-21

5.3.1 Device Queue Behavior	5-21

5.3.2 Scanning Specific Target IDs and LUNs	5-21

5.3.3 Removable Media Support	5-30

5.3.4 Magazine Support	5-32

5.3.5 Changer Support	5-35

5.3.6 Asynchronous Hardware Event Notification	5-37

5.3.7 Avoiding Buffer Mismatches	5-38

5.3.8 Vendor-Pass Through API for CDMs	5-39

Chapter 6 Technical Reference for NWPA Data Structures	6-1

Chapter 7 Technical Reference for NWPA Routines	7-1

Chapter 8 HACB Type Zero Functions	8-1

Chapter 9 CDM Message Types	9-1

Chapter 10 OS Support Routines	10-1

Appendix A Creating NetWare Loadable Modules	A-1

Appendix B Handling HACB Completion Errors	B-1

Appendix C LDI/DDI Specification Supplements	C-1

Figures

Figure 2-1 NWPA Components	2-2

Figure 3-1: NWPA Scatter/Gather List	3-14

Figure 4-1: HAM Initialization	4-10

Figure A-1 Sample Definition File	A-3

Tables

Table 3-1: HACB Control Flag Values	3-5

Table 3-2: HACB Type Values	3-7

Table 3-3: Function Code Mapping of Type Zero HACB's to HAM	3-11

Table 4-1: Device Queue States	4-27

Table 5-1 Scan Completion Codes	5-29

Table 5-2: NWPA's Removable Media Control Functions	5-30

Table 5-3: Additional NWPA Control Functions for Magazine Support	5-33

Table B-1 HACB Completion Code Error Descriptions	B-1

Preface

This document describes the technical requirements and procedures for building device drivers under a driver architecture known as the NetWare Peripheral Architecture, or NWPA. This document provides a description of the NWPA and the Application Programmers Interface (API) set that it provides; along with a detailed description of requirements that the driver developers must meet to be certified by Novell Labs to work within the NWPA environment.

This document is intended for developers of device drivers that will interface with file servers using NetWare 3.12 and above.

Revision History

Version Number	Description of Revision
Version 1.x	Initial Release
Version 2.0	LONG HACBPutHandle replaces struct HACBStruct* as a stack parameter passed to the following APIs (see Chapter 8):

CDI_Abort_HACB()

CDI_Blocking_Execute_HACB()

CDI_Execute_HACB()

CDI_Return_HACB()

LONG *NPAHandle is an additional stack parameter required in CDI_Bind_CDM_To_Object() (see chapter 8)

LONG NPAHandle is an additional stack parameter required in the following APIs (see chapter 8):

CDI_Chain_Message()

CDI_Object_Update()

CDI_Unbind_CDM_From_Object()

CDMTypeStruct has been eliminated from the specification. This was replaced by the Types parameter in the CDI_Register_CDM() API. See chapter 8.

Extended HACB completion codes, see table 3-1.

Queue state indicator moved from ControlFlags field of HACB to most significant bit of hacbCompletion field. See hacbCompletion field in section 3.3.2.

The ControlFlags field name in the HACB was changed to Control_Info, and its purpose was redefined. See Control_Info field in section 3.3.2.

Optional HAM software hot replacement. See section 4.3.4 and HAM_Software_Hot_Replace() in chapter 8.

NWDIAG support required in HAM. See section 4..3.5.

Scatter_Gather and Hardware_Verify bits defined for Function field of CDM message structure. See Function field in section 5.2.2.

Entry points that allow applications to get and set device attributes added to the CDM. See sections 6.1.2, 6.2.5, AttributeInfoStruct in chapter 7 and CDI_Register_Object_Attribute in chapter 8.

Asynchronous Event Notification. For HAM, see section 4.3.2 and HAM_Queue_AEN_HACB() in chapter 9. For CDM see section 6.3.5.

Buffer mismatches. See section 6.3.6.

Addition of Appendix B for greater clarity in HAM and CDM error handling.

QueueLink field defined in CDM Message structure. See QueueLink field in section 5.2.2.
Version 2.1	Added auto error sense support in the HAM and CDM. This required a change to the HACB structure. Refer to the HACB's ErrorSenseBufferLength, VErrorSenseBufferPtr, and PErrorSenseBufferPtr fields in sections 3.3.1 and 3.3.2.

Support of auto error sense introduced a new data struccture See ErrorSenseInfoStruct in chapter 7.

For HAM specific support of auto error sense, see section 4.3.6 and the AttributeFlags field of the DeviceInfoStruct in chapter 7.

For CDM specific support of auto error sense, see section 6.3.7 and the AttributeFlags field of the DeviceInfoStruct in chapter 7.

Added specific target ID and LUN scan, also known as multiple LUN scan, support to the HAM and CDM. This also includes the concept of private and public devices. For the HAM, see seciton 4.3.7 and HAM_Scan_For_Devices in chapter 9. For the CDM, see section 6.2.3. For both HAMs and CDMs, also refer to the AttributeFlags field of the DeviceInfoStruct in chapter 7.

Added CDI_Rescan_Bus() API in conjunction with multiple LUN scan. See chapter 8.

The SCSI command block of the HACB was modified to accomodate 16 byte SCSI commands. The HACommandArea field was extended to be a 16 BYTE array, and the positions of the Reserved3 and HACommandLength fields were swapped. Refer to the SCSI Adapter Command structure in sections 3.3.1 and 3.3.2.

Made corrections to NPA_Unload_Module_Check(). The 2.0 specification stated that the HAM_Unload_Check() and CDM_Unload_Check() routines should make iterative calls to this API. For the correction to the HAM see HAM_Unload_Check() in section 4.1.1 and in chapter 8. For the correction to the CDM see CDM_Unload_Check() in section 6.1.1 and in chapter 8. Also, see NPA_Unload_Module_Check() in chapter 8.

Added two new HAM functions, HAM_Recovery_Reset and HAM_Deactivation_Notification. See section 4.1. and chapter 9.

Introduced the concept of auto detection and auto configuration. See section 4.3.8.

Correction to NPA_Exchange_Message(). The DataDirection parameter has been removed. See chapter 8.

Clarifications made to field descriptions of the UpdateInfoStruct and DeviceInfoStruct. See chapter 7.

Added successful completion code with queue frozen to HACB completion codes in section 3.3.2 and table 3-1.

Clarification made to HAM's abort paradigm in section 4.2.3 and to the HAM_Abort_HACB() return values in chapter 8.

Clarification made to HAM's queue behavior. See section 4.3.1.3 and table 4-1.

Correction made to HAM_Return_Device_Info. The 2.0 specification stated that the HAM should place the HAM-generated device handle in the Parameter0 field of the HACB host command block. This is incorrect. The HAM already places the device handle in the return buffer. See chapter 9.

Addition of AttributeID stack parameter to CDM_Set_Attribute() and CDM_Get_Attribute() routines. See section 6.1.2, 6.2.5, AttributeInfoStruct in chapter 7, and CDI Register_Object_Attribute() in chapter 8.
Version 2.1a	Generally, most of the changes were clarifications of existing concepts, not additions of new concepts.

Throughout the document, NPABindHandle ws changed to CDIBindHandle.

Figure 2-1 was changed.

Figure 2-2 was removed.

Section 3.3.1, CDMPassThrough command block: the structure of the block was changed. The BufferLength, Buffer, and ReturnParameter fields were replaced with the following: BYTE Reserved5[12]. The reason is that the data that was originally assigned to these fields is now part of the main HACB, DataBufferLenght, VDataBufferPtr, Control_Info, respectively.

Chapter 5 and Chapter 7, the CDM MessageStruct:

The definition of the CDMMessageStruct ws changed. The QueueLink field was redefined, and a new 1- LONG field was appended to the structure. The former QueueLink field and the new field were combined to make the following: LONG CDMReserved[2].

A new bit was defined in the upper WORD of the CDMMessageStruct's Function field, the CACHE_OKAY_BIT.

Section 6.2.1: Clarified CDM use of the NPA's command line parser.

Section 6.2.2: Reference to CDMTypeStruct was removed. The change regarding this structure was documented in version 1.x to 2.0 history.

Reorganization of Chapter 6. Some of the seciton numbers were changed. The Error Handling section was moved from Special Topics to the Operational Overview.

Special Topics: Added pertinent infomation regarding Removable-media device and magazine support.
Version 2.1b	Chapter 3 and Appendix B, Malformed Error

Added new HACB error code regarding auto error sense buffers.

Chapters 4, 6, and 9 Asynchronous Event Notification (AEN) Hacbs.

Fixed typo -- The AEN mask is a bitmap, Adapter Reset was changed from 0x00 to 0x08.

Chapter 6, section: CDM Entry Points, secition: Inquiring and Binding to a Device, Chapter 8, CDM_Inquiry - Clarified some of the issues regarding logical binding to a device. CDMHandle parameter is now passed on the stack.

Chapter 7, DeviceInfoStruct

Defined hardware verify and max units per transfer to attributes field.

Chapter 7, UpdateInfoStruct

Clarified meaning of some of the field definitions, and fixed the blocksize information as it relates to the changes made to the DeviceInfoStruct.

Chapter 8, NPA_System_Alert

Added this new API for issuing alert messages to the console screen.

Chapter 10, Insert Functions

Fixed typo. The NPA function code for insert functions should be 0x1B.

Fixed typo. Reset End of Tape should have been Restart Queue.

Chapter 11, AllocateResourceTag and RegisterForEventNotification

Added technical information for these two OS routines.
Version 2.1c	Administrative Revision - Reformatted entire document to reflect Novell Technical Publications standards.

Added Revision History section to document.

Changed text citations of NPA to NWPA (NetWare Peripheral Architecture) to avoid confusion with the Network Professional Association (NPA). However, all API and parameter references using NPA were not changed at this time.

Added new Control Flag to Table 3-1 (No_Freeze_Queue_Flag).

Deleted Chapter 5 since material was also described elsewhere. Changed all subsequent chapter numbers and references to these chapter numbers to reflect deletion.

Added NetWare Bus Interface (NBI) material and APIs. See Figure 2-1, Paragraph 4.2.1, and Chapter 7 for NBI related changes.

Provided detailed description for the design of Software-Hot Replaceable HAMs in section 4.3.4.

Added a description of the Elevator Queueing capabilities of NWPA. See section 4.3.9.

Added two new Vendor-Pass Through APIs: NPA_HACB_Passthru() and NPA_CDM_Passthru() See Sections 4.3.10, 5.3.8, and Chapter 7 for details.

Corrected descriptions of existing event flags and added 2 new event flags to CDM_Inquiry() to support End of Bus cases. See section 5.2.2 and Chapter 7 CDM_Inquiry() for details.

Updated CDM requirements for Unload-time Deregistration. See section 5.2.6 for details.

Updated DeviceInfoStruct and HamInfoStruct parameter lists. Added Product ID Option to Type parameter in NPAOptionStruct.

Updated Case 0 and Case 1 scan requirements.

Updated Chapter 10 OS Support Routines to describe currently implemented OS routines, including correcting the SetFlags() routine to a VOID from a LONG.

Corrected references from .dsk output file to .ham output file in Appendix A.

Changed IDE to IDE\ATA where applicable.

Reformatted Appendix B into one table. Deleted Table 3-1 and replaced references to this table with a reference to Appendix B. Changed Table 3-2 , Table 3-3 and Table 3-4 (along with all text references to these tables) to Table 3-1, Table 3-2 and Table 3-3 respectively.

Added Appendix C LDI/DDI Specification Supplement and Related Material.

Deleted the Index from this revision.
Version 2.1d	Corrected typos, format errors, etc. in preparation for Novell Labs release of document.

Added NPA_Get_Version_Number () API.

Added Blocking flag option for NPA_Allocate_Memory() to Version 4.x NWPA.

Replaced Figure 4-1 with update notice. Figure 4-1 will be updated for the next document release, as noted in paragraph 4.2.1

Updated HAM Device Queue State column in Appendix B to reflect addition of the No_Freeze_Queue_Flag option for CDMs.

Updated DeviceInfoStruct parameter definitions to add SCSI Synchronous Information.

Updated NPAOptionStruct parameter definititions.

Deleted HAI_Get_Slot() and HAI_Get_Slot_Name() APIs to reflect changes in the NBI specification.

Updated the description for NPA_Interrupt_Control().

Added 10 microsecond resolution note to NPA_Micro_Delay().

Added Thread Context information to Inx, InBuffx, Outx and OutBuffx APIs.

Changed the identifying prefix for NBI APIs from HAI_ to NPAB_ to separate them from the existing Host Adapter specific APIs. Updated the references to these APIs throughout the document to reflect this change. Re-sorted Chapter 7 to place the NPAB_ APIs in alphabetical order.

Deleted the NPABusHandle parameter from all of the NPAB_ APIs.

Corrected the return value types for CCmpB() and CCmpD() in Chapter 10 from BYTE to LONG.

Added InvertLong() function definition to Chapter 10.

Updated Draft portion of Appendix C to reflect changes in the LDI/DDI specification.

Updated Appendix A to include a new link.def file example and to list the include files needed for HAMs and CDMs.