UPGRADE YOUR BROWSER

We have detected your current browser version is not the latest one. Xilinx.com uses the latest web technologies to bring you the best online experience possible. Please upgrade to a Xilinx.com supported browser:Chrome, Firefox, Internet Explorer 11, Safari. Thank you!

cancel
Showing results for 
Search instead for 
Did you mean: 
Scholar ronnywebers
Scholar
1,217 Views
Registered: ‎10-10-2014

IP packager - version numbering & version control - best practice

I'm trying to define company standards on how to name & version control (using git) our custom IP, and how to name the source files of that custom IP.

 

Looking at the 'create and package new IP' wizard, we are kind of 'forced' to enter a version number, which becomes :

* part of the display name

* part of the folder name on disk

 

I deliberately entered 2.0 here :

1 - create IP (v2.0).png

 

looking at the initial folder structure :

2 - initial folder structure.png

this '2.0' returns a lot in file names that make up the custom IP.

Notice also the 'bug' in the 'drivers' folder, it's not taking over the version number.

 

this version number is also reflected in the VLNV, with 'rev 1' being the core-revision, and automatically incremented  by IP packager on every 're-package' command :

3 - initial ip catalog view.png

 

now, suppose I added some major new feature, and I want to update my version of the IP to 2.1 -> I can do this in IP packager :

4 - update to 2.1 in IP packager.png

 

so the display name is update to 2.1 -> this is also visible in IP catalog :

5 - rev 1.png

 

We can see that after re-package, the naming on disk of all files & folders stayed the same, except for the xgui script : there is a new script added next to the old script :

6 - folder structure.png

 

so at this point, there's a discrepancy between the version in all the file and folder names, and the 'true / VLNV' version of the IP.

 

So, long story with lot's of screenshots, but here are a few questions :

 

Q1 : what is the use of the Vivado wizard putting the version in moste file and folder name, as descrepancies happen as soon as you update the version in IP packager and re-package?

 

Also, I checked how Xilinx handles their own IP, to see if I could take over this method -  i.e. in the Vivado install folder (data/ip/Xilinx), let's take the 'mem' IP :

7 - xilinx IP.png

 

looks like Xilinx starts a new IP for every 'minor' version update, and puts the 'version' in almost every file and folder name.

 

Q2 : to me, this method doesn't look much VCS / git friendly, or am I missing something : if I want to see the diff between a source file from  the mem_v1_3 ip and mem_v1_5 IP, I must checkout 2 copies and compare the files/folders manually, i.e. compare mem_v1_3_axi_cmd_fsm.sv with mem_v1_5_axi_cmd_fsm.sv

 

This is not how I'm used to do this with software, where we can just compare any 2 commits of a certain source file quickly and easily (i.e. using Sourcetree, SmartGit, ...). This becomes a lot more complicated if the filenames continuously change over time.

 

But ... Xilinx seems to do it this way, and start a new custom IP for every version? So they must see an advantage in doing so? I.e. to support more than 1 version of the IP in a certain Vivado release?

 

I had the following in mind for my own custom IP :

 

1) have no notice of a version in any file or folder name

2) don't start a new custom IP for every new version, but incrementaly work on a single directory and hence git repository over the entire lifetime of the IP

3) increment the version in IP packager when needed :

* Major version update : when API breaks

* minor update : when feature is added or major bug is fixed

* core rev update : when minor bug is fixed

4) use git tags to identify a specific version release  (using this famous gitflow model)

5) use git tags to indicate a migration of the IP to a newever Vivado version

6) if patches are needed on an older version, just branch from that version and work on that branch

 

with a single git repo per IP, for all versions of the IP over time, I would just need checkout the needed version tag of that IP per project,

 

Any thoughts, suggestions, practices, .... are very welcome!

 

 

 

** kudo if the answer was helpful. Accept as solution if your question is answered **
3 Replies
1,181 Views
Registered: ‎03-27-2014

Re: IP packager - version numbering & version control - best practice

Hi,

 

