1.4 NetWare OS Environment

This section discusses NetWare OS issues that affect NWPA, including the following:

The following figure illustrates these interactions:

Figure 1-2 Interactions Between the NetWare OS and NWPA

1.4.1 Operating Mode

All NetWare device drivers are required to run in 32-bit mode, regardless of the language used to write the driver. Drivers can assume SS=ES=DS but should not assume that the Code Segment is identical with DS.

1.4.2 Multitasking and Process Levels

The NetWare OS uses non-preemptive thread scheduling for its multitasking environment. Non-preemptive thread scheduling provides greater system performance because it minimizes context switches, and it eliminates the need for semaphore-based locking and unlocking code.

Ideally, to maintain system performance, all NLM application threads should be designed to quickly perform their respective operations and then return the thread of execution back to the ring process. However, some NLM applications may have code sections where a process must wait a significant number of CPU cycles to complete. An example of this kind of situation is when a device driver communicates with host adapter hardware to determine what devices are attached to its bus. This task could take several hundred milliseconds. Situations like this impact server performance because the current thread hoards CPU time, and other scheduled threads and critical background OS processes do not get the opportunity to run.

NetWare provides a mechanism to minimize such impacts on server performance by allowing an NLM application to designate a process level for each thread it wants scheduled. Likewise, process levels are assigned to OS routines and other routines in NWPA architecture. Drivers must comply with the execution levels provided by the OS and not violate their defined environments.

These process levels are defined in the following subsections:

Blocking

The blocking process level is defined as an execution level that is permitted to temporarily block or suspend its thread of execution by calling an NWPA routine that suspends the process execution until the specified function is completed. At this level the code executes as the operating system's currently scheduled process. Routines called from this level can call other blocking functions that can put the process and the associated thread of execution to sleep until completion.

This level represents the currently scheduled and executing task or process. Driver routines called at this level execute as an extension of the current executing process. Interrupts are normally enabled upon entry to routines.

It is often necessary for a driver to disable interrupts for a period of time during process-level routines to accomplish reentrance, call system functions, or to maintain driver integrity. Care should be taken to disable interrupts for the absolute minimum period required to accomplish necessary functions. Disabling interrupts for greater than 25 milliseconds causes server performance degradation and poor response.

Functions can execute for up to 250 milliseconds before returning to the OS or causing a task switch. If the function requires more than the above period, the driver should initiate a task switch by calling the appropriate NWPA function so that other NetWare processes can be serviced in a timely fashion. Failure to do so may cause the OS to indicate the driver's violation by displaying a message on the server console.

Non-Blocking

The non-blocking process level is defined as an execution level that is not permitted to temporarily block or suspend its thread of execution. At this level the code executes as the OS's currently scheduled process, and it is guaranteed to run to completion. Routines called from this level cannot make calls to routines at the blocking process level that puts the process and the associated thread of execution to sleep.

This level represents the currently scheduled and executing task or process. Driver routines called at this level also execute as an extension of the current executing process. Therefore, routines at this level can call other routines that are at the same level only.

Interrupt

Upon entry to this level, the current process is unknown and interrupts are disabled. Functions that execute at this level can call non-blocking routines only. Calling blocking routines that might put the process and the associated thread of execution to sleep is strictly prohibited. The only entry point at this level in NWPA is the HAM_ISR function.

HAM_ISR is a subfunction that is called by the Master Interrupt Handler in the OS. The Master Interrupt Handler is initiated by the system hardware when an interrupt occurs. It then determines and calls the appropriate subroutine. Upon return from the subroutine, the Master Interrupt Handler adjusts the system interrupt hardware, and the OS resumes execution of the current process.

HAM_ISR is responsible only for those interrupts that are unique to the host adapter(s) it is associated with. Because HAM_ISR is a subfunction, it should return to the calling program using a subfunction return. It must not execute for more than 250 milliseconds at a time, and during its execution, interrupts cannot be disabled for more than 25 milliseconds.

1.4.3 Hot Plug Capability

Hot Plug has the following requirements:

  • NEB.NLM must be loaded before NWPA.NLM is loaded.
  • HAMs must
  • Load the Hot Plug Monitor NLM applications.
  • Load the appropriate Hot Plug Controller Driver for the hardware platform being used.

This section covers the following subtopics:

Hot Plug Monitor NLM Applications

NWPA contains support for hot-pluggable adapters. This support consists of reporting an event when an adapter error occurs—CDMs return an adapter error code within an I/O message—and performing an instance unload for that adapter.

Hot plug capability usually requires custom NLM modules, known as a Hot Plug Monitor and Hot Plug Controller Driver, to be loaded. The Hot Plug Monitor NLM monitors status and give commands to perform the instance unloads as well as turning off power to the adapter being replaced. The Hot Plug Controller Driver is the driver that actually turns the power off to the slots and controls the indicator lights. This driver is vendor specific for the hot plug hardware.

Event Names must be unique and should be registered with Novell DeveloperNet® Labs.

The events to control this capability are sent and received through the Novell Event Bus. The NEB.NLM must be loaded to enable these capabilities. The Event Bus is used to implement the Hot Plug PCI APIs in this specification.

Currently, the following events are implemented within NWPA for this support:

General Process Flow for an Instance Unload

The following figure illustrates an instance unload flow:

Figure 1-3 Instance_Unload Flow

  1. A management NLM sends a HW.PhysicalDeviceUnload event to the event bus.
  2. This event is received by NWPA which consumes the event.
  3. A HACB request is built if the module supports a HAM_Instance_Unload (Function 0x09) HACB.
  4. That particular instance and associated resources are released by the HAM.
  5. NWPA returns a reply HW.PhysicalDeviceUnloadReply. Completion of an unload is detected by HAI_Activate_Bus when resources become unavailable, and when the HAM returns back from receiving the Unload_Instance_HACB.

Supported Event Bus APIs

Several Event Bus APIs are supported in NWPA to allow HAMs and CDMs to register with the Event Bus, such as the following: