Project documentation

[Kevin Kilzer]

Is it reasonable to ask a VHDL designer for planning documents before
coding begins?

Does this seem excessive?
a. general descriptions of the VHDL packages and entities that will
be instantiated, and a block diagram showing the relationships

b. identification of which packages and entities provide
implementation-independent details, and which provide
implementation-dependencies (e.g., packages that define operations vs.
xilinx pin-out wrappers)

c. identification of which packages and entities will likely be
re-used in similar designs that are scheduled but not started

d. count of how many source files will be required for the complete
design

e. VHDL backup, archiving and documentation plans

Thanks in advance.

Kevin

 

[Mike Treseler]

Is it reasonable to ask a VHDL designer for planning documents before
coding begins?

A contractor will charge the same rate to write
documents and research requirements as he will
to write and sim code. I would work out
the requirements in advance and write the
critical ones into the contract.

a. general descriptions of the VHDL packages and entities that will
be instantiated, and a block diagram showing the relationships

I would specify only the top entity
and the top testbench requirements for
function and Fmax. The rest of your
list should be easy to come by once
the design up and simming.

-- Mike Treseler

 

[Mark McDougall]

Does this seem excessive? a. general descriptions of the VHDL
packages and entities that will be instantiated, and a block diagram
showing the relationships
Reasonable.

b. identification of which packages and entities provide
implementation-independent details, and which provide
implementation-dependencies (e.g., packages that define operations
vs. xilinx pin-out wrappers)

Reasonable, as any good engineer will think about these sorts of things
during design/development. However, as Mike hinted at, this will 'fall
out' as the design is implemented.

c. identification of which packages and entities will likely be
re-used in similar designs that are scheduled but not started

IMHO, not the concern of the engineer on this project. As above, a good
engineer will design for re-use (time permitting) but analysis and
second-guessing requirements of other projects is outside the scope of
work. More likely candidates for re-use should be identified outside the
project and written into the requirements for this project.

d. count of how many source files will be required for the complete
design

Definitely not reasonable. And I don't even see why it is important.

e. VHDL backup, archiving and documentation plans

Shouldn't these be the concern of the engineering manager? These should
be governed by company/department-wide policies put in place by
management, and not the place of the project engineer/contractor to specify.

Regards,
Mark

 

[Bill Mills]

Tasks to consider adding:
Points where peer reviews will occur for design and for the VHDL
Code Coverage goals
Bug tracking plan

 

[jpdullius]

Don´t you plan the system that is going to be descripted in diagram
blocks before writting the VHDL code?

 

[Eric Smith]

A contractor will charge the same rate to write
documents and research requirements as he will
to write and sim code.

Some of us might even charge a HIGHER rate for writing requirements
documents and specifications, especially if it wasn't part of the
original contract. Researching and writing that stuff isn't much fun,
in my book.

I would work out the requirements in advance and write the critical
ones into the contract.

Good plan!

 

[Kevin Kilzer]

Reasonable, as any good engineer will think about these sorts of things
during design/development. However, as Mike hinted at, this will 'fall
out' as the design is implemented.


IMHO, not the concern of the engineer on this project. As above, a good
engineer will design for re-use (time permitting) but analysis and
second-guessing requirements of other projects is outside the scope of
work. More likely candidates for re-use should be identified outside the
project and written into the requirements for this project.


Definitely not reasonable. And I don't even see why it is important.


Shouldn't these be the concern of the engineering manager? These should
be governed by company/department-wide policies put in place by
management, and not the place of the project engineer/contractor to specify.

Thanks to you and the others who responded.

You suggest that some of these questions are the responsibility of
"management", so I should tell you that I am that manager. I am
setting (actually resetting), ground rules in a small, growing, design
team. I have been blessed with a VHDL designer that can't seem to
grasp the idea of planning documents, design reviews or version
control. The remainder of the design team is software, so the VHDL
guy thinks he is special.

They way he moans about recording design information, I was starting
to wonder if I was the demon here, or that VHDL guys really are
special. I see by your answers that my concerns are justified.
One of my fears is that the answer to "how many files?" will be "one",
strengthening the notion that the guy is just a hacker.