interesting, I faced the same problems a couple of years ago, I'll discuss how we do it nowadays

 

As far as the IP folders problem goes, the entry point ("myip_v1_0" in your example) is arbitrary, it's just here for us: clients, maintainers, human beings.. usually we name it as the IP top level or at least make it explicit.

 

what's the "bug" in the driver folder you are talking about?

 

the "data", "hdl" and etc.. sub folders are arbitrary and once again just here to help the maintainer. Here we use "hdl", "constraints", and pretty much everything like "Vivado HLS". This is defined in "component.xml" through the IP packager,  you could have all those files in the IP base folder, that would be messy, but would work as well, as long as "component.xml" reflects that.


as far as versioning your IPs and keeping track of modifications goes, modifying "v-x.y" in the GUI creates a new /xgui/ file as you figured. Here we usually backup the latest one in our git repo, to avoid misunderstanding, but it actually does not have to be the last one. XGUI will change when you create new GUI related features, like check boxes, conditions etc.. having _v1.tcl defined in "component.xml" while your IP is currently version 3, would work, as long as no GUI features were introduced.

 

Here we also tend to provide a version log to keep track of modifications, I like this a lot because the client can directly see it along the product guide in Vivado. In my company I pushed it even further, like Xilinx I have a documentation template and we provide the same document base so the user gets familiar with it. Once again, you only have to define things properly in the IP packager for this functionality to work, file names & folders do not matter.

 


ronnywebers wrote: 

Q2 : to me, this method doesn't look much VCS / git friendly, or am I missing something : if I want to see the diff between a source file from  the mem_v1_3 ip and mem_v1_5 IP, I must checkout 2 copies and compare the files/folders manually, i.e. compare mem_v1_3_axi_cmd_fsm.sv with mem_v1_5_axi_cmd_fsm.sv

 


simply back up the IP source files and latest/relevant .xml, .tcl source files. Just try to do thing properly in the IP packager and it will work out smoothly. I even developed a tcl script that actually does that for me, so I usually write my HDL and call my IP packaging script, it takes roughly 5 seconds to package the whole thing, and usually my IPs have the same folders structure. The packaging scripts even writes basic and normalized IP documentation

 

"1) have no notice of a version in any file or folder name"

 

Right, its cleaner but keep in mind, as a maintainer what we said about GUI upgrades

 

"2) don't start a new custom IP for every new version, but incrementaly work on a single directory and hence git repository over the entire lifetime of the IP"

 

absolutely right and it works fine too

 

"with a single git repo per IP, for all versions of the IP over time, I would just need checkout the needed version tag of that IP per project"

 

that seems tedious, here we have one git repo for all our IPs (the entire IP library). Works nicely too, just branch for dedicated topics, ie. when adding new features to a given IP

To conclude, here we pretty much tend to use the IP packager "like Xilinx developers do" & try to keep it simple, but some advanced stuff are not documented or even locked to regular Vivado users, which is a bummer and I would really like to work it around (see my other topics)..

G.W.,
NIST - Time Frequency metrology
Scholar ronnywebers
Scholar
1,163 Views
Registered: ‎10-10-2014

Re: IP packager - version numbering & version control - best practice

thanks a lot @guillaumebres for sharing your way of working!

 

* the 'bug' I mentioned is the fact that IP packager creates the myip_v1_0 folder under drivers, which should have been(consistentl with the other naming) myip_v2_0

 

* so for the gui tcl, one must make sure that component.xml refers to the correct one (version in the name of the tcl file does not matter) ?

 

* think I should try to use a tcl script for packing my IP, I read this in the past on the forum I think.

 

* for the documentation template : do you use some tool like doxygen?

 

* I've been thinking about having a single repository for all our IP, and from every project refer to that repository. But it's too limiting for our applications : some projects will need my_ip  v1.2, and other might need v2.0 -> in some cases we prefer not to upgrade every project to my_ip v2.0 (because of re-testing, or impact on software - if it ain't broke, don't fix it :-)

 

 if you have a library commit A like this :

