Skip to content

Commit cde5e6e

Browse files
SenRamakriSenRamakri
committed
Design process and template for Mbed-OS
1 parent 1ab05c2 commit cde5e6e

19 files changed

+766
-0
lines changed

‎docs/design-documents/README.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Design Process for Mbed-OS
2+
This document defines the software design process for Mbed-OS. Anyone developing for Mbed-OS should use this process to submit the design to get it reviewed from the broader Mbed-OS developer community.
3+
4+
## Design documents location and organization
5+
* It's suggested to write one design document per change, which could be a new feature, defect fixes, tools changes etc. Do not try to address multiple changes in the same document.
6+
* The design document will follow the format represented in [Design Document Template](https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/design_template.md)
7+
8+
* For each design submission, create a folder under *https://github.com/ARMmbed/mbed-os/docs/design-documents/{AREA OR COMPONENT}*. The area/component would be Drivers, Platform, Connectivity, Security, Peripherals etc.
9+
If your implementation is creating new APIs, you should try to match the folder name directly to the new API, otherwise
10+
use the title of the feature as the folder name.
11+
For example, if your implementation is adding new EMAC API, you may name the folder as **New_EMAC_API** or if you are creating a new Serial Driver for Mbed-OS you may name the folder as **Serial_driver_for_Mbed-os**.
12+
* Your design document itself should also be named with the same name of the as the folder, so that it serves
13+
as your master design document, if you happen to use other .md files under same folder as annexures or reference.
14+
* The diagrams you are using may exist in the sub-folder *diagrams* under the new folder you have created.
15+
See [Example Design Document](https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/example_feature_design/example_feature_design.md) for example design document.
16+
17+
### Using diagrams in Design documents
18+
Its highly encouraged to create diagrams to depict your software design. The [Design Document Template]((https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/design_template.md) provided here uses diagrams generated using draw.io. draw.io generates XMLs for each diagram and those corresponding XMLs are also provided under the diagrams folder, and you are free to use that as your reference for generating your own diagrams. And, when you are generating your own diagrams it would be better to provide the metadata/other files(e.g, if you are using draw.io provide XMLs from draw.io) required for future editing of those diagrams.
19+
20+
## Design Process
21+
* Developer generates a design document located under *https://github.com/ARMmbed/mbed-os/docs/design-documents/{AREA OR COMPONENT}* and generates a pull-request to Mbed-OS.
22+
* NOTE: If you are part of an organization and would like to do design review within your organization before landing the pull-request, its ok to do so.
23+
* The pull request may also include the initial code implementation. It's upto to the develper to decide if the initial implementation comes along with the design document or later.
24+
* Although, if you are planning a large change, its encoraged to start the design review early before the implementation. This also help to avoid major re-work of your implementation if required by the design review.
25+
* Design review follows the same process as code review. Please refer contribution process as outlined in [Contributing to Mbed-OS](https://os.mbed.com/contributing/) for more information.
26+
* Once the design is approved, implementation is completed/adjusted according to the latest design document. Developer can create the pull-request with the final implementation, if its coming separately.
27+
28+
## Capturing future changes to design
29+
If your implementation changes in future, corresponsding design documents may be updated to capture the new design.
30+
It's possible that a new implementation may require changes to some previous implementations. In that case, capture
31+
the new changes in the original design document as well. Also create references to other(or older) design documents in the
32+
References section for the new design document.
33+
34+
## Reference documents
35+
[Design Document Template](https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/design_template.md)
36+
37+
[Example Design Document](https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/example_feature_design/example_feature_design.md)
38+
39+
[Design process](https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/README.md)
40+

‎docs/design-documents/design_template.md

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
# Mbed-OS Design Document
2+
Write your feature title above, in this case its "Mbed-OS Design Document"
3+
4+
# Table of Contents
5+
- [Mbed-OS Design Document](#mbed-os-design-document)
6+
- [Table of Contents](#table-of-contents)
7+
- [Revision history](#revision-history)
8+
- [Introduction](#introduction)
9+
- [Overview and Background](#overview-and-background)
10+
- [Requirements and Assumptions](#requirements-and-assumptions)
11+
- [System Architecture and High-Level Design](#system-architecture-and-high-level-design)
12+
- [System Architecture and Component Interaction](#system-architecture-and-component-interaction)
13+
- [Detailed Design](#detailed-design)
14+
- [Usage Scenarios and Examples](#usage-scenarios-and-examples)
15+
- [Tools and Configuration Changes](#tools-and-configuration-changes)
16+
- [Other Information](#other-information)
17+
- [Reusability](#reusability)
18+
- [Deprecations](#deprecations)
19+
- [References](#references)
20+
- [Custom Headings Here](#custom-headings-here)
21+
22+
### Revision history
23+
1.0 - A brief description for this version, e.g. Initial revision - Author name - Date
24+
1.1 - Added new section - Author name - Date
25+
26+
# Introduction
27+
### Overview and Background
28+
Provide a background of this feature. Briefly explain why this feature is needed, what is it accomplishing, what problem its solving. If you already have a requirement written for this feature you may also use the contents of the requirement to provide user with overall context of why this feature is needed.
29+
For example:- This document provides a template for writing software design documents for Mbed-OS features.
30+
31+
### Requirements and Assumptions
32+
Capture the requirements for this feature to work and other assumptions made. For example, if you are assuming specific
33+
hw capabilities, memory requirements, security assets like presence of RoT infrastructure, then capture those here.
34+
For example:- This feature requires QuadSPI interface on the target as it implements block device driver over QuadSPI
35+
interface. It also assumes the system can provide 16K of memory for buffering.
36+
37+
# System Architecture and High-Level Design
38+
This section provides high level information on areas or components needing changes or new development to implement this
39+
feature. The idea here is to capture the high level design goals of this feature for the target reader, the focus here should
40+
be what functionality it provides and not the actual implementation. For example, if you are implementing a new device driver
41+
for a communication peripheral/device then the high level design goals could be as below. Add more descrption to each high level design goal if required.
42+
43+
* `Configuring the device` - The driver should provide a specific interface to configure the communication paramaters for the device.
44+
* `Starting and stopping the device` - The driver should provide interfaces to start and stop all the communications.
45+
* `Reading from and Writing to the device` - Read and Write interfaces should be implemented to support sending single/multiple bytes.
46+
* `Resetting the device` - Functionality to reset the device should be provided.
47+
48+
**NOTE: If you already have supporting architecture documentation in the form of technology documents or other existing documents
49+
feel free to link them here and use that, you don't have to replicate the same documentation here.**
50+
51+
For each high level design goal, provide detailed software design under [Detailed Design](#detailed-design) section providing more details on implementation.
52+
53+
### System Architecture and Component Interaction
54+
Description and diagrams showing overall architecture of how the above-mentioned components/resources interface with each other.
55+
For, example if the new feature is to implement a driver and if it provides interfaces with application and uses memory subsystem in OS
56+
to talk to the device the diagram may look something like below. The goal here is to capture high level components and their interaction and not the
57+
minute details.
58+
59+
![System Architecture and Component Interaction](./diagram_examples/system_arch_example.jpg)
60+
61+
# Detailed Design
62+
This section provides detailed design on implementation of each of the high level design goal mentioned above.
63+
Each components/modules needing changes are also captured in details. The target audience here is a developer
64+
who can read this section and start the real implemention. You can capture things like signature of interfaces,
65+
flow charts showing how the APIs work, data flow diagrams etc. The headings for each detailed design section
66+
should match the headings in high level design goals. For example, based on the example provided above,
67+
the headings for details design sections should be `Configuring the device`, `Starting and stopping the device`,
68+
`Reading from and Writing to the device`, `Resetting the device`.
69+
70+
### Detailed Design 1 - e.g, `Configuring the device`
71+
72+
**API Description**
73+
Detailed API Description like signature of interface, explanation of arguments, return codes etc.
74+
For example, if you are trying to define an interface for configuring the device, you may describe
75+
the API as below.
76+
77+
`Configure API should have following signature:
78+
mbed_error_status_t configure(int speed, enum flow_control_t flow_control, int parity_bits);`
79+
where:`
80+
speed - is an integer value representing the target communication speed
81+
flow_control - is the enum value representing the flow control to be used
82+
parity_bits - is an integer value indicating the parity_bits to be used
83+
84+
And the function should return mbed_error_status_t value indicating the result of the call as below:
85+
MBED_SUCCESS if the call is successful.
86+
MBED_ERROR_INVALID_ARGUMENT if input values are invalid.`
87+
MBED_ERROR_CONFIG_UNSUPPORTED if the device doesnt support the requested configuration.`
88+
89+
**Configuration Sequence Diagram**
90+
91+
Sequence Diagrams, Data flow diagrams etc. For example, the flow chart for configure device API above may
92+
be something like below.
93+
94+
![Configure device operation](./diagram_examples/flow_chart_example.jpg)
95+
96+
### Detailed Design 2 - e.g, `Starting and stopping the device`
97+
98+
**API Description**
99+
Detailed API Description like signature of interface, explanation of arguments, return codes etc
100+
For example, for start and stop functions exported by the driver.
101+
102+
**Sequence Diagrams for `Starting and stopping the device`**
103+
Sequence Diagrams, Data flow diagrams etc. For example, the sequence digram for stopping the device may look
104+
something like below.
105+
106+
![Stopping the device](./diagram_examples/sequence_diagram_example.jpg)
107+
108+
### Detailed Design 3 - e.g, `Reading from and Writing to the device`
109+
110+
**API Description**
111+
Detailed API Description like signature of interface, explanation of arguments, return codes etc
112+
113+
**Sequence Diagram for `Reading from and Writing to the device`**
114+
Sequence Diagrams, Data flow diagrams etc.
115+
116+
### Detailed Design N - e.g, `Resetting the device`
117+
118+
**API Description**
119+
Detailed API Description like signature of interface, explanation of arguments, return codes etc
120+
121+
**Sequence Diagram for `Resetting the device`**
122+
Sequence Diagrams, Data flow diagrams etc.
123+
124+
# Usage Scenarios and Examples
125+
Show pseudo-code or flowcharts explaining the usage of the feature. For example you may want to include
126+
some pseudo code to demonstrate how the read functionality is used with the new driver design you are
127+
proposing.
128+
129+
### Scenario 1 - e.g, `Reading from the device`
130+
Mention the specific usage scenarios here. For example, the below examples shows how to read data from
131+
device using the new APIs.
132+
133+
**Scenario 1 Example 1. - e.g, `Reading a byte from device`**
134+
Mention the specific usage here. For example, the below example shows pseudo-code for how to read a single byte data from
135+
the device using the new APIs.
136+
137+
```C
138+
char in_byte = 0;
139+
int num_bytes_read = read(&in_byte, 1);
140+
if(num_bytes_read == 1) {
141+
//do something
142+
...
143+
}
144+
```
145+
**Scenario 1 Example 2. - e.g, `Reading multiple bytes from device`**
146+
In this example, the pseudo-code below shows how to read multiple bytes of data from the device using the new APIs.
147+
148+
```C
149+
char in_bytes[NUM_BYTES];
150+
int num_bytes_read = read(in_bytes, NUM_BYTES);
151+
if(num_bytes_read == NUM_BYTES) {
152+
//process bytes read
153+
...
154+
}
155+
```
156+
### Scenario 2 - e.g, `Writing to the device`
157+
Mention another usage scenarios here. For example, you can demostrate how to write to the device
158+
and few examples of usage.
159+
160+
**Scenario 2 Example 1. - e.g, `Writing a byte to device`**
161+
Demonstrate the specific example here. For example, how to write a byte of data to device.
162+
163+
**Scenario 2 Example 2. - e.g, `Writing multiple bytes to device`**
164+
Demonstrate another specific example here. For example, how to write mutiple bytes of data to device.
165+
166+
# Tools and Configuration Changes
167+
Explain which tools needs to be changed and the nature of changes.
168+
For example, if the feature requires adding a new sub-command to mbed-cli capture
169+
the details of changes and usage here. Each tool change can be captured under its own
170+
sub-heading as below. You can also capture new configuration values which needs to be
171+
added to mbed json based configuration system. For each, config value added explan
172+
the name of the config value and how to use it and its relation to any pre-processor
173+
defines in the implementation.
174+
175+
### Tool Change 1 - e.g: - Command line additions/changes
176+
177+
### Configuration Changes e.g: - Configuration changes in Json files etc
178+
179+
# Other Information
180+
Add other relevant information you would like to capture. Add custom headings if required.
181+
182+
### Reusability
183+
List the components or pieces of implementation which can be re-used for specific
184+
design patterns/other implementations.
185+
186+
### Deprecations
187+
List the APIs which may be deprecated as part of this feature.
188+
189+
### References
190+
Capture information such as specifications, other design docs, other implementations Urls etc.
191+
192+
### Custom Headings Here
193+
Add your custom headings here, for example security impacts of this feature can be put
194+
under the heading `Security Impacts`.

‎docs/design-documents/diagram_examples/flow_chart_example.jpg

15.1 KB
Loading

‎docs/design-documents/diagram_examples/flow_chart_example.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
<mxfile userAgent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/67.0.3396.99 Safari/537.36" version="8.8.7" editor="www.draw.io" type="device"><diagram name="Page-1" id="edf60f1a-56cd-e834-aa8a-f176f3a09ee4">7Zlbc6IwFMc/DY/dQaKgj4rodmZrO1K7s09OhAjZRuKE4GU//QYJN1GL2+ltFh80OTm5kPPjfzJRAeZqN2Zw7d9RFxFFU92dAoaKpmmq3hY/sWWfWFpqV00sHsOutOUGG/9BqaO0RthFYcmRU0o4XpeNDg0C5PCSDTJGt2W3JSXlWdfQQxWD7UBStf7ELveltaWqecN3hD1fTt3tyIYFdJ49RqNAzqdoYHn4JM0rmI4l/UMfunRbMAFLASajlCel1c5EJN7cdNuSfqMzrdm6GQp4nQ66igzVaOlGD7QAQL0boMmF8X26GcgVeyOrlHGfejSAxMqtg8MDo3hIVdR8viKi2BJFAheIDLI9MSmhTDQFNIi7hRwyLoPfEXUUuP04eKLqEBiG2Hn0cZA0jDBJBxW1QqffiPO9rMOIU2HKF/mD0rXsFXJGn1G6AhEX9fDJWtI4x75LGvARXGES8/uEmAsDKM1ypq6snhqvGgMZlpBGzEFnNl6+MmJLPMTP+HQSnzgghYFlZMeIrhBne+HAEIEcb8owQ/lOeJlfzoUoSDRqYiJXu4EkkrM8QYJdyFH8DH78jYN1xFOfUNF0Ih5rsGCi5PFsmwqclSna+pgjew0PG7YVOlMmK3tx6mB2ReQFZgVP+e6+lgixNV4QUy2IQOwSIhvEONpdDG7a2pMSkmoskPVtQbBSmfELWqWrb8ADABUgfsVBb6TkA6SkU0NKjJpSImm7Ub8ZhtEtEydBqq02cvQHigNecKHLZSjWeYxftoh/JNKoEDmhDZCfFsje1UB2vhCNnQqMfYYKyVGt5sdNnFAVMKqTOX26WkThy1mzDPN/n0M1tZxDs2N5MYeq75ZDq4eqJod+lGQZNSSre7Vk6bpufCHVAlXZanLoJwYypak2ka0SjDevpVEO226XZRWoR3KZPITslSMrggv3Bbd17BAWPd4L/OrZ0aTBEnvVXGxHjoPQAe4mU79dpm5r5dPex2bqbgWPKeIRC4TtbmAN5/bMNC3bvurOo9XcebxIQefozkM7dedxioL2W1DQq1CQBtzFmzTiKRhJg5ij0HbC/YCPNZ3eT+e3k6f+j9vhvD8dz+6syeO5MY6IanTlqls04yhVndIV/b2ISvPvCWGpKskldsz7yeh2PJ9N7NnDw/300RpeJvCCQjU8XcMTqMFTduh/JU+imv9RlJx68r/jgPUX</diagram></mxfile>

‎docs/design-documents/diagram_examples/sequence_diagram_example.jpg

21.3 KB
Loading

‎docs/design-documents/diagram_examples/sequence_diagram_example.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
<mxfile type="device" version="8.8.7" editor="www.draw.io" userAgent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/52.0.2743.116 Safari/537.36 Edge/15.15063"><diagram id="13e1069c-82ec-6db2-03f1-153e76fe0fe0" name="Page-1">7Zpbb6M4FIB/TaTZh1aAIZfHJG2nI3Wk0Xa1s/tUGXCIVYORcW776/cYDAGcNDSXUWcmkSrh47vPdy6Y9tA0Xn8WOJ1/5SFhPceKBA176K7nODb8gSCb45CvCpFViGIs5w2Bj4PXSPBForv2HDTLf0V1iiPySGg0l0X10LO2Fd9pWI5m21at4jnAjDSWoqQNwYyz5mKxEHyVNUQBTxISyIZMcs4kTZsNowUNSUsEh/FM/ysn1YsLN3obo6EWrHWDgY2UBN330FRwLouneD0lTJ1tebJ6nJ7zsKdBtV9BEtmxz8DHPrYD1w+cwcz1rRtU9FhittAbGKepObCea0mEJOum5uWmVABAkKrHRcye6IwwmkBpkhJBYyKJgBqmxd+2sslqTiV5TnGguq6AMpDNZcygZMMjaEZi6CKqMmM4zaifz2qBRJBgITK6JH+SrFCDkvKFVDNNK8XmTRV9JNRDVdBa+bgxDfQzwz5hkwrXKWdcTZ/wfEOZFPyVlEKg2Mp/VU3JqppiRhmrtXzIf0oOu3rAMWWKkr+JCHGCtVijZDu6vGsizGiUgCwABeWHWAEFhko4HK3YKNA1qFElUhqb14zMtbxCuKoZWGlfm9LgdButeGRgBg+atI7U2SZ2JnN7WX0Twho6KaeJzI/Am/S8uxaLXMg5j3iCWZ3GLSHWlRBV45Q0NAhpAlICoZXieqfy4Rp4fFWrvSNLCm4CHgSYu7i6qd8FwmPclNs/2U15BoaP46eXL3HKruhd0duPXt86PUL2O0TITsxdA+J5gbCHBwOi4zV58KyTI6I9MHjIJE9fwjwkfvpjLxy7SVDIUHh1GutT8bmUPIYKkoRj9XqkZIwHrwdV21EtJIR3Nb0Uwny+ut8KJrkAKspVae04lurV2I3EIiL78sPSZjK+EAF5M/XsqnhBGJbgOGuL0F2/KVuq9Ssm1dI3WHBR2zfAeeP6CrSVmlPtGRENd3ibYtAta9VOj8RvdHVHH9MduYe9Ub8VnU7Pz8uEv4YD9kFhL1LgJJsRkV3UI8GIYvOPVnVe+LeT3j+Srxp18VX9H+yrWqR4g515zIm+pPITW3gEkQuRXIAYnhKomoQ4m1dJLVRrbQ9/KmI6RbfRZYgpVmYSg1z7ADHvjm6jFoMj81LzQJf+rguqMwdEZF5RXAPihwiIg4MBEaEWYvbJr2vIvCoA4yI4Iy+CFBZ72ZB4Hjdmeqq6Z9sCWHdvwUIsa75VR+aqkEfmW2fYLwU1eIv4vaYy73FroaEuF50QJCpFud3nGP9ZWuwZI67mqXLNmqcb2C+yhpeKymjYzt+6+2sjwtvtsd7rr1H5Zro3Aphd2q/Hu9KMmr82t8dns4w0d1Z+UliXG71A5uI6hpWP05SBqUjK96cv3e4EEy7J4cs+fX9nuzv8g+RpzZEyMpOqAwxFk+gvVXd30/+FIsaxAQIdvtBrW9zpX7xc84vXWT5iXKn5sNSc4QOEa2aZj+MnEDzhzRWdXxed939AMCNTl2SzlkgGDGeZ0kVd+TvzrGOOwDOT8lJ0eoLkIqeZTxjX7d0TpPZYaODe7rwuezOVgOL2P3uK5tt/n0L3/wM=</diagram></mxfile>

‎docs/design-documents/diagram_examples/system_arch_example.jpg

12.7 KB
Loading

‎docs/design-documents/diagram_examples/system_arch_example.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
<mxfile userAgent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/67.0.3396.99 Safari/537.36" version="8.8.7" editor="www.draw.io" type="device"><diagram id="b86c121c-fc08-67bf-84f8-078ca2c883b8" name="Page-1">zZfLcpswFIafxst2ABlsL20HpzNtZjrjRZOlDCegRCBGCF/69JVA4upkmJS6sReWfh1d+M4vIc/QNjnfc5zFDywEOnOs8DxDdzPHcSxvKX+UcqkU20Z2pUSchFprhD35DVq0tFqQEPJOoGCMCpJ1xYClKQSio2HO2akb9sxod9YMRzAQ9gGmQ/UXCUVcqUvXavRvQKLYzGxbuuWAg9eIsyLV880c9Fx+quYEm7F0fB7jkJ1aEvJnaMsZE1UpOW+BKrgGW9Vv90ZrvW4OqRjTwfQ4YlqAWXK5MHExMCCUbHSVcRGziKWY+o26KR8Y1JCWrL0USWbiMQ+kEouEyooti7nAXKxViqSQshSMtiOU6gEgDU3EgbLgtZJ0gBrkBYS4aNfgQjApNQv7wVhWT8bZK2wZZbx8FORanq9A6BaTWxX7LIdvRXreTn6kPiSqkeWs4IFG5GmPYh6BjlpVkoLX6qazcA8sAcEvMoADxYIcu8bD2r9RHdfkUBZ0Gq+n1Btk9EHNcwdHIpcrC1zOxgdZbnKoaJxiImCf4fIBT3KX97PYA7tG8818cQ3jxnkfo1yLgPO7iHQrMttPnypzc1qcmi1qI63Fre3pWX9PdTGgus4ySgKZO5beCOZu57ur1TQw7TEwnX8EczWAadx5E46blW+t3Wk4uv+To33t9PaonGFzkDvci1TpO/BUvZ9vg7b8TrTfrS7aGnULrXNtv6+mQGsNj1FIWLm+fXH4kl9yAcmNqN7NfXs3kWH7p6jrjTxF0QRUr7ychteN5u0fUJznJOhfGxr5PZgfeNdLqvzyWN9CZOVJVb4q9HAm4lH3V+WmZdQNYTG8IXgjbwitxLhX8mK00RcJPcNPRuR6a184fV9YvXxXT6N7ta+UvYGQ3TsRl72BKgaDgUrv1I89yk5ozO31M9ipcpAxlN2yU2OuJ+27UXYyjD+vn/oXjIX9QT85PT9586n8JKvNP60qvPk/i/w/</diagram></mxfile>

‎docs/design-documents/example_feature_design/diagrams/app_hook.jpg

29.1 KB
Loading

0 commit comments

Comments
 (0)