Over the years, I have found that many engineers (as well as their managers) struggle to separate the various elements or layers of firmware engineering. For example, we are barraged with requests for “design reviews” that turn out to be “code reviews” because the customer is confused about the meaning of “design”.
In the hopes of clearing this up, I propose a concise set of definitions and an architectural analogy.
Requirements
The requirements are the WHAT of the system. A set of requirements is a list of statements each of which begins “The system shall…” Each such statement must be objective and testable. The requirements should not unnecessarily restrict the HOW of the architecture, design, or implementation.
Architecture
The architecture of a system is the outermost layer of HOW. The architecture is a block diagram. The architecture of a system describes dataflow and workflow partitioning at the hardware vs. software level. The architecture of firmware features subsystem-level blocks such as device drivers, middleware, RTOS, etc. The architecture does not include function or variable names. It should be extensible in the direction of anticipated future changes.
Analogy: An architect describes a new building very broadly. A scale model and drawings show the outer dimensions, foundation, and number of floors. The number of rooms and their specific uses are not included at this level.
Design
The design of a system is the middle layer of HOW. A firmware design document identifies finer structural details, such as the names and responsibilities of tasks within the specific subsystems or device drivers, the brand of RTOS (if one is used), and the various interfaces between subsystems. The design does include class, task, function, and variable names that must be agreed upon by all implementers.
Analogy: A designer describes the interior and exterior of the new building in finer detail than the architect. He locates and names the rooms and gives them purposes. The location of pipes and vents and outlets are not included at this level.
Implementation
An implementation is the lowest layer of HOW. There is no document, other than the source code or schematics, to describe the implementation details. If the interfaces are defined sufficiently at the design level above, individual engineers are able to begin implementation in parallel.
Analogy: The carpenter, plumber, and electrician work in parallel and apply their own judgement about the finer details of component placement.
Constructive feedback is welcome via the blog comments or e-mail.