Weird unsigned/int bug with divide in VivadoHLS

Reported here: Xilinx developer forum. Unfortunately, no Xilinx dev or forum administrator has confirmed this issue, but the minimal example shows how this bug can be replicated. You can download the minimal example by clicking here.

ap_uint/ap_int behaviour in VivadoHLS

Small program that demonstrates HLS data-types behaviour with ap_int and ap_uint data-types:

        #include <stdio.h>
        #include "ap_int.h"
        
        int main()
        {
            ap_int<8> acc = 12;
            ap_uint<8> res = 0;
        
            res += acc;
            printf("res = %d\n",(int)res);
        
            acc = -6;
            res += acc;
            printf("res = %d\n",(int)res);
        
            acc = -8;
            res += acc;
            printf("res = %d\n",(int)res);
        
            return 0;
        }
      

Output result is:

        res = 12
        res = 6
        res = 254
      

Conclusion: The accummulation happens correctly in signed integer, but the number is stored and printed as an unsigned integer.

Taskwarrior

Wow, this was hard to setup. Some steps that are not documented, especially for allowing a TW client on a different machine to sync with the server (e.g. some server on the VPN):

1. On your taskwarrior server: sudo ufw allow PORT_NUMBER_YOU_WANT_OPEN_FOR_TW
2. On your taskwarrior server: add a line in /etc/hosts that has your IP address explicitly written out to your hostname. (e.g. 10.123.456.789 YOUR_HOSTNAME)
3. Not entirely sure if this is needed, but this command was the first time I managed to get some response from my TW server (my PC) from my client (my laptop): ssh -L TW_PORT:localhost:22 USERNAME@IP_ADDRESS, where TW_PORT is the port I am using for TW server, and USERNAME/IP_ADDRESS are my login details for connecting to my TW server machine. Then, running task rc.taskd.server:localhost:localport somehow got a response with tasks on my remote server. This didn't really help me solve the problem though, I had to do the two steps above before I was able to run task sync without errors.

Regex back-referencing

Very useful for speeding up tedious tasks, e.g. creating verilog testbenches requires lots of wire declarations when connecting up the interface for the DUT. e.g. module Top ( a, b, c ), in the testbench we want to instantiate Top DUT ( .a(a), .b(b), .c(c) ), which can be done by a single well-constructed regex command. In vim-regex, to capture a matched string, you can do a visual select and use %s/\(YOUR_REGEX_TO_MATCH\)/\.\1(\1)/g. Here, your regex match is capturing groups, and you are back-referencing it using \1.

Another example: "James Bond" use s/\(.*\) \(.*\)/I'm \2, \1 \2/g, which will produce "I'm Bond, James Bond".

Dotfiles management

My dotfiles: https://github.com/sidmontu/dotfiles.

I followed this tutorial: https://www.atlassian.com/git/tutorials/dotfiles

On a new system, inside home directory, run:

1. echo ".cfg" >> .gitignore
2. git clone --bare https://github.com/sidmontu/dotfiles.git $HOME/.cfg
3. alias config='/usr/bin/git --git-dir=$HOME/.cfg/ --work-tree=$HOME'
4. config checkout

UG documentations for Vivado Tools / Related

PYNQ -- Holy grail of the PYNQ software framework.

UG902 -- High-level synthesis (details about HLS data-types, IP cores, pragmas, more)

WP509 -- RF data convert IP block, and understanding key parameters it exposes to the programmer.

SDSoC tutorials

DS926 -- RFSoC data sheet

PG269 -- RF data converter IP data sheet

UG1270 -- VivadoHLS optimization guide (pragmas and their effects mainly).

VivadoHLS pragma list -- HTML page of HLS pragmas, easier to read and navigate than the PDFs

PG085 -- AXI4 stream protocol IP suite for Xilinx.

RFSoC -- getting started guide (setup, tests, etc)

Collection of little oddities in FPGA tools

If you want to use the Xilinx FFT IP core in VivadoHLS, where you're repeatedly calling the HLS core function to evaluate on different vectors of data (not unrolled, since you might not want to instantiate many copies of the FFT core in hardware), then the HLS tool will give an incompatibility error on the interface data-type (ap_auto vs ap_fifo). To solve that, insert HLS interface pragma to declare the input ports of the FFT IP core as type ap_fifo. See: https://forums.xilinx.com/t5/Vivado-High-Level-Synthesis-HLS/ap-auto-incompatible-with-ap-fifo-error-when-using-FFT-IP/td-p/703730.

