takashi kadono / Mbed OS Nucleo_446

Color Oled(SSD1331) connect to STMicroelectronics Nucleo-F466

Dependencies:   ssd1331

mbed-os/docs/design-documents/design_template.md@0:8fdf9a60065b, 2018-10-10 (annotated)

Committer:
kadonotakashi
Date:
Wed Oct 10 00:33:53 2018 +0000
Revision:
0:8fdf9a60065b
how to make mbed librry

Who changed what in which revision?

UserRevisionLine numberNew contents of line
kadonotakashi 0:8fdf9a60065b 1 # Mbed OS design document
kadonotakashi 0:8fdf9a60065b 2
kadonotakashi 0:8fdf9a60065b 3 Write your feature title above. In this case, its "Mbed OS design document."
kadonotakashi 0:8fdf9a60065b 4
kadonotakashi 0:8fdf9a60065b 5 # Table of contents
kadonotakashi 0:8fdf9a60065b 6
kadonotakashi 0:8fdf9a60065b 7 1. [Mbed OS design document](#mbed-os-design-document).
kadonotakashi 0:8fdf9a60065b 8 1. [Table of contents](#table-of-contents).
kadonotakashi 0:8fdf9a60065b 9 1. [Revision history](#revision-history).
kadonotakashi 0:8fdf9a60065b 10 1. [Introduction](#introduction).
kadonotakashi 0:8fdf9a60065b 11 1. [Overview and background](#overview-and-background).
kadonotakashi 0:8fdf9a60065b 12 1. [Requirements and assumptions](#requirements-and-assumptions).
kadonotakashi 0:8fdf9a60065b 13 1. [System architecture and high-level design](#system-architecture-and-high-level-design).
kadonotakashi 0:8fdf9a60065b 14 1. [System architecture and component interaction](#system-architecture-and-component-interaction).
kadonotakashi 0:8fdf9a60065b 15 1. [Detailed design](#detailed-design).
kadonotakashi 0:8fdf9a60065b 16 1. [Usage scenarios and examples](#usage-scenarios-and-examples).
kadonotakashi 0:8fdf9a60065b 17 1. [Tools and configuration changes](#tools-and-configuration-changes).
kadonotakashi 0:8fdf9a60065b 18 1. [Other information](#other-information).
kadonotakashi 0:8fdf9a60065b 19 1. [Reusability](#reusability).
kadonotakashi 0:8fdf9a60065b 20 1. [Deprecations](#deprecations).
kadonotakashi 0:8fdf9a60065b 21 1. [References](#references).
kadonotakashi 0:8fdf9a60065b 22 1. [Custom headings](#custom-headings).
kadonotakashi 0:8fdf9a60065b 23
kadonotakashi 0:8fdf9a60065b 24 ### Revision history
kadonotakashi 0:8fdf9a60065b 25
kadonotakashi 0:8fdf9a60065b 26 1.0 - A brief description of this version. For example, Initial revision - Author name - Date.
kadonotakashi 0:8fdf9a60065b 27 **NOTE: You may also specify the Mbed OS version this revision of design document applies to.**
kadonotakashi 0:8fdf9a60065b 28 1.1 - Added new section - Author name - Date.
kadonotakashi 0:8fdf9a60065b 29
kadonotakashi 0:8fdf9a60065b 30 # Introduction
kadonotakashi 0:8fdf9a60065b 31
kadonotakashi 0:8fdf9a60065b 32 ### Overview and background
kadonotakashi 0:8fdf9a60065b 33
kadonotakashi 0:8fdf9a60065b 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.
kadonotakashi 0:8fdf9a60065b 35
kadonotakashi 0:8fdf9a60065b 36 For example:
kadonotakashi 0:8fdf9a60065b 37
kadonotakashi 0:8fdf9a60065b 38 This document provides a template for writing software design documents for Mbed OS features.
kadonotakashi 0:8fdf9a60065b 39
kadonotakashi 0:8fdf9a60065b 40 ### Requirements and assumptions
kadonotakashi 0:8fdf9a60065b 41
kadonotakashi 0:8fdf9a60065b 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.
kadonotakashi 0:8fdf9a60065b 43
kadonotakashi 0:8fdf9a60065b 44 For example:
kadonotakashi 0:8fdf9a60065b 45
kadonotakashi 0:8fdf9a60065b 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.
kadonotakashi 0:8fdf9a60065b 47
kadonotakashi 0:8fdf9a60065b 48 # System architecture and high-level design
kadonotakashi 0:8fdf9a60065b 49
kadonotakashi 0:8fdf9a60065b 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:
kadonotakashi 0:8fdf9a60065b 51
kadonotakashi 0:8fdf9a60065b 52 - `Configuring the device` - The driver should provide a specific interface to configure the communication paramaters for the device.
kadonotakashi 0:8fdf9a60065b 53 - `Starting and stopping the device` - The driver should provide interfaces to start and stop all the communications.
kadonotakashi 0:8fdf9a60065b 54 - `Reading from and Writing to the device` - Read and Write interfaces should be implemented to support sending single and multiple bytes.
kadonotakashi 0:8fdf9a60065b 55 - `Resetting the device` - Functionality to reset the device should be provided.
kadonotakashi 0:8fdf9a60065b 56
kadonotakashi 0:8fdf9a60065b 57 Add more description to each high-level design goal if required.
kadonotakashi 0:8fdf9a60065b 58
kadonotakashi 0:8fdf9a60065b 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.**
kadonotakashi 0:8fdf9a60065b 60
kadonotakashi 0:8fdf9a60065b 61 For each high-level design goal, provide a detailed software design in the [detailed design](#detailed-design) section, including more details on implementation.
kadonotakashi 0:8fdf9a60065b 62
kadonotakashi 0:8fdf9a60065b 63 ### System architecture and component interaction
kadonotakashi 0:8fdf9a60065b 64
kadonotakashi 0:8fdf9a60065b 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:
kadonotakashi 0:8fdf9a60065b 66
kadonotakashi 0:8fdf9a60065b 67 ![System architecture and component interaction](./diagram_examples/system_arch_example.jpg)
kadonotakashi 0:8fdf9a60065b 68
kadonotakashi 0:8fdf9a60065b 69 # Detailed design
kadonotakashi 0:8fdf9a60065b 70
kadonotakashi 0:8fdf9a60065b 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`.
kadonotakashi 0:8fdf9a60065b 72
kadonotakashi 0:8fdf9a60065b 73 ### Detailed design 1 (For example, `Configuring the device`)
kadonotakashi 0:8fdf9a60065b 74
kadonotakashi 0:8fdf9a60065b 75 **API description**
kadonotakashi 0:8fdf9a60065b 76
kadonotakashi 0:8fdf9a60065b 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:
kadonotakashi 0:8fdf9a60065b 78
kadonotakashi 0:8fdf9a60065b 79 `Configure API should have following signature:
kadonotakashi 0:8fdf9a60065b 80 mbed_error_status_t configure(int speed, enum flow_control_t flow_control, int parity_bits);`
kadonotakashi 0:8fdf9a60065b 81 where:`
kadonotakashi 0:8fdf9a60065b 82 speed - is an integer value representing the target communication speed
kadonotakashi 0:8fdf9a60065b 83 flow_control - is the enum value representing the flow control to be used
kadonotakashi 0:8fdf9a60065b 84 parity_bits - is an integer value indicating the parity_bits to be used
kadonotakashi 0:8fdf9a60065b 85
kadonotakashi 0:8fdf9a60065b 86 And the function should return mbed_error_status_t value indicating the result of the call as below:
kadonotakashi 0:8fdf9a60065b 87 MBED_SUCCESS if the call is successful.
kadonotakashi 0:8fdf9a60065b 88 MBED_ERROR_INVALID_ARGUMENT if input values are invalid.`
kadonotakashi 0:8fdf9a60065b 89 MBED_ERROR_CONFIG_UNSUPPORTED if the device doesnt support the requested configuration.`
kadonotakashi 0:8fdf9a60065b 90
kadonotakashi 0:8fdf9a60065b 91 **Configuration sequence diagram**
kadonotakashi 0:8fdf9a60065b 92
kadonotakashi 0:8fdf9a60065b 93 Sequence diagrams, data flow diagrams and so on. For example, the flow chart for configure device API above may look something like:
kadonotakashi 0:8fdf9a60065b 94
kadonotakashi 0:8fdf9a60065b 95 ![Configure device operation](./diagram_examples/flow_chart_example.jpg)
kadonotakashi 0:8fdf9a60065b 96
kadonotakashi 0:8fdf9a60065b 97 ### Detailed design 2 (For example, `Starting and stopping the device`)
kadonotakashi 0:8fdf9a60065b 98
kadonotakashi 0:8fdf9a60065b 99 **API description**
kadonotakashi 0:8fdf9a60065b 100
kadonotakashi 0:8fdf9a60065b 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.
kadonotakashi 0:8fdf9a60065b 102
kadonotakashi 0:8fdf9a60065b 103 **Sequence diagrams for `Starting and stopping the device`**
kadonotakashi 0:8fdf9a60065b 104
kadonotakashi 0:8fdf9a60065b 105 Sequence diagrams, data flow diagrams and so on. For example, the sequence digram for stopping the device may look something like:
kadonotakashi 0:8fdf9a60065b 106
kadonotakashi 0:8fdf9a60065b 107 ![Stopping the device](./diagram_examples/sequence_diagram_example.jpg)
kadonotakashi 0:8fdf9a60065b 108
kadonotakashi 0:8fdf9a60065b 109 ### Detailed design 3 (For example, `Reading from and Writing to the device`)
kadonotakashi 0:8fdf9a60065b 110
kadonotakashi 0:8fdf9a60065b 111 **API description**
kadonotakashi 0:8fdf9a60065b 112
kadonotakashi 0:8fdf9a60065b 113 Detailed API description, such as the signature of interface, explanation of arguments, return codes and so on.
kadonotakashi 0:8fdf9a60065b 114
kadonotakashi 0:8fdf9a60065b 115 **Sequence diagram for `Reading from and Writing to the device`**
kadonotakashi 0:8fdf9a60065b 116
kadonotakashi 0:8fdf9a60065b 117 Sequence diagrams, Data flow diagrams and so on.
kadonotakashi 0:8fdf9a60065b 118
kadonotakashi 0:8fdf9a60065b 119 ### Detailed design N (For example, `Resetting the device`)
kadonotakashi 0:8fdf9a60065b 120
kadonotakashi 0:8fdf9a60065b 121 **API description**
kadonotakashi 0:8fdf9a60065b 122
kadonotakashi 0:8fdf9a60065b 123 Detailed API description, such as the signature of the interface, explanation of arguments, return codes and so on.
kadonotakashi 0:8fdf9a60065b 124
kadonotakashi 0:8fdf9a60065b 125 **Sequence diagram for `Resetting the device`**
kadonotakashi 0:8fdf9a60065b 126
kadonotakashi 0:8fdf9a60065b 127 Sequence diagrams, data flow diagrams and so on.
kadonotakashi 0:8fdf9a60065b 128
kadonotakashi 0:8fdf9a60065b 129 # Usage scenarios and examples
kadonotakashi 0:8fdf9a60065b 130
kadonotakashi 0:8fdf9a60065b 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.
kadonotakashi 0:8fdf9a60065b 132
kadonotakashi 0:8fdf9a60065b 133 ### Scenario 1 (For example, `Reading from the device`)
kadonotakashi 0:8fdf9a60065b 134
kadonotakashi 0:8fdf9a60065b 135 Mention the specific use scenarios. For example, the below examples shows how to read data from device using the new APIs.
kadonotakashi 0:8fdf9a60065b 136
kadonotakashi 0:8fdf9a60065b 137 **Scenario 1 example 1. (For example, `Reading a byte from device`**)
kadonotakashi 0:8fdf9a60065b 138
kadonotakashi 0:8fdf9a60065b 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.
kadonotakashi 0:8fdf9a60065b 140
kadonotakashi 0:8fdf9a60065b 141 ```C
kadonotakashi 0:8fdf9a60065b 142 char in_byte = 0;
kadonotakashi 0:8fdf9a60065b 143 int num_bytes_read = read(&in_byte, 1);
kadonotakashi 0:8fdf9a60065b 144 if(num_bytes_read == 1) {
kadonotakashi 0:8fdf9a60065b 145 //do something
kadonotakashi 0:8fdf9a60065b 146 ...
kadonotakashi 0:8fdf9a60065b 147 }
kadonotakashi 0:8fdf9a60065b 148 ```
kadonotakashi 0:8fdf9a60065b 149
kadonotakashi 0:8fdf9a60065b 150 **Scenario 1 example 2 (For example,`Reading multiple bytes from the device`**)
kadonotakashi 0:8fdf9a60065b 151
kadonotakashi 0:8fdf9a60065b 152 In this example, the pseudocode below shows how to read multiple bytes of data from the device using the new APIs.
kadonotakashi 0:8fdf9a60065b 153
kadonotakashi 0:8fdf9a60065b 154 ```C
kadonotakashi 0:8fdf9a60065b 155 char in_bytes[NUM_BYTES];
kadonotakashi 0:8fdf9a60065b 156 int num_bytes_read = read(in_bytes, NUM_BYTES);
kadonotakashi 0:8fdf9a60065b 157 if(num_bytes_read == NUM_BYTES) {
kadonotakashi 0:8fdf9a60065b 158 //process bytes read
kadonotakashi 0:8fdf9a60065b 159 ...
kadonotakashi 0:8fdf9a60065b 160 }
kadonotakashi 0:8fdf9a60065b 161 ```
kadonotakashi 0:8fdf9a60065b 162
kadonotakashi 0:8fdf9a60065b 163 ### Scenario 2 (For example, `Writing to the device`)
kadonotakashi 0:8fdf9a60065b 164
kadonotakashi 0:8fdf9a60065b 165 Mention other usage scenarios here. For example, you can demostrate how to write to the deviceand few examples of usage.
kadonotakashi 0:8fdf9a60065b 166
kadonotakashi 0:8fdf9a60065b 167 **Scenario 2 example 1 (For example,`Writing a byte to device`**)
kadonotakashi 0:8fdf9a60065b 168
kadonotakashi 0:8fdf9a60065b 169 Demonstrate the specific example, for example, how to write a byte of data to device.
kadonotakashi 0:8fdf9a60065b 170
kadonotakashi 0:8fdf9a60065b 171 **Scenario 2 example 2 (For example, `Writing multiple bytes to device`**)
kadonotakashi 0:8fdf9a60065b 172
kadonotakashi 0:8fdf9a60065b 173 Demonstrate another specific example, for example, how to write mutiple bytes of data to device.
kadonotakashi 0:8fdf9a60065b 174
kadonotakashi 0:8fdf9a60065b 175 # Tools and configuration changes
kadonotakashi 0:8fdf9a60065b 176
kadonotakashi 0:8fdf9a60065b 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
kadonotakashi 0:8fdf9a60065b 178 the name of the configuration value, how to use it and its relation to any preprocessor defines in the implementation.
kadonotakashi 0:8fdf9a60065b 179
kadonotakashi 0:8fdf9a60065b 180 ### Tool change 1
kadonotakashi 0:8fdf9a60065b 181
kadonotakashi 0:8fdf9a60065b 182 For example, command-line additions and changes
kadonotakashi 0:8fdf9a60065b 183
kadonotakashi 0:8fdf9a60065b 184 ### Configuration changes
kadonotakashi 0:8fdf9a60065b 185
kadonotakashi 0:8fdf9a60065b 186 For example, configuration changes in .json files
kadonotakashi 0:8fdf9a60065b 187
kadonotakashi 0:8fdf9a60065b 188 # Other information
kadonotakashi 0:8fdf9a60065b 189
kadonotakashi 0:8fdf9a60065b 190 Add other relevant information you would like to capture. Add custom headings if required.
kadonotakashi 0:8fdf9a60065b 191
kadonotakashi 0:8fdf9a60065b 192 ### Reusability
kadonotakashi 0:8fdf9a60065b 193
kadonotakashi 0:8fdf9a60065b 194 List the components or pieces of implementation that can be reused for specific design patterns or other implementations.
kadonotakashi 0:8fdf9a60065b 195
kadonotakashi 0:8fdf9a60065b 196 ### Deprecations
kadonotakashi 0:8fdf9a60065b 197
kadonotakashi 0:8fdf9a60065b 198 List the APIs that may be deprecated as part of this feature.
kadonotakashi 0:8fdf9a60065b 199
kadonotakashi 0:8fdf9a60065b 200 ### References
kadonotakashi 0:8fdf9a60065b 201
kadonotakashi 0:8fdf9a60065b 202 Capture information, such as specifications, other design documentation and other implementations URLs.
kadonotakashi 0:8fdf9a60065b 203
kadonotakashi 0:8fdf9a60065b 204 ### Custom headings
kadonotakashi 0:8fdf9a60065b 205
kadonotakashi 0:8fdf9a60065b 206 Add custom headings. For example, you can put security effects of this feature under the heading `Security effects`.