Run DFE Applications With MaxIDE

The following sections explain how to open or create a Maxeler project on Jumax, the location of important files, how to build it and run it on a DataFlow Engine.

Import an example project

Maxeler provides a lot of example and exercise projects on Jumax. We will see how to load an existing simple project.

• At the start of MaxIDE, you have to give a workspace directory. This directory will contain all your projects.
• Once done, you can import a project from the Menu bar using File>Import...
• Then select General>Existing Projects into Workspace and click on Next >.
• Then Browse a root directory: The projects are located in /opt/Software/maxeler/maxcompiler-2018.3.1/examples/. For now select the ./maxcompiler-tutorial/examples/ directory and click on Validate.
• MaxIDE will list all the projects from the folder. Click on Deselect All and re-select only the Tutorial-chap04-example02-simplekernel project. Be sure to select the CPU and the DFE one. The projects are given in two separate folders containing respectively the CPU code, which executes the DFE functions, and the DFE files.
• Tick the copy projects into workspace box to copy them and allow editing. Click on Finish.

Now that the projects are imported, you can open the important files, namely the CPU application, the kernel and the manager.

• The location of the CPU code is /Tutorial-chap04-example02-simplekernel-CPU/src/simplekernel/SimpleCpuCode.c
• The location of the kernel code is /Tutorial-chap04-example02-simplekernel-DFE/src/simple/SimpleKernel.maxj
• The location of the manager code is /Tutorial-chap04-example02-simplekernel-DFE/src/simple/SimpleMAX5CManager.maxj

This application is creating an array of size 1024 and computing the result of x*x+x operation on each element in the DFE by calling the Simple function defined in the kernel. See also that Simple.h (header of the corresponding .max file) and MaxSLiCInterface.h are linked to the C code.

Build and run

Build

To run the application, the DFE part must first be built. There are 2 build types. It can be built for simulation or for hardware DFE. Here are the main differences:

• Simulation: Building for simulation is very fast. It allows to test if our kernel and manager implementations work well. But it runs much slower than real hardware DFE, so it should be tested with small data.
• Hardware DFE: Building for DFE is very slow. The simple kernel program can take up to 2 hours to build. This is why it is important to first test the program in simulation. But running on DFE is very fast, so it should be done on big data to see a clear difference with CPU execution.

To build the DFE part, simply select the DFE folder in the left panel and click on the Build button in the toolbar. You can use the little arrow to choose to either build in SIM or in DFE mode.

Run

Once the build is complete, you can run the program by selecting the CPU folder in the left panel and clicking on the Run button in the toolbar. Again, using the little arrow, you can choose to run either in SIM or DFE mode.

Running the program compiles the CPU application using gcc. On the Jumax machine, gcc 11 is used and requires the libstdc++.so library in version 29. But this library is not up-to-date in the path given by the Makefile. To solve this problem, the Makefile can be edited the following way:

• Open the Makefile in the Tutorial-chap04-example02-simplekernel-CPU folder.
• On line 87, there is the definition of the LD_LIBRARY_PATH for run_dfe. This should be changed to
  run_dfe: export LD_LIBRARY_PATH := $(MAXELEROSDIR)/lib:$(LD_LIBRARY_PATH)
• On line 89, there is the definition of the LD_LIBRARY_PATH for run_sim. This should be changed to
  run_sim: export LD_LIBRARY_PATH := $(MAXCOMPILERDIR)/lib/maxeleros-sim/lib:$(LD_LIBRARY_PATH)

This way we just append the maxcompiler path to LD_LIBRARY_PATH instead of overwriting it.

The original Makefile is also missing two environment variables to find the correct MaxelerOS directory:

• Copy the following line above line 89:
  run_sim: export MAXELEROSDIR=$(MAXCOMPILERDIR)/lib/maxeleros-sim
• Copy the following line above line 87:
  run_dfe: export MAXELEROSDIR=/opt/maxeler/maxeleros

Resulting files

