Downloading the bitstream freezes everything

Hi, for some reason downloading my bitstream on the board freezes it. The SFTP and SSH connection dies as well and I have to manually restart the board and reconnect. I’m running the simple following code.

from pynq import Bitstream
myDesign = Bitstream(path)

The block design is given below.

I understand the problem is something from my overlay and not the setup, but any pointers to what may be causing it will be a great help. My board is ZC706 and I’m using Vivado 2018.2.


What PYNQ image version you are using?


I believe it is version 2.4


Could you open the Jupyter notebook terminal and confirm?


@briansune I checked, it is version 2.4


Then it is sure you need to alignment both the Vivado and the PYNQ image.
See the PYNQ SD Card image — Python productivity for Zynq (Pynq)
2018.2 is targeted for PYNQ 2.3.

Double check if this is the reason


So I need PYNQ 2.3 for bitstreams generated by Vivado 2018.2, but I have 2.4. Would a bitstream from Vivado 2018.3 work on PYNQ 2.4?


Not only bitstream, you need both hwh and bitstream.
I forgot the old format of the hwh but you should get the meaning.
Both files are required in the same folder, while the Vivado alignment is to prevent the PYNQ loading wrong hwh information and casing the freeze of overlay load.


  • A bitstream to configure the FPGA fabric
  • A Vivado design Tcl file to determine the available IP


Yes, I understand that both a bitstream and hwh/tcl file is needed. Thank you for the clarification, I will work on fixing the version clash.

1 Like

If the board hangs when downloading an Overlay it may be down to reconfiguring the board while a PS-PL AXI transaction is in progress. i.e. the transaction never completes.
Do you think this could be happening in your design? For example, if you have a design that is constantly accessing memory, reconfiguring the PL could happen while an AXI transaction is in progress.
This could happen with some of the early pynq base designs. We added decoupling logic (e.g. DFX AXI Shutdown Manager) to the PS-PL interfaces on more recent designs to protect against this.



Cath do you mean old PYNQ will auto insert LEs as decoupling?
Such decoupling logic will consume how much amount of LEs?
Or this is a hard decoupling controller between ARM PS and the PL?

No, this logic is not inserted automatically. When creating a PL design you need to add this yourself if required.
There are different ways to do this. The IP I mentioned above:


@cathalmccabe In my design, I simply want to send some data from the PS to the PL, and have the PL write the results back after processing. After your comment, I changed some things in my design and started using a DMA for the transfers (design attached). However this bitfile also freezes the board. I don’t have the resources to build the PYNQ 2.3 image for my board so I haven’t tried the other solution yet
axis_design.pdf (92.2 KB)


You had make the topic very confusing.
@aspaul20 design do consist of partial reconfiguration or not?
If not, why DFX decoupling would required?
If DFX do required in old PYNQ revision, no matter how simple it is (i.e. GPIO toggle),
any guide he can follow to do so?

@aspaul20 can is simplest GPIO control overlay work?
If this is working add a simple PL AND OR logic on EMIO GPIO to see it is working.
If they above do show no issue, this can simply remove all confusions.

Do try and should takes minimum of effort to debug and break through such situation.


@briansune I made the following simple design for a gain block and tried running its bitstream. It also resulted in the system freezing.


#include “core.h”

void doGain(hls::stream &inStream, hls::stream &outStream, int gain){

#pragma HLS INTERFACE axis port=outStream
#pragma HLS INTERFACE axis port=inStream
#pragma HLS INTERFACE s_axilite port=gain bundle=CTRL_BUS
#pragma HLS INTERFACE s_axilite port=return bundle=CTRL_BUS

for(int idx=0; idx<(5); idx++){
intSdCh valIn =;
intSdCh valOut; =*gain;
valOut.keep = valIn.keep;
valOut.strb = valIn.strb;
valOut.user = valIn.user;
valOut.last = valIn.last; =;
valOut.dest = valIn.dest;


#include <hls_stream.h>
#include <ap_axi_sdata.h>

typedef ap_axis<32,2,5,6> intSdCh;

void doGain(hls::stream &inStream, hls::stream &outStream, int gain);


#include “core.h”

int main(){
hls::stream inputStream;
hls::stream outputStream;

for (int idx = 0; idx<(5); idx++){
intSdCh valIn; = idx;
valIn.keep = 1; valIn.strb=1; valIn.user=1;; valIn.dest=0;
inputStream << valIn;

doGain(inputStream, outputStream, 2);

for(int idxOut = 0; idxOut < (5) ; idxOut++){

  intSdCh valOut;;
  printf("Value is %d\n", (int);

return 0;


The block design is attached as well.
doGain.pdf (89.5 KB)


Can you first eliminates the HLS. Could a simplest MIO controllable via PYNQ Jupyter notebook?
The python code can simplest as toggle.
Invoke the ZYNQ block and just couples of MIOs.