Software:

• Window NT 4.0, Release 3 Operating System.
• Windows 2000 Operating System.
• Windows XP Operating System.

Hardware:

• x86 Computer with PCI or Compact PCI bus.
• PCIHSD2 board or cPCIHSD board.

Knowledge of the Encore HSDII IOCB structure will aid in using the respective board and software.

This driver is installed as a standard Windows NT4.0/2000/XP device driver. It can handle any number of PCIHSD2 or cPCIHSD boards configured for either HSD or IBL mode. The following system calls are supported:

• CreateFile
• CloseHandle
• DeviceIoControl

All access to the device is made through DeviceIoControl calls. Arguments to the DeviceIoControl call provide for reading and writing data, for setting the device operation mode, for reading status, for resetting the PCIHSD, and for varying device timeout on input/output operations.

The driver is registered in Windows NT/2000/XP as both a device and an event-logging driver. The driver can service any number of devices and can operate in a multi-processor environment.

The driver logs events at the time it loads or unloads. Any error that occurs during loading that prevents the driver from remaining loaded is also logged. These events can be viewed using the Event Viewer provided with Windows NT or 2000.

The device name for a PCIHSD device is as follows:

\\.\PCIHSDn

where 'n' is a digit starting with 0 (zero) for the first device and incrementing by one for each additional device in the system.

The driver provides three protocols for initiating a link for data transfers in the InterBus Link (IBL) configuration. The desired mode is specified in the variable passed to the DeviceIoControl system call to Set PCIHSD Operating Mode. If PCIHM_LREQ is specified, the PCIHSD will initiate the link request for all transfers. If PCIHM_LACK is specified, the PCIHSD does not initiate any link request, but expects to wait for, and acknowledge a link request before each data transfer. A third option uses the protocol of the Encore H.IBLG handler under MPX and initiates the link request when the operation is a Write or waits for and acknowledges a link request when the operation is a Read. This method is specified by PCIHM_LIBLG.

The header files, pcihsd.h and pcihsdioctl.h, contain the definitions of symbols used with the DeviceIoControl system call to perform various HSD functions, as well as declarations for data structures used with those calls.

The standard CreateDevice function is called to associate a device handle with the desired PCIHSD device. For example, the most likely parameters to create the PCIHSD device is:

TCHAR csDeviceName[ ] = "\\\\.\\PCIHSD0";
DWORD dwAccess = GENERIC_READ|GENERIC_WRITE;
DWORD dwShareMode = 0;
DWORD dwCreationDisp = OPEN_EXISTING;
DWORD dwFlags = FILE_ATTRIBUTE_NORMAL;
HANDLE hPciHsd;

hPciHsd = CreateFile( csDeviceName,

dwAccess,
dwShareMode,
NULL, // security attributes
dwCreationDisp,
dwFlags,
NULL // template file handle

);

It is possible to perform asynchronous operations on the PCIHSD device by specifying the FILE_FLAG_OVERLAPPED flag as part of the dwFlags parameter.

When the device is created, the PCIHSD is reset and the driver sets a five-second timeout default for all I/O operations.

The standard CloseHandle function must be called to terminate access to the PCIHSD device. Any pending operations for the open device are cancelled and the associated memory areas released when the device is closed.

The DeviceIoControl call is used to perform all operations on the PCIHSD Device. The call requires the user to pass the file handle assigned to the device, a function code and input/output data specific to the function requested. The function may return a value of 0 (zero) indicating an error. The specific error may be retrieved with the function GetLastError and interpreted using the function FormatMessage.

The function codes are defined in the pcihsdioctl.h include file and special parameters are defined in the pcihsd.h include file.

Function Code: IOCTL_HSD_SET_MODE
Input Buffer: pointer to ULONG variable containing the new settings
Output Buffer: pointer to ULONG variable that receives the new configuration
Output Length: size of ULONG variable.

This function sets the current operating mode of the addressed PCIHSD from information found in the variable pointed to by the Input Buffer parameter. The data that can appear in the variable is defined in Section 3. If a value is not specified for a particular group, the current setting is retained. Finally, the new operating mode information is returned to the variable pointed to by the Output Buffer parameter.

Function Code: IOCTL_HSD_RESET
Input Buffer: pointer to ULONG variable specifying the type of reset
Input Length: size of ULONG variable

This call performs reset operations on the addressed PCIHSD. The variable pointed to by the Input Buffer parameter specifies the type of reset:

