data2mem_how_to_use_it_with_picoblaze.txt

Some useful PicoBlaze sources.

A way to use DATA2MEM with PicoBlaze
------------------------------------

Ken Chapman - Xilinx Ltd - 5th July 2005


Introduction
------------

DATA2MEM is a utility which allows the contents of the Block Memories of a device to be changed directly 
in the configuration BIT file without having to recompile the whole design. Since PicoBlaze (KCPSM3) executes
its program from Block Memory, this utility clearly provides a convenient method for modifying PicoBlaze
programs particularly during code development. It is also extremely useful for managing designs containing 
multiple PicoBlaze processors as each PicoBlaze program can be modified independently.

Although DATA2MEM has been provided with ISE for some time, it was not until ISE v7.1i that it supported the 
full 18-bit mode (parity bits) used by the KCPSM3 instructions. It is therefore vital that you are using 
ISE v7.1i or later for the following advice to work.
  
There are several design flows in which DATA2MEM can used including ISE Project Navigator and some advanced 
techniques. However, the objective of this description and associated files is to provide you with one very 
simple flow which is executed from within the DOS window where you will be running the KCPSM3 assembler to 
make code changes. 

Provided with this file is a utility program called 'PB_BMM.EXE' and a batch file called 'change_pb_bits.bat'.
It is hoped that these will provide you with rapid success at using DATA2MEM to modify PicoBlaze programs. 
Should these tools not be successful, or if you want to adapt the way they are used, then there is further 
more detailed descriptions for you to read.

Note that the JTAG_loader utility is still the fastest way to update a single PicoBlaze providing it is 
convenient to use the JTAG port for this purpose. DATA2MEM allows modification to any PicoBlaze program 
ROM in the design without any changes to the actual design. 


7 simple steps to High Speed Code Changes
-----------------------------------------

1) Create your design including at least one KCPSM3 PicoBlaze in the normal way. It will help if your
   instantiation of the program ROM is made using an easily identifiable instance name.
   At the end of this process, your working directory will contain many files but should definitely 
   include the following key files:-
          design_name.ncd   - This is the main design database which can be viewed in FPGA Editor
          design_name.bit   - This is the configuration file for your design (try it in the device!)
              program.psm   - This is an assembler program for your PicoBlaze.

2) Copy the supplied 'PB_BMM.EXE' and 'change_pb_bits.bat' files into your working directory.

3) Make the changes you wish to make to the KCPSM3 assembler program.

4) Open a DOS window in your working directory (just as you would to run KCPSM3).

5) Run the batch file using the following command (note no file extensions)... 
     change_pb_bits progname design_name

6) Assuming your programs assembles correctly, after a sort time you will be presented with a the 
   list containing the instance names and locations of all the Block Memories in your design. If  
   the list is too large to fit in the DOS window you can also view it by opening the 'RAM_LIST.TXT'
   which will have been created in your working directory.
     Enter the number of the Block Memory associated with your PicoBlaze program. 
  
7) A new configuration BIT file will be generated with the same name as the original but preceded 
   with 'new_' (e.g. new_design_name.bit) and you may now download this to your device using Impact
   in the normal way. Note you can start a new Impact project by typing 'impact' in the DOS window. 


Obviously subsequent iterations can use steps 3 to 7 only and further streamlining is possible if you 
read further and understand what steps are being performed in this process.



How does it work?
-----------------

The 'change_pb_bits.bat' batch really documents the stages and options and could easily be modified
to suit your own particular needs and desires. I will now go through the supplied batch file to explain 
what is happening at each stage.

> kcpsm3 %1

The KCPSM3 assembler is run which results in a MEM file which defines the new program op-codes.
Note that this file is only generated by KCPSM3 version v1.30 or later.

> pb_bmm %1.bmm %2.ncd

Having checked that a MEM file was generated by the assembler, the PB_BMM.EXE utility is used to create 
a BMM (Block RAM Memory Map) file. This file describes which Block Memory is to be modified and where it 
is located in the device. This is very simple text files which can be created manually using a text editor
and the following template....

ADDRESS_SPACE <tag_name> RAMB18 INDEX_ADDRESSING [0x00000000:0x000003FF]
    BUS_BLOCK
        <instance_name> [17:0] PLACED = <location>;
    END_BUS_BLOCK;
END_ADDRESS_SPACE;

Although <tag_name> can be virtually any sensible identifier of your own choosing, the <instance_name>
and <location> strings need to be exactly right for your particular design. Obviously you will need to 
a have reasonable idea of the instance name of the Block Memory to be able to distinguish it from any of 
the others that may be in the design, but it is not always easy to determine the exact name when it 
includes the description of hierarchy as well. Likewise, unless you have constrained the position of the 
Block Memory in your design (only to be done in special circumstances) then it is unlikely you will know 
the location.

Fortunately, there are several ways to determine the exact instance name and location of the Block RAM and 
what the PB_BMM utility uses is a Xilinx program called 'xdl'. You can perform the same steps as PB_BMM 
manually if you like.... 

Open a DOS window in your project directory and enter the command as follows:

      xdl -ncd2xdl <design_name>.ncd 

Afer a few seconds a new file should be created called '<design_name>.xdl'. This a a simple text file 
which you can open with a text editor (e.g. Wordpad) and contains a complete description of every instance 
in your design. Your aim is then to locate the Block Memory associated with PicoBlaze. Try using the 'find'
facility in your text editor, search for instances of 'RAMB16' until you recognise it as being the one you 
are interested in. Hopefully you will be able to select a line which looks something like this example:

     inst "program_rom/ram_1024_x_18" "RAMB16",placed BMR8C2 RAMB16_X1Y4  ,

From this you can abstract the vital information to complete the BMM file. In this case the instance name 
and locations are as follows:

     <instance_name> = program_rom/ram_1024_x_18
          <location> = X1Y4

Once a BMM file has been created it does not need to be changed unless you reprocess the design which could 
result in a modified instance name and different placement. So if your only changes are to the PicoBlaze 
program, then the generation of the BMM file can be avoided.


> data2mem -bm %1.bmm -bd %1.mem -bt %2.bit -o b new_%2.bit

Finally the real task of changing the bit file can take place. DATA2MEM must be told the names of the 3 input
files and the new output BIT file. You could generate a new file for every iteration or continuously overwrite 
the original 'design_name.bit' file depending you your personal preference.




Feedback
--------

I do hope this has been a useful introduction to this facility and I would welcome any direct feedback
or suggestions.

[e-mail]

I would also encourage you to share all your PicoBlaze experiences and questions with other users via the 
PicoBlaze Forum which is located at 

www.picoblaze.com

   Select one of the PicoBlaze options (e.g. PicoBlaze for Spartan-3) and then the forum is accessed on the 
   right side of the page.