MaxCompiler generates a few interesting files when building a project. They are mainly located in /Tutorial-chap04-example02-simplekernel-DFE/builds/Tutorial/Simple_MAX5C_DFE_SIM/results.

• Simple.max is the .max file created from the kernel and manager. For more information on its utility, see the following page: Basics of DFE Applications
• Simple.h is the header file of the corresponding .max file.
• Simple-SimpleKernel-original.pxg shows you the graph of your kernel implementation. It gives you an illustrative view of the dataflow through the DFE.
• Simple-SimpleKernel-final-simulation.pxg shows you the graph of your kernel implementation but after optimization and scheduling by MaxCompiler.

Create a new project

The following workflow is the most effective way to create a new DFE project on MaxIDE. Every step should be followed carefully to be able to correctly build and run the application.

Create CPU and DFE projects with the wizard

As seen in the last section, DFE projects are made of two parts: the CPU code and the DFE maxj files. MaxIDE contains a wizard that allows the creation of new projects.

To create a new empty CPU project, click on New>Empty C Slic Project in the toolbar. Choose a name for your project.

To create a new empty DFE project, click on New>Empty Maxj Project in the toolbar. Choose a name for your project, as well as for the main package.

Edit the Makefile

Open the Makefile located in the your-project-name-CPU folder and edit the following elements:

• If your project is in C++ and not in C, on line 2, change CC := gcc to CC := g++. On line 11, change -std=gnu99 to -std=c++11.
• On line 11, you can add any additional flag you need, like -O3 for example.
• On line 14, change EXE := [...] to the executable name of your choice.
• On line 87, there is the definition of the LD_LIBRARY_PATH for run_dfe. This should be changed to
  run_dfe: export LD_LIBRARY_PATH := $(MAXELEROSDIR)/lib:$(LD_LIBRARY_PATH)
• On line 89, there is the definition of the LD_LIBRARY_PATH for run_sim. This should be changed to
  run_sim: export LD_LIBRARY_PATH := $(MAXCOMPILERDIR)/lib/maxeleros-sim/lib:$(LD_LIBRARY_PATH)
• Copy the following line above line 89:
  run_sim: export MAXELEROSDIR=$(MAXCOMPILERDIR)/lib/maxeleros-sim
• Copy the following line above line 87:
  run_dfe: export MAXELEROSDIR=/opt/maxeler/maxeleros

Create new kernels and managers

Once your project is created and ready to go, you can edit the already existing kernel and manager. But you also may want to add other kernels or managers. One important thing to keep in mind is that one manager is equivalent to one .max file (which is also equivalent to one function that you can call from the CPU code). But one manager can have multiple kernels performing different simple tasks.

To add a new kernel or manager, you can just duplicate the existing ones and edit them as you wish.

Build with multiple managers

When building a DFE project using the Build button, MaxCompiler is compiling all the files contained in the src folder. Therefore, all managers and kernels code should be correct and contain no error. But despite the fact that all files are compiled, only one manager is actually built with its associated kernels.

To choose the manager to build, select your DFE project in the left panel. Click on the blue button in the tool bar, called MaxFile Generation Parameters to open the configuration window. You can edit the preference for each mode (DFE and simulation) separately.

The following picture on the right shows a configuration example to build the YourMAX5CManager in simulation mode. The resulting .max file name can also be chosen.

Select .max files for CPU execution

To use one or multiple .max files in a CPU project, you must tell it where to find them and which ones to load. To do that, right-click on your-project-name-CPU in MaxIDE and choose Manage Maxfiles. In this pop-up window, choose the Maxfiles you want to use in your C/C++ code.

One important thing to notice is that if you select your max file from the first frame, it will select the DFE and SIM max files from the corresponding manager. You should only choose the max files corresponding to the nature of your execution (sim or dfe) in the bottom frame.

Maxeler Maxfiles Manager window. Here the SIM maxfile is selected to run the CPU application in simulation mode.