Software Diagramming In Embedded Systems?

afd100 writes "I work for a medium-sized company building embedded systems using C. As of yet, we do not have a great design methodology, but it is something we're working on. For the last 7 years now, we've been documenting our embedded software in an IEEE'esque Software Detailed Design, and using a very cryptic block diagram to explain our software. What does the embedded software community at large currently use to graphical represent their software or do they even try this? Since the programming is functionally decomposed, is UML the right way to go?"

Comments

Maybe Try Formal Modeling?

[Shade of Pyrrhus]

Take it a step up and evaluate some modeling languages and tools, such as AADL and OSATE.

http://www.aadl.info/

This stuff is MADE for real-time, embedded systems. The ultimate goal is to use it through design and analysis, and then go ahead and generate code. It does take some getting used to, and there is a lot to it so keep that in mind.

It's not perfect, and still under development, but very cool. So give it a try, see if you can pick it up. I'm generally a supporter of UML, but after being introduced to AADL and OSATE in an architecture course I was eventually convinced that it could be better than UML for this field.

Statecharts

[Dr.Who]

Most times when people think about using flowcharts, they really should create state transition diagrams http://en.wikipedia.org/wiki/State_diagram/ to discuss, describe, and document behavior. Statecharts are an improvement on earlier state transition diagrams and are included in the latest UML specification.

Some Statechart references:

1. Samek, Miro; Montgomery, Paul: State-Oriented Programming. Embedded.com. 2000-08. http://www.embedded.com/2000/0008/0008feat1.htm/
2. Samek, Miro: Practical Statecharts in C/C++: Quantum Programming for Embedded Systems. CMP Books. 2002-07. http://www.amazon.com/exec/obidos/tg/detail/-/1578201101/002-2659023-9156009/

Re:Ditch diagrams. I'm serious.

[AuMatar]

And uses all the wrong ideas. EEs had a drawing standard for state machines for decades, UML ignored all of it. Yet another reason to ignore UML.

Re:Ditch diagrams. I'm serious.

[raddan]

Since I am currently in the middle of drawing one (and yes, I'm kinda spacing out, reading /.), I would also argue that ER diagrams are useful. Just the drawing of them makes you think through some things that might never have occurred to you if you just started creating tables in a database.

Re:Ditch diagrams. I'm serious.

[jgrahn]

Ditch your diagrams. They're far too often used to: 1) As a thing to show boss that you're working. 2) Unnecessary cruft which no one uses.

And/or 3) something everyone except the boss knows is out-of-date and dangerous to refer to for anything important.

It's strange that the question explicitly asked for diagrams. What if this particular system is better described in plain text -- should there still be diagrams instead?

Apart from that I only have three pieces of advice:

• Any documentation which isn't under revision control together with the software is doomed to fail. That means among other things it has to be inside the source code, or in separate plain text files (so your changes can be merged with my changes, and so they can be reviewed alongside the source code).
• Spend a day or two with doxygen. Make sure you enable its graph-rendering capabilities, and then play with different settings. You can get quite a lot of overview and insight from its output, and it supports plain C.
• Doxygen cannot capture the architectural decisions and rules. Those that change rarely should, I think, be written down in plain text by someone who knows a lot about the system and who can write readable technical documentation. But for the volatile details, I'd rather trust the source code (and the views of the source code which doxygen, emacs, various IDEs ... can offer).