mirror of https://github.com/ARMmbed/mbed-os.git
Merge pull request #7561 from SenRamakri/sen_MbedOSDesignProcess
Design process and template for Mbed-OSpull/7951/head
Martin Kojtal
GitHub
commit
864332f665
|
|
@ -0,0 +1,44 @@
|
|||
## Design process for Mbed OS
|
||||
|
||||
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.
|
||||
|
||||
### Design documents location and organization
|
||||
|
||||
- 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).
|
||||
- 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.
|
||||
- It is acceptable to create new subdirectories to organize similar items together.
|
||||
- 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**.
|
||||
- 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.
|
||||
- Place any diagrams you are using in the subfolder *diagrams* under the new folder you have created.
|
||||
|
||||
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.
|
||||
|
||||
#### Using diagrams in design documents
|
||||
|
||||
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.
|
||||
|
||||
### Design process
|
||||
|
||||
1. Generate a design document under *https://github.com/ARMmbed/mbed-os/docs/design-documents/*, and generate a pull request to Mbed OS.
|
||||
1. Decide whether the initial implementation arrives with the design document or as separate PRs.
|
||||
- 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.
|
||||
- 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.
|
||||
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.
|
||||
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.
|
||||
|
||||
### Capturing future changes to design
|
||||
|
||||
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.
|
||||
|
||||
### General guidelines for creating design documents
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
### Reference documents
|
||||
|
||||
- [Design document template](https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/design_template.md).
|
||||
- [Example design document](https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/example_feature_design/example_feature_design.md).
|
||||
- [Design process](https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/README.md).
|
||||
|
||||
|
|
@ -0,0 +1,206 @@
|
|||
# Mbed OS design document
|
||||
|
||||
Write your feature title above. In this case, its "Mbed OS design document."
|
||||
|
||||
# Table of contents
|
||||
|
||||
1. [Mbed OS design document](#mbed-os-design-document).
|
||||
1. [Table of contents](#table-of-contents).
|
||||
1. [Revision history](#revision-history).
|
||||
1. [Introduction](#introduction).
|
||||
1. [Overview and background](#overview-and-background).
|
||||
1. [Requirements and assumptions](#requirements-and-assumptions).
|
||||
1. [System architecture and high-level design](#system-architecture-and-high-level-design).
|
||||
1. [System architecture and component interaction](#system-architecture-and-component-interaction).
|
||||
1. [Detailed design](#detailed-design).
|
||||
1. [Usage scenarios and examples](#usage-scenarios-and-examples).
|
||||
1. [Tools and configuration changes](#tools-and-configuration-changes).
|
||||
1. [Other information](#other-information).
|
||||
1. [Reusability](#reusability).
|
||||
1. [Deprecations](#deprecations).
|
||||
1. [References](#references).
|
||||
1. [Custom headings](#custom-headings).
|
||||
|
||||
### Revision history
|
||||
|
||||
1.0 - A brief description of this version. For example, Initial revision - Author name - Date.
|
||||
**NOTE: You may also specify the Mbed OS version this revision of design document applies to.**
|
||||
1.1 - Added new section - Author name - Date.
|
||||
|
||||
# Introduction
|
||||
|
||||
### Overview and background
|
||||
|
||||
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.
|
||||
|
||||
For example:
|
||||
|
||||
This document provides a template for writing software design documents for Mbed OS features.
|
||||
|
||||
### Requirements and assumptions
|
||||
|
||||
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.
|
||||
|
||||
For example:
|
||||
|
||||
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.
|
||||
|
||||
# System architecture and high-level design
|
||||
|
||||
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:
|
||||
|
||||
- `Configuring the device` - The driver should provide a specific interface to configure the communication paramaters for the device.
|
||||
- `Starting and stopping the device` - The driver should provide interfaces to start and stop all the communications.
|
||||
- `Reading from and Writing to the device` - Read and Write interfaces should be implemented to support sending single and multiple bytes.
|
||||
- `Resetting the device` - Functionality to reset the device should be provided.
|
||||
|
||||
Add more description to each high-level design goal if required.
|
||||
|
||||
**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.**
|
||||
|
||||
For each high-level design goal, provide a detailed software design in the [detailed design](#detailed-design) section, including more details on implementation.
|
||||
|
||||
### System architecture and component interaction
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
# Detailed design
|
||||
|
||||
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`.
|
||||
|
||||
### Detailed design 1 (For example, `Configuring the device`)
|
||||
|
||||
**API description**
|
||||
|
||||
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:
|
||||
|
||||
`Configure API should have following signature:
|
||||
mbed_error_status_t configure(int speed, enum flow_control_t flow_control, int parity_bits);`
|
||||
where:`
|
||||
speed - is an integer value representing the target communication speed
|
||||
flow_control - is the enum value representing the flow control to be used
|
||||
parity_bits - is an integer value indicating the parity_bits to be used
|
||||
|
||||
And the function should return mbed_error_status_t value indicating the result of the call as below:
|
||||
MBED_SUCCESS if the call is successful.
|
||||
MBED_ERROR_INVALID_ARGUMENT if input values are invalid.`
|
||||
MBED_ERROR_CONFIG_UNSUPPORTED if the device doesnt support the requested configuration.`
|
||||
|
||||
**Configuration sequence diagram**
|
||||
|
||||
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 (For example, `Starting and stopping the device`)
|
||||
|
||||
**API description**
|
||||
|
||||
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.
|
||||
|
||||
**Sequence diagrams for `Starting and stopping the device`**
|
||||
|
||||
Sequence diagrams, data flow diagrams and so on. For example, the sequence digram for stopping the device may look something like:
|
||||
|
||||
|
||||
|
||||
### Detailed design 3 (For example, `Reading from and Writing to the device`)
|
||||
|
||||
**API description**
|
||||
|
||||
Detailed API description, such as the signature of interface, explanation of arguments, return codes and so on.
|
||||
|
||||
**Sequence diagram for `Reading from and Writing to the device`**
|
||||
|
||||
Sequence diagrams, Data flow diagrams and so on.
|
||||
|
||||
### Detailed design N (For example, `Resetting the device`)
|
||||
|
||||
**API description**
|
||||
|
||||
Detailed API description, such as the signature of the interface, explanation of arguments, return codes and so on.
|
||||
|
||||
**Sequence diagram for `Resetting the device`**
|
||||
|
||||
Sequence diagrams, data flow diagrams and so on.
|
||||
|
||||
# Usage scenarios and examples
|
||||
|
||||
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.
|
||||
|
||||
### Scenario 1 (For example, `Reading from the device`)
|
||||
|
||||
Mention the specific use scenarios. For example, the below examples shows how to read data from device using the new APIs.
|
||||
|
||||
**Scenario 1 example 1. (For example, `Reading a byte from device`**)
|
||||
|
||||
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.
|
||||
|
||||
```C
|
||||
char in_byte = 0;
|
||||
int num_bytes_read = read(&in_byte, 1);
|
||||
if(num_bytes_read == 1) {
|
||||
//do something
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
**Scenario 1 example 2 (For example,`Reading multiple bytes from the device`**)
|
||||
|
||||
In this example, the pseudocode below shows how to read multiple bytes of data from the device using the new APIs.
|
||||
|
||||
```C
|
||||
char in_bytes[NUM_BYTES];
|
||||
int num_bytes_read = read(in_bytes, NUM_BYTES);
|
||||
if(num_bytes_read == NUM_BYTES) {
|
||||
//process bytes read
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
### Scenario 2 (For example, `Writing to the device`)
|
||||
|
||||
Mention other usage scenarios here. For example, you can demostrate how to write to the deviceand few examples of usage.
|
||||
|
||||
**Scenario 2 example 1 (For example,`Writing a byte to device`**)
|
||||
|
||||
Demonstrate the specific example, for example, how to write a byte of data to device.
|
||||
|
||||
**Scenario 2 example 2 (For example, `Writing multiple bytes to device`**)
|
||||
|
||||
Demonstrate another specific example, for example, how to write mutiple bytes of data to device.
|
||||
|
||||
# Tools and configuration changes
|
||||
|
||||
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
|
||||
the name of the configuration value, how to use it and its relation to any preprocessor defines in the implementation.
|
||||
|
||||
### Tool change 1
|
||||
|
||||
For example, command-line additions and changes
|
||||
|
||||
### Configuration changes
|
||||
|
||||
For example, configuration changes in .json files
|
||||
|
||||
# Other information
|
||||
|
||||
Add other relevant information you would like to capture. Add custom headings if required.
|
||||
|
||||
### Reusability
|
||||
|
||||
List the components or pieces of implementation that can be reused for specific design patterns or other implementations.
|
||||
|
||||
### Deprecations
|
||||
|
||||
List the APIs that may be deprecated as part of this feature.
|
||||
|
||||
### References
|
||||
|
||||
Capture information, such as specifications, other design documentation and other implementations URLs.
|
||||
|
||||
### Custom headings
|
||||
|
||||
Add custom headings. For example, you can put security effects of this feature under the heading `Security effects`.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 15 KiB |
|
|
@ -0,0 +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>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
|
|
@ -0,0 +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>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
|
|
@ -0,0 +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,0 +1 @@
|
|||
# Design Documents - Drivers
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 29 KiB |
|
|
@ -0,0 +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.9.1" editor="www.draw.io" type="device"><diagram name="Page-1" id="13e1069c-82ec-6db2-03f1-153e76fe0fe0">7VlNc6M4EP01Ps4WiA/jY+xJJofdqqlJ1e5ZQAOqCMQKEdv761cC8Q01TuyJnd34YvEkdUP3e40kVtYuPXzjOE/+YCHQFTLCw8r6ukLINGwk/xRyrBHHcGog5iTUgzrgifwDzUyNliSEYjBQMEYFyYdgwLIMAjHAMOdsPxwWMTr0muMYJsBTgOkU/YuEItGoaRhdxyOQONGuPUd3+Dh4jjkrM+1vhayo+tXdKW5s6fFFgkO270HW/craccZE3UoPO6Aqtk3Y6nkPC73tfXPIxCkT1j72sRnYfoDWke0bX7zawgumpY7FXZ5TEmBBWKbsIJdKy1ufy1asWk/HQkCqH0ccmxDKJ8tVs0zp7yQCSjJ5tc2BkxQEcNlDNfy9w7b7hAh4ynGgpu4luSSWiJTKK1M2Zb4FllN4e00pzgviV14NiXAISl6QF/gBRU0rhbJSKE+7li7VUJUmCLWpNhNGZTclgW5T7APdtnndMcqU+4xVD1QIzp6hAWW6PeRbrtv2NPRRLiJCaW9k6IAX2gqXT/WAU0KVWv4EHuIMa1hLw0T6ujfdqH4Sx5TEmcQCmfMqiFMSaF68ABdw6EGaFN+AyQTwoxzS9DYE1QL29OW+p4ZGDElPCM5ag1grMG5NdyyUDU3EBRabExJO6NUjRc5IJip3znblfB2xjHGRsJhlmPZ5NkmbG3jgRzNJwuBFkgrbmOOQwCADa8AuGLMBX9TVyRmwnUECNnMJmMbf3Fwg/utJ+O9lTZWCNx5xFkohxZ9q1xTwPcd2jFPUHnkBBMFtqr2V92vV7l1C7ZuPr/YzxT0f8Gm8L1FckfW/D7eN3i/c0/VUVUsfGXt+yD7LaEOE9cY3TiujEbi3WkZt+4plFH38RdO5ayTLeT9dT19an2uk//QayTWuKW7nw4t789qAj1/aJ+6ALrIBNWbCrc89mmOPBlAcHCTC/btkTceXWnF3coBp54eusz08AdGuBxqL8u5qo0NHEu45X06+ijAJML3TIvCZECyVHZCFd+psTGGUBc+zilxUSsFKHmhvS7tbgXkMw0UahIOTtmm2e+lslMKBYiEL1sD/XD61te+K7r2zi81QqcgYUaJ+FD2rfzg2MoRGknfHUq6fd2JIRhkfe8O0HBdv2Br5MdeDQzvZqC123G3jdxqd0XvT+QELTG+bz9cgprv5bbRicUdGTqWmhX5qaoGcb+APWi6H59FlwsIdrhwPtkhzbFkg1nWL4rQGelejmm0OS0q75b3VGmhboxu2LlsD0bQGchAln+7BX8kaloPs2oa4SNqVs+zWy1Tv7Xw64516Jnl+mvNTyTP+ivDLyDNiu2NcmDz2exXAH5DL5bneSn7gyre5mcrndC/d19LXHZ3nTD5uXYi+jjvv5430lZfdB+R6ePeV3rr/Fw==</diagram></mxfile>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 24 KiB |
|
|
@ -0,0 +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.9.1" editor="www.draw.io" type="device"><diagram id="653eb958-43ae-f509-9384-b251daec6120" name="Page-1">3Vlbc5s4FP41fmwHA8L4MbXTy8x22mmys+mjgAPWREaskGNnf/1KIJmLILV3cdLEfrB0ztFB+s4VeeattodPHBebrywBOnOd5DDz1jPXnTu+K38U5bGmIAfVhIyTRAs1hBvyD5iVmrojCZQdQcEYFaToEmOW5xCLDg1zzvZdsZTR7lMLnIFFuIkxtal/kURsamqInIb+GUi2MU+eO5oT4fg+42yX6+fNXC+tPjV7i40uLV9ucML2LZJ3PfNWnDFRj7aHFVCFrYGtXvdxhHvcN4dcnLJA2+kB0x2YHVf7Eo8Gi+o0oOTnM+/DfkME3BQ4Vty9tL6kbcSWanZKKF0xyni11kswhGks6aXg7B5anCAOIUolx96xPsQDcAGHFkmf4BOwLQj+KEUMN9Boam8LzHzf2M4PNW3TspuRw9pdsqPqBjI50KgNIxgOIBhQoc5c4FyOMzW+lk7JpdhKhorhS81tEUOOeJ/SllpDSnIiCMvLUT2jBnTONmCK1HfQgNXnMgZEvm3AuXshAy4tAxpjfcW5DPStOpd8hAxp1/ksfyjJMzn8kgvgqcJxyohJwxjiwYiJQuQjZxrAPfcEwIMLAW6S/ADif7Asq9B99Yj63nMiekIal5WmUMOUwuFKlUh5bsgTPVzHFJcliZ9Gsq5kBklTGZUkHIi4UxnmPdKzn5ozim3JdjyGThKFpFOWbbBbYKIBLA2NA8WCPHSL+RDA+gnfGalifCQdLZY9G9Vb16va1bWnyHVHCpNRJDDPQFiKKnsfj32aC/i/doFBc5dyD+JJLxiwdi731TK3mp5lb51z6+N3s8Kb84F5T5F/OR9AL+IDbQ9o4v+ulRkazjne8dY8AfWL7uJynhDYJfYQQ6H6xk4X8+rqrAXic7aKx+2+dJIdLrdPQtwOMNdOv2805p4x+w68S6+5hICX04ZZmrrDYZYEUYAmeiPzl73OZYFOCzNvijDzLCS/S3dKGd9ODCUEI1AulpEz1ZuB95JQ2m3hVVFQEuO6FEyIZoIgTPwhNEM38ia7KghfEs0TGqzf7j3rN0npyF++R91cbC6Fz26kbFVBT9WEad1upY43df2LupRV22y8Ifh7xwzjXVldc19JgblfHBrmry8A5R5r1RY5Gr31k/Ekul7GQe4AR5WAym2FQqfCC32YobWk4J1g9S6rBZiSLJdjCqlSpYJUJg56pcmCFfXlZCxbyVs1Wb/zJ+ry5ouufRehFeVDQe5OEeSLcw1e025u19/+vB03YkMxt10/oGBclP/Hyibb5EzAJVqJjOOESDt2ViXLqbI56rdnC7ubH7q4n/+HbC6nzf8qdSJo/rzyrv8F</diagram></mxfile>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
|
|
@ -0,0 +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.9.1" editor="www.draw.io" type="device"><diagram id="27f5bc82-62af-765d-0fcb-618869901ef9" name="Page-1">3VhNc5swEP01nkkuGUBGdo+x66SHdCYzOTQ9ZWRYQI2MGCFiu7++EgjzIWynjeNm4oulx9PX213twgjNV5tbQbLkOw+BjTwn3IzQ15Hnuc7YU38a2VaI748rIBY0NKQGeKC/oR5p0IKGkHeIknMmadYFA56mEMgORoTg6y4t4qy7akZisICHgDAb/UFDmVTo1Hca/BvQOKlXdh3zZEmC51jwIjXrjTwUlb/q8YrUcxl+npCQr1sQWozQXHAuq9ZqMwemta1lq8bd7Hm627eAVL5qADL7kNv67BAqKUyXC5nwmKeELRp0Vp4P9AyO6iVyxVTTVU3YUPloYN3+qdtXrm+69yDoCiSImpJKsX2sx+pONUDzf4GUW+MYpJBcQc1m7jjPzDD7wEaDnBciMEcy3iiJiMGwjD/qw7aGGZFugat9iq0iCGBE0peuXxDjXvGO10isGkblPYqP31/xjyg4/m+C4/cXfPoRFfdPrXg59FoIsm0RMk5TmbdmvteAIphkgLDZR50Kpr0bqc+vr9J/5GPs9Lyj2nHjK7ujv8p9jLAvhBVGoYVKMOKOxyMPMyX1bClUK9atC0WcUxEUjCjMmRVRBOLS5lkOmUvBn3epxuu6nMoRmeatNrHOtlcR4+sgIUJehUSSJcm1w64TKuEhI6U/rBVPYRFlbM4ZF+UiOhF5QaAnLFdrPQnxEvv4kKu9gJCwOehG++xd22fdJFJjIidp59A6Jb4p1l1L2hPEumtdricNXWSHrvchQtdDXVOiY6H45SD/zaGIrFBcLSF8Ah2PF5eW5Ru7unsCpGXrXqyEBKbRYKzgYArL6DSx0gsVhOxQcScDsYJPECrjYTGVCz4xksvPo+r4nKr6+1UtBX2iacQ/g6r4nKri/apGVHwmZ/XPKevEkvWGFExf6LAJIJOUp3pVkoZMFbSn1DaaBjBciiyn/th3TqOt3ysNz3q/DhSOdm2Shtf6a4XqBerSzWnQq/z66vgOXujlZt2CcUBhjG/Ub+8Li+cfeDkpHw5WIEdrGeNS7VoGDduoZQN/wAQ19ncVjlWSTLoeMOlbttq7GXSgtNlVp/VEbm+i6sTWRMerHNVtPvdU9OabGlr8AQ==</diagram></mxfile>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 15 KiB |
|
|
@ -0,0 +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.9.1" editor="www.draw.io" type="device"><diagram name="Page-1" id="bd83a815-5ea8-2e97-e5ec-87c9f400f2fa">rVZZc5swEP41zLgP7iARU/sxvtqHpskkzXT6KGA5JgK5Qvjor+8KJDD4mKa1/YD07fHtrhZWjrfI958l26QPIgLuUDfaO97SoZS4dxQfGjk0yGRigERmkVHqgJfsN1hLg1ZZBGVPUQnBVbbpg6EoCghVD2NSil1fLRa8z7phCZwALyHjFv046fAfWaRSgxN/1gm+QJakhnxK/UYQsPAtkaIqDKNDvbj+NeKcWV8m1TJlkdgdQd7K8RZSCNWs8v0CuK6uLZy1UwcbrePNU5Vz3BBc1uL1BWPyN8aYnIRCHdNd9GfOdct4ZR1Sn6PtXLEAObAgQkYga5n/q9JpzUm3RIVdW99W7iLrpKcUIu+GRVFWJD3Vu55Wl5cFjfN7FFqvbqObmtM7I2pCHoeCc7YpodFpd0eEfmKeTcaBwIYfgvJsXF2baBohGw5sFvYpnOnXx4TSF9pO6sVpUtjsNZHgeDS17mwaxJRciTbVLwvPkqIXGIdYnRp5ZEQ0YaY+WPtAWuE937FDieJvkDCVbcGqYN9olv/hdcd0NqINdXmG++VQKsiR6EmUGVZgvahKJfLbRUCnY3p33V00RILW2BsTfzQdho9ugqGNdn3i6Ipr4o/dEfH/2bUG5QnfO5sVWEwj70b9eDnXMbll5b7/fFrd0t+oKqoSUL6WUILcQnTTg354XL5+vWnAq+fnx2c8lMXj8v1+z/aNBs99/DTejAGLD6aPgr3qT6BSSfEGi6bNUMULXf1HSZxxfoSbb6E3F1uQMa9nqFZBpG5V0CPKbUlRCckGQ78bc6QdvXipAZGDkpiNaw3s1D0M9t3sov7MYOnRtYDYGw0zN5Kk9d1NVVyYwWq33fivZUe3LG/1Bw==</diagram></mxfile>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 26 KiB |
|
|
@ -0,0 +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.9.1" editor="www.draw.io" type="device"><diagram id="27f5bc82-62af-765d-0fcb-618869901ef9" name="Page-1">7VnbUtswEP0aP9JxfGv6SEKAzrTTTsNMy6Nib2yBIrmycuPrK9mSL5HJJBSSGQZesI5W0ursnpUEjj9ebG44yrPvLAHieG6ycfwrx/MGbuDJXwrZVkjohhWQcpxoowaY4icwIzW6xAkUHUPBGBE474IxoxRi0cEQ52zdNZsz0l01RylYwDRGxEZ/40RkFToM3Qa/BZxmZuWBq3tmKH5MOVtSvZ7j+fPyp+peIDOXti8ylLB1C/Injj/mjInqa7EZA1HcGtqqcdfP9NZ+c6DikAGejkshtmbvkEgqdJNxkbGUUUQmDToq9wdqBle2MrEg8nMgP2GDxR8Ffwp16970UMG3rS7VvNcTPIAQW50DaCmYhJp1vzGW6znsventFmzJY+29r7MF8RS0lcHUxlrjNCE3wBYgvZEGHAgSeNXNAaRTKa3tGjrlh2a0n1298AqRpZ70Ms8JjuUqjMrB020hYOF4EVrITY7orMjLfUZEuj6acfmVqq/JBuJlNWa3ywpfExzF2TrDAqY5KulZS7F2AzbHhIwZYbwc6ycIhvNY4oXg7BFaPVE8hNl8XxBWwAVs9vKre4c693VtGES6vW6UVmNZS2UG+5+I9IRksokhr8h1b1GeAy32kOoeTep8GEPcS+psGAah+yak1u1TkBq4FmHHFpGH5SI39ojHr1FWClkDxKU6DCRAGQWDXWO1k9IGaGIsZoTFjxWkDQZH1KYqtuasOLhaeZFdrnzvXOXKeNMSx/cZJBc/phJsyWS3Bt0imhCQTfcrXUkakjcuU6dRVBCcUVK+a4XC1pidvAkqsprUHgUNWvppSeZPLQejn7Kvm9RRr0yPD01XYIfJpO9Ujw6USStcYU+0DHawmvQKPxmWHtfZ4rvdbPGDnSyo9qNHtW9kuxOFO2n3ZWeiigRrIpkKaNsyy5VBYeVcTcxhaWhU007DStsJXnXSMfq7VJfWkVSXuEAEp9TxL9UVXQZW1QbT31SEap4iR9Rge6qN9LRt2YJLR56f8y39bQrfHcdpCrwpfUf5axnvKF352BU0hwI/oVlpoESloy2tw5ETXklEnVZFdXCpAXqHVwTmaipVBuU9lFxqWKiTTO0txjS9K4+1i+B16qh1Nfns2XXU61Gm/xpXk56y+XE1Oegh5fVcTc73kvKsQvQLYsaT/TeTMaOldt7jfcT/csorfvChoxfqqOfu4gdn05H9/v3GUuVeBkpKkin+LtUSuqdUS/ShlheqJehRS3g2tQSWWm6AAkcCes4aLh9f0vhKRu5dSiganPIBHFrU3yIi6kpV/+n0/fH82Xs7nmWz+edC9SBs/oPjT/4B</diagram></mxfile>
|
||||
|
|
@ -0,0 +1,552 @@
|
|||
# WARNING: THIS IS AN EXAMPLE DESIGN DOCUMENT
|
||||
|
||||
# Standardized error coding and error handling
|
||||
|
||||
# Table of contents
|
||||
|
||||
1. [WARNING: THIS IS AN EXAMPLE DESIGN DOCUMENT](#warning-this-is-an-example-design-document).
|
||||
1. [Standardized error coding and error handling](#standardized-error-coding-and-error-handling).
|
||||
1. [Table of contents](#table-of-contents).
|
||||
1. [Revision history](#revision-history).
|
||||
1. [Introduction](#introduction).
|
||||
1. [Overview and background](#overview-and-background).
|
||||
1. [Requirements and assumptions](#requirements-and-assumptions).
|
||||
1. [System architecture and high-level design](#system-architecture-and-high-level-design).
|
||||
1. [System architecture and component interaction](#system-architecture-and-component-interaction).
|
||||
1. [Detailed design](#detailed-design).
|
||||
1. [Usage scenarios and examples](#usage-scenarios-and-examples).
|
||||
1. [Tools and configuration changes](#tools-and-configuration-changes).
|
||||
1. [Other information](#other-information).
|
||||
1. [Reusability](#reusability).
|
||||
1. [Deprecations](#deprecations).
|
||||
1. [References](#references).
|
||||
|
||||
### Revision history
|
||||
|
||||
1.0 - Initial version - Senthil Ramakrishnan - 7/1/2018
|
||||
|
||||
# Introduction
|
||||
|
||||
### Overview and background
|
||||
|
||||
Presently Mbed OS error handling is not standardized in terms of error codes used and how its handled. This should not be the case as error handling should be unified/standardized and handled in OS level and should be a service available to every component in the system. This makes developing for Mbed OS easier as it enables standard way to describe and communicate error scenarios. This can also enable better error analysis/analytics tools in future. Implementation of standardized error handling should provide APIs for setting the errors and retrieving runtime errors occurred in the system. OS level error handler should collect required data on error scenarios to make it easier for developer to triage the issues later. Error handling implementation should also handle fault exceptions such as Hard Fault, Bus Faults, MemManage faults, Usage Faults to capture the faults context and report them as required and halt the system based on exception type. Sufficient documentation and code comments, in the form of Doxygen comments, should also be provided to enable easy usage of error handling APIs and data structures. This document defines the software design and test strategy for implementing Standardized error codes and error handling in Mbed OS.
|
||||
|
||||
### Requirements and assumptions
|
||||
|
||||
This feature requires serial terminal support to emit the error report when the system encounters a error scenario. The error reports are printed out for non-release builds only. For release builds, the system still captures the error context (but not printed out) and can be retrieved using error handling APIs.
|
||||
|
||||
# System architecture and high-level design
|
||||
|
||||
Below are the high-level design goals for "Standardized Error Coding and Error Handling" feature.
|
||||
|
||||
**Common error code definitions**
|
||||
|
||||
Generic error codes should be defined for common/generic error scenarios. For example, out of memory situation is a common error which needs to be identified with an error code. Any layer of Mbed OS should be able to use these error codes in their implementations to report the errors. It’s up to the receiver/handler of the error code to decide whether the error code should be considered fatal based on current context. Other functionalities, like conversion of error code to human readable string, may also be implemented depending on capability of the target platform like memory available, build profile etc. Applications who should also be able to extend or custom define the error code definitions as required.
|
||||
|
||||
**Error handling and management functions**
|
||||
|
||||
Implementation should provide necessary APIs for applications and other parts of the system to do the following:
|
||||
|
||||
1. Error setting API – An API should be provided for the application to set a system level error using the error code definitions.
|
||||
1. Error retriever API – Application should be able to read the errors reported over a period, get the number of errors or read the last reported error.
|
||||
1. Error clearing API – Application should be able to reset/clear the current set of errors recorded by the system.
|
||||
1. Fatal Error API – APIs should be provided to handle fatal error scenarios, so that applications can make that call if the error is fatal based on context and the system should record that and halt the system.
|
||||
|
||||
**Error logging**
|
||||
|
||||
The implementation should include support for error logging where in the system should capture and log the last N number of errors reported. These errors can be retrieved later for device-health reporting or to analyze the past errors. The error log should also capture the error code, error type and other information as required. The error handling functions mentioned in Section 4.2 should use this logging mechanism to record or retrieve the errors.
|
||||
|
||||
**Error reporting**
|
||||
|
||||
Implementation should include mechanisms to report errors or fault exceptions to the user through standard input/output or other channels as required when an error scenario happens. The error report should include relevant information to enable efficient triaging of error scenario. There are few different ways to report errors once its captured as below:
|
||||
|
||||
1. Print the error report to STDIO/Serial terminal – Almost all development boards have access to serial port as its STDIO and thus reporting it through serial port is required.
|
||||
|
||||
**Fault exceptions handling and reporting**
|
||||
|
||||
When the system crashes due to fault exceptions, the error handling infrastructure should handle the exception scenario and generate a crash dump containing relevant information for triaging the scenario. The crash dump generated should be reported using the error reporting mechanisms as mentioned in Section 4.4.
|
||||
|
||||
**Application hook for error handling**
|
||||
|
||||
In many cases, applications developers may want to implement custom error handling for all the errors or custom defined errors. Implementation should include mechanisms to register custom error handler and should call that in the event of an error scenario.
|
||||
|
||||
### System architecture and component interaction
|
||||
|
||||
The below diagram shows overall architecture of how the above-mentioned components/resources interface with each other.
|
||||
|
||||
|
||||
|
||||
As shown in the diagram above all software components including Application, Platform code, Drivers can use common error code definitions to represent errors conditions and use that to report the error to Error Handling component. The error handling component interfaces with Error Logging and Error Reporting component to log and report the errors and halt the system if required. Fault exceptions will also be handled by the Exception Handling component and then logged and reported. Also note that a copy of error log may be put in a reserved area in RAM, so that we can report this after a warm reset when the system is back in good state.
|
||||
|
||||
# Detailed design
|
||||
|
||||
### Common error code definitions
|
||||
|
||||
Common error scenarios should be identified and each of them should have corresponding error code defined. The error codes should be extensible by applications needing to define custom error codes. To facilitate efficient use of memory, 32-bit values should be used to represent each error and encode following information using different fields.
|
||||
|
||||
- Code (16 bits) – Unique code identifying the error.
|
||||
- Entity (8 bits) – Entity or component generating the error.
|
||||
- Type (2 bits) – System defined error or Custom defined error.
|
||||
- 31st Bit is always set to make the error code negative.
|
||||
|
||||
**NOTE: Remaining bits will be unused and may be used for future expansion/extension.**
|
||||
|
||||
The error codes, entity and type should be defined in a platform level header file accessible to all layers of the system (applications, drivers, sdks etc).
|
||||
|
||||
**Capturing POSIX error codes**
|
||||
|
||||
Presently many modules (like filesystems) under Mbed OS use Posix error codes to report error back into the system. It’s better to make sure the Posix error code definitions doesn’t overlap with Mbed Error code standardization and make it easier for developers to report Posix error codes into Mbed error coding/handling system if required. Although we support Posix error codes for backward compatibility, its highly encouraged that all future Mbed OS focused implementations use Mbed OS error code definitions so that errors reported works seamlessly with error reporting and handling implementation in Mbed OS.
|
||||
|
||||
To incorporate Posix error code representation into Mbed OS, a portion of error space is allocated for Posix error codes. Since Mbed OS error codes will always be negative, we will capture the negative of the actual Posix error code in the error code defintions. For example, the error code equivalent for EPERM in Mbed OS error code space would be -EPERM. This aligns with Mbed OS error coding convention of using negative values, but the numerical value will be same as the Posix error code.
|
||||
|
||||
**Using error codes**
|
||||
|
||||
The Mbed OS error codes can be used under 2 circumstances:
|
||||
|
||||
1. It can be used as a return value when a function returns indicating the error situation.
|
||||
A successful return should be either 0 or a positive value. The Mbed OS defined error codes should always be negative as mentioned above.
|
||||
1. It can also be used to report a fatal/non-fatal error into the Mbed OS error handling system to be reported and recorded in the error log.
|
||||
|
||||
**NOTE: If you are using Posix error code to report into the Mbed OS error handling system make sure you are using the negative of the Posix error code.**
|
||||
|
||||
**Error code definitions**
|
||||
|
||||
Below are some of the error code definitions to be captured.
|
||||
ERROR_UNKNOWN
|
||||
ERROR_INVALID_ARGUMENT
|
||||
ERROR_INVALID_DATA
|
||||
ERROR_INVALID_FORMAT
|
||||
ERROR_INVALID_INDEX
|
||||
ERROR_INVALID_SIZE
|
||||
ERROR_NOT_FOUND
|
||||
ERROR_ACCESS_DENIED
|
||||
ERROR_NOT_SUPPORTED
|
||||
ERROR_BUFFER_FULL
|
||||
ERROR_MEDIA_FULL
|
||||
ERROR_ALREADY_IN_USE
|
||||
ERROR_TIMEOUT
|
||||
ERROR_NOT_READY
|
||||
ERROR_FAILED_OPERATION
|
||||
ERROR_OPERATION_PROHIBITED
|
||||
ERROR_OPERATION_ABORTED
|
||||
ERROR_WRITE_PROTECTED
|
||||
ERROR_NO_RESPONSE
|
||||
ERROR_SEMAPHORE_LOCK_FAILED
|
||||
ERROR_MUTEX_LOCK_FAILED
|
||||
ERROR_SEMAPHORE_UNLOCK_FAILED
|
||||
ERROR_MUTEX_UNLOCK_FAILED
|
||||
ERROR_CRC_ERROR
|
||||
ERROR_OPEN_FAILED
|
||||
ERROR_CLOSE_FAILED
|
||||
ERROR_INITIALIZATION_FAILED
|
||||
ERROR_BOOT_FAILURE
|
||||
ERROR_OUT_OF_MEMORY
|
||||
ERROR_OUT_OF_RESOURCES
|
||||
ERROR_ALLOC_FAILED
|
||||
ERROR_FREE_FAILED
|
||||
ERROR_OVERFLOW
|
||||
ERROR_UNDERFLOW
|
||||
ERROR_STACK_OVERFLOW
|
||||
ERROR_ISR_QUEUE_OVERFLOW
|
||||
ERROR_TIMER_QUEUE_OVERFLOW
|
||||
ERROR_CLIB_SPACE_UNAVAILABLE
|
||||
ERROR_CLIB_MUTEX_INIT_FAILURE
|
||||
ERROR_CREATE_FAILED
|
||||
ERROR_DELETE_FAILED
|
||||
ERROR_THREAD_CREATE_FAILED
|
||||
ERROR_THREAD_DELETE_FAILED
|
||||
ERROR_PROHIBITED_IN_ISR_CONTEXT
|
||||
ERROR_PINMAP_INVALID
|
||||
ERROR_RTOS_EVENT
|
||||
ERROR_RTOS_THREAD_EVENT
|
||||
ERROR_RTOS_MUTEX_EVENT
|
||||
ERROR_RTOS_SEMAPHORE_EVENT
|
||||
ERROR_RTOS_MEMORY_POOL_EVENT
|
||||
ERROR_RTOS_TIMER_EVENT
|
||||
ERROR_RTOS_EVENT_FLAGS_EVENT
|
||||
ERROR_RTOS_MESSAGE_QUEUE_EVENT
|
||||
ERROR_DEVICE_BUSY
|
||||
ERROR_CONFIG_UNSUPPORTED
|
||||
ERROR_CONFIG_MISMATCH
|
||||
ERROR_ALREADY_INITIALIZED
|
||||
ERROR_HARDFAULT_EXCEPTION
|
||||
ERROR_MEMMANAGE_EXCEPTION
|
||||
ERROR_BUSFAULT_EXCEPTION
|
||||
ERROR_USAGEFAULT_EXCEPTION
|
||||
|
||||
**Error type definition**
|
||||
|
||||
Below are the error types supported. Mbed OS defined error codes should be classified as system error codes. A platform or implementation can always define their own error codes but should use custom error types to classify those. In addition, Posix error codes should also be supported under error code definitions, handling and reporting. This enables better diagnostics and routing for defects reported by the system. To capture all these error types under negative integer space, each error type will be assigned a range of negative error space. See Section 5.1.6 - Error Codes Values/Ranges for details.
|
||||
|
||||
ERROR_TYPE_SYSTEM,
|
||||
ERROR_TYPE_CUSTOM,
|
||||
ERROR_TYPE_POSIX ( = 3 )
|
||||
|
||||
**Entity or component type generating the error**
|
||||
|
||||
There should be definitions to capture the origination or location of the error. The below are some of the entity definitions which should be captured by the error handling system to identify where the error is originating from.
|
||||
|
||||
ENTITY_ANY ( = 0 ),
|
||||
ENTITY_APPLICATION,
|
||||
ENTITY_PLATFORM,
|
||||
ENTITY_KERNEL,
|
||||
ENTITY_NETWORK_STACK,
|
||||
ENTITY_HAL,
|
||||
ENTITY_MEMORY_SUBSYSTEM,
|
||||
ENTITY_FILESYSTEM,
|
||||
ENTITY_BLOCK_DEVICE,
|
||||
ENTITY_DRIVER,
|
||||
ENTITY_DRIVER_SERIAL,
|
||||
ENTITY_DRIVER_RTC,
|
||||
ENTITY_DRIVER_I2C,
|
||||
ENTITY_DRIVER_SPI,
|
||||
ENTITY_DRIVER_GPIO,
|
||||
ENTITY_DRIVER_ANALOG,
|
||||
ENTITY_DRIVER_DIGITAL,
|
||||
ENTITY_DRIVER_CAN,
|
||||
ENTITY_DRIVER_ETHERNET,
|
||||
ENTITY_DRIVER_CRC,
|
||||
ENTITY_DRIVER_PWM,
|
||||
ENTITY_DRIVER_QSPI,
|
||||
ENTITY_DRIVER_USB,
|
||||
ENTITY_TARGET_SDK,
|
||||
|
||||
The bit field representation of these fields in unsigned 32-bit integer should be as below. The error code will always be represented as negative.
|
||||
|
||||
|
||||
|
||||
The platform should define a data type which maps to error status. For example, typedef int MbedErrorStatus;
|
||||
|
||||
The implementation should also provide convenient macros to combine Error Code, error type and Entity to build the error status. For example, the following could be the helper macro.
|
||||
|
||||
MAKE_ERROR (type, entity_type, code)
|
||||
|
||||
For example, the usage would be:
|
||||
|
||||
my_new_error_status = MAKE_ERROR (ERROR_TYPE_SYSTEM, ENTITY_DRIVER, ERROR_OUT_OF_MEMORY );
|
||||
|
||||
**Error codes values and ranges**
|
||||
|
||||
Based on error code definitions below are the error code ranges for each error type.
|
||||
Posix Error Codes: 1 to 255
|
||||
System Error Codes: 256 to 4095
|
||||
Custom Error Codes: 4096 to 65535
|
||||
|
||||
The corresponding error status encoding for entity = 0(ENTITY_ANY) entity should be encoded as below. Note that error statuses are always negative.
|
||||
Posix Error Statuses: 0xFFFFFFFF – 0xFFFFFF01 – This corresponds to Posix error codes in negative.
|
||||
System Error Statuses: 0x80000100 – 0x80000FFF - This corresponds to Custom error codes with entity field set to ENTITY_ANY.
|
||||
Custom Error Statuses: 0x80001000 – 0x8000FFFF - This corresponds to System error codes with entity field set to ENTITY_ANY.
|
||||
|
||||
### Error handling and management functions
|
||||
|
||||
The implementation should provide necessary APIs for error handling and error management. These APIs are expected to be called from C and C++ code as this will be used by SDK/Target/HAL code as well. The system should also capture each error with some context specified by a data structure. That error context data structure should capture information such as – current thread, filename of the source file where the error is logged from etc. A sample error context data structure may be as below.
|
||||
|
||||
**Error context data structure**
|
||||
|
||||
Below shows what the Error context data structure may contain.
|
||||
|
||||
```C
|
||||
typedef struct _mbed_error_ctx {
|
||||
uint32_t error_function_address;
|
||||
uint32_t thread_id;
|
||||
uint32_t thread_entry_address;
|
||||
uint32_t thread_stack_size;
|
||||
uint32_t thread_start_mem;
|
||||
uint32_t thread_current_sp;
|
||||
char error_filename[n];
|
||||
uint32_t error_line_number;
|
||||
} mbed_error_ctx;
|
||||
```
|
||||
|
||||
The filename capture will be in the form of an ascii string and the maximum size of that string depends on memory/resources provided by the platform and can be made a configurable.
|
||||
|
||||
Below are some APIs expected to be supported:
|
||||
|
||||
**mbed_error ()**
|
||||
|
||||
This call can be used to log a fatal error and halt the system. The caller will not get the control back as the system will be halted.
|
||||
|
||||
The API signature shall be as below, the error_msg is optional and can be NULL.
|
||||
|
||||
MbedErrorStatus set_error_fatal(MbedErrorStatus error_status, char *error_msg, unsigned int error_value, char *filename, int line_number);
|
||||
|
||||
**mbed_get_last_error ()**
|
||||
|
||||
This API is called to get the last error code logged into the system. If there are no errors recorded this function should return ERROR_NOT_FOUND.
|
||||
|
||||
The API signature shall be as below:
|
||||
|
||||
MbedErrorStatus get_last_error(void)
|
||||
|
||||
**mbed_get_error_count ()**
|
||||
|
||||
This API should return the total number of errors reported from the last boot. Note that this is different from number of errors we logged which may be only a subset of recent errors reported.
|
||||
|
||||
The API signature shall be as below:
|
||||
int get_error_count ()
|
||||
|
||||
**mbed_get_error_log_info ()**
|
||||
|
||||
This API is called to retrieve the error context information which is logged as part set_error() call. It should take the index of the error for which the error information is requested. If there is no error information found it should return NULL for error_info, and function should with an error value (ERROR_NOT_FOUND?). If the index is invalid it should return an error code (ERROR_INVALID_INDEX?).
|
||||
|
||||
The API signature shall be as below:
|
||||
|
||||
MbedErrorStatus get_error_log_info (int index, mbed_error_ctx *error_info);
|
||||
Memory for error_info should be pre-allocated by the caller.
|
||||
|
||||
**mbed_get_last_error_log_info ()**
|
||||
|
||||
This API is called to retrieve the error context information which is logged as part of the last set_error() call. If there is no error information found it should return NULL for error_info, and function should with an error value (ERROR_NOT_FOUND?).
|
||||
|
||||
The API signature shall be as below:
|
||||
|
||||
MbedErrorStatus get_last_error_log_info (mbed_error_ctx *error_info);
|
||||
|
||||
**mbed_get_error_log_count ()**
|
||||
|
||||
This API should return the total number of errors in the error log. Note that this will be a set of latest reported errors depending on the size of error log.
|
||||
|
||||
The API signature shall be as below:
|
||||
|
||||
int get_error_log_count ()
|
||||
|
||||
**mbed_clear_all_errors ()**
|
||||
|
||||
This API will reset the logged errors and set the error count to 0 as well. This can be useful for testing purposes and initialization.
|
||||
|
||||
The API signature shall be as below:
|
||||
|
||||
MbedErrorStatus clear_all_errors ()
|
||||
|
||||
### Error logging
|
||||
|
||||
The implementation should provide an error logging system to record a limited number of most recent errors. The number of entries in the log may be configurable depending on memory constraints. The error log can be implemented as a circular buffer which captures most recent errors. The APIs described above will act on this buffer. The buffer may not be exposed externally, and the users or applications should use the APIs to interact with this buffer. The error log should also be able to record some error data specific to the error being reported maxed at pre-defined number of bytes (For example, 64 bytes? per entry). This may be configurable depending on use case. Below diagram shows the interaction between error log and the APIs which access the log buffer.
|
||||
|
||||
|
||||
|
||||
### Error reporting
|
||||
|
||||
When a subsystem or any component in the system encounters a fatal error, it will be reported to the error reporting subsystem which should print the error information through STDOUT (which is usually the serial terminal) with relevant information. The information printed out should contain the error code, the function (address) which reported the error, the stack trace (raw data from the current stack), the time of crash etc, current task info etc. For example, below shows a sample of what could be reported as part of fatal error handling.
|
||||
|
||||
Error Code: error code
|
||||
Error Function: calling function
|
||||
File: filename:nnn
|
||||
Task Info: current task
|
||||
Stack Dump: dump some words from the stack
|
||||
|
||||
The error reporting subsystem may support backing this error log into filesystem, if provided by the platform. Every time we back that up in filesystem, we also clear the current log in RAM. The backing up of Error log into filesystem should be triggered by calling an explicit API such as below.
|
||||
|
||||
**mbed_save_error_log()**
|
||||
|
||||
This API should be called to save the current error logs to a backup device such as filesystem.
|
||||
|
||||
The API to save the error log may be as below:
|
||||
|
||||
MbedErrorStatus save_error_log(char *backupFileName)
|
||||
The backupFileName captures the filename to be used for error log in filesystem.
|
||||
|
||||
### Fault Exceptions Handling
|
||||
Cortex-M based processors trigger fault exceptions when the core encounters an unrecoverable error. Below are the fault exceptions triggered by Cortex-M based processor.
|
||||
|
||||
- MemManage Exception - Memory accesses that violate the setup in the MPU and certain illegal memory accesses trigger memory management faults.
|
||||
- BusFault Exception - When an error response is received during a transfer on the AHB interfaces, it produces bus faults.
|
||||
- UsageFault Exception - Division by zero, unaligned accesses and trying to execute coprocessor instructions can cause usage faults.
|
||||
- HardFault Exception - Triggered on all fault conditions or if the corresponding fault handler (one of the above) is not enabled.
|
||||
|
||||
Not all faults exceptions are supported by all cores. For example, Cortex-M0/M0+ processors (or any ARMv6M processors) do not have MemManage, BusFault and UsageFault exceptions implemented. In those cases, all exceptions are reported as HardFault exception. For ARMv7M processors, MemManage, BusFault and UsageFault exceptions trigger only if they are enabled in System Handler Control and State Register (SHCSR). When these exceptions happen, they should be handled by proper exception handlers to generate a crash dump and should update the error log with this information. It should also be reported over STDOUT (serial terminal). The crash information should contain register context at the time of exception, exception type, current threads in the system etc. Below diagram depicts how the exception handling works.
|
||||
|
||||
|
||||
|
||||
### Application hook for error handling
|
||||
|
||||
Some applications may need to do custom error handling on some scenarios. To facilitate this, a mechanism should be provided to register a custom error handling/hook function from application side to the error handling sub-system. When such a hook is present, the error handling system should call the registered callback when an error is encountered before handling the error.
|
||||
|
||||
**Error hook API**
|
||||
|
||||
The API to register a hook function may be as below:
|
||||
|
||||
MbedErrorStatus set_error_hook( ErrorHookFunction custom_error_hook )
|
||||
where ErrorHookFunction is
|
||||
typedef MbedErrorStatus (*ErrorHookFunction)(unsigned int error_code)
|
||||
|
||||
Below sequence diagram shows how the API hook works when an error happens in the system:
|
||||
|
||||
|
||||
|
||||
# Usage scenarios and examples
|
||||
|
||||
Below (pseudocode) are some common usage scenarios using the error handling APIs.
|
||||
|
||||
### Defining error codes
|
||||
|
||||
**Defining a nonfatal out-of-memory error.**
|
||||
|
||||
As shown in the example below, you can fabricate new error codes using MAKE_ERROR macro.
|
||||
|
||||
```
|
||||
char *dataPtr = malloc( datasize );
|
||||
If( dataPtr == NULL )
|
||||
{
|
||||
// Make a new error code
|
||||
uint32 errorCode = MAKE_ERROR(
|
||||
ERROR_TYPE_SYSTEM,
|
||||
ENTITY_DRIVER,
|
||||
ERROR_OUT_OF_MEMORY);
|
||||
set_error( errorCode, NULL, NULL );
|
||||
}
|
||||
```
|
||||
|
||||
Below (pseudocode) are some common usage scenarios using the error handling APIs.
|
||||
|
||||
### Defining error codes
|
||||
|
||||
**Defining a nonfatal out-of-memory error.**
|
||||
|
||||
As shown in the example below, you can fabricate new error codes using MAKE_ERROR macro.
|
||||
|
||||
```
|
||||
char *dataPtr = malloc( datasize );
|
||||
If( dataPtr == NULL )
|
||||
{
|
||||
// Make a new error code
|
||||
uint32 errorCode = MAKE_ERROR(
|
||||
ERROR_TYPE_SYSTEM,
|
||||
ENTITY_DRIVER,
|
||||
ERROR_OUT_OF_MEMORY);
|
||||
set_error( errorCode, NULL, NULL );
|
||||
}
|
||||
```
|
||||
|
||||
### Reporting errors
|
||||
|
||||
**Reporting a fatal error using set_error_fatal API**
|
||||
|
||||
The below sample code shows how to report a fatal error using set_error_fatal API:
|
||||
|
||||
```
|
||||
char *dataPtr = malloc( datasize );
|
||||
If( dataPtr == NULL )
|
||||
{
|
||||
// Make a new error code
|
||||
uint32 errorCode = MAKE_ERROR(
|
||||
ERROR_TYPE_SYSTEM,
|
||||
ENTITY_DRIVER,
|
||||
ERROR_OUT_OF_MEMORY);
|
||||
set_error_fatal( errorCode, NULL, NULL );
|
||||
}
|
||||
```
|
||||
|
||||
### Setting up an error hook function
|
||||
|
||||
**Defining and registering an error hook function**
|
||||
|
||||
The below shows a definition for error hook function, followed by Error hook registration from main.
|
||||
|
||||
```
|
||||
MbedErrorStatus MyErrorHookFunction(unsigned int error_code)
|
||||
{
|
||||
printf( “New error received” %X”, error_code );
|
||||
//Do more processing
|
||||
…
|
||||
}
|
||||
//Main function registering the Error hook function.
|
||||
Main()
|
||||
{
|
||||
set_error_hook(MyErrorHookFunction);
|
||||
.. Continue
|
||||
}
|
||||
```
|
||||
|
||||
### Getting error info
|
||||
|
||||
**Getting error info using get_error_log_count and get_error calls.**
|
||||
|
||||
The below sample code shows how to retrieve all the recorded error codes from the error log.
|
||||
int totalErrorsInLog = get_error_log_count();
|
||||
for( index = 0; index < totalErrorsInLog; index++)
|
||||
{
|
||||
printf( “Error %d: Code = 0X%08X”, get_error(index));
|
||||
}
|
||||
Reporting errors
|
||||
|
||||
**Reporting a fatal error using set_error_fatal API**
|
||||
|
||||
The below sample code shows how to report a fatal error using set_error_fatal API.
|
||||
char *dataPtr = malloc( datasize );
|
||||
If( dataPtr == NULL )
|
||||
{
|
||||
// Make a new error code
|
||||
uint32 errorCode = MAKE_ERROR(
|
||||
ERROR_TYPE_SYSTEM,
|
||||
ENTITY_DRIVER,
|
||||
ERROR_OUT_OF_MEMORY);
|
||||
set_error_fatal( errorCode, NULL, NULL );
|
||||
}
|
||||
|
||||
### Setting up an error hook function
|
||||
|
||||
**Defining and registering an error hook function**
|
||||
|
||||
The below shows a definition for error hook function, followed by Error hook registration from main.
|
||||
MbedErrorStatus MyErrorHookFunction(unsigned int error_code)
|
||||
{
|
||||
printf( “New error received” %X”, error_code );
|
||||
//Do more processing
|
||||
…
|
||||
}
|
||||
//Main function registering the Error hook function.
|
||||
Main()
|
||||
{
|
||||
set_error_hook(MyErrorHookFunction);
|
||||
.. Continue
|
||||
}
|
||||
|
||||
### Getting error info
|
||||
|
||||
**Getting error info using get_error_log_count and get_error calls.**
|
||||
|
||||
The below sample code shows how to retrieve all the recorded error codes from the error log.
|
||||
int totalErrorsInLog = get_error_log_count();
|
||||
for( index = 0; index < totalErrorsInLog; index++)
|
||||
{
|
||||
printf( “Error %d: Code = 0X%08X”, get_error(index));
|
||||
}
|
||||
|
||||
# Tools and configuration changes
|
||||
|
||||
### Platform configuration options for error handling infrastruture
|
||||
|
||||
Below is the list of new configuration options added to configure error handling functionality. All of these options are capture in mbed_lib.json file in platform folder.
|
||||
|
||||
**error-all-threads-info**
|
||||
|
||||
Enabling this reports all the threads in the system as part of error report.
|
||||
|
||||
**error-filename-capture-enabled**
|
||||
|
||||
Enables capture of filename and line number as part of error context capture, this works only for debug and develop builds. On release builds, filename capture is always disabled
|
||||
|
||||
**error-hist-enabled**
|
||||
|
||||
Enable this option for error history tracking.
|
||||
|
||||
**error-hist-size**
|
||||
|
||||
This options sets the number of most recent errors the system keeps in its history, needs error-hist-enabled set to true for this to work.
|
||||
|
||||
**max-error-filename-len**
|
||||
|
||||
Sets the maximum length of buffer used for capturing the filename in error context. This needs error-filename-capture-enabled feature.
|
||||
|
||||
# Other information
|
||||
|
||||
### Reusability
|
||||
|
||||
The error handling implementation is very generic that other components should no longer need to implement their own error codes or handling. For example, fault exception handling implements part of error handling (like halting the system) which is no longer needed and can be switched to use common error handling which handles system behavior on a fatal error.
|
||||
|
||||
### Deprecations
|
||||
|
||||
### References
|
||||
|
||||
|
||||
|
||||
|
|
@ -0,0 +1 @@
|
|||
# Design Documents - Connectivity
|
||||
|
|
@ -0,0 +1 @@
|
|||
# Design Documents - Filesystem
|
||||
|
|
@ -0,0 +1 @@
|
|||
# Design Documents - Security
|
||||
|
|
@ -0,0 +1 @@
|
|||
# Design Documents - Storage
|
||||
|
|
@ -0,0 +1 @@
|
|||
# Design Documents - Hardware Abstraction Layer
|
||||
|
|
@ -0,0 +1 @@
|
|||
# Design Documents - Platform
|
||||
|
|
@ -0,0 +1 @@
|
|||
# Design Documents - RTOS
|
||||
|
|
@ -0,0 +1 @@
|
|||
# Design Documents - Tools
|
||||
Loading…
Reference in New Issue