IpQuart-485-DSP1dyneng.com/ip_quart_485_dsp1_wdm_man_a.pdf · The IP-QuadUART-485-DSP1 driver, is a Win32 driver model (WDM) device driver for the IP-QuadUART-485-DSP1 board from

DYNAMIC ENGINEERING435 Park Dr., Ben Lomond, Calif. 95005831-336-8891 Fax 831-336-3840

http://[email protected]

Est. 1988

IpQuart-485-DSP1Driver Documentation

Win32 Driver Model

Revision ACorresponding Hardware: Revision B

10-2002-1702Corresponding Firmware: Revision A

Page 2 Electronics Design • Manufacturing Services

IpDSP1WDM Device Driver for theIP-QuadUART-485-DSP1 IP Module

Dynamic Engineering435 Park DriveBen Lomond, CA 95005831- 336-8891831-336-3840 FAX

This document contains information of proprietary interest toDynamic Engineering. It has been supplied in confidence andthe recipient, by accepting this material, agrees that thesubject matter will not be copied or reproduced, in whole orin part, nor its contents revealed in any manner or to anyperson except to meet the purpose for which it wasdelivered.

Dynamic Engineering has made every effort to ensure thatthis manual is accurate and complete. Still, the companyreserves the right to make improvements or changes in theproduct described in this document at any time and withoutnotice. Furthermore, Dynamic Engineering assumes noliability arising out of the application or use of the devicedescribed herein.

The electronic equipment described herein generates, uses,and can radiate radio frequency energy. Operation of thisequipment in a residential area is likely to cause radiointerference, in which case the user, at his own expense, willbe required to take whatever measures may be required tocorrect the interference.

Dynamic Engineering’s products are not authorized for useas critical components in life support devices or systemswithout the express written approval of the president ofDynamic Engineering.

This product has been designed to operate with IP Modulecarriers and compatible user-provided equipment.Connection of incompatible hardware is likely to causeserious damage.

©2005 by Dynamic Engineering.

Trademarks and registered trademarks are owned by theirrespective manufactures.Manual Revision A. Revised January 31, 2006.


Table of Contents

Introduct ion 5

Note 5

Driver Installation 5

Windows 2000 Installation 5

Windows XP Installation 6

Driver Startup 7

IO Controls 10IOCTL_IPDSP1_GET_INFO 10IOCTL_IPDSP1_SET_IP_CONTROL 10IOCTL_IPDSP1_GET_IP_CONTROL 10IOCTL_IPDSP1_SET_TIMER_CONFIG 10IOCTL_IPDSP1_READ_TIME_COUNT 11IOCTL_IPDSP1_RESET_CHAN_FIFOS 11IOCTL_IPDSP1_SET_CHAN_CONFIG 11IOCTL_IPDSP1_GET_CHAN_CONFIG 11IOCTL_IPDSP1_WRITE_CHAN_DATA 11IOCTL_IPDSP1_READ_CHAN_DATA 11IOCTL_IPDSP1_WRITE_TEST_DATA 11IOCTL_IPDSP1_READ_TEST_DATA 12IOCTL_IPDSP1_GET_CHAN_STATUS 12IOCTL_IPDSP1_SET_RX_AFL_LEVEL 12IOCTL_IPDSP1_GET_RX_AFL_LEVEL 12IOCTL_IPDSP1_REGISTER_EVENT 12IOCTL_IPDSP1_ENABLE_INTERRUPT 13IOCTL_IPDSP1_DISABLE_INTERRUPT 13IOCTL_IPDSP1_FORCE_INTERRUPT 13IOCTL_IPDSP1_SET_VECTOR 13IOCTL_IPDSP1_GET_VECTOR 13IOCTL_IPDSP1_GET_ISR_STATUS 13

Write Error! Bookmark not defined.

Read Error! Bookmark not defined.

WARRANTY AND REPAIR 14


Service Policy 14Out of Warranty Repairs 14

For Service Contact: 14


