Project documentation

Discussion in 'VHDL' started by Kevin Kilzer, Feb 7, 2006.

  1. Kevin Kilzer

    Kevin Kilzer Guest

    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
     
    Kevin Kilzer, Feb 7, 2006
    #1
    1. Advertising

  2. Kevin Kilzer wrote:

    > 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
     
    Mike Treseler, Feb 7, 2006
    #2
    1. Advertising

  3. Kevin Kilzer wrote:

    > 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
     
    Mark McDougall, Feb 7, 2006
    #3
  4. Kevin Kilzer

    Bill Mills Guest

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

    Kevin Kilzer wrote:
    > 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
     
    Bill Mills, Feb 7, 2006
    #4
  5. Kevin Kilzer

    Guest

    DonĀ“t you plan the system that is going to be descripted in diagram
    blocks before writting the VHDL code?
     
    , Feb 7, 2006
    #5
  6. Kevin Kilzer

    Eric Smith Guest

    "Mike Treseler" <> writes:
    > 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!
     
    Eric Smith, Feb 7, 2006
    #6
  7. Kevin Kilzer

    Kevin Kilzer Guest

    On Tue, 07 Feb 2006 15:14:53 +1100, Mark McDougall <>
    wrote:

    >Kevin Kilzer wrote:
    >
    >> 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.


    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
     
    Kevin Kilzer, Feb 8, 2006
    #7
  8. 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.


    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
     
    Mark McDougall, Feb 8, 2006
    #8
  9. 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
     
    Colin Paul Gloster, Feb 8, 2006
    #9
  10. Kevin Kilzer <> writes:

    > 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
    --
    Kai Harrekilde-Petersen <khp(at)harrekilde(dot)dk>
     
    Kai Harrekilde-Petersen, Feb 8, 2006
    #10
  11. Kevin Kilzer <> writes:

    > 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
     
    Colin Marquardt, Feb 8, 2006
    #11
  12. Kevin Kilzer

    Andy Peters Guest

    Colin Paul Gloster wrote:
    > 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
     
    Andy Peters, Feb 9, 2006
    #12
  13. Kevin Kilzer

    Kevin Kilzer Guest


    >Colin Paul Gloster wrote:
    >> 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.


    <...and...>

    On 9 Feb 2006 11:40:46 -0800, "Andy Peters" <>
    wrote:
    >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
     
    Kevin Kilzer, Feb 10, 2006
    #13
  14. On 9 Feb 2006 11:40:46 -0800, "Andy Peters" <>
    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.
     
    Colin Paul Gloster, Feb 10, 2006
    #14
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Juergen
    Replies:
    2
    Views:
    7,078
    Juergen
    Jan 20, 2005
  2. Wendy S

    [OT] Project documentation

    Wendy S, Feb 16, 2005, in forum: Java
    Replies:
    3
    Views:
    405
    Tilman Bohn
    Feb 22, 2005
  3. Cameron Laird
    Replies:
    1
    Views:
    693
    Josiah Carlson
    Apr 3, 2004
  4. Kenneth McDonald
    Replies:
    2
    Views:
    792
  5. Replies:
    1
    Views:
    1,265
    Andy Dingley
    Sep 16, 2006
Loading...

Share This Page