Does VHDL have an industry standard coding style guidelines?

[matrixofdynamism]

Python has the PEP 8 which is a very detailed document, a very helpful endeavour for Python programmers. Is there a VHDL coding style guidelines that one should learn to follow and implement it in their company? It will cover small details on how to write code that does certain things so that the coding style becomes similar across teams.

 

[TrickyDicky]

There are no official style guidelines. But plenty of companies have tried to enforce their own. The problem is they often end up being out of date very soon after being imposed. The main issue is tool support. Tools are evolving the language templates they support with each new version, and hence if there is a style guide, it would prevent trying out these new templates. I would suggest reading the documentation of the tool vendor you are using and see what templates they support.

Also, as general "idustry standard" practices that are used by most people.
- Use signals for registers. Variables generally only used for combinatorial logic before a register
- Be readable - add plenty of comments explaining WHY you've done something in a certain way. The "how" should be explained by the code itself.
- When using stuff from a package, if you have several packages included, try and be clear where the items are coming from (it can be very annoying hunting through 3/4 packages for a specific function)
- Always use named association
- Try and avoid monolithic processes. Try and break the functionality over several processes if possible.
- When modifying other people's code, keep to their style.

If you stick to the above, you're less likely to antaganise other engineers who have to modify your code.

All of the above applies to synthesisable code. When it comes to simulation - you should generally be free to do what you want. Variables are faster and its great if you use as many of these as possible (remember to remain understandable). Also remember that VHDL has a lot of software style constructs (pointers, protected types) that are very useful for verification, but many people dont seem to use. I highly recommend learning to use them.
Now, it also may be useful to use one of the open source VHDL verification frameworks now available. These would be OSVVM, UVVM, cocotb and VUnit. Each has their strengths and using a common verification framework can save you re-writing the same basic things over and over.

 

[dpaul]

Is there a VHDL coding style guidelines that one should learn to follow and implement it in their company?

Every company has their own, we also have our internal guidelines. You may possibly have to change styles when you change jobs.
Knowing a set of coding guidelines is not a strict criteria for getting a job or changing a job. I have never come across job interviews where they ask you about coding styles.
If you want to use something now, use the comments from Tricky.

 

[kaz1]

Have seen a lot of those in-house rules. Some funny and demoralizing, examples I have seen:

--now is time to declare a package
package.....
--package declared above

--now the input ports
clock: in std_logic; --clock

 

[ads-ee]

Have seen a lot of those in-house rules. Some funny and demoralizing, examples I have seen:

--now is time to declare a package
package.....
--package declared above

--now the input ports
clock: in std_logic; --clock

companies that enforce these kind of coding rules are enforcing useless information to be added to the code, it also results in other inserting more useless comments in the code as that is the recommended style.

What you end up with is code that has no useful comments that have the WHYs of the code (like Tricky suggests) and are instead filled with comments that can just repeat what is in the code.

e.g.

-- The clocked process
main:process(clk,resetn)
-- many hundreds of lines of FSM and outputs with not even a single comment and state names like s1, s2, s3, ..., s100, s101,s102...yes it was an FSM with 100's of states.
end process; -- end of the clocked process

The above example is from code I had to work on recently. This is code has been edited by multiple engineers over the years and none of them added a comment!? This is a case of following the original coding "style" and not doing anything to make the code usable by someone new to the code (is this some stupid form of job security?).

 

[TrickyDicky]

This is a case of following the original coding "style" and not doing anything to make the code usable by someone new to the code (is this some stupid form of job security?).

What could be worse than killing a golden goose? Killing someone else's golden goose

When fixing legacy bugs turns out to be a career-limiting move

www.theregister.com

 

[ads-ee]

@tricky, Oh my, I better refuse to fix any of our products bugs as those bugs must be important to someone. They must want the product to fail when a customer has it.

