Search

In this paper we draw on our experience in the automotive industry to portray the clear need for proper documentation of Simulink models when they describe the implementations of embedded systems. We effectively discredit the “model is documentation” motto that has been hounding the model-based paradigm of software development. The state of the art of documentation of Simulink designs of embedded systems, both in academia and industrial practice, is reviewed. We posit that lack of proper documentation is costing industry dearly, and propose that a significant change in development culture is needed to properly position documentation within the software development process. Further, we discuss what is required to foster such a culture.

The importance of appropriate software design documentation has been well-established. Yet in industrial practice design documentation of large software systems is often out of date or entirely lacking in large part due to the effort required to produce and maintain useful design documents. While model-based design (mbd) partially addresses this problem, large complex models still require additional design documentation to enable development and maintenance. This paper introduces tool support for documenting the Software Design Description (sdd) of embedded systems developed using mbd with Simulink. In particular, the paper proposes a template for a sdd of a Simulink model. Then, the tool support we have developed for semi-automatic generation of sdds from the template is introduced. The tool support integrates MathWorks' Simulink Report Generator and our previously developed Signature Tool that identifies the interfaces of Simulink subsystems.

Model-Based Development (MBD) has been gaining traction in the development of embedded software in many industries, especially in safety-critical domains. The models are typically described using domain-specific languages and tools that are readily accessible to the domain experts. Consequently, domain experts, despite not having formal software engineering training, find themselves creating models (designs) from which code is generated, thus effectively contributing to the design and coding activities of software development. This new role for domain experts as software developers can have a direct impact on the system safety if the domain experts do not follow software engineering best practices. In this chapter, we describe our experiences as software engineers in multiyear collaborations with domain experts from the automotive industry, who are developing embedded software with the MBD approach. We provide guidelines that strengthen the collaboration between domain experts and software engineers and improve the quality, and hence safety, of embedded software systems developed using MBD. We clarify the role of some of the most commonly used software engineering principles and artefacts, while also addressing issues and misconceptions encountered in adopting software engineering practices in MBD. Although this chapter focuses on the MBD of automotive embedded software in Matlab Simulink, the guidelines we provide are applicable to the MBD of software in general.