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.
NOTE: This document ONLY applies to FrontPanel-3 users. If you are using a previous version of the FrontPanel API and firmware, please ignore this document.
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.
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.
Just a few changes are all that are needed to move your existing statically-linked to the dynamically-linked stuff:
okFrontPanelDLL.cpp to your project.okFrontPanelDLL.h rather than okCUsbFrontPanel.h in your source.okFrontPanel.lib anymore.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().
FrontPanel 1.x:
xem = new okCUsbXEM3001v2(); xem = new okCUsbXEM3010();
FrontPanel 3.0:
xem = new okCUsbFrontPanel();
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:
FrontPanel 1.x:
// XEM3001v2 xem->GetPLLConfiguration(...); xem->SetPLLConfiguration(...); xem->GetEepromPLLConfiguration(...); xem->SetEepromPLLConfiguration(...); // XEM3010 (instance of okCUsbXEM3010 class) xem->GetPLLConfiguration(...); xem->SetPLLConfiguration(...); xem->GetEepromPLLConfiguration(...); xem->SetEepromPLLConfiguration(...);
FrontPanel 3.0:
// XEM3001v2 xem->GetPLL22150Configuration(...); xem->SetPLL22150Configuration(...); xem->GetEepromPLL22150Configuration(...); xem->SetEepromPLL22150Configuration(...); // XEM3010 xem->GetPLL22393Configuration(...); xem->SetPLL22393Configuration(...); xem->GetEepromPLL22393Configuration(...); xem->SetEepromPLL22393Configuration(...);
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, consuld the FrontPanel API Reference Guide.
| ErrorCodes defined by the okCUsbFrontPanel class | ||
|---|---|---|
| NoError | DeviceNotOpen | CommunicationError |
| Failed | InvalidEndpoint | InvalidBitstream |
| Timeout | InvalidBlockSize | FileError |
| DoneNotHigh | I2CRestrictedAddress | I2CNack |
| TransferError | I2CBitError | I2CUnknownStatus |
| UnsupportedFeature | ||
| API methods that return an ErrorCode | |
|---|---|
| OpenBySerial | GetPLL22393Configuration |
| ResetFPGA | SetPLL22393Configuration |
| ConfigureFPGAFromMemory | GetEepromPLL22393Configuration |
| ConfigureFPGA | SetEepromPLL22393Configuration |
| WriteI2C | SetWireInValue |
| ReadI2C | ActivateTriggerIn |
| LoadDefaultPLLConfiguration | WriteToPipeIn |
| GetPLL22150Configuration | ReadFromPipeOut |
| SetPLL22150Configuration | WriteToBlockPipeIn |
| GetEepromPLL22150Configuration | ReadFromBlockPipeOut |
| SetEepromPLL22150Configuration | |
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_22150BoardModel → ok_BoardModelFor 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.
FrontPanel 1.x:
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));
FrontPanel 3.0:
okHostInterface okHI( .hi_in(hi_in), .hi_out(hi_out), .hi_inout(hi_inout), .ti_clk(ti_clk), .ok1(ok1), .ok2(ok2));
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.
FrontPanel 1.x:
okWireOut ep22 (
.ti_clk(ti_clk),
.ti_control(ti_control),
.ti_data(ti_data),
.ep_addr(8'h22),
.ep_datain(ep22wire));
FrontPanel 3.0:
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.