HAM_Scan_For_Devices (Function 0x01)
Mandatory function. Tells the HAM to scan (probe) for devices attached to a specified bus and build a list of detected devices on that bus.
For each device in its list, the HAM is expected to fill out an instance of a DeviceInfoStruct, which includes a HAM-generated, unique access handle (deviceHandle) to the device. The HAM will receive one scan request for each bus instance it registers using HAI_Activate_Bus.
The HACB indicating this function is received on a non-blocking thread. Because a bus scan could take milliseconds or even seconds to complete, the HAM should spawn (schedule) a separate, blocking thread to perform the physical scan. Blocking threads can be created using NPA_Spawn_Thread.
HAM_Scan_For_Devices must handle four different scan cases according to the parameters given in the HACB's host command block. NWPA classifies each scan case as either Case 0, Case 1, Case 2, or Case 3 corresponding to the value received in the parameter2 field of the host command block. Case 0 scans are issued by the OS, and Cases 1 - 3 scans are issued by CDMs.
These scan cases also tell the HAM whether to declare a device public or private. The Public vs. Private Devices section defines this concept in detail.
The objectives of each scan case are as follows:
|
Case |
Description |
|---|---|
|
Case 0: |
This scan case tells the HAM to perform a typical “scan for new devices” by probing all public target locations. These locations include unit number 0 (and any other unit numbers as specified under Case 2) of all target IDs on the specified bus. This scan case is issued by the OS, and an object for each device is created and added to the Media Manager's device database. The command “scan for new devices” is a NetWare command that can be issued from any .ncf file or at the command line by the user. The purpose of “scan for new devices” is to make storage devices attached to the server visible to the NetWare OS.) The term 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. |
|
Case 1: |
This scan case tells the HAM to probe a particular unit number on a particular target ID of the bus. If a device is detected, it is declared private, and information about the device is returned as defined by NWPA's DeviceInfoStruct. A device object is not created for the Media Manager's device database. This scan case is issued by a CDM allowing it to probe unit numbers other than zero of the specified target ID to detect additional devices that enhance the functionality of the unit number 0 device. An example would be a magazine, addressed at unit number 1, attached to a tape drive at unit number 0. |
|
Case 2: |
This scan case has the same function and purpose as the Case 1 scan except that the target device is declared public, and a device object is created and added to the Media Manager's device database. |
|
Case 3: |
This scan tells the HAM to discard the device object, associated with the specified unit number and target ID, from its device list. This scan case is issued by a CDM. |
The remaining subsections provide more details by describing the following:
The HAM does not decide the public/private attribute of a device. This decision is made either by the OS (Case 0) or a CDM (Cases 1 and 2) according to the scan case issued. The HAM declares a device public by clearing the Private_Public_Flag in the attributeFlags field of the device's DeviceInfoStruct. To declare a device private, the HAM sets the Private_Public_Flag. All devices detected by Case 0 and Case 2 scans should be declared public. All devices detected by a Case 1 scan should be declared private.
Following a Case 0 or Case 2 scan, the HAM's HAM_Return_Device_Info (Function 0x02) function gets called on the target bus, which reports the bus's device list to NWPA. For all public devices in the list, NWPA creates a corresponding device object and adds it into the Media Manager's device database. The Media Manager then makes these devices visible to the application layer. This is the criterion that defines a public device.
The criterion that defines a private device is that the device's Private_Public_Flag is set, and no corresponding object is added to the Media Manager's device database. Thus, the device is not visible to the application layer. NWPA makes private devices visible only to the CDM layer.
This subsection defines the HACB's host command block parameters associated with each scan case along with a paradigm description of the how the HAM should handle each case.
Field Values in Host Command Block
A Case 0 scan request is issued by the NetWare OS following a “scan for new devices” command issued either in a .ncf file or at the command line by a user.
When the HAM receives a Case 0 scan request, it is expected to do the following:
Any device object added to the device list through a Case 2 scan should also be probed and updated in any subsequent Case 0 scans.
An essential data member of the DeviceInfoStruct is the unique deviceHandle the HAM assigns to the device. This deviceHandle is the token that NWPA and CDMs will use to route HACB I/O requests, through the HAM, to a device.
Field Values in Host Command Block
Field Values in Main HACB
A Case 1 scan request is issued by a CDM, allowing it to inquire about the existence of a device on a specific target ID and unit number (other than unit number 0). The purpose of this scan case is to grant a CDM private access to a device attached to the target ID and unit number by providing the CDM with a deviceHandle.
When the HAM receives a Case 1 scan request it is expected to do the following:
If the HAM detects a device at this location and there is no corresponding object for this device already existing in the HAM's device list:
NOTE:An essential data member of theDeviceInfoStruct is the unique deviceHandle the HAM assigns to the device. This deviceHandle is the token that the CDM uses to route HACB I/O requests, through the HAM, to a device.
If the HAM detects a device at this location and a corresponding object for this device already exists in the HAM's device list and the value in the HACB's deviceHandle field matches a device handle assigned to an object in the HAM's device list:
If the HAM detects a device at this location and a corresponding object for this device already exists in the HAM's device list and the value in the HACB's deviceHandle field is equal to -1:
If the HAM does not detect a device at this location:
Field Values in Host Command Block
Field Values in Main HACB
A handle that maps to a private device already existing in the HAM's device list. The HAM returned this device handle to the calling CDM in a previous Case 1 scan request, thereby giving the CDM exclusive ownership of the private device. Because of device ownership, no execution restrictions apply to this request.
A Case 2 scan request is issued by a CDM, allowing it to inquire about the existence of a device on a specific target ID and unit number (other than unit number 0) and make the device public.
Any device object added to the device list through a Case 2 scan should also be probed and updated in any subsequent Case 0 scans.
IMPORTANT:This function is required to support user scan commands or the /LUN command line option. See LUNs.
When the HAM receives a Case 2 scan request it is expected to do the following:
If the HAM detects a device at this location and there is no corresponding object for this device already existing in the HAM's device list:
An essential data member of the DeviceInfoStruct is the unique deviceHandle the HAM assigns to the device. This deviceHandle is the token that the CDM uses to route HACB I/O requests, through the HAM, to a device.
If the HAM detects a device at this location and a corresponding object for this device already exists in the HAM's device list and the value in the HACB's deviceHandle field matches a device handle assigned to an object in the HAM's device list:
If the HAM detects a device at this location and a corresponding object for this device already exists in the HAM's device list and the value in the HACB's deviceHandle field is equal to -1:
If the HAM does not detect a device at this location:
IMPORTANT:If a device object exists in the HAM's device list, meaning that at one time a device did exist at the target ID and unit number but has now gone away, the HAM should remove the object from the list and free the memory using NPA_Return_Memory.
If the HAM does not detect a device at this location and it determines there are no more devices attached to the current target ID (parameter1):
Field Values in Host Command Block
Field Values in Main HACB
A handle that maps to a private device already existing in the HAM's device list. The HAM returned this device handle to the calling CDM in a previous Case 1 or Case 2 scan request, thereby giving the CDM exclusive ownership of the private device. Because of device ownership, no execution restrictions apply to this request.
A Case 3 scan request is issued by a CDM after it determines that a device object (found from a previous Case 1 or Case 2 scan request) is a phantom, or in other words, a reflection of the device at unit number 0. Its main purpose is to have the HAM remove the target object from its device list.
When the HAM receives a Case 3 scan request, it is expected to do the following:
If the target object does not exist, meaning a previous Case 1 or Case 2 scan request was never received for the target ID and unit number:
If the target object exists, but the value in the HACB's deviceHandle field is equal to -1:
If the target object exists and the value in the HACB's deviceHandle field matches the target object's device handle:
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.