This document describes the differences between the 3.0.x and 3.1 release versions of the Opal Kelly FrontPanel framework. The API has not changed in this release. However, there has been a slight change to how endpoint modules are connected to the FrontPanel Host Interface. Additionally, the Windows driver has been modernized and now supports 64-bit editions of Windows XP and Windows Vista.

FrontPanel 3.1 ships with a new USB driver for the Opal Kelly FrontPanel-enabled devices. This driver now support 64-bit editions of Windows XP and Windows Vista.

Although the API has not changed, you will need to use the latest DLL to communicate with the new driver. In most cases, you should be able to just drop in the new DLL. No re-build will be necessary. Note that Windows will associate all devices with the new driver, so a “mixed” system with both old and new drivers is not possible.

With the new driver installed and associated with an attached device (in this case, an XEM3001v2), your device list within Device Manager will now display as shown below. Note that a new device family (FrontPanel devices) has been added.

Devices attached to the NEW driver will look as shown above. Devices attached to the OLD driver will appear in the Universal Serial Bus Controllers group at the bottom of the list.

Note: Windows will only automatically update the driver for devices that are attached at the time you install the new FrontPanel software. To update other devices, after FrontPanel is installed, just right click on the device in Device Manager and click “Update Driver Software…” Windows should take care of the rest.

The FrontPanel 3.0 and previous HDL modules used a shared bus to connect the endpoint modules to the host interface module. This was done using a bus described in HDL as a tri-state bus. Xilinx FPGAs have not supported tri-states within the fabric for some time now, including Spartan-3. However, the synthesis tools have accommodated by converting the bus into a large mux.

With new devices such as the Virtex-5, Xilinx has deprecated this conversion support. Therefore, we have chosen to describe the bus as a Wire-OR configuration where all endpoint modules are bitwise-ORed and the result is sent to the okHost. This change requires a slight change in your HDL as you migrate to the new modules.

The okWireOR HDL modules is a simple parameterizable piece of HDL which creates 16 N-input OR gates. These combine the ok2 busses from each of the endpoints into a single ok2 bus on the okHost. For convenience, both VHDL and Verilog versions take a parameter (N) to set the size of the gates. As you add endpoints to your design, you must increase this N appropriately.

Consider the Counters sample. The Verilog host interface declarations with FrontPanel 3.0 looked like this:

okHostInterface okHI(
  .hi_in(hi_in), .hi_out(hi_out), .hi_inout(hi_inout),
  .ti_clk(ti_clk), .ok1(ok1), .ok2(ok2));
 