And just for the record, the owner of the company requested that the
two designs be done concurrently, but it seems that concept is foreign
to him, too. The later project is a superset of the earlier. Had I
understood the situation, I would have started the larger project
first, because it is looking more and more like it will start with a
clean sheet of paper.

Kevin

 

[Mark McDougall]

You suggest that some of these questions are the responsibility of
"management", so I should tell you that I am that manager.

Do you have pointy hair?

They way he moans about recording design information, I was starting
to wonder if I was the demon here, or that VHDL guys really are
special. I see by your answers that my concerns are justified.
One of my fears is that the answer to "how many files?" will be
"one", strengthening the notion that the guy is just a hacker.

*** KLANG !!! *** *** KLANG !!! ***

That's the sound of (very loud) alarm bells ringing.

I'm actually originally from a software background, and all the good
design and project management principles that I learnt are definitely
applicable to VHDL, if not actual hardware (PCB) design as well.

This guy wouldn't get his foot in the door here... we specialise in
delivering our customers' IP so that anything from design maintenance to
manufacturing can be done independently of us.

And just for the record, the owner of the company requested that the
two designs be done concurrently, but it seems that concept is
foreign to him, too. The later project is a superset of the earlier.
Had I understood the situation, I would have started the larger
project first, because it is looking more and more like it will start
with a clean sheet of paper.

I'd give him the task to design the latter, then when it's finished to
your satisfaction, ask him to modify the document for the former. And
all this before he is allowed to write a single line of VHDL. But it
sounds like it's too far down the track for this now?

If his job description requires design documentation, then he can moan
all he likes - but if he wants to keep his job...

Regards,
Mark

 

[Colin Paul Gloster]

On Wed, 8 Feb 2006, Kevin Kilzer wrote:

"[..]

You suggest that some of these questions are the responsibility of
"management", so I should tell you that I am that manager. I am
setting (actually resetting), ground rules in a small, growing, design
team."

I wish you success for this.

" I have been blessed with a VHDL designer that can't seem to
grasp the idea of [..] version
control."

I have edited the quotation with "[..]" not because the omitted items in
the list are unimportant -- they are important -- but because others have
already answered you about them.

