Best Practices for Hardware Designers

Perhaps you need the "Synopsys Design Reuse Style Guide".

If the designs are 1) going to be reused or 2) need to be interfaced with other engineers such as dedicated verification engineers for formal verification, then the appropriate documentation and standards are appropriate. However, if the design is a single-point solution and will not be reused there *will* be significant waste in getting the code "pretty" enough for someone else to use. A good engineer can parse through HDL and understand the flow of the modules with minor comments. The time to get the understanding is typically less than the time needed to generate documentation in the first place. Once. If the code has to be perused more than once, the payback starts to come in.

For huge code or schematics, documentation is a sincere help. If a Verilog module is used for some glue logic, typically the great dissertations on what the individual elements are up to isn't necessary.

So it's not clear but depends more on the product, the design environment, the support requirements (1 year? 20 years?) and to some extent the turnover rate in the engineering group. If Charlie will always be around, he can always help when his code needs tweaking. If Charlie's expected to move on in a year and the code has a long support lifespan, something's needed.

The standards for any piece of software are the same regardless of what they are compiled to do. The technique you use depends on how you are brought up and what company policy is but every variable or group of variables should be described in one line same with process (function calls)

It is also incredibly important to document exceptions well... if there is something unusual to be handled, then the description should explain the fault, how it is created and what the fixup is. This is more so for hardware than software as real life timings are involved. Hardware should also document interactions between modules... makes it easier to identify triggers especially in state machines.

The idea is to make sure the next person to work on the design understands what is happening.. this can mean the difference between spending a week going thru a design and a month or more.

Simon

Do the three things that nobody teaches and almost nobody does:

Comment, comment, and comment.

John

You can get an improvement in this area, if you change what 'finished' means. To some, it is the first sign of a pulse, on the test bench :)

If you make finished more precisely defined as a sign-off, that includes a verified schematic == HW, & true BOM, that solves the schematic/PCB side.

Getting someone to follow standards in source code is more difficult but you can encourage this with a common template/form for source block headings, that everyone agrees on, and they need to fill out. A problem with mandates on comments, and style itself, is that can degenerate into nit-picking, and there are also the types that view clearer code as reduced job security!

-jg

The only way to do this is by example.

Let it go and get on with your own work.

Consider publishing your own design documentation as a reference for other engineers.

-- Mike Treseler

Hello all, I want to thank you for your comments. I should have said that in 90% of the work that is done is my shop will always come back to the shop for upgrades, or will be passed onto another engineers for testing. In most cases the original engineer is around to answer any questions, but in a hypothetical case if that design engineer left the job position and he/she did not document their work (either in their code or schematics) or decided not to follow a communication interface standard then the new engineer must take additional time to figure that out. I work for the government and when I see this happen I get upset because this extra time costs the taxpayers money. Furthermore, I have taken a few Systems Engineering courses and what I most remember is to document your work and that most engineering problems occur at the interface. I get frustrated when I see my co-worker not following these suggestions and don't set a good example to the newer engineers. Seems to be if one follows some of the things in a Systems Engineering course, or a Risk Management course, or an Interoperability course you actually save the tax payers money for the total cost of the design.

Thanks again and if you find any good web resources on best practiced please let me know.

joe snipped-for-privacy@hotmail.com

There is no good excuse for sloppy work. It doesn't take much time to properly outline and structure code. For FPGA vhdl code I fine following this simple rule useful.

Top level should contain no processes if possible. Processes should be grouped into seperate entities and used as components in the top level.

This has several advantages.

1. You can create individual test benches for simulation of the seperate components. Simulation is much faster.
2. Generation of the RTL schematic provides a cleaner, block diagram look.
3. Individual components(entities) are easier to troubleshoot and optimize.
4. Easier to locate parts of the design which are slow and require additonal work.
5. Tighter control of shared signals. Althought routing these signals between entities is more difficult. It is easier to follow their useage and prevent conflicts.
6. Xilinx ISE tool shows a nice hierarchy tree.
7. Updating the design is easier by adding addtional componets, or modifing only the appropriate component.

Example.

module_control (top.vhd) top.ucf system_tstbd (system_test.vhd) --SIMULATION TESTBENCH pc_interface (pc_intrfc.vhd) pc_tstbd (pc_test.vhd) --SIMULATION TESTBENCH data_in (data_in.vhd) datain_tstbd(datain_test.vhd) --SIMULATION TESTBENCH data_out (data_out.vhd) dataout_tstbd(dataout_test.vhd) --SIMULATION TESTBENCH motor_control (mtr_cntrl.vhd) mtr_tstbd (mtr_test.vhd) --SIMULATION TESTBENCH