okWireIn ep00 (.ok1(ok1), .ok2(ok2), .ep_addr(8'h00), .ep_dataout(ep00wire));
 
okWireOut ep20 (.ok1(ok1), .ok2(ok2), .ep_addr(8'h20), .ep_datain(ep20wire));
okWireOut ep21 (.ok1(ok1), .ok2(ok2), .ep_addr(8'h21), .ep_datain(ep21wire));
okWireOut ep22 (.ok1(ok1), .ok2(ok2), .ep_addr(8'h22), .ep_datain(ep22wire));
 
okTriggerIn ep40 (.ok1(ok1), .ok2(ok2), .ep_addr(8'h40), .ep_clk(clk2), .ep_trigger(ep40wire));
 
okTriggerOut ep60 (.ok1(ok1), .ok2(ok2), .ep_addr(8'h60), .ep_clk(clk1), .ep_trigger(ep60trig));
okTriggerOut ep61 (.ok1(ok1), .ok2(ok2), .ep_addr(8'h61), .ep_clk(clk2), .ep_trigger(ep61trig));Code language: PHP (php)

with FrontPanel 3.1, this same set of declarations looks like this:

wire [17*5-1:0] ok2x;
okHost okHI(
  .hi_in(hi_in), .hi_out(hi_out), .hi_inout(hi_inout), .ti_clk(ti_clk),
  .ok1(ok1), .ok2(ok2));
 
okWireOR # (.N(5)) wireOR (ok2, ok2x);
 
okWireIn     wi00(.ok1(ok1),                           .ep_addr(8'h00), .ep_dataout(ep00wire));
okWireOut    wo20(.ok1(ok1), .ok2(ok2x[ 0*17 +: 17 ]), .ep_addr(8'h20), .ep_datain(ep20wire));
okWireOut    wo21(.ok1(ok1), .ok2(ok2x[ 1*17 +: 17 ]), .ep_addr(8'h21), .ep_datain(ep21wire));
okWireOut    wo22(.ok1(ok1), .ok2(ok2x[ 2*17 +: 17 ]), .ep_addr(8'h22), .ep_datain(ep22wire));
okTriggerIn  ti40(.ok1(ok1),                           .ep_addr(8'h40), .ep_clk(clk2), .ep_trigger(ep40wire));
okTriggerOut to60(.ok1(ok1), .ok2(ok2x[ 3*17 +: 17 ]), .ep_addr(8'h60), .ep_clk(clk1), .ep_trigger(ep60trig));
okTriggerOut to61(.ok1(ok1), .ok2(ok2x[ 4*17 +: 17 ]), .ep_addr(8'h61), .ep_clk(clk2), .ep_trigger(ep61trig));Code language: PHP (php)

The only difference is how the ok2 bus is connected. In FrontPanel 3.0, all HDL modules had an ok2 port. In FrontPanel 3.1, some do not. Also note the additional okWireOR module. Finally, note that each of the HDL modules with an ok2 port attach to a different range of signals on ok2x.

In the example above,

• wo20.ok2 is attached to ok2x[16:0], the first 17 bits of ok2x.
• wo21.ok2 is attached to ok2x[33:17], the second 17 bits of ok2x.
• …and so on…

The okWireOR takes this 17*5-bit (85-bit) bus and distills it to a single 17-bit bus which is attached to the okHost.

It is important to note the following:

1. ok2x is declared as a 17*5-bit (85-bit) wire bus.
2. okWireOR has the parameter N set to 5.
3. There are exactly 5 HDL module connections to ok2x and none are shared.

Updating your HDL code from FrontPanel 3.0 to FrontPanel 3.1 should be a relatively routine task. Although not currently required on Spartan-3 devices, this migration was necessary to support the Virtex-5 devices and others for which Xilinx will deprecate tristate synthesis in their ISE tools.

The WireOR declaration is little awkward but should result in slightly lower resource usage for the FrontPanel host interface.

This document describes the differences between the 1.x and 3.0 release versions of the Opal Kelly FrontPanel API. For the most part, applications developed with FrontPanel v1.x will easily port to v3.0 with relatively minor changes required at the software and HDL level. The new performance and features of 3.0 will be available with additional updates to your software and HDL.

The central architecture of FrontPanel, with its Wires, Triggers, and Pipes abstractions, has been very useful to a large number of varied applications. One notable limitation has been the availability of a “throttled” or “negotiated” Pipe. With FrontPanel 1.x, Pipe transfers were always performed at full-length and full-speed with the Host Interface acting as master. Any throttling of this transfer had to be done at a higher level, typically using some combination of Wires and/or Triggers to implement BUSY, READY, or DONE signals.

FrontPanel 3.0 introduces a new Block Throttled Pipe or BTPipe module that provides a higher-performance synchronous data transfer mode. With the BTPipe, the HDL can throttle data transfer at a block level for optimal performance and low-level throttling. All even block sizes of 2 through 1024 bytes are supported to best suit your HDL design and transfer requirements. Due to implementation specifics, power-of-two block sizes are fastest.

In addition to the methods to support the BTPipe, many methods have been updated with more robust return codes. These error codes provide more information when a given method fails. In the particular case of the BTPipe, the additional reporting allows for a recoverable timeout in case the hardware becomes unresponsive. Additionally, the board-specific classes derived from okCUsbFrontPanel have been eliminated and are no longer necessary.

• API First – You can migrate to the latest API at any time. We recommend upgrading your software to the latest API even if you do not (or cannot) upgrade devices to the latest firmware. The new API will automatically recognize older FrontPanel firmware and work properly.
• HDL and Firmware – The HDL and device firmware must be upgraded simultaneously. New firmware will not operate with an FPGA configuration file made with previous versions of the HDL modules.

Applications taking advantage of new FrontPanel 3.0 features will require a firmware update to the associated devices. The new firmware is available for XEM3001v2 and XEM3010 products. A firmware update will not be provided for the XEM3001v1. In the past, each product line has had an independent release to add features or fix bugs. Firmware releases have now been unified to a standard release version so that all devices will share the same firmware version number.

To update the firmware on a particular module, it must be attached to a computer with the FrontPanel Application installed. You can then use the firmware update wizard to upgrade the firmware using a Firmware Package available from Opal Kelly.

The new Software API fully supports communication with Opal Kelly devices with older firmware. In other words, you can update your PC software application with the new API and it will still work with an XEM3001v2 or XEM3010 hardware with older firmware. Features only available with updated firmware will simply return the UnsupportedFeature error code.

The event-based distribution of wire and trigger updates has been deprecated. Specifically, this means that the okCEventHandler class is no longer present. Also gone are the methods UnregisterAll and AddEventHandler from the API.

Note that these methods were never supported in the DLL and are rarely used in practice.

Static libraries (i.e. those that you compile-in to your software) for all platforms have been deprecated. Static libraries are compiler-specific which makes it difficult to support different compilers such as Borland and even different versions of VisualStudio. Our DLL has been available for over a year now and is the recommended way to build FrontPanel into your application.

Because the DLL is C as opposed to the C++ of the static library, we have built a C++ wrapper around the DLL. This means that most existing FrontPanel applications can be rebuilt with just a single additional line of code to load the DLL:

okFrontPanelDLL_LoadLib(NULL); // Load the FrontPanel DLL.Code language: PHP (php)

Just a few changes are all that are needed to move your existing statically-linked to the dynamically-linked stuff:

1. Add the above line of code somewhere in the initialization section of your source.
2. Add okFrontPanelDLL.cpp to your project.
3. Include okFrontPanelDLL.h rather than okCUsbFrontPanel.h in your source.
4. Do NOT link with okFrontPanel.lib anymore.
5. Make sure okFrontPanel.dll is located in your executable’s directory.

The classes derived from okCUsbFrontPanel (i.e. okCUsbXEM3001v2, okCUsbXEM3010, etc.) have been eliminated. A single class (okCUsbFrontPanel) contains all the functions necessary to communicate with any of the board models. You can always find out what type of board you’re connected to by calling GetBoardModel().

xem = new okCUsbXEM3001v2();xem = new okCUsbXEM3010();Code language: JavaScript (javascript)

xem = new okCUsbFrontPanel();Code language: JavaScript (javascript)

The PLL access methods were previously part of the derived classes. The unification of the okCUsbFrontPanel class has brought them under its umbrella. This required a bit of renaming, but should be easy to follow:

// XEM3001v2 xem->GetPLLConfiguration(...);xem->SetPLLConfiguration(...);xem->GetEepromPLLConfiguration(...);xem->SetEepromPLLConfiguration(...); // XEM3010 (instance of okCUsbXEM3010 class)xem->GetPLLConfiguration(...);xem->SetPLLConfiguration(...);xem->GetEepromPLLConfiguration(...);xem->SetEepromPLLConfiguration(...);Code language: JSON / JSON with Comments (json)

// XEM3001v2 xem->GetPLL22150Configuration(...);xem->SetPLL22150Configuration(...);xem->GetEepromPLL22150Configuration(...);xem->SetEepromPLL22150Configuration(...);   // XEM3010 xem->GetPLL22393Configuration(...);xem->SetPLL22393Configuration(...);xem->GetEepromPLL22393Configuration(...);xem->SetEepromPLL22393Configuration(...);Code language: JSON / JSON with Comments (json)

More thorough error reporting has been added to the FrontPanel API. This comes in the form of more verbose error codes from many methods that could, potentially, fail under some circumstances. For more information on the meaning of the return codes for particular methods, consult the FrontPanel API Reference Guide.

Support for Block Throttled Pipes comes in the form of two new API methods. These methods work similar to the existing WriteToPipeIn and ReadFromPipeOut methods provided for “standard” pipes with the addition of a blocksize parameter. For more information on how to apply the new Block Throttled Pipes, consult the FrontPanel User’s Manual.

The DLL (.so under Linux or .dylib under Mac OS X) has been fitted with a new C++ wrapper around all the functionality. You may still use the DLL from pure C if you wish; C++ functionality is compiled only when using C++ compilers.

In order to avoid namespace collisions, we have renamed the enumerated types in the DLL to appear more “Opal Kelly specific”. For example,

• ClockSource_22150 → ok_ClockSource_22150
• BoardModel → ok_BoardModel
• …and so on…

For the most part, HDL changes for a particular project are minor and represent changes in naming conventions. With superficial changes, all HDL projects should work. These projects will immediately benefit from the additional bandwidth possible with FrontPanel 3.0 pipes. With additional redesign, these projects can take advantage of the BTPipes.

In order to clean up the wiring required to attach the host interface, the bundle of host interface connections from FrontPanel 1.x (HI_CLK, HI_RDWR, HI_CS, HI_ADDR, HI_DATA, etc) has been replaced with only three busses: HI_IN, HI_OUT, and HI_INOUT. This is mostly a cosmetic change.

okHostInterface okHI(.hi_clk(hi_clk),.hi_rdwr(hi_rdwr),.hi_cs(hi_cs),.hi_irq(hi_irq),.hi_busy(hi_busy),.hi_addr(hi_addr),.hi_data(hi_data),.ti_clk(ti_clk),.ti_control(ti_control),.ti_data(ti_data));Code language: CSS (css)

okHostInterface okHI(.hi_in(hi_in),.hi_out(hi_out),.hi_inout(hi_inout),.ti_clk(ti_clk),.ok1(ok1),.ok2(ok2));Code language: CSS (css)

Similar to the cosmetic change on the host interface bundle, the target interface bundle has been consolidated into two busses. One from the host interface to endpoint modules (OK1[30:0]) and one from the endpoint modules to the host interface (OK2[16:0]).

The elimination of a bidirectional bus on the target interface works better with the internal architecture of the FPGA and capabilities of the synthesis tools.

okWireOut ep22 (.ti_clk(ti_clk),.ti_control(ti_control),.ti_data(ti_data),.ep_addr(8'h22),.ep_datain(ep22wire));

okWireOut ep22 (.ok1(ok1),.ok2(ok2),.ep_addr(8'h22),.ep_datain(ep22wire));

Support for the new Block Throttled Pipes has been added. Two new modules support these endpoints. Please see the FrontPanel User’s Manual for more details.