Kenji Arai
mbed-os5 only for TYBLE16
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
platform/cxxsupport/README.md@1:9db0e321a9f4, 2019-12-31 (annotated)
- Committer:
- kenjiArai
- Date:
- Tue Dec 31 06:02:27 2019 +0000
- Revision:
- 1:9db0e321a9f4
updated based on mbed-os5.15.0
Who changed what in which revision?
| User | Revision | Line number | New contents of line |
|---|---|---|---|
| kenjiArai | 1:9db0e321a9f4 | 1 | ## C++ support ## |
| kenjiArai | 1:9db0e321a9f4 | 2 | |
| kenjiArai | 1:9db0e321a9f4 | 3 | Mbed OS supports a number of toolchains, and the files here provide support |
| kenjiArai | 1:9db0e321a9f4 | 4 | to smooth over C++ library differences. |
| kenjiArai | 1:9db0e321a9f4 | 5 | |
| kenjiArai | 1:9db0e321a9f4 | 6 | The current baseline version is C++14, so we hope for full C++14 library |
| kenjiArai | 1:9db0e321a9f4 | 7 | support. |
| kenjiArai | 1:9db0e321a9f4 | 8 | |
| kenjiArai | 1:9db0e321a9f4 | 9 | Omissions are: |
| kenjiArai | 1:9db0e321a9f4 | 10 | * areas like chrono and threads, which depend on OS support, where |
| kenjiArai | 1:9db0e321a9f4 | 11 | retargeting is not complete. |
| kenjiArai | 1:9db0e321a9f4 | 12 | * atomics and shared pointers, as atomic implementations for ARMv6-M |
| kenjiArai | 1:9db0e321a9f4 | 13 | are not provided by all toolchains, and the ARMv7-M implementations include |
| kenjiArai | 1:9db0e321a9f4 | 14 | DMB instructions we do not want/need for non-SMP. |
| kenjiArai | 1:9db0e321a9f4 | 15 | |
| kenjiArai | 1:9db0e321a9f4 | 16 | User code should normally be able to include C++14 headers and get |
| kenjiArai | 1:9db0e321a9f4 | 17 | most expected functionality. (But bear in mind that many C++ library |
| kenjiArai | 1:9db0e321a9f4 | 18 | features like streams and STL containers are quite heavy and may |
| kenjiArai | 1:9db0e321a9f4 | 19 | not be appropriate for small embedded use). |
| kenjiArai | 1:9db0e321a9f4 | 20 | |
| kenjiArai | 1:9db0e321a9f4 | 21 | However, ARM C 5 has only C++11 language support (at least a large subset), and |
| kenjiArai | 1:9db0e321a9f4 | 22 | no C++11/14 library. For the headers that are totally new in C++11, |
| kenjiArai | 1:9db0e321a9f4 | 23 | they are provided here in TOOLCHAIN_ARMC5 under their standard C++11 name. |
| kenjiArai | 1:9db0e321a9f4 | 24 | (Eg `<array>`, `<cinttypes>`, `<initializer_list>`, `<type_traits>`). |
| kenjiArai | 1:9db0e321a9f4 | 25 | But for headers that already exist in C++03, extensions are required. |
| kenjiArai | 1:9db0e321a9f4 | 26 | |
| kenjiArai | 1:9db0e321a9f4 | 27 | So, to support ARM C 5, use `#include <mstd_utility>`, rather than |
| kenjiArai | 1:9db0e321a9f4 | 28 | `#include <utility>` if you need C++11 or later features from that header. |
| kenjiArai | 1:9db0e321a9f4 | 29 | |
| kenjiArai | 1:9db0e321a9f4 | 30 | Each `mstd_` file includes the toolchain's corresponding header file, |
| kenjiArai | 1:9db0e321a9f4 | 31 | which will provide its facilities in `namespace std`. Any missing |
| kenjiArai | 1:9db0e321a9f4 | 32 | C++11/C++14 facilities for ARM C 5 are also provided in `namespace std`. |
| kenjiArai | 1:9db0e321a9f4 | 33 | |
| kenjiArai | 1:9db0e321a9f4 | 34 | Then APIs from `namespace std` are added to `namespace mstd`, with adjustment |
| kenjiArai | 1:9db0e321a9f4 | 35 | if necessary, and APIs being omitted if not suitable for embedded use. |
| kenjiArai | 1:9db0e321a9f4 | 36 | For example: |
| kenjiArai | 1:9db0e321a9f4 | 37 | |
| kenjiArai | 1:9db0e321a9f4 | 38 | * `std::size_t` (`<cstddef>`) - toolchain's `std::size_t` |
| kenjiArai | 1:9db0e321a9f4 | 39 | * `mstd::size_t` (`<mstd_cstddef>`) - alias for `std::size_t` |
| kenjiArai | 1:9db0e321a9f4 | 40 | * `std::swap` (`<utility>`) - toolchain's `std::swap` (not move-capable for ARM C 5) |
| kenjiArai | 1:9db0e321a9f4 | 41 | * `mstd::swap` (`<mstd_utility>`) - alias for `std::swap` or move-capable ARM C 5 replacement. |
| kenjiArai | 1:9db0e321a9f4 | 42 | * `std::atomic` (`<atomic>`) - toolchain's `std::atomic` (not implemented for IAR ARMv6) |
| kenjiArai | 1:9db0e321a9f4 | 43 | * `mstd::atomic` (`<mstd_atomic>`) - custom `mstd::atomic` for all toolchains |
| kenjiArai | 1:9db0e321a9f4 | 44 | * `std::void_t` (`<type_traits>`) - toolchain's `std::void_t` if available (it's C++17 so likely not) |
| kenjiArai | 1:9db0e321a9f4 | 45 | * `mstd::void_t` (`<mstd_type_traits>`) - alias for `std::void_t` if available, else local implementation |
| kenjiArai | 1:9db0e321a9f4 | 46 | * `std::thread` (`<thread>`) - toolchain's `std::thread` - not available or ported |
| kenjiArai | 1:9db0e321a9f4 | 47 | * `mstd::thread` - doesn't exist - `mstd` APIs only exist if available on all toolchains |
| kenjiArai | 1:9db0e321a9f4 | 48 | |
| kenjiArai | 1:9db0e321a9f4 | 49 | Using `std::xxx` will generally work, but may suffer from toolchain variance. `mstd::xxx` should always be better - it will either be an alias to `std::xxx`, or work better for Mbed OS. |
| kenjiArai | 1:9db0e321a9f4 | 50 | |
| kenjiArai | 1:9db0e321a9f4 | 51 | In portable code, when compiling for non-Mbed OS, the directive `namespace mstd == std` can be used |
| kenjiArai | 1:9db0e321a9f4 | 52 | to cover the difference: |
| kenjiArai | 1:9db0e321a9f4 | 53 | |
| kenjiArai | 1:9db0e321a9f4 | 54 | ```C++ |
| kenjiArai | 1:9db0e321a9f4 | 55 | // my_code.c |
| kenjiArai | 1:9db0e321a9f4 | 56 | #if TARGET_LIKE_MBED |
| kenjiArai | 1:9db0e321a9f4 | 57 | #include <mstd_atomic> |
| kenjiArai | 1:9db0e321a9f4 | 58 | #else |
| kenjiArai | 1:9db0e321a9f4 | 59 | #include <atomic> |
| kenjiArai | 1:9db0e321a9f4 | 60 | namespace mstd = std; |
| kenjiArai | 1:9db0e321a9f4 | 61 | #endif |
| kenjiArai | 1:9db0e321a9f4 | 62 | |
| kenjiArai | 1:9db0e321a9f4 | 63 | mstd::atomic my_atomic; |
| kenjiArai | 1:9db0e321a9f4 | 64 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 65 |