You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[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)
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).
21
23
22
24
### Revision history
23
-
1.0 - A brief description for this version, e.g. Initial revision - Author name - Date. NOTE: You may also specify the Mbed OS version this revision of design-document applies to.
24
-
1.1 - Added new section - Author name - Date
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.
25
29
26
30
# 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 publicly available 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
-
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.
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
+
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:
76
78
77
79
`Configure API should have following signature:
78
80
mbed_error_status_t configure(int speed, enum flow_control_t flow_control, int parity_bits);`
@@ -86,53 +88,55 @@ the API as below.
86
88
MBED_ERROR_INVALID_ARGUMENT if input values are invalid.`
87
89
MBED_ERROR_CONFIG_UNSUPPORTED if the device doesnt support the requested configuration.`
88
90
89
-
**Configuration Sequence Diagram**
91
+
**Configuration sequence diagram**
90
92
91
-
Sequence Diagrams, Data flow diagrams etc. For example, the flow chart for configure device API above may
92
-
be something like below.
93
+
Sequence diagrams, data flow diagrams and so on. For example, the flow chart for configure device API above may look something like:
###Detailed Design 2 - e.g, `Starting and stopping the device`
97
+
###Detailed design 2 (For example, `Starting and stopping the device`)
97
98
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.
99
+
**API description**
101
100
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.
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:
105
106
106
107
107
108
108
-
### Detailed Design 3 - e.g, `Reading from and Writing to the device`
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.
109
118
110
-
**API Description**
111
-
Detailed API Description like signature of interface, explanation of arguments, return codes etc
119
+
### Detailed design N (For example, `Resetting the device`)
112
120
113
-
**Sequence Diagram for `Reading from and Writing to the device`**
114
-
Sequence Diagrams, Data flow diagrams etc.
121
+
**API description**
115
122
116
-
### Detailed Design N - e.g, `Resetting the device`
123
+
Detailed API description, such as the signature of the interface, explanation of arguments, return codes and so on.
117
124
118
-
**API Description**
119
-
Detailed API Description like signature of interface, explanation of arguments, return codes etc
125
+
**Sequence diagram for `Resetting the device`**
120
126
121
-
**Sequence Diagram for `Resetting the device`**
122
-
Sequence Diagrams, Data flow diagrams etc.
127
+
Sequence diagrams, data flow diagrams and so on.
123
128
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.
129
+
# Usage scenarios and examples
128
130
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.
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
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.
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.
136
140
137
141
```C
138
142
char in_byte = 0;
@@ -142,8 +146,10 @@ if(num_bytes_read == 1) {
142
146
...
143
147
}
144
148
```
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.
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.
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
178
189
179
-
# Other Information
180
190
Add other relevant information you would like to capture. Add custom headings if required.
181
191
182
192
### Reusability
183
-
List the components or pieces of implementation which can be re-used for specific
184
-
design patterns/other implementations.
193
+
194
+
List the components or pieces of implementation that can be reused for specific design patterns or other implementations.
185
195
186
196
### Deprecations
187
-
List the APIs which may be deprecated as part of this feature.
197
+
198
+
List the APIs that may be deprecated as part of this feature.
188
199
189
200
### References
190
-
Capture information such as specifications, other design docs, other implementations Urls etc.
191
201
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`.
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`.
0 commit comments