Document State Machines?

[o]

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

 

[Kevin Neilson]

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

 

[Bert]

"Kevin Neilson" <kevin_neilson@removethiscomcast.net> wrote in message
news:2pVfc.151171$w54.1057538@attbi_s01...

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

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

 

[Tim at this Newsgroup]

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

 

[Jacek Mocki]

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

"Bert" <_wegvoorspam_lmaarsen@xs4all.nl> wrote in message
news:40804f32$0$562$e4fe514c@news.xs4all.nl...

"Kevin Neilson" <kevin_neilson@removethiscomcast.net> wrote in message
news:2pVfc.151171$w54.1057538@attbi_s01...
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


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