Version control is important. A VHDL colleague is quite obsessed with it,
and I have certainly found it useful when using CVS ( WWW.NonGNU.org/cvs/
) that when I check in a new revision of one of over thirty files (for a
small one-man codebase with 959 lines with semicolons), I can document it
better because after so much typing I have at least once forgotten at
least one of at least two major changes but CVS pointed this out to me so
that I documented it better than I would have without a revision tracker.
CVS is not the only tool suitable for tracking changes, but it is the only
one I have used. For a completely new project, it may be worth considering
Subversion ( http://subversion.tigris.org/ ) instead as it is used for GCC
now instead of CVS but many of the alleged improvements will not affect
the early adoption of the tool. Of course, a defiant person might use
preferring to use something which is really easy to learn as an excuse
so perhaps a commercial version control system would be worthwhile. CVS
and probably most others are language-independent, so if your other
software personnel (you and the VHDL employee seem to be under the
misimpression that writing VHDL source code is not writing software)
already use a versioning tool, make the VHDL person use that. That way,
they can check whether he is committing revisions with something other
than a blank comment, they do not need to understand any VHDL to spot
this kind of cheating.

Many versioning tools are discussed in the discussion "CVS or SVN ?!" on
http://lists.gnu.org/archive/html/avr-gcc-list/2005-09/threads.html
and
http://lists.gnu.org/archive/html/avr-gcc-list/2005-10/threads.html

Mentioned in two of those emails, is a still incomplete list of different
versioning tools at
http://better-scm.berlios.de/comparison/comparison.html

If CVS is chosen, instead of starting with the manual, I recommend from
first hand experience reading http://cvsbook.red-bean.com/ and it took me
probably less than a month from starting this free book to starting a
project very well with CVS.

" The remainder of the design team is software, so the VHDL
guy thinks he is special.

They way he moans about recording design information, I was starting
to wonder if I was the demon here, or that VHDL guys really are
special. "

Such arrogance and snobbery towards software people is common in hardware
people, though fortunately not where I am currently based. I have never
had to work with a hardware description language user like this, but I
used to work with a hardware (diodes and resistors etc. with CAD) person
who naively and incorrectly believed that the laws of logic and the laws
of Nature change if you remove functionality from software and transfer
it to hardware: he would do this and eventually find that his attempted
solution was even worse than the original software and revert the
responsibility back to the software developer (i.e. myself).

" I see by your answers that my concerns are justified."

Definitely.

"One of my fears is that the answer to "how many files?" will be "one",
strengthening the notion that the guy is just a hacker.

[..]"

There should be many more than just one file because in a well designed;
loosely coupled; and cohesive sourcebase, intelligibly tracking
(reviewing) changes later can be difficult if the only file changed each
time is the same file because it contains everything.

Regards,
Colin Paul Gloster

 

[Kai Harrekilde-Petersen]

Thanks to you and the others who responded.

You suggest that some of these questions are the responsibility of
"management", so I should tell you that I am that manager. I am
setting (actually resetting), ground rules in a small, growing, design
team.

Congrats, Kevin.

I have been blessed with a VHDL designer that can't seem to
grasp the idea of planning documents, design reviews or version
control. The remainder of the design team is software, so the VHDL
guy thinks he is special.

From where I come from - Ethernet switching silicon, with millions of
gates and lots of RAM on a single die, the "VHDL designer" would have
been thoroughly spanked by peers as well as managers for his lack of
understanding. And if he didn't do it, he'd be doing fpga's instead.

In 0.13um, an error that requires a respin can easily cost 1 mio USD,
just in manpower costs, new masks and extra testing. Depending on the
lifecycle of your product, the lost market revenues/profits can be a
lot higher. And add to that that you're late for the next project...

IMHO, you *must* start with documentation, specification,
requirements. Otherwise, how do you know what you're going to build?
How do you know when you're done?

The "number of files" thing is somewhat a religiuos thing (dangerous
to say in these days), but we chose to cut every design unit into a
separate file, e.g. every architecture, entity, package, package body,
and configuration had it's own file. This reduces the number of files
you need to recompile/resynthesize, when a single file is changed
(unless it's a central package).

Sure, we're extreme, but c'mon it's not that big a problem. Also, it
makes it easier to identify the right file when filename and
arch/ent/package identifier is the same.


Kai

 

[Colin Marquardt]

You suggest that some of these questions are the responsibility of
"management", so I should tell you that I am that manager. I am
setting (actually resetting), ground rules in a small, growing, design
team. I have been blessed with a VHDL designer that can't seem to
grasp the idea of planning documents, design reviews or version
control. [...]
One of my fears is that the answer to "how many files?" will be "one",
strengthening the notion that the guy is just a hacker.

Uh oh. I guess in that case it's best to require even more
documentation than usual (and review doc and code, and ideally run
the code through a lint tool), for the case that you have to replace
him or get someone else into the team.

In addition to the design itself and its documentation, there should
be a verification plan so that you have a way to determine when you
are done simulating.

http://verificationguild.com/modules.php?name=Forums&file=viewtopic&t=1045
has a list of things to include in that plan, although it's probably
a bit on the excessive side.

And most of the points in "The Joel Test"
(http://www.joelonsoftware.com/articles/fog0000000043.html) also
apply to writing in a HDL, not just traditional software.

Good luck,
Colin

 

[Andy Peters]

On Wed, 8 Feb 2006, Kevin Kilzer wrote:
" I have been blessed with a VHDL designer that can't seem to
grasp the idea of [..] version
control."

I have edited the quotation with "[..]" not because the omitted items in
the list are unimportant -- they are important -- but because others have
already answered you about them.

Version control is important. A VHDL colleague is quite obsessed with it,
and I have certainly found it useful when using CVS ( WWW.NonGNU.org/cvs/
) that when I check in a new revision of one of over thirty files (for a
small one-man codebase with 959 lines with semicolons), I can document it
better because after so much typing I have at least once forgotten at
least one of at least two major changes but CVS pointed this out to me so
that I documented it better than I would have without a revision tracker.
CVS is not the only tool suitable for tracking changes, but it is the only
one I have used. For a completely new project, it may be worth considering
Subversion ( http://subversion.tigris.org/ ) instead as it is used for GCC
now instead of CVS but many of the alleged improvements will not affect
the early adoption of the tool.

I've found that since I started using version control -- specifically,
Subversion -- I'm a lot more organized and I'm able to tell the boss
immediately what change I made to the latest version of my FPGA.

I use Subversion for my FPGA designs -- the sources, test benches,
build scripts, everything you need to build a chip gets put into the
repository (but no binaries or build results). When I decide my design
is ready for a pre-release for testing by others, I tag it and include
the binaries (.mcs or whatever) in the tag; this way I can keep track
of versions in various boards. Once we decide that a prerelease design
is golden, it's tagged as a release version.

Modules that I'll use in more than one design are in the repo as their
own "projects," and they're included in the chip design using svn's
externals property. This way, when you check out a project, you
automagically get not only design files specific to the design but also
the common modules.

I also use Subversion for microcontroller and DSP firmware as well as
host (Windows) software that I've written to drive test fixtures. I
even put schematics and PCB layouts into the repo, although you can't
diff them. (Subversion does a good job of compressing binaries so they
don't eat up a lot of space in the repo.) The great thing about
putting schematics and layouts into the repo is that when you commit a
change, you have to include a comment, and it's a lot easier to put a
verbose "this is what I did and why I did it" comment in the repo than
in the schematic.

Once you start understanding the power of a version-control system, you
start to wonder how you ever got along without one. And if you're
using Subversion on Windows, you should use TortoiseSVN
(http://tortoisesvn.tigris.org/), which is a Windows shell extension
that's remarkable. It gives instant indication as to the status of a
working copy. It does a great job of hiding the command-line
complexity and makes version control easy.

FWIW, if you're choosing a version-control system, avoid Microsoft
Visual Source Safe. Yuck.

-a

 

[Kevin Kilzer]

<...and...>


I've found that since I started using version control -- specifically,
Subversion -- I'm a lot more organized and I'm able to tell the boss
immediately what change I made to the latest version of my FPGA.

I fully agree. For software, I not only use CVS, but also a wiki. In
the wiki, we (my software colleagues and I), can record overviews of
major changes and bug investigations, then add links to the CVS
browser pages in case anyone wants to see the diff.

We have tried to lead by example, but the VHDL guys won't get on
board. A guy from another project has some phobia that CVS will
change carriage returns in his source, and that will somehow break the
Xilinx compiler. He had a bad experience 5 or 6 years ago at a
different employer, and now the entire group is stuck.

Thanks again for all the good comments. I just looked in the mirror,
and I don't see pointy hair, yet.

Kevin

 

[Colin Paul Gloster]

On 9 Feb 2006 11:40:46 -0800, "Andy Peters" <[email protected]>
wrote:
"I've found that since I started using version control [..]
I'm able to tell the boss
immediately what change I made [..]"

Though I am able to do this, I used to be managed by someone who did not
and does not care to read the version control system's logs and replaced
me with someone who admitted "I really don't use CVS like I should" who so far
(after replacing me in October 2005) has uploaded files once to the CVS
server (in January 2006) with drastic changes and just "*** empty log
message ***" for everything.

On Fri, 10 Feb 2006, Kevin Kilzer wrote:

"[..]

We have tried to lead by example, but the VHDL guys won't get on
board. A guy from another project has some phobia that CVS will
change carriage returns in his source, and that will somehow break the
Xilinx compiler. He had a bad experience 5 or 6 years ago at a
different employer, and now the entire group is stuck.

[..]"

Bull. For many reasons. The line endings can be changed if such a problem
is ever caused by any tool. As for CVS specifically, the ignoramous (I am
aware this is not the same VHDL person who you had mentioned in an earlier
post in this thread) must be forced to read
the paragraph immediately before
http://cvsbook.red-bean.com/cvsbook.html#Repository Permissions
and
http://cvsbook.red-bean.com/cvsbook.html#CVS is not doing line-end conversion correctly
and not be allowed to make up excuses without checking reality.