Best Practices for Hardware Designers

Hello, I'm looking for some information that describes some of the best
practices or habits for successful electronic design or embedded
design. I'm trying to convince some co-workers that it is important to
document their work and follow standards in their designs. Some of my
co-workers are very fast designers and are respected by their peers,
but in their rush to get the design done they often ignore standards
and don't document their work, such as in their schematics or in their
FPGA code. I feel these habits and behavior actually wastes money, by
that I mean that if someone has to take their undocumented work, they
won't know what is going on. I realize that I might not be able to
change more senior engineers, but I might be able to leave an
impression on the newer engineers. If anyone knows of some habits or a
list of some best practices that make a successful design, please pass
them onto me. Most of these habits I would assume fall into proper
system engineering.

thanks,
joe

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

jjlindula@hotmail.com wrote:

> Hello, I'm looking for some information that describes some of the best
> practices or habits for successful electronic design or embedded
> design. I'm trying to convince some co-workers that it is important to
> document their work and follow standards in their designs. Some of my
> co-workers are very fast designers and are respected by their peers,
> but in their rush to get the design done they often ignore standards
> and don't document their work, such as in their schematics or in their
> FPGA code. I feel these habits and behavior actually wastes money, by
> that I mean that if someone has to take their undocumented work, they
> won't know what is going on. I realize that I might not be able to
> change more senior engineers, but I might be able to leave an
> impression on the newer engineers. If anyone knows of some habits or a
> list of some best practices that make a successful design, please pass
> them onto me. Most of these habits I would assume fall into proper
> system engineering.
> 
> thanks,
> joe

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


"JJ" <johnjakson@yahoo.com> wrote in message
news:1118530886.298739.256360@o13g2000cwo.googlegroups.com...
>
> Perhaps you need the "Synopsys Design Reuse Style Guide".
>

On 11 Jun 2005 15:03:31 -0700, "jjlindula@hotmail.com"
<jjlindula@hotmail.com> wrote:

>Hello, I'm looking for some information that describes some of the best
>practices or habits for successful electronic design or embedded
>design. I'm trying to convince some co-workers that it is important to
>document their work and follow standards in their designs. Some of my
>co-workers are very fast designers and are respected by their peers,
>but in their rush to get the design done they often ignore standards
>and don't document their work, such as in their schematics or in their
>FPGA code. I feel these habits and behavior actually wastes money, by
>that I mean that if someone has to take their undocumented work, they
>won't know what is going on. I realize that I might not be able to
>change more senior engineers, but I might be able to leave an
>impression on the newer engineers. If anyone knows of some habits or a
>list of some best practices that make a successful design, please pass
>them onto me. Most of these habits I would assume fall into proper
>system engineering.
>
>thanks,
>joe

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

Comment, comment, and comment.

John

jjlindula@hotmail.com wrote:

> Hello, I'm looking for some information that describes some of the best
> practices or habits for successful electronic design or embedded
> design. I'm trying to convince some co-workers that it is important to
> document their work and follow standards in their designs. Some of my
> co-workers are very fast designers and are respected by their peers,
> but in their rush to get the design done they often ignore standards
> and don't document their work, such as in their schematics or in their
> FPGA code. I feel these habits and behavior actually wastes money, by
> that I mean that if someone has to take their undocumented work, they
> won't know what is going on. I realize that I might not be able to
> change more senior engineers, but I might be able to leave an
> impression on the newer engineers. If anyone knows of some habits or a
> list of some best practices that make a successful design, please pass
> them onto me. Most of these habits I would assume fall into proper
> system engineering.

  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

jjlindula@hotmail.com wrote:

>  I'm trying to convince some co-workers that it is important to
> document their work and follow standards in their designs.

The only way to do this is by example.

> Some of my
> co-workers are very fast designers and are respected by their peers,
> but in their rush to get the design done they often ignore standards
> and don't document their work, such as in their schematics or in their
> FPGA code.

Let it go and get on with your own work.

> I realize that I might not be able to
> change more senior engineers, but I might be able to leave an
> impression on the newer engineers.

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
jjlindula@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.




"jjlindula@hotmail.com" <jjlindula@hotmail.com> wrote in 
news:1118527411.599463.25430@g49g2000cwa.googlegroups.com:

> Hello, I'm looking for some information that describes some of the best
> practices or habits for successful electronic design or embedded
> design. I'm trying to convince some co-workers that it is important to
> document their work and follow standards in their designs. Some of my
> co-workers are very fast designers and are respected by their peers,
> but in their rush to get the design done they often ignore standards
> and don't document their work, such as in their schematics or in their
> FPGA code. I feel these habits and behavior actually wastes money, by
> that I mean that if someone has to take their undocumented work, they
> won't know what is going on. I realize that I might not be able to
> change more senior engineers, but I might be able to leave an
> impression on the newer engineers. If anyone knows of some habits or a
> list of some best practices that make a successful design, please pass
> them onto me. Most of these habits I would assume fall into proper
> system engineering.
> 
> thanks,
> joe
> 

From: <jjlindula@hotmail.com>

> I'm trying to convince some co-workers that it is important to
> document their work and follow standards in their designs.

Good luck.

> Some of my
> co-workers are very fast designers and are respected by their peers,
> but in their rush to get the design done they often ignore standards
> and don't document their work, such as in their schematics or in their
> FPGA code. I feel these habits and behaviour actually wastes money, by
> that I mean that if someone has to take their undocumented work, they
> won't know what is going on.

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?)