Software Diagramming In Embedded Systems? 52
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?"
Real Time UML (Score:3, Interesting)
Experiment (Score:2)
UML is what everybody uses (in my environment at least). A lot of aspects of UML assume object-oriented programming, but nobody stops you from cherry-picking whatever is in UML.
Of course you can think of objects as structs in C, and you can go a long way. However, I found that thinking in objects requires exercise. At first, you'll have people on your hands that will think of your regular C API as an object -- which is not alwa
Unique diagrams (Score:4, Funny)
Architecture diagrams (Score:3, Insightful)
If you've got a reasonably small code base you might want to keep the documentation style you've got. I'm not sure what a "very cryptic block diagram" looks like, but a simple drawing showing the functional blocks of your software may be good enough. For smaller embedded projects I've done in C or assembly (2-4 people on the team, 10K lines of code, minimal use of 3rd party code other than maybe the C std lib) this is the design/documentation style I've used:
1) Create an architectural design. Identify the main functional blocks of software in a drawing, include a one-paragraph explanation of what each block does.
2) Define the external interfaces, from the physical level on up. Define any internal interfaces necessary to support development, but don't go crazy, internal interface documentation is hard to maintain.
3) Code to the design. The "detailed documentation" is the comments you put in the code. Every file, function and most globals should have a brief comment describing what it contains or what it's for.
For a simple embedded system I've found this is a good approach. Things that will require a higher level of documentation: large code size, library-type code that will be heavily reused in the future, a large number of developers. Embedded systems are often a very different animal than applications, and some embedded software is inherently not reusable.
The real question you should ask yourself is "What extra help am I getting from my new documentation format, and does it justify the extra time I'm going to be putting into it?".
Fully agree (Score:2)
This approach has given the best bang for bucks that I have seen.
Re: (Score:2)
I've been doing it for a while now, too. I use post-it notes and highlighters. You'd be amazed how many sizes and colors people are selling post-it note in.
Ditch diagrams. I'm serious. (Score:5, Interesting)
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.
About the only case where diagrams are helpful are FSM diagrams.
Re: (Score:3, Informative)
About the only case where diagrams are helpful are FSM diagrams.
Re:Ditch diagrams. I'm serious. (Score:5, Informative)
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: (Score:2)
The only time I've ever had diagrams help me is when I am designing complicated data structures, particularly self-balancing trees and the like. Other than that, they're pretty useless.
Re: (Score:3, Insightful)
In my experience, the only time diagrams are worthwhile (unless required to get paid) are if you manage to find a tool that will generate usable code from the diagrams. Otherwise, the diagram and the code will always disagree in any system complex enough to be useful.
Re: (Score:1)
Like this one, though I suppose I should get the bloody installer working if I'm going to slashdot myself: http://www.statesharp.net/ [statesharp.net]
FSM diagram tool that generates code.
I wrote it because if your diagram doesn't generate your code, or vice versa, then they *will* get out of sync, and the only thing worse than no documentation is *wrong* documentation.
Re: (Score:2, Redundant)
2) Unnecessary cruft which no one uses.
I disagree completely. If you have ever walked blindly into a system with nothing but code and diagrams to help you through, you'd know that those diagrams are invaluable. Unless you want to waste man power by having another architect hand-hold your way through the system for hours/days/weeks until you've got a firm grasp on it, there's just no substitute for well-made design docs.
I think the notion of "diagrams are useless" spawns from system architects who don't have the foresight to realize that diag
Re: (Score:3, Informative)
I did this many times. UML class, use-case and sequence diagrams were NEVER helpful - it's just much easier to explore code with a good IDE.
The argument that a new architect will have to spend days familiarizing with the code is moot. Architects are arguably THE main people in a project - their mistakes can cost A LOT. So I'd rather let him/her spend some time and get acquainted with the code and code 'style' then let him/her rush into drawing more diagrams.
Also, diagrams have a very nasty habit to fall out
Re: (Score:2)
I did this many times. UML class, use-case and sequence diagrams were NEVER helpful - it's just much easier to explore code with a good IDE.
The argument that a new architect will have to spend days familiarizing with the code is moot.
Re: (Score:2)
Might have something to do with learning style. Some people seem to benefit from the way UML lays things out, other people find them more frustrating then just looking over the headers or example code.
Re: (Score:2)
Seconded, regardless of whether the project is embedded ASM, JEE, Ada, or whatever. I've walked into a number of projects, either late-in-the-game when the project needs saved, or well afterwards when changes need made, and invariably the code is badly commented, buggy, and may or may not do what was intended. In situations like this, people go into ass-covering mode, so information is hard to get anyway... You just don't have time to sift through thousands of lines of code, figure the intent, find the bugs
Re: (Score:2)
I now make it a habit to write documentation and use diagrams to help others in my group as well as anyone coming after me. I think we all know we won't be working a
Re: (Score:2)
I don't know, as a 'someone else' I find diagrams pretty useless for understanding a system. A good API document, spec, or header file directory does wonders.
Re: (Score:2)
And then, presumably, only to those who have been Touched by His Noodly Appendage...
Re: (Score:2)
Actually, a lot of FSM diagrams do look like the FSM!
Ahhhhhhhhhh!!!!
Re:Ditch diagrams. I'm serious. (Score:4, Informative)
Re: (Score:2)
Yes, you are absolutely right.
I forgot about ER-diagrams and they are very useful.
Re: (Score:2)
omg, undoing incorrect moderation! I meant to mod my "enemy" down!
Re:Ditch diagrams. I'm serious. (Score:4, Informative)
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:
Re: (Score:1)
About the only case where diagrams are helpful are FSM diagrams.
His noodly appendages don't take kindly to being diagrammed you insensitive clod.
Re: (Score:1)
> Ditch your diagrams.
This is simply wrong. A good diagram will clearly
reflect your actual design. And the exercise of
creating one will often highlight problems in what
you are doing. Not only that, it will show, in a
non-code representation, what your intent is, and
this allows others to verify it (and makes sure they
are thinking what you are thinking).
Documentation is a fundamental part of good design.
Skipping it is evidence of weak engineering
discipline.
Interfaces and Timing Diagrams (Score:4, Insightful)
I too work in embedded systems, more specifically aircraft controls. In most of our design documents we tend to keep the design to the interface level of each software component (CSC), and the interaction between them. Drawing this is usually down using more simple drawing elements than that of UML. Draw a couple of boxes to show your major components, and label the interfaces of those. In subsequent sections, show only one of the components at a time, with a drawing of its sub-components if applicable. Only go about 3 levels deep if at all possible here. The attention span of most reviews will get lost after that. Besides, your requirements already specify WHAT has to happen, your only job here is to specify WHERE those requirements happen.
While UML is nice, I have found that most of the reviewers of these types of documents are not UML savvy. The one drawing mechanism of UML that I do find invaluable in this line of work is the sequence diagrams. Large amounts of requirements can often be shown more precisely by a sequence diagram, detailing the interactions between a handful of component interfaces at a time.
Maybe Try Formal Modeling? (Score:5, Informative)
http://www.aadl.info/ [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 (Score:5, Informative)
Most times when people think about using flowcharts, they really should create state transition diagrams http://en.wikipedia.org/wiki/State_diagram/ [wikipedia.org] 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:
Re: (Score:2)
I'd say the opposite is true too: most times when people draw a state transition diagram, they're really drawing a flowchart.
State transition diagram are exactly that: to show the transitions between states in a system. You first need to determine what are the events that your system responds to, and then, for EACH state in the system, determine what happens in response to such events. "What happens" can be, but isn't always, a transition to another state. The benefit of such a diagram is that you make sure
SysML (Score:1)
UML doesn't solve all problems (Score:1)
Doing Hard-Time (with UML) (Score:2, Informative)
The code is the design, documentation the intent (Score:1)
Process Process Process (Score:2, Insightful)
My background is close to 20 years in embedded software in the aerospace environment. Most of the time, the process by which we got to SDR, including prior SSR and PDR, was dictated by higher management (read: pointy haired types), often based on a MIL2167A-like scheme, and generally ignored after CDR.
What you need is:
1) Written system requirements that are formally controlled, precise, unambiguous and testable. The precise format doesn't matter much as long as it's consistent inside the project and there i
State Diagrams (Score:1)
If you are thinking of using the diagram as a means to share your design concepts and inner workings of the system for review then State Diagrams [wikipedia.org] are the way to go. They are conceptually simple, so it is easy to explain them even to users. They are very close to the reality of the environment and machine, and when you begin to model the design on events then you get (IMHO) a minimized, stable, and functional design.
Go Agile (Score:2)
Re: (Score:2)
I am genuinely curious how your Agile methodology satisfies the independence criteria for design and verification for DO-178B - I believe it can be done, but it seems very tricky (And I understand if you are not able to talk about it). Thi
Re: (Score:2)
Without going into all the dirty details here are some general answers.
With respect to independence the only area where independence is required is for verification activities. Independence can be achieved by using a different person OR tool. Nothing prevents one from calling out a process in an SDP that uses a throw away prototype lifecycle model for an arch
Re: (Score:2)
Re: (Score:2)
I had not considered working out the details of the design generation in the SDP.
Many people don't! They write a SDP that is generic and simply regurgitate DO-178B, i.e. use DO178B as a plan rather than guidance for coming up with a plan.
You should check out the Yahoo group on DO178B. I started that a few years back when I was toiling with DO178b and seeking ways to do things "faster, better, cheaper" while still meeting the objectives. The group never took off as much as I wanted, but there is still hope.
Many companies are trying; there is no standard (Score:2)
Straight-up UML seems to be a bad match for most embedded systems - embedded systems tend to be built on procedural design principles, and matching them to object-oriented principles is often an exercise in frustration. Bruce Powell Douglas ( Doing Hard Time [amazon.com], Real Time UML [amazon.com]) seems to have the best handle on which core diagram types make sense for most of the embedded systems out there - I can't recommend his work highly enough.
There is no definitive diagram standard for the embedded systems industry - th
WINE for OS X (Score:1)
Illustration, not representation (Score:2)
I use diagrams. Usually two per subsystem. However when I do it, I do pretty much everything in a way, opposite to what diagram-lovers are accustomed to.
The principles are:
1. Diagram is an illustration. It does not represent the code because any diagram properly representing any kind of real-life code would be too complex to be readable. It only makes sense to use diagrams to illustrate documentation where some part of it are more readable in a graphical form.
2. Diagram should be very clear about what it ac