Each of the components can be individually synthesized, checked for functionality and maximum performance. Synthesis tool will report the maximum speed. If the design was flat with only one entity, synthesis would report the maximum speed for the slowest process, but you would not know which process.

FPGA's must always be functionally simulated. With most designs, there are thousands of signals and a logic analyzer is useless. A good functional simulation with the proper stimulus will always find your errors and quickly identify the problem.

" snipped-for-privacy@hotmail.com" wrote in news: snipped-for-privacy@g49g2000cwa.googlegroups.com:

From:

Good luck.

Agree with you entirely.

However many (most?) companies are in a mad rush to do things faster.

They don't see the point of slowing down code production for future benefit.

At one job, my predecessor was a fast coder, could re-write heaps overnight, but left the company with next to no documentation about how he meant his code to work. I spent heaps of time reverse engineering it, found lots of things to clean up, and some bits were just messy/confusing. The system had some kind of state machine I could not make elegant or modify without it falling over. That job didn't last! Only my predecessor could understand it, which he did because his new job did not work out and he came back.

One old cow-orker there had a closed mind: "Can't do it like that, there ain't time". Kept repeating statements like that so he didn't have to listen to heretical suggestions that things could be done better or differently.

One of my friends is a software project manager. He regularly finds code that isn't documented and says it is almost always quicker to re-write than to document the old code.

Making anything complex without documentation is like driving without insurance. It saves you time and money and is perfectly fine. Right up to the moment when it isn't! Then you are up shit creek.

Don't skip documentation unless you are prepared to throw your work away, because sooner or later somebody will.

If you are an employer, be aware of the consequences of letting coders skip documentation. They will have you by the snarglies when they ask for a pay rise and you dare not let them go. (hmm, that's not encouraging coders to document stuff is it?)

Documenting a design with text comments from the top down and/or the bottom up, does not take any more total time than any other method. You write them mainly for yourself because design details are quickly forgotten.

A good designer does not slow anything down.

Non-trivial working code -- however ugly -- has value. If you are modifying ugly working code, don't edit it. Write a testbench for it. Do the modifications as a wrapper module. If the ugly code doesn't work, throw it away.

Make working code elegant is icing, not cake. The top focus is to make the changes that the customer wants. Make your own code elegant. Focus on the needed changes first. Recode the ugly module later if there is time, but that is the final task, not the first.

There is no need to understand the internal details to write a testbench for a working design module.

If someone is not helping you, don't waste a minute considering their opinions.

No it isn't. A professional designer is self-motivated. He documents as he goes because it is the fastest way to get the job done.

-- Mike Treseler

Well, documentation is widely considered an unwelcome nuisance job to do, so rightly or wrongly it often gets left out.

I agree that a modest yet useful mount of commenting takes little or no time.

Not everyone is a good designer. Demand outstrips supply.

It wasn't working.

It was not in neat modular form that I could test individual modules.

One early step was to section it into modules so I could know which ones were believed okay or not.

They would not let me.

Agreed, but in this case it was impossible for me to see WTF was going on. Elegant I can read, inelegant I can read, but this was something else beyond that...

Agreed.

But this project didn't even have high-level specs to write a test for.

It was a real-time control system so it was not practical for me to write a testbench to simulate loads of asynchronous events going on (joystick, emergency stop, limit switches, unplugged peripherals, etc).

Alas, their opinions dictate their actions which hindered progress and quality.

I document/comment all my code to make my own life easier (like in a years time when I get asked to mod something) and as a side effect it would help those who inherit my code.

Some more gifted coding virtuosos can carry it all in their head. Great for them, but makes life a bugger for mere demi-geeks like me.

It takes less than no time. The act of commenting cuts debug time more than the time it takes to type the comments, becauses it forces the coder to think about what he's doing. Extreme Programming has similar dynamics: *two* programmers working on a single piece of code are more efficient than one!

John

"Mike Treseler" schrieb im Newsbeitrag news: snipped-for-privacy@comcast.com...

Very good statement! 100 ACK!

Regards Falk

"Kryten" schrieb im Newsbeitrag news:JWXre.25126$ snipped-for-privacy@newsfe1-gui.ntli.net...

What you describe is one of the worst task for an engineer. Fix things that almost work (so thinks your boss, just some small fixes and all is going well). And the ***** that messed it all up is gone. I had this situation more than once, but luckyly the design wasnt too big and they let me throw away the code and rewrite it form the very beginning. But still, a dangerous situation. You end up as the scapegoat.

Regards Falk