Tutorial: Creating a Custom Bitfile: Difference between revisions

From Cpre584
Jump to navigation Jump to search
← Older edit
Tyler07 (talk | contribs)
45 edits
 
(25 intermediate revisions by 2 users not shown)
Line 2: Line 2:


== Building a Bitfile ==
== Building a Bitfile ==
Copy rev 2011_11_22 of the [[Running the Vector Adder Example Application#Compiling the Project|example project]] and set your [[Convey environment setup|environment variables]] if you have not done so already.  You can make a small modification to the verilog code if you wish.
Copy the newest version of the [[Running the Vector Adder Example Application#Compiling the Project|example project]] and set your [[Convey environment setup|environment variables]] if you have not done so already.  You can make a small modification to the verilog code if you wish, such as making it a vector subtractor instead of a vector adder.
 
Next, compile your bitfile:


  cd ~/pdk_sample/cae_vadd/phys
  cd ~/pdk_sample/cae_vadd/phys
  make
  make


The bitfile will take a long time to create (while the Reference Manual states 2 to 4 hours; mine took 18 hours to finish).  Be patient.
The bitfile will take a long time to create (while the Reference Manual states 2 to 4 hours, it may take much longer).  Be patient.


== Packaging the Bitfile ==
Next, package your bitfile using the command:


cd ~/pdk_sample/cae_vadd/phys
  make release
  make release


This will create a new directory (~/pdk_sample/cae_vadd.release/).  Then something magical happens that I don't quite understand yet.
After make release has finished there will be a directory on the same level as your top level project directory called:
 
myproject.released
 
Inside of that folder there will be a folder with the current date. Go to the most recent directory and there will be a file called cae_fpga.tgz, this file needs to be copied into the directory:
 
/myprojectname/personalities/<personality number>/
 
Example command:
 
cp cae_fpga.tgz ../../myprojectname/personalities/<personality number>/ae_fpga.tgz
 
Note that cae_fpga.tgz needs to be renamed to ae_fpga.tgz
 
Note that make and make release will NOT do this copy for you. If you forget you will still be using the old personality
 
 
=== FPGA Usage Statistics ===
 
The device usage statistics are displayed on the terminal while building the bitfile.  The log is saved to disk at:
 
{project directory}/phys/cae_fpga.map
OR
{project directory}/phys/cae_fpga.par
 
Search the end of the log file for "Design Summay" for a percentage break down in LUT, Flip flop, and BRAM usage.
 
== Choose a New Signature ==
Custom personalities should not use the default PDK signature (4.1.1.1.0).  Choose a new signature between 65000 and 65535.  In this example, we will use 65123.1.1.1.0.
 
You will need to create a new directory and copy the pertinent files to this directory:
 
cd /opt/convey/personalities
mkdir 65123.1.1.1.0
cd 65123.1.1.1.0
cp /home/PROJECT_RELEASE/DATE/cae_fpga.tgz ./ae_fpga.tgz
 
This is the only required file, but you may copy PersDesc.dat from the default PDK folder to your new folder and uncomment additional custom instructions you have used.
 
  cp /opt/convey/personalities/4.1.1.1.0/PersDesc.dat ./
 
Instead of adding a new directory to Convey's personality folder as done above, you may set the CNY_PERSONALITY_PATH environment variable to any directory, i.e.
 
export CNY_PERSONALITY_PATH=/home/PROJECT_PATH/
  or
setenv CNY_PERSONALITY_PATH /home/PROJECT_PATH/
 
The default when the CNY_PERSONALITY_PATH is not set is to use the /opt/convey/personalities folder.


== Installing the Bitfile ==
You will also need to update the ''customdb'' file in /opt/convey/personalities (or create your own customdb file in your user defined personalities folder).  This file is used by the cny_get_signature function and converts strings to a signature number.  Our customdb file contains the following text: 


Any ideas? Intuition tells me we'd need higher privilledges to install the RPM to the /opt/convey/personalities/ folder.
  65123.1.1.1.0,subtractor


== Using the Bitfile in C Code ==
Finally, there are certain places in the code where you should ensure that the signature has been updated.
My current understanding is that running a routine on the coprocessor requires two parts:
* A call to the '''cny_get_signature''' function to get the signature of the custom personality you created
* A cny coprocessor funcation call (ex: l_copcall_fmt, d_copcall_fmt, etc)


If you want to pass parameters to your function call, the vector adder set the standard of using an assembly file to marshal registers back and forth between the processor / coprocessor, though there may be other ways.
* In the simulator (/sim/CaeIsaVadd.cpp), update: '''#define PERS_SIGN_CAE 0xfe63001000101000LL''', where 0xfe63 is the hex value for your signature (65123).
* In the C code, (SampleAppVadd/UserApp.c) update: '''cny_get_signature("subtractor", &sig, &sig2, &stat);''', where "subtractor" is the pseudo name of your CAE given in the customdb file.
* In the assembly code, (SampleAppVadd/cpVadd.s) update the signature directive: '''.signature pdk=65123'''


=== Getting the Signature ===
When you change the personalities directory, flush the MP cache.  This will erase the cache, which is necessary if you've updated your custom bitfile:
  cny_image_t        sig2;
  cny_image_t        sig;
  int stat;
  if (cny_get_signature)
    cny_get_signature("your custom personality name", &sig, &sig2, &stat);
  else
    fprintf(stderr,"ERROR: cny_get_signature not found\n");


=== Allocated Memory on the Coprocessor Board ===
  /opt/convey/sbin/mpcache -f
System memory and memory used for the coprocessor are physically separate. In the example C file, function calls such as '''cny_cp_malloc''' and '''ny_cp_posix_memalign'''.


See: [[Media:ConveyProgrammersGuide.pdf | Convey Programmers Guide (.pdf)]] - Chapter 9
You can also add a signature, and preload a given bitfile by using the commands:


=== Making a Coprocessor Call ===
/opt/convey/sbin/mpcache -add  -S<personality number>
The vector adder example uses:
  /opt/convey/sbin/mpcache -load -S<personality number>
  act_sum = l_copcall_fmt(sig, cpVadd, "AAAA", a1, a2, a3, size);


In this case, the l at the beginning of l_copcall_fmt means the return type is a long (64 bits). The first two arguments are always (1) the bitfile signature and (2) a assembly function name. The third argument lists the type and number of optional arguments that are passed (starting at register A8).  For example, "AAAA" means there are 4 long variables passed to the coprocessor call.
Additional details are available in Appendix D of the [[Media:ConveyPDKReferenceManual.pdf | Convey PDK Reference Manual (.pdf)]].


See: [[Media:ConveyProgrammersGuide.pdf | Convey Programmers Guide (.pdf)]] - Appendix G
== See Also ==
* [[Using a Custom Bitfile in C Code]]


== References ==
== References ==
* [[Media:ConveyPDKReferenceManual.pdf | Convey PDK Reference Manual (.pdf)]] - Sections 9.4.6, 9.4.7, 10 and Appendix D
* [[Media:ConveyPDKReferenceManual.pdf | Convey PDK Reference Manual (.pdf)]] - Sections 9.4.6, 9.4.7, 10, Appendix D
* [[Media:ConveyProgrammersGuide.pdf | Convey Programmers Guide (.pdf)]] - Chapter 9 and Appendix G

Latest revision as of 02:12, 5 February 2013

This page covers the creation and installation of a custom personality/bitfile (a modification of the vector adder sample project).

Building a Bitfile

Copy the newest version of the example project and set your environment variables if you have not done so already. You can make a small modification to the verilog code if you wish, such as making it a vector subtractor instead of a vector adder.

Next, compile your bitfile: 

cd ~/pdk_sample/cae_vadd/phys
make

The bitfile will take a long time to create (while the Reference Manual states 2 to 4 hours, it may take much longer). Be patient.

Next, package your bitfile using the command: 

make release

After make release has finished there will be a directory on the same level as your top level project directory called: 

myproject.released

Inside of that folder there will be a folder with the current date. Go to the most recent directory and there will be a file called cae_fpga.tgz, this file needs to be copied into the directory: 

/myprojectname/personalities/<personality number>/

Example command: 

cp cae_fpga.tgz ../../myprojectname/personalities/<personality number>/ae_fpga.tgz

Note that cae_fpga.tgz needs to be renamed to ae_fpga.tgz

Note that make and make release will NOT do this copy for you. If you forget you will still be using the old personality


FPGA Usage Statistics

The device usage statistics are displayed on the terminal while building the bitfile. The log is saved to disk at: 

{project directory}/phys/cae_fpga.map
OR
{project directory}/phys/cae_fpga.par

Search the end of the log file for "Design Summay" for a percentage break down in LUT, Flip flop, and BRAM usage.

Choose a New Signature

Custom personalities should not use the default PDK signature (4.1.1.1.0). Choose a new signature between 65000 and 65535. In this example, we will use 65123.1.1.1.0.

You will need to create a new directory and copy the pertinent files to this directory: 

cd /opt/convey/personalities
mkdir 65123.1.1.1.0
cd 65123.1.1.1.0

cp /home/PROJECT_RELEASE/DATE/cae_fpga.tgz ./ae_fpga.tgz

This is the only required file, but you may copy PersDesc.dat from the default PDK folder to your new folder and uncomment additional custom instructions you have used. 

cp /opt/convey/personalities/4.1.1.1.0/PersDesc.dat ./

Instead of adding a new directory to Convey's personality folder as done above, you may set the CNY_PERSONALITY_PATH environment variable to any directory, i.e. 

export CNY_PERSONALITY_PATH=/home/PROJECT_PATH/
  or
setenv CNY_PERSONALITY_PATH /home/PROJECT_PATH/

The default when the CNY_PERSONALITY_PATH is not set is to use the /opt/convey/personalities folder.

You will also need to update the customdb file in /opt/convey/personalities (or create your own customdb file in your user defined personalities folder). This file is used by the cny_get_signature function and converts strings to a signature number. Our customdb file contains the following text: 

65123.1.1.1.0,subtractor

Finally, there are certain places in the code where you should ensure that the signature has been updated.

  • In the simulator (/sim/CaeIsaVadd.cpp), update: #define PERS_SIGN_CAE 0xfe63001000101000LL, where 0xfe63 is the hex value for your signature (65123).
  • In the C code, (SampleAppVadd/UserApp.c) update: cny_get_signature("subtractor", &sig, &sig2, &stat);, where "subtractor" is the pseudo name of your CAE given in the customdb file.
  • In the assembly code, (SampleAppVadd/cpVadd.s) update the signature directive: .signature pdk=65123

When you change the personalities directory, flush the MP cache. This will erase the cache, which is necessary if you've updated your custom bitfile: 

/opt/convey/sbin/mpcache -f

You can also add a signature, and preload a given bitfile by using the commands: 

/opt/convey/sbin/mpcache -add  -S<personality number>
/opt/convey/sbin/mpcache -load -S<personality number>

Additional details are available in Appendix D of the Convey PDK Reference Manual (.pdf).

See Also

References

Retrieved from "https://wikis.ece.iastate.edu/cpre584/index.php?title=Tutorial:_Creating_a_Custom_Bitfile&oldid=803"