ip1 v1.0

ip2 v2.0

 

commit B:

ip1 v1.1

ip2 v2.0

 

commit C:

ip1 v1.1

ip2 v2.1

 

and you need in a project

ip1 v1.0 

ip2v 2.1

 

-> if it's all a single repo, you cannot get both ip's form a single clone/checkout

 

I've been thinking about using git submodules, but for the time being it's just a repo per IP - but you're right, it looks tedious.

 

Q if I may : if you want to simulate your custom IP (entirely or only some sub-modules of it) during development, how do you handle this? Can you check out this post from me, and give your opinion on that (probably better to keep that simulation topic for my other thread)

** kudo if the answer was helpful. Accept as solution if your question is answered **
0 Kudos
1,130 Views
Registered: ‎03-27-2014

Re: IP packager - version numbering & version control - best practice

hey, 

 

you're more than welcome 

 


@ronnywebers wrote:

 

* so for the gui tcl, one must make sure that component.xml refers to the correct one (version in the name of the tcl file does not matter) ?

 



 the component.xml description is the only thing Vivado has when it comes to adding your IP to a block design. So you just need to make sure it is viable. For the xgui.tcl, Vivado will "version" them by appending whatever version you are packaging, but you could check that its content only changes when you are editing the user interface.


@ronnywebers wrote:

 

 

* think I should try to use a tcl script for packing my IP, I read this in the past on the forum I think.

* for the documentation template : do you use some tool like doxygen?

 



I'll share my script with you in PM there's nothing confidential in it, it's not super interesting either. I just scripted whatever the IP packager is doing and figured it's always doing the same thing, plus I added two or three convenient things. It took me like a day to achieve what I wanted. Our template uses latex. Our IP tool suite uses TCL for packaging & IP simulation, Python for any other stuff: IP verifications, documentation templates etc..

 


@ronnywebers wrote:

 

 

* I've been thinking about having a single repository for all our IP, and from every project refer to that repository. But it's too limiting for our applications : some projects will need my_ip  v1.2, and other might need v2.0 -> in some cases we prefer not to upgrade every project to my_ip v2.0 (because of re-testing, or impact on software - if it ain't broke, don't fix it :-)

  

I've been thinking about using git submodules, but for the time being it's just a repo per IP - but you're right, it looks tedious.


OK i see your point. We actually never faced issues with that because we usually add new features or improve our IPs. Functionalities do not disappear, IPs either get better or more complex. To me, submodule is a pain to work with but I haven't looked at it into detail (things might be changing in a near future too). But yes, that would be the only option to really achieve what you want with git.

 


@ronnywebers wrote:

 

Q if I may : if you want to simulate your custom IP (entirely or only some sub-modules of it) during development, how do you handle this? Can you check out this post from me, and give your opinion on that (probably better to keep that simulation topic for my other thread)


So I have this packaging environment that we already discussed, but I also have a simulation environment. I consider it mandatory to provide a test bench with any IP. It does not have to be packaged probably though. I consider it mandatory because your client will need it when the IP is embedded in a complex function:

 

  • latency could be an issue and they want to be aware of it
  • DSP, maths might produce "non sense" in case it requires initialization, how does your IP deal with that? is that a problem for the overal system?
  • is the internal DSP affected by input truncation & how do I operate internal truncation to really achieve my requirement? 
  • can I actually corrupt my system if this "black box" oscillates or is non stable (non stable transfer function?)
  • the way the overall pipeline behaves might not be what you expect in the first place (is it like a shift register or something else?)

overall it's also the only option for someone who wants a better understanding of how your block operates.

to conclude, packaging is done in shell like "package-ip my_ip --version=1.0 --author=myself"

and simulation is done in a dedicated folder using makefile: "make my_ip --pre --post simulation"
it's fairly simple but can achieve pretty advanced stuff like automated frequency/impulse response monitoring, pattern tests, quantization noise evaluation, noise floor testing is what I do on a daily basis

G.W.,
NIST - Time Frequency metrology
0 Kudos