Instruction Framework Tutorial

[balexand]

The attached .zip file contains a tutorial for getting started with the Instruction Framework library, a LabVIEW FPGA Instrument Design Library (IDL) used in several NI-provided sample project designs.  This tutorial will bring FPGA developers up to speed on basic Instruction Framework concepts, and how to get started with a simple design that uses the Instruction Framework.

(Posted in response to http://forums.ni.com/t5/LabVIEW/LV-FPGA-Instruction-Framework/td-p/3222547 )

Required Software

This tutorial was created with the following software:

1. LabVIEW 2014
   
2. LabVIEW FPGA 2014
   
3. FlexRIO 14.1
   

Newer versions which maintain backwards compatibility may work as well.

Introduction

The Instruction Framework library evolved from the Register Bus library used in the VST LV FPGA designs.

See: http://zone.ni.com/reference/en-XX/help/373680A-01/rfvst/register_bus_design_library_overview/

The library defines two interfaces which may be implemented by clients.

• Address Space
  • Receives instructions from the framework, and is expected to provide a response.
  • See instr.lib\_niInstr\Instruction Framework\v1\FPGA\Interfaces\Address Space\Address Space.lvclass
• Instruction Producer
  • Sends instructions into the framework, and waits for a response.
  • See instr.lib\_niInstr\Instruction Framework\v1\FPGA\Interfaces\Instruction Producer\Instruction Producer.lvclass

At this time, the FIFO Register Bus is the only library with an Instruction Producer.

See instr.lib\_niInstr\FIFO Register Bus\v1\FPGA

This FIFO Register Bus library is nearly identical to the VST Register Bus, except this library implements the Instruction Producer interface that lets it hook into the Instruction Framework.  It may be worth noting that the FIFO Register Bus library also augmented the capabilities of the VST Register Bus by allowing for instructions with 64-bits of data, and a 32-bit address.

One of the benefits of using the Instruction Framework is that it provides encapsulation of details that you don't necessarily care about.  On VST, the Register Bus is placed in a SCTL at the top level of the design.  The instruction output from each Register Bus is passed to a network comprised of Register VIs, Arbiters, and Muxes, and the read data is passed back.  With Instruction Framework, you create a Register Configuration object, and connect Address Spaces and Instruction Producers using a simple registration API.

Some Instruction Framework features that were added:

• Improved arbitration between shared subsystems (producers can talk to unblocked subsystems while shared subsystems are blocked)
• Added inspection of attached address spaces / subsystems using metadata parameters: UID, instance number, parent.
• Added version check capability using metadata parameters: version, oldest compatible version

[UMASO]

Thanks for providing the wonderful framework.  It is so much well-designed, implemented, and true invention.  

As for tutorial, would you add two details about the followings?

1. what "abort" does, and when it is asserted in Bus Interface
2. how address map collection works and when to use.  

(1) When I made one of my address space, I first thought to make a kind of small state machine inside Bus Interface.  In that case, I wanted to reset the state machine somehow through instruction framework.  Then, I noticed "abort" input is available.  However, since I could not figure out when it is asserted, I did not rely on to "abort" input to reset state machine.  How is the "abort" input expected to be used?

"abort" input in Bus Interface of Address Space

(2) Your Instruction Framework is the key to customize FPGA Extensions like VST.  I ported my IP with the Extension with a specific UID, and found an error occurs on host-side looking up single address space.  Then, I realized that user IP is joined to a part of "collection" of multiple address spaces on Extension layer.  I did not find any tutorial about this use-case neither on your tutorial nor VST documentation.  

Space Collection on FPGA Extension

Once I noticed that UID can be set as layer by "collection", I successfully reached to my IP by chaining the "parent context" like below.  (2411: Extension Collection Address >> 32769: My Address)

Host-side Access

Best regards,

Osamu Fujioka

TRIONIX ltd.  (NI partner in Japan)

[UMASO]

Hello, my customer is interested in developing host PC application on C++ for FPGA bitfile implemented with Instruction Framework.  Is it possible to get header file for niifw.dll? 

Best regards, 

[JVP]

I don't know how active this thread is but I am also looking for developing C++ application for FPGA bitfile implemented with Instruction Framework. If this is something that I need to request from different channel please let me know??

[Terry_ALE]

I would recommend posting to the LabVIEW FPGA Idea Exchange: https://forums.ni.com/t5/LabVIEW-FPGA-Idea-Exchange/idb-p/lvfpgaideas

[balexand]

Hello Osamu and Jignesh,

It's nice to hear from you. What an interesting coincidence that you both have a request for a C header file for the Instruction Framework host library. You're not working for the same company, I presume? We had an engineer prototype a C header plus example with NiFpga and niifw yesterday. I think we will try to get it posted to NI's GitHub account shortly.

We may also post import libraries (.lib) for niifwu.dll, since those do not ship with the installed library.

Please accept that we are delivering this software AS-IS and with no warranty, as it is not part of an official NI driver software installer.

Sincerely,

Brian Alexander

[UMASO]

Hello Brian, 

I am so glad to hear from you and so so glad to know that you still keep staying with us as a fantastic R&D engineer at NIC.  I am also surprised that Jignesh has had a same request, and we are definitely not working fot the same company, but Jignesh is a former NI employee so am I.  

Thanks much for sharing C header + .lib.  I definitely understood that those are provided outside of official products and as-is. 

Just out of curiousity, isn't a header file generated, when a DLL is generated?  Each of Instruction Framework API calls DLL functions and I assume those APIs have been auto-generated through LabVIEW's shared library import utility, arent they?  

Let me ask one more question, will IDL, software-designed-instrument, and FlexRIO be continuous as NI's key products?  Or will they be discontinued?  

Regards, 

Osamu Fujioka

[balexand]

Honestly, not a lot of this was auto-generated.  The niifw DLL is written in C++, compiled with a C++ compiler which produces .dll and .lib.  The exported functions are C prototype functions, and we've hand-written a header for it.  The header already exists internally, we just needed to change a few things so it will work outside of our internal build system.  The Call Library Nodes inside of the Instruction Framework host VIs were actually developed by hand.  Most of this was done back in 2015, and the main interfaces have remained stable.

There aren't any upcoming plans to discontinue IDLs, SDIs, or FlexRIO. We are continuing to make PXI products that support LabVIEW FPGA and the IDLs.

[balexand]

The C API for Instruction Framework Instrument Design Library has been posted to GitHub here:

https://github.com/ni/idl_ifw_capi

[UMASO]

Hello Brian, thanks much for sharing all the files.  

I tested the files by calling niIFW function APIs on my .cpp, in almost the same way as on the Host VI of your Instruction Framework Tutorial.  (LabVIEW 2019 SP1, VS 2013)

In my environment, it looks like I had to add one typedef as shown below.  Then, it worked!

Let me attach my test codes here.  vs solution file is located as shown below.  

... I tried to attach a .zip file on this thread, but couldn't.  Would you have any suggestion where to share it?  

 

Thank you so much again, and thank you also for telling the wonderful news that IDLs, SDIs, and FlexRIO will be continuing as key products!!  I will keep doing my best to spread these fantastic products in Japan.  

Best regards,  

[JVP]

Hi Brian,

Thank you for the response. As Osamu mentioned we are not at the same company and we may not even be using the same instrument either.

I was a software dev at one point in my NI history and you actually gave me a training on Instruction Framework as it was going to be used on the VST (the driver team I was on at NI). And because of my history on the VST I knew this existed internally and in my current application I am using VST through C# (I should be able create wrapper based on what you have shared). I am glad you are able to share this publicly!

[JVP]

The solution posted is also working with my application! Thank you for your help!

[Intaris]

I have only recently looked at this toolkit. It seems to do something similar to code we have already developed for our relatively mature FPGA code.

I have a couple of questions though:

1) Is the storage of data on the FPGA inherently limited to registers, or could one implement a child class which stores data in a BRAM for example?

2) Can we loop-back Instructions from the FPGA to other modules on the FPGA using this tool?

3) Is the response hard-wired into the toolkit or can it also function as "fire and forget"?

[balexand]

1) Is the storage of data on the FPGA inherently limited to registers, or could one implement a child class which stores data in a BRAM for example?

You can use whatever data storage you like! Instruction Framework is sometimes even been used to read/write registers that are on a different chip entirely (e.g. connected by SPI). It is also possible to just store your register data in a feedback node inside Bus Interface.vi.  The framework is responsible for delivering instructions and responses, the storage is up to the client.

2) Can we loop-back Instructions from the FPGA to other modules on the FPGA using this tool?

You can create your own Instruction Producer subclass which lets you write FPGA code that can send instructions to any of the Address Space implementations that are connected.

3) Is the response hard-wired into the toolkit or can it also function as "fire and forget"?

There is not currently a "fire and forget" mode.