Communicating with the Basys2 using the Adept SDK

Writing code for development boards is fun: LEDs flash, respond to button presses, etc. Eventually though, we would like to be able to communicate with our boards using a PC. Many boards include a RS-232 (serial) port for just this purpose. RS-232 has a few drawbacks though, most notably that if your computer was purchased this millennium, you will probably have to use a USB-serial converter. These are cheap and prevalent, but it is just another thing to clutter up your workspace. Also, transferring large amounts of non-ASCII data (i.e. raw hex) can be challenging and time consuming. Since legacy ports are going the way of the Dodo bird, many developers are omitting the serial port from their development boards, and instead including a USB controller. The Basys2 from Digilent is one such board. This leaves us in a lurch, unless we can find a way to interact with the device through its USB controller. And that's were the Adept SDK comes in.

Instead of having to look up the specifics of the USB chip on the board, the Adept SDK provides APIs to interact with the board. In this post, I'll cover just 2 of the libraries: the device access management library (DMGR) and the asynchronous parallel port library (DEPP). Note that DEPP is so named for the similarity to the Enhanced Parallel Port (EPP) protocol used by parallel ports.

The Adept SDK provides code samples for each of the libraries. For the DMGR library, there are 2 examples: EnumDemo and GetInfoDemo. To get started, download the Adept SDK and Adept Runtime from Digilent. Install the runtime, and decompress the SDK somewhere you can find it. The SDK contains:

• Documentation: PDF files describing how to use the libraries in the doc folder
• Header Files: The include folder contains header files
• Static Libraries: The APIs are provided as precompiled libraries
• Code Samples: Example code for each library is included in the samples folders

After downloading the SDK for Windows, I set about to compiling some of the samples. There are introductions on how to do this in the samples directory, but they are specific to Visual Studio. In my case, I am using MinGW's toolchain. The linkers in the two toolchains expect library files to be named differently. Visual Studio expects a library file named <library name>.lib, and this is how the libraries are provided by Digilent. MinGW's linker, ld, only accepts library files in the format lib<library name>.a. Similarly, ld running under Linux expects a file lib<library name>.so. So, in order to use the Windows libraries provided by Digilent, I had to rename all of the files. dmgr.lib had to be renamed libdmgr.a, for example. The Windows version of the SDK contains the libraries in the lib or lib64 directories. The Linux version installs the libraries with the runtime.

In order to get g++ to compile the examples, I had to specify the include directory using -I, specify the library directory using -L, and specify which libraries to use AFTER the filename. For example, a project that uses only the DMGR library would have -ldmgr after the file name.

I compiled and executed the DMGR examples EnumDemo and GetInfoDemo. These confirmed that there was in fact a Basys2 attached to my system, and that it supported the DEPP library. I then instantiated a DEPP interface on the FPGA that included 2 operand registers and a result register. The operand registers can be written by the PC, and the result register can be read. Actually creating those structures on the FPGA will be covered in another post, but project files can be found here.

I wanted to write some code to write values to the operand registers, then read the result out. Here's what it looks like (full file here):

 #if defined(WIN32)
/* Include Windows specific headers here.*/
#include <windows.h>
#endif

This makes the necessary types available on a Windows.

#include <stdio.h>
#include "dpcdecl.h"
#include "dmgr.h"
#include "depp.h"

All of the header files needed for this project.

#define OP1ADDR         0x00
#define OP2ADDR         0x01
#define RESADDR         0x00

I chose to use text substitutions to define the register locations, to make my code easier to read. And then we start with main():

int main()
{
        HIF deviceHandle;
        int status = fTrue;
        char deviceName[32] = "Basys2";
        unsigned char result;

The type HIF is defined in dpcdecl.h, and is a structure that holds a handle to a device. This handle is used to interact with the Basys2. The status variable will be used for error detection/error handling. The device name is the UserName of the device. I found the UserName using EnumDemo. result will hold the result of the arithmetic that we read back from the device.

//Open a handle to the device
status = DmgrOpen(&deviceHandle,deviceName);
if (status)
printf("Successfully opened a handle to %s\n", deviceName);
else
{
status = DmgrGetLastError();
printf("Error code: %d\n", status);
}

 The first step in interacting with the device is to open a handle to it. Note that the API functions return FALSE if there is an error, and TRUE if they are successful.

//Enable the default port (Port 0) on the device
status = DeppEnable(deviceHandle);
if (status)
printf("Successfully enabled Port 0\n");
else
{
status = DmgrGetLastError();
printf("Error code: %d\n", status);
}

The EPP port must be enabled before reading or writing.

//Do some math
DeppPutReg(deviceHandle, OP1ADDR, 0x00, fFalse);
DeppPutReg(deviceHandle, OP2ADDR, 0x00, fFalse);
DeppGetReg(deviceHandle, RESADDR, &result, fFalse);
printf("0x00 + 0x00 = 0x%02X\n", result);
//...
DeppPutReg(deviceHandle, OP1ADDR, 0xFF, fFalse);
DeppPutReg(deviceHandle, OP2ADDR, 0x01, fFalse);
DeppGetReg(deviceHandle, RESADDR, &result, fFalse);
printf("0xFF + 0x01 = 0x%02X\n", result);

Here's where I actually transfer some data to and from the device. I write to the operand registers using DeppPutReg(), and then read the result register using DeppGetReg(). I ran through several scenarios to make sure that the adder was working properly.

//Disable the active port on the device
status = DeppDisable(deviceHandle);
if (status)
printf("Successfully disabled DEPP port\n");
else
{
status = DmgrGetLastError();
printf("Error code: %d\n", status);
}

//Close our handle to the devicestatus = DmgrClose(deviceHandle);
if (status)
printf("Successfully closed device handle\n");
else
{
status = DmgrGetLastError();
printf("Error code: %d\n", status);
} 

This is all cleanup to make sure that I gracefully release the device.

When it was all said and done, the output looked like this:
Successfully opened a handle to Basys2
Successfully enabled Port 0
0x00 + 0x00 = 0x00
0x01 + 0x00 = 0x01
0x01 + 0x01 = 0x02
0xA5 + 0x5A = 0xFF
0xFF + 0x01 = 0x00
Successfully disabled DEPP port
Successfully closed device handle

And so, I successfully moved raw data to the device, and read a result. While an unsigned 8-bit adder is trivial, this gives me all of the building blocks to do something more interesting, like cryptographic work.