IntroductionThe IP-QuadUART-485-DSP1 driver, is a Win32 driver model (WDM) devicedriver for the IP-QuadUART-485-DSP1 board from Dynamic Engineering.Each IP-QuadUART-485-DSP1 board has differential clock and data out,differential clock and data in. There is a single ended monitor and strobe,used to manage data transfers. A separate Device Object controls eachIP-QuadUART-485-DSP1 board, and a separate handle references eachDevice Object. IO Control calls (IOCTLs) are used to configure the boardand ReadFile and WriteFile calls are used to move data in and out of theFIFO channel data buffers.

NoteThis documentation will provide information about all calls made to thedriver, and how the driver interacts with the hardware for each of thesecalls. For more detailed information on the hardware implementation, referto the IP-QuadUART-485-DSP1 device user manual (also referred to as thehardware manual).

Driver InstallationWarning: The appropriate IP carrier driver must be installed before any IPmodules can be detected by the system.

There are several files provided in each driver package. These files includeIpDsp1.sys, IpDevice.inf, DDIpDsp1.h, IpDsp1GUID.h, IpDsp1Def.h,IPDsp1Test.exe, and IPDsp1Test source files.

Windows 2000 InstallationCopy IpDevice.inf and IpDsp1.sys to a floppy disk, or CD if preferred.

With the hardware installed, power-on the PCI host computer and wait forthe Found New Hardware Wizard dialogue window to appear.• Select Next.• Select Search for a suitable driver for my device.• Select Next.• Insert the disk prepared above in the desired drive.• Select the appropriate drive e.g. Floppy disk drives.• Select Next.• The wizard should find the IpDevice.inf file.• Select Next.• Select Finish to close the Found New Hardware Wizard.


Windows XP InstallationCopy IpDevice.inf to the WINDOWS\INF folder and copy IpDsp1.sys to afloppy disk, or CD if preferred. Right click on the IpDevice.inf file icon in theWINDOWS\INF folder and select Install from the pop-up menu. This willcreate a precompiled information file (.pnf) in the same directory.

With the hardware installed, power-on the PCI host computer and wait forthe Found New Hardware Wizard dialogue window to appear. The IP -QuadUART–485-DSP1, should be named in the dialogue box. Follow thesteps below:• Insert the disk prepared above in the appropriate drive.• Select Install from a list or specific location• Select Next• Select Don’t search. I will choose the driver to install• Select Next• Select Show all devices from the list• Select Next• Select Dynamic Engineering from the Manufacturer list• Select IPQuaduart-485-DSP1 Device from the Model list• Select Next• Select Yes on the Update Driver Warning dialogue box.• Enter the drive e.g. A:\ in the Files Needed dialogue box.• Select OK.• Select Finish to close the Found New Hardware Wizard.This process must be completed for each new device that is installed.

The DDIpDsp1.h file is the C header file that defines the ApplicationProgram Interface (API) to the driver. The IpDsp1GUID.h file is a C headerfile that defines the device interface identifier for the IP-Quart-485-DSP1.These files are required at compile time by any application that wishes tointerface with the IpDsp1 driver. The IpDsp1Def.h file contains the relevantbit defines for the IP-QuadUART-485-DSP1 registers. These files are notneeded for driver installation.

The IPDsp1Test.exe file is a sample Win32 console application that makescalls into the IpQuart-485-DSP1 driver to test the driver calls withoutactually writing an application. It is not required during the driverinstallation. Open a command prompt console window and typeIPDsp1Test -d0 -? to display a list of commands (the IPDsp1Test.exe filemust be in the directory that the window is referencing). The commandsare all of the form IPDsp1Test -dn -im where n and m are the devicenumber and driver ioctl number respectively. This application is intended totest the proper functioning of the driver calls, not for normal hardwareoperation.


Driver StartupOnce the driver has been installed it will start automatically when thesystem recognizes the hardware.

A handle can be opened to a specific board by using the CreateFile()function call and passing in the device name obtained from the system.

The interface to the device is identified using a globally unique identifier(GUID), which is defined in IpDsp1GUID.h.

