Document State Machines?

hi , i do contract design and most of my fpga designs have one or more state machines written in VHDL , my question is how you document this for the customer as a deliverable ?

1) ok, well written and commented VHDL is self documenting .. sortof . but only to the company software types , managers do not get a warm and fuzzy and when there is maintenance at a later time it doesn't work well for managers/customers/new engineers to work with ..

2) the old stand by is a flow chart, easy to use in a trouble shooting meeting with a wide variety of participants looking for the problem , bad part is they are expensive to make and maintain and my customers don't like me to quote time doing them , the pc programs that do them seem to take a lot of entry time and are expensive, i still often sketch out design flows in chart form on a big piece of paper on the wall before VHDL coding and keep it updated during the development but putting this into deliverable form is a pain ...

i was recently hired to solve a problem with a design I worked on a couple of years ago which their engineers were having trouble with , the deliverable documents had well written VHDL and text descriptions but at the time I quoted an additional manweek to provide computer generated system flowdiagrams and that was turned down ..

so when i returned i dug into the cellar and found my old original pencil drawn working chart , it was a 3' by 7' chart of the entire system including mini flowdiagrams of each state machine .. i slapped that on my customers conference room wall and 2 days later the problem was solved after an intense session with engineering/customer/managers all using it .. ok the customer is happy but perplexed how come i didn't supply such a diagram ... well , at the time they were unwilling to pay me a week to "professionalize" it ... and i even tried to get their document department to save a copy of the big chart and the snooty document department said that they would not save the "hand written mess" ... mmmm

i would like to be enlightened , thanks

Reply to
o
Loading thread data ...

I tried a few of those tools that allow you to draw state machines and then generate the code, but I never liked the code they generated and I don't like having "source for the source". So you can use them just for documentation, but then you have the problem that the document always differs from the actual code when you make a change. I normally just do what you do, which is to have a "hand-written mess" before I code the machine. I guess I'd recommend using the Mentor tool or something similar to make a picture for the customer to see, but not necessarily for code generation. If there were a tool that could load in a state machine and print it graphically, this would be ideal. Synplicity's synthesizer does do this for state machines it extracts, but the graphical version isn't really pretty enough to show to managers. -Kevin

Reply to
Kevin Neilson

then

do

really

For state machines we use Ease, a tool for graphical FPGA design entry. It includes also a nice manner to draw state macines. The output is used in our company as the documentation.

I agree that the generated code is never as you wish it should be, but I am not very unhappy with it. But to be honest only for very complex state machines I will use this tool, for all other state machines I write my own VHDL and provide a state machine drawing in our hardware documentation.

The time I need to draw the machine, set al the conditions and actions is mostly just a little bit less than writing the case statement by yourself.

Bert

Reply to
Bert

Hi, o,

I'm afraid I can't enlighten you in respect of tools that create FSM diagrams from code, but how about a bit o' working practices enlightenment?

I'm often engaged in design work under contract and like you end up designing FSMs for my clients (as well as other more fun blocks of hardware).

Some clients appreciate the time you spend thinking, analysing requirements, architecturing and designing 'before' you begin coding. They're the smart guys. I've had 5 clients like this.

Other clients just expect you to start coding on the first day. Try to educate them, you may not succeed completely, but you might buy enough time to do some of the pre-coding work which in the long run usually pays off. I've had 1 client like this.

If you have an interview before you start, try to guage "How smart is the client?". If they just want a code-monkey, you might think about turning them down - in my experience, clients who skimp on doing things properly in terms of design tend to skimp in other areas, too - the skimp concept permeates their entire culture.

Incidentally, I have a software engineer pal who hasn't written a line of code for over a decade as part of his day-to-day work; he analyses and documents, defines standards and other software engineering 'things' - he writes code at the weekends whilst at home to keep up-to-date as a programmer; his oft-quoted comment is "One day, I'll get paid to do this!". Ironic how the software community seems to understand that it "isn't about the code", isn't it?

I guess how you document FSMs isn't that important, just documenting them is the key thing - that documentation department ought to know better!

Tim

Reply to
Tim at this Newsgroup

Hi,

I have used an Aldec's Active-HDL software to change code to machine. The name of the module is Code2Graphics.

Similar to Kevin I never got result where code after conversion looked like the one before. In your case it is possible to use the tool to document only.

Very user friendy software

Regards

Jacek

similar

does

Reply to
Jacek Mocki

ElectronDepot website is not affiliated with any of the manufacturers or service providers discussed here. All logos and trade names are the property of their respective owners.