In VivadoHLS, if you wish to interpret an ap_uint/ap_int data-type as fixed-point data-type, i.e. you want the ap_fixed number to have the bit-exact value as the ap_uint/ap_int number, then you can use the .V statement. E.g. ap_fixed<8,6> fxp_num is a Q6.2 fixed-point number, and ap_uint<8> uint_num = 0x0f, by setting "fxp_num.V = uint_num", fxp_num bits will be set to 0x0f, which will be interpreted as 3.75. See: https://forums.xilinx.com/t5/Vivado-TCL-Community/A-question-about-Type-Conversion-in-Vivado-HLS/td-p/711413

No Clock-Domain-Crossing (CDC) in VivadoHLS. Which is weird, since you can specify a separate clock for your s_axilite ports (e.g. #pragma HLS interface port=axilite_port clock=config_clk). Either it's broken, or I need to investigate further whether the timing errors reported on the path can actually be ignored as false paths. See https://forums.xilinx.com/t5/Vivado-High-Level-Synthesis-HLS/no-clock-domain-crossing-in-HLS/td-p/933543.

How to connect interrupts in block design (or how not to): https://forums.xilinx.com/t5/Embedded-Linux/A-key-error-when-I-am-trying-to-access-a-DMA-IP-on-PYNQ-Z1-board/td-p/847817

For some obscure reason, if Xilinx tools (e.g. Vivado) is in your $PATH, some C/C++ projects report build errors - I observed this error from trying to build Ettus RFNoC framework using PyBOMBs. Removing Xilinx tools from the $PATH in a fresh terminal does the trick.

Pynq Jupyter environment sometimes fails to load even the basic pynq overlay modules. If you see a "ValueError: bad marshal data", then perhaps there are corrupt compiled python module files (.pyc). I've fixed this once by running "(sudo) find /usr -name '*.pyc' -delete". Stackoverflow link.

Python __slots__

Interesting little feature in Python: instead of a dynamic __dict__ of attributes, __slots__ is a statically declared dictionary you know your class instances will have, i.e. not mutable at runtime. Effect is you get better runtime performance (faster lookup), and savings in memory usage. See: Stackoverflow discussion

Very useful guide on choosing a loss function in Tensorflow

Stackoverflow link

Tensorpack custom DataFlow class

If you have a very large dataset that is dynamically-loaded from disk - i.e. if you keep track of pointers in your get_data() routine to yield data to the trainer at runtime, remember to reset these pointers appropriately at the beginning of the get_data() routine. This is because Tensorpack spawns multiple threads for feeding the Tensorpack trainer at runtime, and without a "reset_state()" function will cause out-of-range memory access errors.

Xilinx pblocks

Pblock is a physical block to constrain nets to physical areas on the FPGA. Pblocks can be nested, but Xilinx recommend at most one-level of nesting, and to avoid it altogether if possible. Pblock can be shaped into custom shapes (instead of just a rectangle) by clicking on the "add pblock rectangle" option when selecting the pblock you wish to reshape. The pblock properties can be exported to a xdc constraints file automatically using "save constraints as" option under "File". These constraints are basically tcl commands that look something like the following:

create_pblock "name you wish to give to the pblock"
add_cells_to_pblock [get_pblocks "name of pblock"] [get_cells -quiet [list "name of module you wish to assign to pblock"]
resize_pblock [get_pblocks "name of pblock"] -add {SLICE_"XY-COORD":SLICE_"XY-COORD"}
resize_pblock [get_pblocks "name of pblock"] -add {DSP48_"XY-COORD":DSP48_"XY-COORD"}
resize_pblock [get_pblocks "name of pblock"] -add {RAMB18_"XY-COORD":RAMB18_"XY-COORD"}
resize_pblock [get_pblocks "name of pblock"] -add {RAMB36_"XY-COORD":RAMB36_"XY-COORD"}

You can do a DRC check for floorplanning to make sure pblock specified for the module meets expectations. Basically, this is a sanity test.

Vivado has an auto-floorplanning tool as well (under Tools - Floorplanning - Auto-create Pblocks). Also worth checking out "Window - Phyiscal Constraints" tab, which will show connectivity between different Pblocks for better visualization of dataflow in your circuit. Individual logic can also be locked into exact locations so that there is consistency between runs (i.e. you don't get a completely different placed/routed solution that you can't quantify whether your changes made any difference between implementation runs).

Floorplanning can improve performance and consistency between runs. Some guidelines: floorplan what is necessary, do not over-floorplan. Choose modules to floor-plan that do not have connectivity to lots of other modules, as those modules are better to be broken apart to reduce critical path lengths. Use RTL hierarchy, DRC checks, properties and other Vivado tools to judge what is best and how to floorplan. Finally, floorplanning can be an iterative process.

Reference resource: https://www.xilinx.com/video/hardware/design-analysis-floorplanning-with-vivado.html

Arch Linux + bspwm + sxhkd

Weird thing I found that if, instead of using urxvt as the main terminal, you are using termite, then there is a weird idiosyncrasy with how a bspc rule has to be declared. In fact, it seems like urxvt also has an oddity from a stackoverflow post that I saw

Instead of :

bspc rule -a termite state=floating
bspc rule -a urxvt state=floating

You must declare the following (basically the capitalization) :

bspc rule -a Termite state=floating
bspc rule -a URxvt state=floating

for the rule to register when creating the window. By the way, what's with the weird names (sxhkd, urxvt)?

Problems: panel does not launch automatically on startx.

Custom IP on Pynq

Tested with Vivado(HLS) 2017.4

For reference: https://www.youtube.com/watch?v=Dupyek4NUoI

For reference: Pynq-Z1 board part number is xc7z020clg400-1

For reference: Pynq-Z1 board files from: https://github.com/cathalmccabe/pynq-z1_board_files (installation instructions in the .md file in repo)

Steps (roughly) :

1) Easiest way is to start with VivadoHLS, write your own HLS module that interfaces with the host CPU. Add HLS INTERFACE pragmas to define the I/O ports and their types. e.g. #pragma HLS INTERFACE s_axilite port=. You can choose axi, s_axilite, axis for port type (as far as I know for now). Also add #pragma HLS INTERFACE ap_ctrl_none port=return to turn off function call handshake, which creates a whole bunch of extra ports like ap_start, ap_done, ap_idle, and ap_ready, which might not be required. See https://www.xilinx.com/support/answers/55279.html for more info.
2) Run C synthesis, make sure there are no errors and you understand the warnings.
3) Click button for "Export RTL". We can use default settings and click ok. This will package your design as an IP. Choose the language you prefer as well (I go with Verilog mostly).
4) This is the first interesting part to pay attention to: Under "solution1" folder (assuming you're using the default solution name for Vivado synthesis process), go to impl>misc>drivers>"your ip name">src and open x"ip name"_hw.h. Make a note of all the addresses of each register that is being assigned to your ports. You'll need this later to be able to write your software Python drivers that send data to these memory-mapped AXI ports.
5) Switch over to Vivado.

