Digilent Port Communications User Manual
DDiiggiilleenntt PPoorrtt CCoommmmuunniiccaattiioonnss
PPrrooggrraammmmeerrss RReeffeerreennccee MMaannuuaal
Revision: 06/03/05 215 E Main SuiteD | Pullman, WA 99163
l
www.digilentinc.com
(509) 334 6306 Voice and Fax
TM
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 DL L 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 from 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.com. 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.
© Digilent, Inc. Doc: 576-000
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 sy stem at program
run time. The DLL file should either be placed
in the same directory as the 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
DPCUTIL Programmer’s Manual
The following is a simple list of all DP
CUTIL API functions (with return types) available for public use:
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 (nonblocking). 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
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.
Digilent, IncTM
www.digilentinc.com
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 use d, 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.
BOOL DpcInit BOOL DpcPutTmsTdiBits
VOID DpcTerm BOOL DpcGetTdoBits
BOOL DpcGetDpcVersion BOOL DpcOpenData
BOOL DpcStartNotify BOOL DpcCloseData
BOOL DpcEndNotify BOOL DpcPutReg
BOOL DpcQueryConfigStatus BOOL DpcGetReg
BOOL DpcPendingTransactions BOOL DpcPutRegSet
BOOL DpcAbortConfigTransaction BOOL DpcGetRegSet
BOOL DpcClearConfigStatus BOOL DpcPutRegRepeat
BOOL DpcWaitForTransaction BOOL DpcGetRegRepeat
ERC DpcGetFirstError VOID DvmgStartConfigureDevices
BOOL DpcOpenJtag int DvmgGetDevCount
BOOL DpcCloseJtag BOOL DvmgGetDevName
BOOL DpcEnableJtag BOOL DvmgGetDevType
BOOL DpcDisableJtag int DvmgGetDefaultDev
BOOL DpcSetTmsTdiTck int DvmgGetHDVC
BOOL DpcPutTdiBits
© Digilent, Inc. Page 2 of 14
DPCUTIL Programmer’s Manual
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.
Digilent, IncTM
www.digilentinc.com
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). If 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
© Digilent, Inc. Page 3 of 14
DPCUTIL Programmer’s Manual
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
To stop notifica tion 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:
Digilent, IncTM
www.digilentinc.com
the device using DpcDisableJtag and
DpcCloseJtag.
Multiple Instances of DPCUTIL (for
Win32 applications)
M ore than one application can use the
DPCUTIL.DLL at once. This presents the
possibility of the devic e 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:
HWND user specified window handle
MSG WM_COMMAND
WPARAM
low order word
high order word
LPARAM 0
user specified identifier.
0
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
© Digilent, Inc. Page 4 of 14
DPCUTIL Programmer’s Manual
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
Digilent, IncTM
www.digilentinc.com
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)
Parameters
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.
© Digilent, Inc. Page 5 of 14
Loading...