RESET_HSD: Reset HSD controller
RESET_FIFO: Reset FIFO's
RESET _BOTH: Reset FIFO's and HSD controller
RESET _DVC: Reset external device (IOReset)
RESET_TDV: Issue Terminate Device Signal to External Device
RESET _GEN: General reset (HSD/FIFO/External Device)

Function Code: IOCTL_HSD_GET_STATUS
Output Buffer: pointer to PCIHSD_STATUS structure
Output Length: size of PCIHSD_STATUS structure

This function stores into the structure, pointed to by the Output Buffer parameter, the current board status word and HSD sequencer state word.

Function Code: IOCTL_HSD_START
Input Buffer: pointer to an Encore type IOCB list array
Input Length: size of the input array
Output Buffer: pointer to an array that will receive the IOCB list after completed
Output Length: size of the output array

This function is used to present a list of IOCBs that perform the operation desired by the user. The user must be familiar with the Encore IOCB design and IOCB fields. The IOCB structure is defined in the include file, pcihsdioctl.h.

The IOCB list can be made up of all the commands permitted by the HSD except for a Transfer In Channel (TIC) command. The IOCBs are linked together by either the Command Chain bit or the Data Chain bit as required. The driver processes the entire list, transforming the IOCBs into appropriate PCIHSD descriptors to execute the operation. Since data is moved directly to or from the user's data arrays, those areas of the user's memory are locked into physical memory for the duration of the call.

The Output Array is optional. The only time it is necessary is for those IOCB lists that contain a Device Status Request IOCB. In this case, the device status and residual count is stored in the fourth word of the IOCB. The user must provide an area for the system to return the list to get the device status information.

Function Code: IOCTL_HSD_TERMINATE

This function causes any current Input/Output operation to cease.

Function Code: IOCTL_HSD_SET_TIMEOUT
Input Buffer: pointer to LONG variable containing the interval timeout value
Input Length: size of LONG variable
Output Buffer: pointer to LONG variable receiving the previous timeout value
Output Length: size of LONG variable

This function assumes the value pointed to by the Input Buffer is in units of seconds and is capable of specifying a long timeout on data transfers through the PCIHSD.

Note: a fast timeout value takes precedence over a slow timeout value. The fast timeout value must be reset to zero for the slow timeout value to be used.

Function Code: IOCTL_HSD_SET_FAST_TIMEOUT
Input Buffer: pointer to LONG variable containing the interval timeout value
Input Length: size of LONG variable
Output Buffer: pointer to LONG variable receiving the previous timeout value
Output Length: size of LONG variable

This function assumes the value pointed to by the Input Buffer is in units of milliseconds and is capable of specifying a short timeout on data transfers through the PCIHSD. To cancel a fast timeout, the value of the fast timeout must be set to zero. See note above.

Function Code: IOCTL_HSD_TIMEOUT_CONTROL
Input Buffer: pointer to a PCIHSD_TIMECTRL structure with new values
Input Length: size of PCIHSD_TIMECTRL variable
Output Buffer: pointer to PCIHSD_TIMECTRL structure for the old values
Output Length: size of PCIHSD_TIMECTRL variable

This function is the preferred method of setting timeout values to govern Input/Output operations. With this function, the timeout method used by the driver is set to correspond to the units of the time value. If the time value is in milliseconds, then the driver employs a high-speed timer and timeouts can be as short as 20 milliseconds. If the time value is in seconds, then the driver employs a low-speed timer with the minimum timeout being one second. See the description of the PCIHSD_TIMECTRL structure in Section 3 for information on the contents of the structure.

This section describes the data structures and variables used with the DeviceIoControl function calls to perform I/O operations with the PCIHSD. Data structures and data constants are defined in the file pcihsd.h.

Refer to the respective Encore MPX-32 Operating System Reference and Technical software manuals for a detailed description of the software requirements for the IOCB structure and the HSDII board operation. For a comprehensive hardware description of the Encore HSDII compatible card refer to:

• Encore HSDII Technical Manual, Document # 303-329131-000
• Encore MPX-32 Volume 2, Reference Manual, Document #323-001011-300

Refer to the following documents for assistance programming the PCIHSD card:

• ADS PCIHSD Technical Manual, Document # 0900098
• ADS PCIHSD2 Technical Manual, Document # 0900117
• ADS cPCIHSD Technical Manual, Document # 0900122

The variable passed in the Set Mode DeviceIoControl function contains the following groups of items:

Op Mode:

• Board operating mode code containing one of the following defined values:
• PCIM_HSD operating as HSD
• PCIM_IBL operating as IBL

