D i g i l e n t P o r t C o m m u n i c a t i o n s P r o g r a m m e r s R e f e r e n c e M a n u a l
TM www.digilentinc
Revision: 06/03/05 215 E Main SuiteD | Pullman, WA 99163
(509) 334 6306 Voice and Fax
Introduction
The DPCUTIL Dynamic Link Library (DLL) provides an Applications Programming Interface (API), allowing Digilent system boards to communicate with applications software running under Microsoft Windows on a host computer.
When using DPCUTIL DLL a Digilent Communication Module is requred to create a communications channel between the host PC and a system board. Digilent currently provides communications modules supporting Ethernet, USB 2.0, and Serial RS-232 communication protocols.
The DPCUTIL API has functions for controlling and communicating with the scan chain of JTAG devices connected to a Digilent board. The DPCUTIL API can also send and recieve data to and fro
m the user logic configured into the gate array on a connected Digilent board.  The JTAG scan chain manipulation functions are primarily for configuration of the programmable logic devices in the scan chain.  The JTAG scan chain manipulation functions can also be used to access to the boundary scan registers in the device scan chain for loading of test vectors, the read back of test results, and other manipulations of the JTAG scan chain supported by the attached devices. The DPCUTIL data transfer functions require that the gate array configuration contain a parallel port interface compatible with the Digilent Parallel Interface Module specification and reference design, available on the Digilent web site, at www.digilentinc. This interface allows the user to define a set of addressable registers that can be accessed by the DPCUTIL data transfer API functions. The data transfer API functions allow for writing or reading a single register, writing or reading sets of registers, or reading or writing a stream of data into or out of a single register. The DPCUTIL DLL was created and compiled using the Microsoft C++ compiler in Visual Studio 6. The API is defined as a set of C callable functions, and can be used with programs written in either C or C++. It is also possible to write programs using Microsoft Visual BASIC to access the DPCUTIL API functions, but Digilent does not provide technical support for this use.
Overview
The Components
In order to use any of the DPCUTIL API functions, a program source module must include the following header files in this order: #include <windows.h>
#include “dpcdefs.h”
#include “dpcutil.h”
These header files should be placed in a directory visible to the compiler. The files should include a path for the development environment that causes the compiler to search the appropriate directory at compilation time.
The program must be linked with the dpcutil.lib library. This establishes the dynamic link references between the application program and the DPCUTIL dynamic link library. This library file should be placed in a directory visible to the linker and the linker library search path set in the development environment to cause the linker to search the appropriate directory at program link time.
The DPCUTIL Dynamic Link Library (dpcutil.dll) must be in a directory that is searched by the operating system at program run time. The DLL file should either be placed in the same directory as t
he application program, or in a directory that is listed on the operating system PATH environment variable. When a program is executed, the operating system will look for dynamic link libraries in the
directory where the program executable
resides or in any directory listed on the system PATH environment variable.
DPCUTIL API functions
Most DPCUTIL API calls are formed into
transactions.  These transactions are put into a queue and processed on a first-in-first-out
basis (FIFO).  A function can either return upon completion (blocking) or return immediately and be processed on another thread (non-blocking).  A transaction entered into the
queue is assigned a TRID (Transaction ID), a value used to distinguish between transactions.
DPCUTIL API functions that require an
established connection with a communications device must be passed a HIF (interface
reference group
handle) to specify the connection to use.  This handle is acquired by calling DpcOpenJtag  or DpcOpenData .
Most DPCUTIL API functions require a pointer to an error code of type ERC.  This variable will hold the error code for a completed transaction.
Most JTAG and Data Transfer functions have a pointer of type TRID as a parameter.  If this parameter is set to NULL, the function will block and not return until the transaction has completed.  Otherwise, if a non-null TRID pointer is sent, the function will return immediately and the transaction will be
processed on a different thread.  Since none of the data sent to DPCUTIL is copied, all data sent to a non-blocking API call must remain intact and unchanged until the transaction is complete.  Calling the DpcWaitForTransaction  function and sending it the TRID of a particular transaction will allow an application to wait for the completion of the transaction.  Sending a TRID of NULL to DpcWaitForTransaction will force a wait on all transactions in the queue.
Initializing DPCUTIL
Before any of the DPCUTIL API functions can be used, the DpcInit  function must be called.  If it returns false, an error occurred while attaching and initializing the DLL.  The
application must not call any other DPCUTIL API functions if DpcInit  returns false.
The Device Table
All communication modules accessed through DPCUTIL are kept in a table called the device table.  All details needed to connect to a device are stored in this table.  Each device in the table is assigned a name and DPCUTIL uses this name (and not the index) to access the device.  The device table can only be modified through a dialog box included in the DPCUTIL DLL.  Calling the DvmgStartConfigureDevices function will open this dialog box.
To get the total number of devices in the device table, call the DvmgGetDevCount function.  To get the name of a device with a given index, call the DvmgGetDevName function.  A device table always has a default device in it.  The index of this device can be obtained by calling DvmgGetDefaultDev.  If there are no devices in the device table, DvmgGetDefaultDev will return –1.
Using the DPCUTIL Data Transfer functions
The data transfer functions in DPCUTIL rely on the logic loaded into the FPGA.  This logic must reserve byte-sized registers used for reading and/or writing.  Through these registers, the DPCUTIL data transfer functions will communicate with the FPGA through a connected communications module.  As mentioned before, the data transfer functions allow for:
1.    a register be written to or read from
2. many registers can be written to or
read from as a single transaction.
3.    a stream of bytes to be sequentially
written to or read from a single
register
In this way, an application can communicate with an FPGA through DPCUTIL.  For a more detailed explanation of the interface between the FPGA and communications module, see Digilent Parallel Interface Module Reference Manual.Before using any data transfer functions, the application must connect to a communication device using DpcOpenData.  The first parameter is a pointer to an interface handle (hif).  I f the function returns successfully, this handle will be used to connect to the device in all proceeding data transfer calls.  The device is specified by its assigned name in the device table and passed as the second parameter in the DpcOpenData function.
After this API function is called, any of the data transfer functions can be used.  When finished, close the device using DpcCloseData.
About JTAG
Most logic memory devices are programmable.  Many chip manufacturers accomplish this by conforming these devices to a standard specified in IEEE 1149.1.  This is the Joint Test Action Group, or JTAG.  A device is said to be JTAG compliant if it contains a JTAG TAP controller and the following pins:  TDI, TDO, TMS, and TCK.
TDI inputs data into the JTAG TAP controller, and TDO provides outputs.  TMS is used to set the JTAG TAP controller to a specified state, and TCK is used to clock bits into and out of the JTAG TAP controller.  After being set to the proper state by TMS, bits are shifted into the TAP controller on TDI while bits are shifted out on TDO.  Any FPGA, CPLD, or PROM that is JTAG compliant can be erased, programmed, and verified using this standard.
The TDI and TDO pins of several JTAG devices can be connected together to form a chain.  This is called a JTAG scan chain.  In order to program a device in the JTAG scan chain, all other devices are first set to BYPASS, meaning that they are ignored and not to be configured.  Then a series of bits are shifted into the scan chain through TDI to configure the device.
For more information on JTAG functionality and programming, read the IEEE 1149.1
specification and Xilinx app notes on device programming.
Using the DPCUTIL JTAG functions
Before using any JTAG functions,
DpcOpenJtag  must be called to connect to a communication device.  The first parameter is a HANDLE pointer.  If the function returns successfully, this handle will be used to
connect to the device in all proceeding JTAG calls.  The device is specified by name and passed as the second parameter in the DpcOpenJtag function.
DpcEnableJtag  must be called directly after DpcOpenJtag .  This enables the driving of JTAG signals on the communication device.
After these two API functions are called, any of the JTAG functions can be used.  When
finished, disable the JTAG interface and close the device using DpcDisableJtag and DpcCloseJtag .
Multiple Instances of DPCUTIL (for Win32 applications)
More than one application can use the DPCUTIL.DLL at once.  This presents the possibility of the device table being changed leaving other instances with outdated information about it.  To remedy this, an application should register itself with the DpcStartNotify function.  Whenever a
modification is made to the device table, a registered application will be notified of the change via a message sent to the provided window handle.  The application can then
reload all needed information about the device table.  The following is a description of the
message parameters to the window procedure:
To stop notification messages, an application should call the DpcEndNotify  function.
Description of Data TypesTRID
16 bit data type that holds the ID of a transaction (used for non-blocking calls)
ERC
32 bit (signed) data type.  Holds error code for a finished transaction  TRT
32 bit (signed) data type.  Holds code for transaction type  STS
32 bit (signed) data type.  Holds code for transaction status
DVCT
32 bit (signed) data type.  Holds code for communications interface type. TRS
Structure that contains the following information about a transaction:
Typedef struct tagTRS  { TRT trt; /* transaction type */ TRID trid; /* transaction ID */
STS sts; /* status of transaction */
ERC erc; /* error code for transaction */ }TRS;
Description of API calls
API Startup/Cleanup calls
BOOL DpcInit(ERC * perc)
Parameters  perc  - pointer to store error code
Return Values
Returns true if DLL instance is properly initialized
Description
This function performs startup
initialization of the DLL.  It must be
called before any of the other API calls
can be used.
void DpcTerm()
Parameters
none
Return Values
none
Description
This function must be called to clean up
resources when the application is done
using the DLL.
API Transaction and Utility calls
BOOL DpcStartNotify (HWND hwnd, WORD idNotify, ERC *perc)
Parameters
hwnd - handle of window
that is to be sent notification messages
idNotify - message
identifier to be sent upon device table
change
perc - pointer to store
error code
Return Values
Returns true if successful.  Returns
false otherwise.
Description
Used to register a window handle for
being notified of device table changes.
When a change (deletion, addition, or
modification) occurs in the device table,
all registered windows are sent their
specified messages.
BOOL DpcEndNotify (HWND hwnd, ERC
*perc)
Parameters
hwnd - handle of window
that is to no longer be sent notification
messages
perc - pointer to store
error code
Return Values
Returns true if successful.  Returns
false otherwise.
Description
De-registers a specified window handle
from being notified of device table
changes
BOOL DpcPendingTransactions(HANDLE hif, int * pctran, ERC *perc)
Parameters
hif - handle to JTAG
interface
pctran - pointer to store
number of pending transactions
perc - pointer to store
error code
Return Values
Returns true if any non-blocking
transactions are pending.
Description
Used to check if non-blocking
transactions are still pending.  If the
function returns true, the number of
non-blocking, pending transactions is
returned by reference in pctran.
BOOL DpcQueryConfigStatus(HANDLE hif, TRID trid, TRS * ptrs, ERC * perc)
hif - handle to JTAG
interface
trid - transaction ID to
query.  If 0, then the status of the oldest
transaction is
queried.
ptrs - pointer to store
information about transaction
perc - pointer to store
error code
Return Values
Returns true if transaction ID is found.
Returns false otherwise.

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。