Slashdot Mirror
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?"
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?".
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.
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.
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 is as little ambiguity as possible.
These requirements need to include a precise and unambiguous description of the interface with the outside world and a precise and unambiguous description of the required functionality - ie. what the software does. This is what should come out of the SRR (Software Requirements Review) process. In my experience it rarely does.
2) A written description of the top level CSCIs (or whatever you want to call the first level of design decomposition) that is formally controlled, precise and unambiguous . This should include both internal interface and functionality descriptions for each CSCI. These descriptions should explicitly include how they will satisfy the top level requirements. This is what should come out of the PDR (Preliminary Design Review) process. In my experience it rarely does.
As for charts, there are lots of chart types you might use. Which is most appropriate depends mainly on the problem at hand. It seems as if there are as many different types of chart as there are consultants trying to sell their take on it. There is no shortage of chart types from which to choose.
Note that formal software design processes that require specific charts with no flexibility will invariably be found to be covered with the fingerprints of someone with pointy hair.
You will likely want to use several different chart types. Some of the alternatives include traditional flow charts (while useful for design, after the design is done they are close to worthless), state-transition diagrams, control flow diagrams, hierarchy diagrams, N**2 diagrams as well as many other types.
3) A written description of each CSC that is formally controlled, precise, unambiguous, including interfaces and functionality. To the set of charts available from the PDR level, to this level one may add pseudo code. Some languages (Ada is notorious for this) may serve as pseudo code, but this technique may needlessly restrict some options. This, along with the design documentation from SRR and PDR, is what should come out of the CDR process. In my experience it rarely does.
Good luck. You will need it.