Connect:

• Board connector configuration code containing one of the following defined values:
• PCIM_CNRM Normal (HSD) connectors
• PCIM_CREV Reverse (IBL) connectors

Note: on an IBL link, certain signals must be transposed from one HSD device to the other. This is accomplished by either 1) using a cable with the appropriate wires interchanged and normal connectors on both HSD's or 2) using a straight-through cable and setting one of the HSD devices in a Reverse connector configuration.

Byte Swap:

• Data swap option containing one of the following defined values:
• PCIM_BSWAP Swap bytes/words
• PCIM_NSWAP No swap

Note: byte swapping is dependent on the type of processor running Windows NT. For those systems running on an Intel x86 processor, select PCIM_NSWAP for this option.

Link type:

• IBL link request mode containing a code specifying the desired IBL link protocol.
• PCIM_LREQ Always request IBL link when initiating a transfer.
• PCIM_LACK Never request IBL link when initiating transfer.
• PCIM_LIBLG Use link protocol of the Encore H.IBLG handler for MPX. (Request link if writing, don't request if reading.)

Link prior:

• IBL link request priority containing a code specifying the hardware link priority desired.
• PCIM_HIPRI Set high link priority.
• PCIM_LOPRI Set low link priority.

The PCIHSD_STATUS structure is used with the Get Status DeviceIoControl call to return PCIHSD status. This structure contains the following information (all are unsigned 32-bit words):

ulBoardStatus: Current PCIHSD status.

ulState: Current HSD emulation sequencer state word.

The PCIHSD_TIMECTRL structure is used with the Time Control DeviceIoControl call to set time out values. This structure contains the following information:

lTimeValue: A signed long integer that holds the desired time out value.

bTimeValueInMSecs: A boolean value that when set TRUE, lTimeValue is interpreted in milliseconds. When set FALSE, lTimeValue is interpreted in

Status returns from the system calls used to access the PCIHSD driver are consistent with other Windows NT/ 2000/XP device drivers.

In case of an error, the DeviceIoControl system function called will return 0 (zero) and the function GetLastError can be called to get the error code. The error codes returned are standard Windows NT/2000/XP error codes and can be translated into messages using the FormatMessage function.

The PCIHSD device driver is distributed on a CDROM floppy and contains the following components:

• Device driver code: Part Number 0950110
• Test HSD example code

• PCIHSD.sys PCIHSD Device Driver.
• pcihsd.h Include file that defines structures and constants for programming.
• pcihsdioctl.h Include file that defines DeviceIoControl function calls and IOCB structure for programming.
• pcihsd.reg PCIHSD registration file containing the proper entries for the Registry.
• install.bat Batch file for completing NT 4.0 installation.
• Pcihsd.inf Driver information file for Windows 2000.

The files, found in the testhsd folder, comprise a complete C++ project which when compiled creates a program for testing the PCIHSD using Applied Data Sciences' HSD Analyzer/Tester. The project is included as an example of PCIHSD programming.

Log on Windows NT as "Administrator" or as any user that has access rights for modifying the NT Registery.
Start Windows Explorer and locate the pcihsd directory on the diskette. Double click on the install.bat file to install the PCIHSD Device Driver. This action causes,

1. the PCIHSD.sys file to be copied to the \winnt\system32\drivers folder.
2. regedit is executed specifying pcihsd.reg as a parameter to properly register the driver with Windows NT and inform Windows NT that the driver is an event logging process

Reboot the computer.

The installation process registers the driver with Windows NT as a manual loading device driver. This is intended as a precaution to ensure that the driver will load properly and not cause the Windows NT system any undue grief. Assuming the PCIHSD board has been physically installed in the desired computer system, load the driver through the following steps.

1. From the Windows NT Start menu, select Settings.
2. From Settings, select Control Panel.
3. From Control Panel, select Devices.
4. In the Devices window, scroll down to the PCIHSD entry. The PCIHSD entry should show no current Status and Startup should be set to Manual.
5. Select the PCIHSD entry and click the Start button. The system will now attempt to start the PCIHSD device driver. If it starts properly, the Status for the entry will change to Started. If it does not start properly, use the Event Viewer to examine the Event Log for the reason why the driver failed to load. Correct the problem and retry starting the driver.
6. Once the driver loads properly, in the Devices window select the PCIHSD entry and click the Startup button. Select the type of start up desired (most likely Automatic) since the driver is not required for proper system operation.

To view the PDF formatted example programs, please download the printable version.