Unit number is a generic term that refers to device subaddresses if they are defined by the host architecture. For example, in the SCSI architecture this number refers to the Logical Unit Number, or LUN.
The procedure discussed here applies only to SCSI. For a more detailed description and generic definition of unit number, refer to HAM_Scan_For_Devices (Function 0x01).
This sections covers the following topics:
In order for devices to be initially detected and recognized by the NetWare OS, an initial scan for new devices command must be issued either at the command line or in a .ncf file. When the OS receives this command, it causes NWPA to issue a scan message to all HAMs loaded on the server. For SCSI, the initial scan message tells each HAM to scan LUN 0, and only LUN 0, of all its target IDs.
There are three reasons why the OS limits its initial scan to LUN 0:
Under NWPA, the HAM is not expected to differentiate between real and phantom devices. This responsibility belongs to the CDM.
During the scan for new devices thread, NWPA iteratively calls the CDM's CDM_Inquiry routine for each device found on the SCSI bus that matches the device type the CDM registered for. As mentioned in Inquiring and Binding to a Device, CDM_Inquiry is the entry point where the CDM gets a chance to look at a device and determine if it will field I/O requests for the device by binding to it. However, given the OS's initial scan paradigm, the CDM only sees devices attached to LUN 0 of any given target ID.
To make it possible for devices at unit numbers other than zero to be detected and recognized, NWPA provides its own set of scan messages that the CDM can issue to the HAM.
These scan messages are in the form of hacbType = 0 requests. This indicates to the HAM that the HACB's union command area is defined by the host adapter command structure. The CDM then sets values in the HACB (particularly the fields of the host adapter command block) according to the scan case (or action) it wants the HAM to perform.
NWPA defines three scan cases. These cases are referred to numerically as either Case 1, Case 2, or Case 3, corresponding to the value the CDM sets in the parameter2 field of the host command block.
A public device is one that is visible to any CDM that registers with a matching device type. NWPA makes a public device visible to these CDMs by calling their respective CDM_Inquiry entry points, thus giving any one of them the opportunity to bind to the device. A public device has a corresponding object in NWPA's device database, and the Private_Public_Bit in the attributeFlags field of the device's DeviceInfoStruct is cleared. Because a corresponding object exists in NWPA's device database, a public device is also visible to applications. Any application can reserve a public device and issue control and I/O messages to it.
All unit number 0 devices detected in the initial scan for new devices command are public.
A private device is one that is visible only to the CDM that detected it through a specific target ID and unit number scan. This CDM has exclusive ownership of the device.
A private device does not have a corresponding object in NWPA's device database, and the Private_Public_Bit in the attributeFlags field of the device's DeviceInfoStruct is set. Because a corresponding object does not exist in NWPA's device database, a private device is invisible to applications.
The purpose of the private-device-feature is to allow a CDM to present a group of devices that enhance each other's functionality as a single device to NWPA. This prevents a competing CDM from stealing one of the devices from the group. A scenario where this feature might be useful is a magazine device, addressed at unit number 1, attached to a public tape drive at unit number 0. The CDM can present these devices as one device with both tape and magazine functionality.
The CDM provides the input values prior to issuing the scan request. After the request completes, the CDM reads the applicable outputs to interpret results to the HAM. The value in the HACB's hacbCompletion field is the key for determining if any additional outputs are valid.
This section covers the following topics:
INPUTS to HACB:
Field Values in Host Command Block:
The Target ID is equivalent to the value in the busID field of the DeviceInfoStruct associated with the current device. The current device is the one on which the current iteration of CDM_Inquiry is being called, and the DeviceInfo parameter points to the device's corresponding DeviceInfoStruct
Field Values in Main HACB:
OUTPUTS from HACB:
If Successful_Completion:
A Case 1 scan allows the CDM to do the following:
if (deviceHandle == -1):
if (deviceHandle == Existing handle to a device owned by the CDM):
deviceHandle == -1
The CDM issues this instance of a Case 1 scan during its CDM_Inquiry routine when it knows that the unit number 0 device on which the inquiry is being called supports additional devices at other unit numbers. In addition, a Case 1 scan indicates that the CDM wants to control these additional devices privately and present the group as a single device with extended functionality to NWPA. Because CDM_Inquiry is called on a blocking thread, the CDM can issue the request using CDI_Blocking_Execute_HACB.
If a device responds at the specified target ID and unit number, it is declared private and information about the device is returned in the HACB's data buffer. The structure of the return information is defined by NWPA's DeviceInfoStruct. This structure includes a deviceHandle that allows access to the device, and the bus-specific inquiry information about the device. (The inquiry information in specific to the bus interface. For SCSI, this information is identical to that returned by the standard INQUIRY command. For IDE-ATA, this information is identical to that returned by the IDENTIFY command.)
The CDM uses this return information to determine if the device is real or a phantom, and, if the device is real, to decide whether or not it wants to field I/O requests for the device. As a part to making this decision, the CDM can use the deviceHandle to issue non-destructive HACB requests to get additional information about the device. A non-destructive request is one that does not alter the current state of the device, such as a SCSI MODE SENSE command.
If the device is real and the CDM wants to field requests for the device, it remembers the device's deviceHandle. This is a private deviceHandle giving the CDM exclusive access to the device. No other CDM can have access to this device until the owner CDM relinquishes control by either issuing a Case 3 scan or by declaring the device public.
In order for a CDM to have access to a private device, it must first be bound to a public companion device on that same target ID. Otherwise, NWPA will not route I/O to the private device.
The CDM should bind to the public device on which its CDM_Inquiry routine was called, which is also the thread in which the CDM scanned and detected the private device.
If the CDM determines it does not want to field requests for the device or that the device is a phantom, it should issue a Case 3 scan to remove the device object from the HAM's device list.
deviceHandle == Existing Handle
The CDM can issue this instance of a Case 1 scan whenever it deems appropriate, as long as the CDM owns the target device through either a previous Case 1 scan (private case) or through a previous bind to the device (public case). A valid deviceHandle to the target device is what constitutes ownership. If the target device responds at the specified target ID and unit number, the same information generated from the scan request that first detected the device is returned in the HACB's data buffer. Additionally, if the device's status was originally public, it is changed to private.
Since the scan invokes an actual probe of the bus, the CDM should spawn a blocking thread (NPA_Spawn_Thread) to execute this instance of a Case 1 scan.
Whenever, the CDM issues a scan request that changes a device's status (public to private or private to public), it must follow up the scan with a call to CDI_Rescan_Bus. This call updates NWPA's device database.
INPUTS to HACB:
Field Values in Host Command Block:
Field Values in Main HACB:
OUTPUTS from HACB:
If Successful_Completion:
A Case 2 scan allows the CDM to do the following:
if (deviceHandle == -1):
if (deviceHandle == Existing handle to a device owned by the CDM):
deviceHandle == -1
The CDM issues this instance of a Case 2 scan during its CDM_Inquiry routine when it knows that the unit number 0 device on which the inquiry is being called supports additional devices at other unit numbers. In addition, a Case 2 scan indicates that the CDM wants to present these additional devices, singly, as public objects so that they can be controlled by an application. Because CDM_Inquiry is called on a blocking thread, the CDM can issue the request using CDI_Blocking_Execute_HACB.
If a device responds at the specified target ID and unit number, it is declared public and information about the device is returned in the HACB's data buffer. The structure of the return information is defined by NWPA's DeviceInfoStruct. This structure includes a deviceHandle that allows access to the device, and the bus-specific inquiry information about the device. (The inquiry information in specific to the bus interface. For SCSI, this information is identical to that returned by the standard INQUIRY command. For IDE-ATA, this information is identical to that returned by the IDENTIFY command.)
The CDM uses this return information to determine if the device is real or a phantom, and, if the device is real, to decide whether or not it wants to field I/O requests for the device. As a part to making this decision, the CDM can use the deviceHandle to issue non-destructive HACB requests to get additional information about the device. A non-destructive request is one that does not alter the current state of the device, such as a SCSI MODE SENSE command.
If the device is real and the CDM wants to field requests for the device, it will conclude the current iteration of its CDM_Inquiry routine with a call to CDI_Rescan_Bus. This call causes NWPA to create an object for the device and place the object in its device database, which is critical to making the device public.
Unlike the private device paradigm (Case 1 scan), the CDM must not take control of a public device during the same CDM_Inquiry thread in which it detected (via a Case 2 scan) the device. Instead, the CDM must wait until its CDM_Inquiry routine gets called again for that device, and officially bind to it using CDI_Bind_CDM_To_Object. At that time, the CDM sets up the I/O channel by remembering the device's deviceHandle. Adherence to this public-device-paradigm is essential, and it is a requirement for CDM certification.
For the CDM's CDM_Inquiry routine to be called on the new public device, the CDM must have registered for that device's device type.
If the CDM determines it does not want to field requests for the device or that the device is a phantom, it should issue a Case 3 scan to remove the device object from the HAM's device list.
deviceHandle == Existing Handle
The CDM can issue this instance of a Case 2 scan whenever it deems appropriate, as long as the CDM owns the target device through either a previous Case 1 scan (private case) or through a previous bind to the device (public case). A valid deviceHandle to the target device is what constitutes ownership. If the target device responds at the specified target ID and unit number, the same information generated from the scan request that first detected the device is returned in the HACB's data buffer. Additionally, if the device's status was originally private, it is changed to public. Since the scan invokes an actual probe of the bus, the CDM should spawn a blocking thread (NPA_Spawn_Thread) to execute this instance of a Case 2 scan.
Whenever, the CDM issues a scan request that changes a device's status (public to private or private to public), it must follow up the scan with a call to CDI_Rescan_Bus. This call updates NWPA's device database.
INPUTS from HACB:
Field Values in Host Command Block:
Field Values in Main HACB:
OUTPUTS to HACB:
A Case 3 scan request allows the CDM to remove the target device from the HAM's device list, and it causes the HAM to free any objects associated with the device. The purpose of a Case 3 scan is twofold: It allows the CDM to delete phantom devices from the HAM's device list; and, at unload time, it allows a CDM to relinquish private devices under the CDM's control.
Scan Completion Codes summarizes the scan completion codes described in the specific cases above. The table also includes additional error-completion codes common to all scan cases. These completion codes are posted to the HACB's hacbCompletion field.