mirror of https://github.com/ARMmbed/mbed-os.git
Design process and template for Mbed-OS
Senthil Ramakrishnan
parent
1ab05c28f6
commit
cde5e6edd4
|
|
@ -0,0 +1,40 @@
|
|||
# Design Process for Mbed-OS
|
||||
This document defines the software design process for Mbed-OS. Anyone developing for Mbed-OS should use this process to submit the design to get it reviewed from the broader Mbed-OS developer community.
|
||||
|
||||
## Design documents location and organization
|
||||
* It's suggested to write one design document per change, which could be a new feature, defect fixes, tools changes etc. Do not try to address multiple changes in the same document.
|
||||
* The design document will follow the format represented in [Design Document Template](https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/design_template.md)
|
||||
|
||||
* For each design submission, create a folder under *https://github.com/ARMmbed/mbed-os/docs/design-documents/{AREA OR COMPONENT}*. The area/component would be Drivers, Platform, Connectivity, Security, Peripherals etc.
|
||||
If your implementation is creating new APIs, you should try to 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 new EMAC API, you may name the folder as **New_EMAC_API** or if you are creating a new Serial Driver for Mbed-OS you may name the folder as **Serial_driver_for_Mbed-os**.
|
||||
* Your design document itself should also be named with the same name of the as the folder, so that it serves
|
||||
as your master design document, if you happen to use other .md files under same folder as annexures or reference.
|
||||
* The diagrams you are using may exist in the sub-folder *diagrams* under the new folder you have created.
|
||||
See [Example Design Document](https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/example_feature_design/example_feature_design.md) for example design document.
|
||||
|
||||
### Using diagrams in Design documents
|
||||
Its highly encouraged to create diagrams to depict your software design. The [Design Document Template]((https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/design_template.md) provided here uses diagrams generated using draw.io. draw.io generates XMLs for each diagram and those corresponding XMLs are also provided under the diagrams folder, and you are free to use that as your reference for generating your own diagrams. And, when you are generating your own diagrams it would be better to provide the metadata/other files(e.g, if you are using draw.io provide XMLs from draw.io) required for future editing of those diagrams.
|
||||
|
||||
## Design Process
|
||||
* Developer generates a design document located under *https://github.com/ARMmbed/mbed-os/docs/design-documents/{AREA OR COMPONENT}* and generates a pull-request to Mbed-OS.
|
||||
* NOTE: If you are part of an organization and would like to do design review within your organization before landing the pull-request, its ok to do so.
|
||||
* The pull request may also include the initial code implementation. It's upto to the develper to decide if the initial implementation comes along with the design document or later.
|
||||
* Although, if you are planning a large change, its encoraged to start the design review early before the implementation. This also help to avoid major re-work of your implementation if required by the design review.
|
||||
* Design review follows the same process as code review. Please refer contribution process as outlined in [Contributing to Mbed-OS](https://os.mbed.com/contributing/) for more information.
|
||||
* Once the design is approved, implementation is completed/adjusted according to the latest design document. Developer can create the pull-request with the final implementation, if its coming separately.
|
||||
|
||||
## Capturing future changes to design
|
||||
If your implementation changes in future, corresponsding design documents may be updated to capture the new design.
|
||||
It's possible that a new implementation may require changes to some previous implementations. In that case, capture
|
||||
the new changes in the original design document as well. Also create references to other(or older) design documents in the
|
||||
References section for the new 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,194 @@
|
|||
# Mbed-OS Design Document
|
||||
Write your feature title above, in this case its "Mbed-OS Design Document"
|
||||
|
||||
# Table of Contents
|
||||
- [Mbed-OS Design Document](#mbed-os-design-document)
|
||||
- [Table of Contents](#table-of-contents)
|
||||
- [Revision history](#revision-history)
|
||||
- [Introduction](#introduction)
|
||||
- [Overview and Background](#overview-and-background)
|
||||
- [Requirements and Assumptions](#requirements-and-assumptions)
|
||||
- [System Architecture and High-Level Design](#system-architecture-and-high-level-design)
|
||||
- [System Architecture and Component Interaction](#system-architecture-and-component-interaction)
|
||||
- [Detailed Design](#detailed-design)
|
||||
- [Usage Scenarios and Examples](#usage-scenarios-and-examples)
|
||||
- [Tools and Configuration Changes](#tools-and-configuration-changes)
|
||||
- [Other Information](#other-information)
|
||||
- [Reusability](#reusability)
|
||||
- [Deprecations](#deprecations)
|
||||
- [References](#references)
|
||||
- [Custom Headings Here](#custom-headings-here)
|
||||
|
||||
### Revision history
|
||||
1.0 - A brief description for this version, e.g. Initial revision - Author name - Date
|
||||
1.1 - Added new section - Author name - Date
|
||||
|
||||
# Introduction
|
||||
### Overview and Background
|
||||
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.
|
||||
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
|
||||
hw capabilities, memory requirements, security assets like presence of RoT infrastructure, then capture those here.
|
||||
For example:- This feature requires QuadSPI interface on the target as it implements block device driver over 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 on areas or components needing changes or new development to implement this
|
||||
feature. The idea here is to capture the high level design goals of this feature for the target reader, the focus here should
|
||||
be what functionality it provides and not the actual implementation. For example, if you are implementing a new device driver
|
||||
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.
|
||||
|
||||
* `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/multiple bytes.
|
||||
* `Resetting the device` - Functionality to reset the device should be provided.
|
||||
|
||||
**NOTE: If you already have supporting architecture documentation in the form of technology documents or other existing documents
|
||||
feel free to link them here and use that, you don't have to replicate the same documentation here.**
|
||||
|
||||
For each high level design goal, provide detailed software design under [Detailed Design](#detailed-design) section providing more details on implementation.
|
||||
|
||||
### System Architecture and Component Interaction
|
||||
Description and diagrams showing overall architecture of how the above-mentioned components/resources interface with each other.
|
||||
For, example if the new feature is to implement a driver and if it provides interfaces with application and uses memory subsystem in OS
|
||||
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
|
||||
minute details.
|
||||
|
||||
|
||||
|
||||
# Detailed Design
|
||||
This section provides detailed design on implementation of each of the high level design goal mentioned above.
|
||||
Each components/modules needing changes are also captured in details. The target audience here is a developer
|
||||
who can read this section and start the real implemention. You can capture things like signature of interfaces,
|
||||
flow charts showing how the APIs work, data flow diagrams etc. The headings for each detailed design section
|
||||
should match the headings in high level design goals. For example, based on the example provided above,
|
||||
the headings for details design sections should be `Configuring the device`, `Starting and stopping the device`,
|
||||
`Reading from and Writing to the device`, `Resetting the device`.
|
||||
|
||||
### Detailed Design 1 - e.g, `Configuring the device`
|
||||
|
||||
**API Description**
|
||||
Detailed API Description like signature of interface, explanation of arguments, return codes etc.
|
||||
For example, if you are trying to define an interface for configuring the device, you may describe
|
||||
the API as below.
|
||||
|
||||
`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 etc. For example, the flow chart for configure device API above may
|
||||
be something like below.
|
||||
|
||||
|
||||
|
||||
### Detailed Design 2 - e.g, `Starting and stopping the device`
|
||||
|
||||
**API Description**
|
||||
Detailed API Description like signature of interface, explanation of arguments, return codes etc
|
||||
For example, for start and stop functions exported by the driver.
|
||||
|
||||
**Sequence Diagrams for `Starting and stopping the device`**
|
||||
Sequence Diagrams, Data flow diagrams etc. For example, the sequence digram for stopping the device may look
|
||||
something like below.
|
||||
|
||||
|
||||
|
||||
### Detailed Design 3 - e.g, `Reading from and Writing to the device`
|
||||
|
||||
**API Description**
|
||||
Detailed API Description like signature of interface, explanation of arguments, return codes etc
|
||||
|
||||
**Sequence Diagram for `Reading from and Writing to the device`**
|
||||
Sequence Diagrams, Data flow diagrams etc.
|
||||
|
||||
### Detailed Design N - e.g, `Resetting the device`
|
||||
|
||||
**API Description**
|
||||
Detailed API Description like signature of interface, explanation of arguments, return codes etc
|
||||
|
||||
**Sequence Diagram for `Resetting the device`**
|
||||
Sequence Diagrams, Data flow diagrams etc.
|
||||
|
||||
# Usage Scenarios and Examples
|
||||
Show pseudo-code or flowcharts explaining the usage of the feature. For example you may want to include
|
||||
some pseudo code to demonstrate how the read functionality is used with the new driver design you are
|
||||
proposing.
|
||||
|
||||
### Scenario 1 - e.g, `Reading from the device`
|
||||
Mention the specific usage scenarios here. For example, the below examples shows how to read data from
|
||||
device using the new APIs.
|
||||
|
||||
**Scenario 1 Example 1. - e.g, `Reading a byte from device`**
|
||||
Mention the specific usage here. For example, the below example shows pseudo-code 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. - e.g, `Reading multiple bytes from device`**
|
||||
In this example, the pseudo-code 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 - e.g, `Writing to the device`
|
||||
Mention another usage scenarios here. For example, you can demostrate how to write to the device
|
||||
and few examples of usage.
|
||||
|
||||
**Scenario 2 Example 1. - e.g, `Writing a byte to device`**
|
||||
Demonstrate the specific example here. For example, how to write a byte of data to device.
|
||||
|
||||
**Scenario 2 Example 2. - e.g, `Writing multiple bytes to device`**
|
||||
Demonstrate another specific example here. For example, how to write mutiple bytes of data to device.
|
||||
|
||||
# Tools and Configuration Changes
|
||||
Explain which tools needs to be changed and the nature of changes.
|
||||
For example, if the feature requires adding a new sub-command to mbed-cli capture
|
||||
the details of changes and usage here. Each tool change can be captured under its own
|
||||
sub-heading as below. You can also capture new configuration values which needs to be
|
||||
added to mbed json based configuration system. For each, config value added explan
|
||||
the name of the config value and how to use it and its relation to any pre-processor
|
||||
defines in the implementation.
|
||||
|
||||
### Tool Change 1 - e.g: - Command line additions/changes
|
||||
|
||||
### Configuration Changes e.g: - Configuration changes in Json files etc
|
||||
|
||||
# Other Information
|
||||
Add other relevant information you would like to capture. Add custom headings if required.
|
||||
|
||||
### Reusability
|
||||
List the components or pieces of implementation which can be re-used for specific
|
||||
design patterns/other implementations.
|
||||
|
||||
### Deprecations
|
||||
List the APIs which may be deprecated as part of this feature.
|
||||
|
||||
### References
|
||||
Capture information such as specifications, other design docs, other implementations Urls etc.
|
||||
|
||||
### Custom Headings Here
|
||||
Add your custom headings here, for example security impacts of this feature can be put
|
||||
under the heading `Security Impacts`.
|
||||
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>
|
||||
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,524 @@
|
|||
# WARNING: THIS IS AN EXAMPLE DESIGN DOCUMENT
|
||||
|
||||
# Standardized Error Coding and Error Handling
|
||||
|
||||
# Table of Contents
|
||||
- [WARNING: THIS IS AN EXAMPLE DESIGN DOCUMENT](#warning-this-is-an-example-design-document)
|
||||
- [Standardized Error Coding and Error Handling](#standardized-error-coding-and-error-handling)
|
||||
- [Table of Contents](#table-of-contents)
|
||||
- [Revision history](#revision-history)
|
||||
- [Introduction](#introduction)
|
||||
- [Overview and Background](#overview-and-background)
|
||||
- [Requirements and Assumptions](#requirements-and-assumptions)
|
||||
- [System Architecture and High-Level Design](#system-architecture-and-high-level-design)
|
||||
- [System Architecture and Component Interaction](#system-architecture-and-component-interaction)
|
||||
- [Detailed Design](#detailed-design)
|
||||
- [Usage Scenarios and Examples](#usage-scenarios-and-examples)
|
||||
- [Tools and Configuration Changes](#tools-and-configuration-changes)
|
||||
- [Other Information](#other-information)
|
||||
- [Reusability](#reusability)
|
||||
- [Deprecations](#deprecations)
|
||||
- [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.
|
||||
2. 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.
|
||||
3. Error clearing API – Application should be able to reset/clear the current set of errors recorded by the system.
|
||||
4. 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
|
||||
analyse 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 focussed 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.
|
||||
2. 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/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 sub-system 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(pseudo-code) are some common usage scenarios using the error handling APIs.
|
||||
### Defining Error codes
|
||||
**Defining a non-fatal 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(pseudo-code) are some common usage scenarios using the error handling APIs.
|
||||
|
||||
### Defining Error codes
|
||||
**Defining a non-fatal 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
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue