5.2.2. Guideline for Detailed Design documentation

5.2.2.1. Purpose

In order to develop correctly a software module, it is required to first write down a detailed design document which will guide you to develop correctly your module. Indeed, beginning with a design document will force you to think about:

  • What your SW module shall do
  • What are its dependencies
  • What will be its structure
  • How it will do its functions.

Once these steps are down, it will make things easier to specify your APIs and then develop them.

5.2.2.2. General information

Such document generally contains requirements traceability in order to make sure that high level requirements are correctly fulfilled. In our case, we don't have input requirements for the moment, but this is the next evolution planned for the project (2019.03.27).

Also, in order to guide you with the content of this document, you need to think as a "tester" in order for him to know what he needs to test in order to make sure that the implementation of your module is correct. Indeed, based on this detailed design document, both software implementation AND software unit tests will be developed, ideally by 2 different persons.

These steps are based on the V Cycle development process:

graph LR Detailed-Design-->SW-Implementation; Detailed-Design-->SW-Unitary-tests; SW-Implementation-->SW-Unitary-tests;

5.2.2.3. Example

Below is an example of sections which can/shall be present in the detailed specification of a driver. It is based on the automotive standard "AUTOSAR" which defines, among lot of other documents, low level driver specification, like a CAN driver: AUTOSAR_SWS_CANDriver.pdf. All the AUTOSAR specification can be found here if needed: https://www.autosar.org/standards/classic-platform/

The goal is not to write text for fun but to provide enough information for other to understand how is developed your module, what it contains and why you chose to make the choice you made. Indeed, some functionalities can be implemented in various ways, but some are most probably more adapted to your case so please indicate the reasons of your choice.

5.2.2.4. Typical document structure

Below is the detailed design document' structure. A dedicated documentation page is provided as template: simply copy its content and paste it in a new page when creating a new modules's detailed design.

  1. General description of the driver and of the dedicated chip (including link to datasheet, best if attached directly in the documentation page)
  2. Acronyms and abbreviations
  3. Constraints and assumptions

  4. Limitations: Functionalities of the chip which are not supported by the driver

  5. Assumptions: describe if assumptions were made when developing the driver (unclear specification, etc.)
  6. Dependencies to other modules: Indicates the API, structure or types defined in other modules and which are necessary in this driver

  7. OSS

  8. HAL
  9. UTL
  10. Other
  11. File Structure
  12. Functional specification

  13. Driver Scope

  14. Driver State Machine
  15. Initialization
  16. Tx
  17. Rx
  18. Sleep/Wakeup
  19. Interruption
  20. Development errors (if applicable)
  21. API Specification

  22. Types definition

  23. Function definitions
  24. Call-back notifications
  25. Scheduled functions
  26. Sequence diagrams
  27. Configuration specification