Skip to content

Commit 864332f

Browse files
0xc01700xc0170
authored
Merge pull request #7561 from SenRamakri/sen_MbedOSDesignProcess
Design process and template for Mbed-OS
2 parents f82feec + 10b9ad7 commit 864332f

28 files changed

+819
-0
lines changed

‎docs/design-documents/README.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
## Design process for Mbed OS
2+
3+
This document defines the software design process for Mbed OS. To developing for Mbed OS, use this process to submit a design to have the broader Mbed OS developer community review it.
4+
5+
### Design documents location and organization
6+
7+
- The design document follows the format represented in [the design document template](https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/design_template.md).
8+
- For each design submission, create a folder under *https://github.com/ARMmbed/mbed-os/docs/design-documents/* at the appropriate level. We have organized the directory structure under design-documents to align with the `mbed-os` directory structure.
9+
- It is acceptable to create new subdirectories to organize similar items together.
10+
- If your implementation is creating a new API, match the folder name directly to the new API. Otherwise, use the title of the feature as the folder name. For example, if your implementation is adding a new EMAC API, you may name the folder **New_EMAC_API**, or if you are creating a new serial driver for Mbed OS, you may name the folder **Serial_driver_for_Mbed_OS**.
11+
- Give your design document the same name as the folder, so it serves as your master design document, if you happen to use other .md files under the same folder as reference materials.
12+
- Place any diagrams you are using in the subfolder *diagrams* under the new folder you have created.
13+
14+
Please see the [example design document](https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/example_feature_design/example_feature_design.md) for an example.
15+
16+
#### Using diagrams in design documents
17+
18+
We highly encourage creating diagrams to depict your software design. The [design document template](https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/design_template.md) uses diagrams generated using draw.io. draw.io generates XMLs for each diagram, and the diagrams folder also provides those corresponding XMLs. You are free to use that as your reference for generating your own diagrams. When generating your diagrams, please provide the metadata and other files (for example, if you are using draw.io, provide XMLs from draw.io) required for future editing of those diagrams.
19+
20+
### Design process
21+
22+
1. Generate a design document under *https://github.com/ARMmbed/mbed-os/docs/design-documents/*, and generate a pull request to Mbed OS.
23+
1. Decide whether the initial implementation arrives with the design document or as separate PRs.
24+
- If you are planning a large change, we encourage you to start the design review early before the implementation. This helps to avoid major rework of your implementation if required by the design review.
25+
- The initial submission of the design document doesn't need to be complete or refined in terms of capturing all the details, as you may use the design document itself to brainstorm and discuss on your idea or new feature being proposed.
26+
1. Design review follows the same process as code review. Please refer to the contribution process as outlined in [Contributing to Mbed OS](https://os.mbed.com/contributing/) for more information.
27+
1. Once the design is approved, implementation is completed or adjusted according to the latest design document. You can create the pull request with the final implementation, if it's arriving separately.
28+
29+
### Capturing future changes to design
30+
31+
If your implementation changes in future, update the corresponding design documents to capture the new design. If a new implementation requires changes to some previous implementations, capture the new changes in the original design document, as well.
32+
33+
### General guidelines for creating design documents
34+
35+
It's up to you to make a judgment on whether a change requires a design document. Small localized changes may not require design documents. However, larger changes, such as the addition of new features and functionality or changes with code turmoil across multiple components, require a backing design document.
36+
37+
It's not necessary to start implementation only after design document review. The caveat is if the proposed design changes significantly in the process of review, it affects your implementation, as well. Therefore, for large features for which you expect a lot of design feedback, we advise you start your implementation after major feedback is captured. For example, API designs can invite a lot of feedback. In such cases, capture that feedback before starting the implementation cycle. For very localized implementations that don't affect other parts of the system or other APIs, it may be acceptable to provide an initial implementation (in the same PR) as a reference along with design document.
38+
39+
### Reference documents
40+
41+
- [Design document template](https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/design_template.md).
42+
- [Example design document](https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/example_feature_design/example_feature_design.md).
43+
- [Design process](https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/README.md).
44+

‎docs/design-documents/design_template.md

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

‎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>

0 commit comments

Comments
 (0)