Using requirements planning in embedded systems design: Part 1 - Dissecting the requirements document

At this level, the general organization of the software needs to be developed, including definition of the tasks, layout of the communications, determination of the overall system timing, and the high-level definition of the priority structure.

These four areas—tasks, communications, timing, and priorities—are the four basic requirements for multitasking. The development of the system tasks includes context switching, but for our purposes, it is expanded to include 1) the creation of the tasks; 2) the development of a communications plan to handle all the communications between tasks; 3) a timing control system to insure that each task is active at the right time to accomplish its function; and, finally, 4) a priority manager to shift execution time to those tasks that are important to the system at any given moment.

If the requirements document does not contain all of these answers, and it typically doesn’t, then it is up to the designer to obtain this information. The answer may come through asking questions of the department that generated the document, such as Marketing. Some of the information may be implied through a reference to another document, such as an industry standard on RS-232 serial communications. And, in some cases, the designer may simply have to choose.

Wherever the answers come from, they should end up in the requirements document. As part of the design, this document will be a living entity throughout the design process.

As the requirements change, either through external requests from other departments or through compromises that surface in the design, the changes must be documented and must include an explanation of the reason for the change. In this way, the requirements document not only defines what the system should be, but also shows how it evolved during the development.

Some may ask, “Why go to all this trouble? Isn’t commenting in the listing sufficient?” Well, yes, the commenting is sufficient to explain how the software works, but it does not explain why the software was designed in a certain way.

It can’t explain that the allocation of the tasks had to be a certain way to meet the system’s priorities. It can’t explain that halfway through the design additional functions were added to meet a new market need. And it can’t explain why other design options were passed over because of conflicts in the design. Commenting the listing conveys the how and what, while the requirements document conveys the why.

An effective shorthand technique is to also list the information in a design notes file. This file should be kept simple; a text file is typically best. In this file, all of the notes, decisions, questions, and answers should be noted.

Personally, I keep a text file open in the background to hold my design notes when I dissect a requirements document. That way, I can note important information as I come across it.

Another good reason to keep a design notes text file is that it is an excellent source of documentation for commenting. Whether generating a header comment for a software function or source information for a user’s guide, all a designer has to do is copy and paste applicable information out of the design notes file. This saves time and eliminates errors in typing and memory. It also tends to produce more verbose header comments.