I better rethink my philosophy of making sure a product works to specification. I don't want to be discovered killing someone else's golden goose...I'd rather be the one accused of sinking the company ship...

 

[wwfeldman]

in general, regardless of language or platform:
document your work
use variable names that have some meaning
comment, comment, comment, preferably in sentences and paragraphs
be clear and straightforward

if in doubt, add more comments

one day you might return to said project
the better you document what you did, the easier it will be for you to "pick up where you left off"

experience indicates you have a choice:
document your work so someone junior can pick it up and continue, and you can move on to bigger and better
or
don't document your work and get Dilbert's "Holy Grail of Computing" - 10,000 lines of spaghetti logic
and never move off that project to bigger and better (until management gets sufficiently frustrated and fires you anyway)

 

[matrixofdynamism]

I have seen a project that has basically no documentation, it was refactoring part of an older project by adding new features. The old project was also not documented and as it turns out, the testbench code was lost and there is only RTL. The production design uses the old code and is few years old now.

The old code is split into literally dozens of small entities, all written in VHDL. The new code which is incomplete attempts to combine functionality of multiple smaller entities into one bigger entity. The older code works as it has been in production for some years. There are no checks done on the new incomplete code to see if any functionality of the old design was broken due to bugs in the refactored code. Also, there is no documentation that can be used to create test and verification plans or to check how many features the old design had which must be verified again in the new design. Also, no list of what specific features are required in the new design for which test and verification plan must be written.

The only thing is, some top level requirements for the new design.

Has anyone seen something like this before?

 

[TrickyDicky]

Yes. I am fairly certain most engineers that have been around a few years will have experienced this. Usually, this would then result in a re-write of the system with new engineer, hopefully improving the situation somewhat.

I would say this used to be more common, but I currently work where we are encouraged to make self checking testbenches and add those testbenches to the CI system when you've "released" your code. So every time the design is modified, the testbench is re-run automatically, and FPGA builds cannot be run when unless all of the testbenches run successfully. I cant talk for all companies but where I have worked for the last 10 years there has been efforts to try and prevent your situation.

We have no formal coding guidelines other than encouraging the above but we are a small mixed firmware/hardware team of 7, but there is now a bigger push to gather requirements and reviews before a single line of code is written. It is usually poor requirements and specification that lead to poor code, rather than the code itself. Add to that the problem of feature creep and leaving engineers to scope and design the project without much scrutiny and it can easily become a problem very quickly.

Setting up CI is not something to do lightly, and does require some admin overhead, but the payoff can be massive. It keeps testbenches relevent and tries to prevent code rot. Im sure we've all been in a situation trying to fix a defect only to find the testbench we want to use no longer compiles let alone runs. We run gitlab but jenkins is an open source option, and often use PyTest as a test runner. Vunit is also an open source python/vhdl testbench ecosystem that does most of the CI heavy lifting for you and can be use to architect a testbench and as a runner.

Other main VHDL options are OSVVM and UVVM but you will have to script these up yourself (OSVVM is starting to provide TCL scripts to get things going running testbenches).

 

[dpaul]

Has anyone seen something like this before?
Yes I had seen something alike. The only relief for me at that time, was just adding a new functionality, verifying just that functionality through simulation, and prove that the total design with the new functionality was working in an FPGA. Those were the worst 6 months of me as an engineer and I did not have much experience when I was given that task. To make matters worse my boss had no idea of hw logic design.

 

[ads-ee]

I have seen a project that has basically no documentation, it was refactoring part of an older project by adding new features. The old project was also not documented and as it turns out, the testbench code was lost and there is only RTL. The production design uses the old code and is few years old now.

Has anyone seen something like this before?

I've seen this far more times than I care to remember.

If the code is as you've describe (sounds like spaghetti hw) then it's going to require a new testbench be written to have a chance of making sure any changes don't break something. You're going to have to treat the code as a black box and determine what the interfaces are and how they are used and build the BFMs to exercise the FPGA code.