AXI-STREAM interface on Pynq (with DMA)

Obscure artifact #1: Interrupts from AXI DMA block have to be handled by an AXI Interrupt controller, instead of simply concat into IRQ_F2P port of Zynq-PS. See https://forums.xilinx.com/t5/Embedded-Linux/A-key-error-when-I-am-trying-to-access-a-DMA-IP-on-PYNQ-Z1-board/td-p/847817

DFT/FFT footnotes

Mostly grabbed from a great semi-technical summary in a reddit comment, Source: https://www.reddit.com/r/explainlikeimfive/comments/9cbi8p/eli5_what_is_the_fast_fourier_transform_or_fft/e5axg1n/

• The DFT is N dot products of N sized vectors, which means its computational complexity is N². That means doubling your DFT precision results in quadrupling the number of computations.
• The key to the FFT is exploiting the symmetry of the transform kernel, one of the vectors used in the dot product. This allows you to break up your N sized DFT into two N/2 sized DFTs. IE if you have a 128 sized DFT, you can compute it with two 64 sized DFTs, which can be broken to two 32 sized DFTs, and down into two 16 sized, to two 8 sized, etc. This changes the complexity into Nlog₂(N) computational complexity. The smallest size FFT you take is called the "radix," which can be 2, 4, 8 etc.
• To get non power of two sized DFTs you use a "mixed" radix, meaning you factor it into 2, 3, 4, 5, etc sized chunks.
• There are additional optimizations. The first is for a real valued input, the output is symmetric. Meaning if you want to take a 256 sized FFT of real valued inputs (audio, images, stock prices, whatever), you get a 256 sized output with the same values symmetric about the midpoint. So you only need to compute half as many outputs.
• The next optimization has to do with what are called SIMD operations, single instruction multiple data. If you're familiar with GPUs, this is what makes them fast. The DFT is stateless, meaning that a given output point for a particular radix doesn't depend on any other outputs or inputs. This allows you to compute multiple outputs points of the DFT simultaneously.
• Another big optimization that pops up in terminology is "in place" versus "out of place" FFTs. An "in place" FFT writes the output values to the same memory used for the input, this makes the memory complexity O(1) instead of O(N) and it's a major speedup on modern processors, and also critical on embedded systems with limited memory.
• A twiddle factor is a coefficient constant that is precomputed and multiplied with the real data. This is relevant to the recursive Cooley-Tukey (actually, really Gauss) algorithm for doing FFT (instead of the O(N²) DFT). A twiddle factor is also referred to as a phase factor.
• There are a bunch of other tricks to speed up the FFT, like bit twiddling techniques (note: this is not related to twiddle factors described above) on the vector indices to reduce intermediate computations. Generally, this is useful to in-place FFTs (see definition in point above), which are quite challenging to optimize. This is because the destination address being written to does not necessarily swap with the source value being used for the computation. Hence, this requires a permutation computation that trades-off runtime for savings in memory usage. Unfortunately, these permutations can prevent the compiler from recognizing "shared code" in these recursive calls to the FFT algorithm, such as reuse of trigonometric constants. One example is doing a bit-reversal permutation. E.g. FFT-8 inputs can be arranged in natural order, i.e. [0,1,2,3,4,5,6,7]. Each of those indices can be represeted as a 3b number, i.e. [000,001,010,011,100,101,110,111]. By doing a bit-reversal on those 3b, we can compute a new permutation which looks like [000,100,010,110,001,101,011,111], which is [0,4,2,6,1,5,3,7]. Note how this bit-reversal technique has collected all the even indices to the front, and odd-indices to the back. This guarantees the correctness of executing the recursive FFT algorithm, and saves computation time for index calculation.
• Lastly there are some very useful properties of the FFT that make it crucial for modern applications. The first is that the DFT isn't special in and of itself, rather it's a member of a family of operations called Finite Length Orthogonal Transforms, and for a subset of that family the FFT algorithm can be tweaked to compute those other operations. One of the most popular is the DCT, or discrete cosine transform. This is used in almost every lossy compression codec.
• Finally going back to that convolution issue you brought up, that is the operation used for some filtering (think blurring in images, among other tricks). For large filter lengths, the FFT can be used to implement them faster than linear convolution.

