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?"
There are a number of commercial UML solutions for embedded and real-time systems. e.g. Rhapsody which with IBM's acquisition of telelogic becomes the natural upgrade path for system development with UML.
XML is a known as a key material required to create SMD: Software of Mass Destruction
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 always a good fit to say the least.
So if you go this way, prepare for some education. And don't start the new way of working with an important project.
8 of 13 people found this answer helpful. Did you?
Personally, I just refer to this diagram. It's the 42 of diagrams. You don't need any others.
You are using English. Please learn the difference between loose and lose; they're, there, and their; your and you're.
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?".
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.
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.
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.
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:
You might also want to look into SysML, which is a lot like UML with a few extra diagrams for modeling systems.
UML can be helpful at times. The tricky part is keeping the design in sync with the current state of code. You may design a system a certain way initially, but as you fix bugs and improve functionality, the original design documents become stale. I find the javadoc and doxygen (http://doxygen.org/) way of API documentation to be very helpful. Even Visual C# has integrated helpful API documentation techniques into the environment. This allows you to keep the documentation with the code, and it allows you to generate readable API documentation without all the fuss of keeping separate files in sync. Doxygen does work on C and C++ headers, and it has the ability to automatically generate C++ derivation trees and other helpful features. UML can be okay from a high level perspective, but like any hammer, you don't have to use it for everything.
by Bruce Powel Douglass explains how to use UML to model real-time embedded systems. I picked it up when i needed to come up with graphical designs for my senior thesis a couple of years ago. I had never once worked on a real-time system but this book helped me a lot in that it stresses the importance of the state and sequence diagrams (as many previous posters are also). Douglass does a good job of showing how to use the state diagram and nested states for multi-threading which helped me on my specific project. With this book i was able to catch a lot mistakes in my initial "swag" design and better able to understand how all the multi-threading parts would need to fit together. And why wouldn't UML work for decomposed functions? Use case, sequence, and state diagrams are not limited to any level of abstraction/detail, right?
Use well commented clear code. On top of it use technical notes to explain the design and implementation of the system at a moment in time along with the requirements at that moment in time. Concerning UML, there was a recent thread on slashdot: Is UML Really Dead, Or Only Cataleptic?
www.littletutorials.com
Don't under estimate the power of models.
Our C developers build a 3D model with spaghetti.
This approach has given the best bang for bucks that I have seen.
Engineering is the art of compromise.
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.
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 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.
Yes, I know, another fanboy touting how great Agile/Lean is... But seriously, I am an embedded developer for Flight Management Systems. I have been doing a lot of soul searching in this area. I have to tell everyone that the principle of Lean and Agile really do make sense, in particular for design documents. For the development we do, we are bound by DO-178B so we have to have some design "documentation" because there are objectives defined that require proof of compliance. The rub is that out of the 60+ objectives defined only 3 pertain to "design" (40 are for verification).
If you take the primary principle of Lean, which is "if work does not contribute to the final product it is muda {waste}", the exception to that "if work is required by an authority and does not contribute to the final product, do the minimum".
Now, take the Agile Manifesto into account which states "working software OVER comprehensive documentation" and to me, design documentation is a waste. We generate tons of useless design documents. We have tribal diagrams that supposedly tell me something about the system, but get out of date and require me to go to the tribal elder to decipher them. No, here is what I say (sorry it took so long to get to the point)
Design diagrams and documentation is needed, but only when you are crafting a new architecture and most importantly should only be used to get a code class/package architecture or development plan (which set of design patterns are going to be used, interfaces, etc.) Once the software takes form THROW OUT THE DOCUMENTATION and use a good tool to auto generated documentation from your software. Be vigilant about refactoring. If something breaks the design don't bolt on a fix. Refactor it, then regenerate the design.
Whenever possible, use self-documenting code or something that can auto generate code. We have a lot of interfaces and we get a little "ICD" happy (that's Interface Control Document). We have yet to realize ICDs can take any form and we should be using a form that can be used to generate a code module that represents the interfaces.
So in short (yeah right), design diagrams and documentation is a good place to start, but it is a means to an end. The end is good quality, well architected code. Oh, and spend your time doing some form of unit testing or something rather than creating useless design documents.
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 , Real Time UML ) 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 - the industry is still trying things out. In my corner of aerospace, Matlab Simulink is rapidly becoming our de facto standard for low-level algorithm requirements and design, with Rhapsody UML diagrams used everywhere else.
Whatever you decide on, make sure it is a technology that will be around when you need to re-visit your code. Many legacy programs are littered with the remnants of the diagrams from the SASD movement (structured analysis, structured design) which paved the way to UML. If you need to maintain your diagram system in-house, that's fine - the only reason I see people gravitating towards UML-type diagrams is the warm fuzzy feeling that UML is a well-documented diagram system that will be understood in two decades' time.
As a windows developer, I'd like to run my software on Apple hardware. I am trying to get my services established and being able to run on Apple would be such a boon. Is there a concise set of instructions that I can follow to configure WINE for OS X? Ideally I would be able to do "agile" installation with my Apple friend to guide him through the process. Assuming that is successful, what is the process for copying my software over to OS X to test if it runs? (please don't flame me, I come in peace)
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 actually represents. If it's a state, make sure that it captures a moment in time and maybe possible outcome -- for the new state draw another diagram. If it represents dependencies, make sure that all dependencies can be derived from it. If it represents relationships, communications, data structures, etc. make sure that types of objects, relationships, etc. are clearly distinguished from each other. If an arrow represents pointer, reference or mapping, another arrow that represents data flow or message transfer SHOULD BETTER LOOK NOWHERE CLOSE to the first one. No one cares if they are all one-to-one or one-to-many -- what is important, they are fundamentally different things. If you ran out of arrow types, draw a line with a penis on its end -- it means your diagram is too complex to be helpful to other people anyway.
3. Despite all this clarity, it should be clear that diagram is an informal drawing that illustrates your specification or code. It is not a language. It does not contain everything necessary for implementation of your software. You can't use it to generate anything. It does not matter what tool generated it -- it's a picture. You still have to write clear documentation.
4. If it makes sense (it usually does), represent multiple entities in lists as 2-3 examples with an ellipsis between them, add torn edges to tables, etc. to show a usable example of how your system deals with complex data, communications, etc.
5. Finite state machines usually have more states than you thought. Much more. Last two times I have seen proper representation of a finite state machine as a diagram were diagrams of TCP connection states and example diagrams of language scanners for compilers. If everything was FSM, people would never invent dynamic memory allocation. In reality you most likely have to deal with objects participating in a complex systems of relationships with other objects, each such relationship having its own state, and object as a whole having its "state" derived from all of them. An attempt to draw a "FSM" diagram for this kind of system usually creates a very misleading view of how things behave in reality, encouraging wrong data models, race conditions, severe underestimation of resources usage, memory leaks, etc.
6. Last time people had any hope to use flowcharts for something useful was in 70's. And those were people who programmed exclusively in assembly language and Fortran. And by Fortran I mean Fortran IV. Have you tried to understand an algorithm implemented in Fortran IV? You would think, flowchart is a better representation, too, but it's actually wrong -- a better representation would be pseudocode. Procedural languages such as C and Pascal, and later object-oriented languages made pseudocode unnecessary.
7. There are really a lot of things that no one cares about, and even less so wants to see in a diagram form. Imagine a large ractangle labeled "libc", with a tree growing out of it with include files, groups of functions, functions and arguments attached to them. Have you seen it when studying C and libc? Do you know why you didn't? That's right, because it would be a confusing mess, distracting from both syntax and functionality, emphasizing superficial over essential. Your project does not need it any more than libc does.
8. Use simple tools that allow you to concentrate on readability, not completeness or compliance with a standard that makes you pretend that your diagram is formal and not informal part of documentation. XFig, Inksc
Contrary to the popular belief, there indeed is no God.