Below is example code for opening a handle for device N, where N is theinstance number of the device (starting with 0). The device number isunderlined and italicized in the SetupDiEnumDeviceInterfaces call.

// The maximum length of the device name for// a given instance of an interface#define MAX_DEVICE_NAME 256// Handle to the device objectHANDLE hIpDsp1 = INVALID_HANDLE_VALUE;// Return status from commandLONG status;// Handle to device interface information structureHDEVINFO hDeviceInfo;// The actual symbolic link name to use in the createfileCHAR deviceName[MAX_DEVICE_NAME];// Size of buffer required to get the symbolic link nameDWORD requiredSize;// Interface data structures for this deviceSP_DEVICE_INTERFACE_DATA interfaceData;PSP_DEVICE_INTERFACE_DETAIL_DATA pDeviceDetail;

hDeviceInfo = SetupDiGetClassDevs((LPGUID)&GUID_DEVINTERFACE_IPDsp1, NULL, NULL, DIGCF_PRESENT |DIGCF_DEVICEINTERFACE);

if(hDeviceInfo == INVALID_HANDLE_VALUE){ printf("**Error: couldn't get class info, (%d)\n", GetLastError()); exit(-1);}

interfaceData.cbSize = sizeof(interfaceData);

// Find the interface for device N if(!SetupDiEnumDeviceInterfaces(hDeviceInfo, NULL, (LPGUID)&GUID_DEVINTERFACE_IPDsp1, N ,


&interfaceData)){ status = GetLastError(); if(status == ERROR_NO_MORE_ITEMS) { printf("**Error: couldn't find device(no more items), (%d)\n",N ); SetupDiDestroyDeviceInfoList(hDeviceInfo); exit(-1); } else { printf("**Error: couldn't enum device, (%d)\n", status); SetupDiDestroyDeviceInfoList(hDeviceInfo); exit(-1); }}

// Get the details data to obtain the symbolic link nameif(!SetupDiGetDeviceInterfaceDetail(hDeviceInfo, &interfaceData, NULL, 0, &requiredSize, NULL)){ if(GetLastError() != ERROR_INSUFFICIENT_BUFFER) { printf("**Error: couldn't get interface detail, (%d)\n", GetLastError()); SetupDiDestroyDeviceInfoList(hDeviceInfo); exit(-1); }}

// Allocate a buffer to get detailpDeviceDetail = (PSP_DEVICE_INTERFACE_DETAIL_DATA)malloc(requiredSize);if(pDeviceDetail == NULL){ printf("**Error: couldn't allocate interface detail\n"); SetupDiDestroyDeviceInfoList(hDeviceInfo); exit(-1);}pDeviceDetail->cbSize = sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA);

// Get the detail infoif(!SetupDiGetDeviceInterfaceDetail(hDeviceInfo, &interfaceData, pDeviceDetail, requiredSize, NULL, NULL)){


printf("**Error: couldn't get interface detail(2), (%d)\n", GetLastError()); SetupDiDestroyDeviceInfoList(hDeviceInfo); free(pDeviceDetail); exit(-1);}// Save the namelstrcpyn(deviceName, pDeviceDetail->DevicePath, MAX_DEVICE_NAME);

// Cleanup searchfree(pDeviceDetail);SetupDiDestroyDeviceInfoList(hDeviceInfo);

// Open driver and Create the handle to the devicehIpDSP1 = CreateFile(deviceName, GENERIC_READ | GENERIC_WRITE, FILE_SHARE_READ | FILE_SHARE_WRITE, NULL, OPEN_EXISTING, NULL, NULL);

if(hIpDSP1 == INVALID_HANDLE_VALUE){ printf("**Error: couldn't open %s, (%d)\n", deviceName, GetLastError()); exit(-1);}


IO ControlsThe driver uses IO Control calls (IOCTLs) to configure the device. IOCTLsrefer to a single Device Object in the driver, which controls a single board.IOCTLs are called using the Win32 function DeviceIoControl(), and passingin the handle to the device opened with CreateFile(). IOCTLs generally haveinput parameters, output parameters, or both. Often a custom structureis used (defined in DDIpDsp1.h).