Tensorflow visualizing the graph

https://www.tensorflow.org/guide/graphs#visualizing_your_graph

To see the graph of the model you're training, run tensorbord --logdir , and load in browser at port 6006 (e.g. localhost:6006)

Compilers

From: http://venge.net/graydon/talks/CompilerTalk-2019.pdf

Frances Allen "A Catalogue of Optimizing Transformations" (1971 paper). Write 8 passes to get ~80% best-case performance (used by many modern compilers). They are:

• Inline
• Unroll/Vectorize
• Common Subexpression Elimination
• Dead Code Elimination
• Code Motion
• Constant Fold
• Peephole

Support vector machines

Notes from Caltech lecture on SVMs: https://www.youtube.com/watch?v=eHsErlPJWUU

• Goal: maximize the "margin". Solution is obtained analytically.
• "Fat" margin (yellow area below) is intuitively better for doing classification:
  
• Dichotomies of lines of points in a plane (growth function):
  
  3 points have 2^3 = 8 dichotomies. I.e. there are 8 lines we can draw such that each data-point is labeled "X" or "O" in 8 different ways. If all 3 points are collinear (lie on the same line), then "XOX" and "OXO" are not valid dichotomies, since we can't create a valid line that can do the 'XO' binary classification on the points. See example below:
  
  Hence, there are at least 6 dichotomies for 3 points, i.e. less than 2^3 dichotomies.
• However, the growth of the number of dichotomies can get further restricted if we introduce another constraint on the "fatness" of the margin. The fatter the margin, the fewer the number of valid dichotomies, and the more confidence we can have on the out-of-sample error (i.e. validation error) being better. That is, if we maximize the margin when trying to find the classification boundary, we are inherently reducing the out-of-sample error as well.

Kernel Methods

Notes from Caltech lecture on kernel methods: https://www.youtube.com/watch?v=XUj5JbQihlU