catbstream.py
=============

This is a simple program that allows for concatenating two FPGA bitstreams
into one contiguous bitstream. It is intended for applications where two
bitstreams are stored on a Flash chip for applications such as MultiBoot.

The script asks the user for the bitstream file names (two input and one
output) and stores the concatenated version of the two bitstreams to the
output file.

There can be two modes of running:
(1) -- Concatenate two raw .bin files to another .bin file
(2) -- Concatenate two Xilinx .bit files to an .mcs file

In both cases, you are asked for the input and output files. Note that you
have to supply the input and output file extensions, and if they are not
correct, the script warns you and exits.


(1) Two .bin files into another .bin file
-----------------------------------------

In this mode, the second second bitstream starts on a sector boundary. If the
first bitstream is smaller than the second, the script pads with zeroes until
the sector boundary.

The output bitstream of two concatenated bitstreams would look like this:

0x000000     ================================
                      bitstream 1
                      bitstream 1
                      bitstream 1
[end bs1]    ...................0000000000000
             00000000000000000000000000000000
[next sect]  ================================
                      bitstream 2
             ================================

At the time of writing of this readme, the file is designed for M25P flash
chips, which have 64kB sectors. To change the sector boundaries, all one needs
to do is change line 39 in the file for the sector boundary on his or her
flash of choice:

  # 0x10000 is the sector boundary in the M25P flash
  lt = 0x10000 - (len(a1)%0x10000)



(2) Two .bit files into an .mcs file
------------------------------------

In this mode, the script makes use of the Xilinx PROMGEN tool. You also need
to do more work than before, in that apart from the input files, you also have
to give the flash chip size and start addresses for the bitstream.

Then, the script calls the PROMGEN tool to do all the work of concatenating
the bitstreams.

Note that apart from the needed .mcs file, some extra output files are also
generated. However, you don't need to worry about these, only the .mcs should
be interesting to you.