IOCTL_IPDSP1_GET_INFOFunction: Returns the current driver version, instance number.Input: NoneOutput: DRIVER_IPDSP1_DEVICE_INFO structureNotes: This call does not access the hardware, only driver parameters.See DDIpDsp1.h for the definition of DRIVER_IPDSP1_DEVICE_INFO.

IOCTL_IPDSP1_SET_IP_CONTROLFunction: Sets the configuration of the IP slot.Input: Register configuration (unsigned long integer)Output: NoneNotes: Controls the IP clock speed and interrupt enables for the IP slotthat the board occupies. See the bit definitions in the IpDsp1Def.h headerfile for more information.

IOCTL_IPDSP1_GET_IP_CONTROLFunction: Returns the configuration of the IP slot.Input: NoneOutput: Register configuration (unsigned long integer)Notes: Returns the values set in the previous call.

IOCTL_IPDSP1_SET_TIMER_CONFIGFunction: Sets timer configuration.Input: IPDSP_TIMER_CONFIG structureOutput: NoneNotes: Control clearing timer, and enabling the timer. See DDIpDsp1.hfor the definition of IPDSP1_ CONFIG structure and IpDsp1Def.h for bitdefinitions.


IOCTL_IPDSP1_READ_TIME_COUNTFunction: Returns the time count value.Input: NoneOutput: unsigned long intNotes: Returns the 32-bit, time count value.

IOCTL_IPDSP1_RESET_CHAN_FIFOSFunction: Resets either one or both FIFO’s.Input: FIFO_SELECTOutput: NoneNotes: Resets either one or both FIFO’s specified FIFO_SELECT register.See DDIpDsp1.h header file for more information.

IOCTL_IPDSP1_SET_CHAN_CONFIGFunction: Sets control configuration for FIFO.Input: IPDSP1_CHAN_DATA structureOutput: NoneNotes: See DDIpDsp1.h for more information on the IPDSP1_CHAN_DATAstructure.

IOCTL_IPDSP1_GET_CHAN_CONFIGFunction: Returns FIFO control configuration.Input: unsigned charOutput: unsigned shortNotes: Returns stored data from selected channel.

IOCTL_IPDSP1_WRITE_CHAN_DATAFunction: Write a 16-bit word to Rx FIFO.Input: IPDSP1_CHAN_DATA structureOutput: NoneNotes: Rx FIFO write is used for test. See DDIpDsp1.h for moreinformation on the IPDSP1_CHAN_DATA structure.

IOCTL_IPDSP1_READ_CHAN_DATAFunction: Reads a 16-bit from Rx FIFO.Input: unsigned charOutput: unsigned shortNotes: Reads data stored from selected Rx FIFO. See IpDsp1Def.hheader file for more details on FIFO channel bit definitions.

IOCTL_IPDSP1_WRITE_TEST_DATAFunction: Write a 16-bit Tx FIFO word.Input: IPDSP1_CHAN_DATA structure


Output: NoneNotes: See DDIpDsp1.h for more information on the IPDSP1_CHAN_DATAstructure.

IOCTL_IPDSP1_READ_TEST_DATAFunction: Read a 16-bit Tx FIFO.Input: unsigned charOutput: unsigned shortNotes: Read 16-bit word from Tx FIFO. Used for FIFO testing

IOCTL_IPDSP1_GET_CHAN_STATUSFunction: Returns status of selected FIFO channel.Input: unsigned charOutput: unsigned shortNotes: See IpDsp1Def.h header file for more details on FIFO channel bitdefinitions.

IOCTL_IPDSP1_SET_RX_AFL_LEVELFunction: Write to register, to set, when, the receive FIFO almost fullstatus is asserted.Input: IPDSP1_CHAN_DATAOutput: NoneNotes: See DDIpDsp1.h for more information on the IPDSP1_CHAN_DATAstructure.

IOCTL_IPDSP1_GET_RX_AFL_LEVELFunction: Returns almost full status of selected channel.Input: unsigned charOutput: unsigned shortNotes: See IpDsp1Def.h header file for more details on FIFO channel bitdefinitions.

IOCTL_IPDSP1_REGISTER_EVENTFunction: Registers an event to be signaled when an interrupt occurs.Input: Handle to Event objectOutput: NoneNotes: The caller creates an event with CreateEvent() and supplies thehandle returned from that call as the input to this IOCTL. The driver thenobtains a system pointer to the event and signals the event when aninterrupt is serviced. The user interrupt service routine waits on thisevent, allowing it to respond to the interrupt. In order to un-register theevent, set the event handle to NULL while making this call.


IOCTL_IPDSP1_ENABLE_INTERRUPTFunction: Set master interrupt enable.Input: NoneOutput: NoneNotes: Enabling master interrupt, enables COS and I/O interrupts.

IOCTL_IPDSP1_DISABLE_INTERRUPTFunction: Disable Dsp1 interrupts.Input: NoneOutput: NoneNotes: I/O interrupt (Data transfer complete) and COS interrupt (TTL bitchanges) are ignored.

IOCTL_IPDSP1_FORCE_INTERRUPTFunction: Force interrupt to occur if master interrupt is enabled.Input: NoneOutput: NoneNotes: Used for hardware or software development

IOCTL_IPDSP1_SET_VECTORFunction: Set the interrupt vector value.Input: unsigned characterOutput: NoneNotes: Write 8 bit vector value.

IOCTL_IPDSP1_GET_VECTORFunction: Returns the interrupt vector value.Input: NoneOutput: unsigned characterNotes: Returns the values set in the previous call.

IOCTL_IPDSP1_GET_ISR_STATUSFunction: Returns the interrupt status, vector values, and state of COSbits.Input: NoneOutput: IPDSP1_INT_STAT structureNotes: The status contains the contents of the IPDSP1_INT_STAT registerread in the last driver interrupt service routine execution. See DDIpDsp1.hfor the definition of IPDSP1_INT_STAT.


Warranty and RepairDynamic Engineering warrants this product to be free from defects undernormal use and service and in its original, unmodified condition, for a periodof one year from the time of purchase. If the product is found to bedefective within the terms of this warranty, Dynamic Engineering's soleresponsibility shall be to repair, or at Dynamic Engineering's sole option toreplace, the defective product.

Dynamic Engineering's warranty of and liability for defective products islimited to that set forth herein. Dynamic Engineering disclaims and excludesall other product warranties and product liability, expressed or implied,including but not limited to any implied warranties of merchandisability orfitness for a particular purpose or use, liability for negligence inmanufacture or shipment of product, liability for injury to persons orproperty, or for any incidental or consequential damages.

Dynamic Engineering’s products are not authorized for use as criticalcomponents in life support devices or systems without the express writtenapproval of the president of Dynamic Engineering.

Service PolicyBefore returning a product for repair, verify as well as possible that thedriver is at fault. The driver has gone through extensive testing and in mostcases it will be “cockpit error” rather than an error with the driver. Whenyou are sure or at least willing to pay to have someone help then call theCustomer Service Department and arrange to speak with an engineer. Wewill work with you to determine the cause of the issue. If the issue is one ofa defective driver we will correct the problem and provide an updatedmodule(s) to you [no cost]. If the issue is of the customer’s making[anything that is not the driver] the engineering time will be invoiced to thecustomer. Pre-approval may be required in some cases depending on thecustomer’s invoicing policy.

Out of Warranty RepairsOut of warranty support will be billed. The current minimum repair chargeis $125. An open PO will be required.

For Service Contact:Customer Service DepartmentDynamic Engineering435 Park Dr.Ben Lomond, CA 95005831-336-8891831-336-3840 fax


[email protected]

All information provided is Copyright Dynamic Engineering

Documents

IpQuart-485-DSP1dyneng.com/ip_quart_485_dsp1_wdm_man_a.pdf · The IP-QuadUART-485-DSP1 driver, is a Win32 driver model (WDM) device driver for the IP-QuadUART-485-DSP1 board from