From 0fd0de6f31547654c4d395b85e661fd57bf580ab Mon Sep 17 00:00:00 2001 From: Simon Butcher Date: Wed, 26 Sep 2018 16:33:17 +0100 Subject: [PATCH 01/63] Update the Mbed TLS README.md Add content missing from the README.md taken from the Yotta/Mbed OS 3 Readme. --- features/mbedtls/README.md | 92 +++++++++++++++++++++++++++++++++++--- 1 file changed, 87 insertions(+), 5 deletions(-) diff --git a/features/mbedtls/README.md b/features/mbedtls/README.md index efb1ceace9..cbfc2ca6d3 100644 --- a/features/mbedtls/README.md +++ b/features/mbedtls/README.md @@ -1,14 +1,96 @@ -README for mbed TLS +README for Mbed TLS =================== -mbed TLS for mbed OS +Mbed TLS for Mbed OS -------------------- -This edition of mbed TLS has been adapted for mbed OS and imported from its standalone release, which you can find on [github here](https://github.com/ARMmbed/mbedtls). This edition of mbed TLS does not include test code, sample applications, or the scripts used in the development of the library. All of these can be found in the standalone release. +This edition of Mbed TLS has been adapted for Mbed OS and imported from its standalone release, which you can find on [github here](https://github.com/ARMmbed/mbedtls). This edition of Mbed TLS does not include the test code or the scripts used in the development of the library. All of these can be found in the standalone release. -Getting Help and Support ------------------------- +Getting Started +--------------- + +Several example programs are available that demonstrate the use of Mbed TLS with +Mbed OS. These are a great way of getting to know the library. + +1. [**TLS Client:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/tls-client) TLS Client demonstrates the use of Mbed TLS to establish a client TLS connection to a remote server. + +2. [**Benchmark:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/benchmark) Benchmark measures the time taken to perform basic cryptographic functions used in the library. + +3. [**Hashing:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/hashing) Hashing demonstrates the various APIs for computing hashes of data (also known as message digests) with SHA-256. + +4. [**Authenticated encryption:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/authcrypt) Authcrypt demonstrates usage of the Cipher API for encrypting and authenticating data with AES-CCM. + + +These examples are fully integrated into Mbed OS. Each of them comes with complete usage instructions as a `README.md` file in the directory of each example. + + +Configuring Mbed TLS features +----------------------------- + +Mbed TLS makes it easy to disable any feature during compilation, if that feature isn't required for a particular project. The default configuration enables all modern and widely-used features of the TLS protocol, which should meet the needs of most projects. It also disables all older and less common features, to minimize the code footprint. + +The list of available compilation flags is available in the fully documented [config.h file](https://github.com/ARMmbed/mbedtls/blob/development/include/mbedtls/config.h). + +If you need to adjust those flags, you can provide your own supplementary configuration-adjustment file with suitable `#define` and `#undef` statements. These will be included between the default definitions and the sanity checks. Your configuration file should be in your application's include directory, and can be named freely; you just need to let mbed TLS know the file's name. To do that, you can use the [Mbed OS Configuration +system](https://docs.mbed.com/docs/mbed-os-api/en/latest/api/md_docs_config_system.html) + +For example, if you wanted to enable the options, `MBEDTLS_PEM_WRITE_C` and `MBEDTLS_CMAC_C`, and provide your own additional configuration file for Mbed TLS named `my_config.h`, you could define these in a top level `mbed_app.json` configuration file in the root directory of your project. + +The Mbed TLS configuration file would be specified in the `.json` file as follows. + +``` +{ + "macros" : [ + + "MBEDTLS_USER_CONFIG_FILE" : "my_config.h", + + "MBEDTLS_PEM_WRITE_C", + "MBEDTLS_CMAC_C" + ] + ....remainder of file... +} +``` + +The additional configuration file, `my_config.h`, can then be used as a normal configuration header file to include additional configurations. For example, it could include the follow lines to include ECJPAKE, and the CBC block mode: + +``` + #define MBEDTLS_ECJPAKE_C + #define MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED + + #undef MBEDTLS_CIPHER_MODE_CBC +``` + +## Getting Mbed TLS from GitHub + +Mbed TLS is maintained and developed in the open, independently of Mbed OS, and its source can be found on GitHub here: [ARMmbed/mbedtls](https://github.com/ARMmbed/mbedtls). As a consequence, unlike other parts of mbed OS, changes to Mbed TLS must be committed upstream in the Mbed TLS repository. + +To import into an instance of Mbed OS a different version of Mbed TLS, a `Makefile` script is provided to update the local git repository, extract a specific version, and to modify the configuration files to those used for the Mbed OS defaults. + +To use the `Makefile`, you can either set `MBED_TLS_RELEASE` environment variable to the git tag or commit id of the Mbed TLS Release or version you want to use, or alternatively you can modify the `Makefile` itself. + +You should then run the following commands in the `importer` directory in the Mbed TLS directory: + +``` + make update + make +``` + +`make update` will pull the specified version of Mbed TLS into the local `importer/TARGET_IGNORE` directory and `make` will transform it into the `src` directory, modifying its configuration file as necessary. + +Once these steps are complete, you can make your Mbed OS build normally with the new version of Mbed TLS. + +## Differences between the standalone and mbed OS editions + +While the two editions share the same code base, there are still a number of differences, mainly in configuration and integration. You should keep in mind those differences when reading some articles in our [knowledge base](https://tls.mbed.org/kb), as currently all the articles are about the standalone edition. + +* The Mbed OS edition has a smaller set of features enabled by default in `config.h`, in order to reduce footprint. While the default configuration of the standalone edition puts more emphasize on maintaining interoperability with old peers, the mbed OS edition only enables the most modern ciphers and the latest version of (D)TLS. + +* The following components of mbed TLS are disabled in the mbed OS edition: `net_sockets.c` and `timing.c`. This is because Mbed OS includes its own equivalents. + + +Help and Support +---------------- The [mbed TLS website](https://tls.mbed.org/) contains full documentation for the library, including function by function descriptions, knowledgebase articles, blogs and a support forum for questions to the community. From fee476e48172c1a4437688649092519534660938 Mon Sep 17 00:00:00 2001 From: Simon Butcher Date: Wed, 3 Oct 2018 09:34:53 +0100 Subject: [PATCH 02/63] Update Mbed TLS README.md followng review Numerous changes to language, grammar, and corrections, following review. --- features/mbedtls/README.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/features/mbedtls/README.md b/features/mbedtls/README.md index cbfc2ca6d3..3e27766b35 100644 --- a/features/mbedtls/README.md +++ b/features/mbedtls/README.md @@ -4,7 +4,7 @@ README for Mbed TLS Mbed TLS for Mbed OS -------------------- -This edition of Mbed TLS has been adapted for Mbed OS and imported from its standalone release, which you can find on [github here](https://github.com/ARMmbed/mbedtls). This edition of Mbed TLS does not include the test code or the scripts used in the development of the library. All of these can be found in the standalone release. +This edition of Mbed TLS has been adapted for Mbed OS and imported from its standalone release, which you can find on [github here](https://github.com/ARMmbed/mbedtls). This edition of Mbed TLS does not include the test code or the scripts used in the development of the library. These can be found in the standalone release. Getting Started @@ -13,16 +13,16 @@ Getting Started Several example programs are available that demonstrate the use of Mbed TLS with Mbed OS. These are a great way of getting to know the library. -1. [**TLS Client:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/tls-client) TLS Client demonstrates the use of Mbed TLS to establish a client TLS connection to a remote server. +1. [**TLS Client:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/tls-client) TLS Client demonstrates the use of Mbed TLS to establish a TLS connection to a remote server. 2. [**Benchmark:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/benchmark) Benchmark measures the time taken to perform basic cryptographic functions used in the library. 3. [**Hashing:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/hashing) Hashing demonstrates the various APIs for computing hashes of data (also known as message digests) with SHA-256. -4. [**Authenticated encryption:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/authcrypt) Authcrypt demonstrates usage of the Cipher API for encrypting and authenticating data with AES-CCM. +4. [**Authenticated encryption:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/authcrypt) Authcrypt demonstrates usage of the cipher API for encrypting and authenticating data with AES-CCM. -These examples are fully integrated into Mbed OS. Each of them comes with complete usage instructions as a `README.md` file in the directory of each example. +These examples are fully integrated into Mbed OS. Each of them comes with complete usage instructions as a `README.md` file. Configuring Mbed TLS features @@ -30,10 +30,9 @@ Configuring Mbed TLS features Mbed TLS makes it easy to disable any feature during compilation, if that feature isn't required for a particular project. The default configuration enables all modern and widely-used features of the TLS protocol, which should meet the needs of most projects. It also disables all older and less common features, to minimize the code footprint. -The list of available compilation flags is available in the fully documented [config.h file](https://github.com/ARMmbed/mbedtls/blob/development/include/mbedtls/config.h). +The list of available compilation flags is available in the fully documented [`config.h` file](https://github.com/ARMmbed/mbedtls/blob/development/include/mbedtls/config.h). -If you need to adjust those flags, you can provide your own supplementary configuration-adjustment file with suitable `#define` and `#undef` statements. These will be included between the default definitions and the sanity checks. Your configuration file should be in your application's include directory, and can be named freely; you just need to let mbed TLS know the file's name. To do that, you can use the [Mbed OS Configuration -system](https://docs.mbed.com/docs/mbed-os-api/en/latest/api/md_docs_config_system.html) +If you need to adjust those flags, you can provide your own supplementary configuration adjustment file with suitable `#define` and `#undef` statements. These will be included between the default definitions and the sanity checks. Your configuration file should be in your application's include directory, and can be named freely; you just need to let Mbed TLS know the file's name. To do that, you can use the [Mbed OS Configuration system](https://docs.mbed.com/docs/mbed-os-api/en/latest/api/md_docs_config_system.html) For example, if you wanted to enable the options, `MBEDTLS_PEM_WRITE_C` and `MBEDTLS_CMAC_C`, and provide your own additional configuration file for Mbed TLS named `my_config.h`, you could define these in a top level `mbed_app.json` configuration file in the root directory of your project. @@ -52,7 +51,7 @@ The Mbed TLS configuration file would be specified in the `.json` file as follow } ``` -The additional configuration file, `my_config.h`, can then be used as a normal configuration header file to include additional configurations. For example, it could include the follow lines to include ECJPAKE, and the CBC block mode: +The additional configuration file, `my_config.h`, can then be used as a normal configuration header file to include or exclude configurations. For example, it could include the following lines to include ECJPAKE, and to disable the CBC block mode: ``` #define MBEDTLS_ECJPAKE_C @@ -61,13 +60,14 @@ The additional configuration file, `my_config.h`, can then be used as a normal c #undef MBEDTLS_CIPHER_MODE_CBC ``` +This can be used to change any configuration normally configured in the `config.h` file. + + ## Getting Mbed TLS from GitHub -Mbed TLS is maintained and developed in the open, independently of Mbed OS, and its source can be found on GitHub here: [ARMmbed/mbedtls](https://github.com/ARMmbed/mbedtls). As a consequence, unlike other parts of mbed OS, changes to Mbed TLS must be committed upstream in the Mbed TLS repository. +Mbed TLS is maintained and developed in the open, independently of Mbed OS, and its source can be found on GitHub here: [ARMmbed/mbedtls](https://github.com/ARMmbed/mbedtls). To import into an instance of Mbed OS a different version of Mbed TLS, a `Makefile` script is provided to update the local git repository, extract a specific version, and to modify the configuration files to those used for the Mbed OS defaults. -To import into an instance of Mbed OS a different version of Mbed TLS, a `Makefile` script is provided to update the local git repository, extract a specific version, and to modify the configuration files to those used for the Mbed OS defaults. - -To use the `Makefile`, you can either set `MBED_TLS_RELEASE` environment variable to the git tag or commit id of the Mbed TLS Release or version you want to use, or alternatively you can modify the `Makefile` itself. +To use the `Makefile`, you can either set `MBED_TLS_RELEASE` environment variable to the git tag or commit id of the Mbed TLS Release or version you want to use, or alternatively you can modify the `Makefile` itself. If `MBED_TLS_RELEASE` is unset, the HEAD of the main development branch will be extracted. You should then run the following commands in the `importer` directory in the Mbed TLS directory: @@ -80,19 +80,20 @@ You should then run the following commands in the `importer` directory in the Mb Once these steps are complete, you can make your Mbed OS build normally with the new version of Mbed TLS. -## Differences between the standalone and mbed OS editions + +## Differences between the standalone and Mbed OS editions While the two editions share the same code base, there are still a number of differences, mainly in configuration and integration. You should keep in mind those differences when reading some articles in our [knowledge base](https://tls.mbed.org/kb), as currently all the articles are about the standalone edition. -* The Mbed OS edition has a smaller set of features enabled by default in `config.h`, in order to reduce footprint. While the default configuration of the standalone edition puts more emphasize on maintaining interoperability with old peers, the mbed OS edition only enables the most modern ciphers and the latest version of (D)TLS. +* The Mbed OS edition has a smaller set of features enabled by default in `config.h`, in order to reduce footprint. While the default configuration of the standalone edition puts more emphasis on maintaining interoperability with old peers, the Mbed OS edition only enables the most modern ciphers and the latest version of (D)TLS. -* The following components of mbed TLS are disabled in the mbed OS edition: `net_sockets.c` and `timing.c`. This is because Mbed OS includes its own equivalents. +* The following components of Mbed TLS are disabled in the Mbed OS edition: `net_sockets.c` and `timing.c`. This is because Mbed OS includes its own equivalents. Help and Support ---------------- -The [mbed TLS website](https://tls.mbed.org/) contains full documentation for the library, including function by function descriptions, knowledgebase articles, blogs and a support forum for questions to the community. +The [Mbed TLS website](https://tls.mbed.org/) contains full documentation for the library, including function by function descriptions, knowledge base articles and blogs. In addition there is a [support forum](https://forums.mbed.com/c/mbed-tls) for questions to the community. Contributing to the Project @@ -103,5 +104,4 @@ We gratefully accept bug reports and contributions from the community. There are - Simple bug fixes to existing code do not contain copyright themselves and we can integrate without issue. The same is true of trivial contributions. - For larger contributions, such as a new feature, the code can possibly fall under copyright law. We then need your consent to share in the ownership of the copyright. We have a form for this, which we will send to you in case you submit a contribution or pull request that we deem this necessary for. -Contributions should be submitted to the [standalone mbed TLS project](https://github.com/ARMmbed/mbedtls), not to the mbed OS imported edition of mbed TLS. - +Contributions should be submitted to the [standalone Mbed TLS project](https://github.com/ARMmbed/mbedtls), not to the version of Mbed TLS embedded within Mbed OS. From 29f7d9d50849116b69225a424cdf3bc7589af541 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Tue, 23 Oct 2018 12:11:02 +0100 Subject: [PATCH 03/63] NonCopyable: Prevent doc generation for protected member function. --- platform/NonCopyable.h | 2 ++ 1 file changed, 2 insertions(+) diff --git a/platform/NonCopyable.h b/platform/NonCopyable.h index 90fce492fb..3357aa358a 100644 --- a/platform/NonCopyable.h +++ b/platform/NonCopyable.h @@ -148,6 +148,7 @@ namespace mbed { */ template class NonCopyable { +#ifndef DOXYGEN_ONLY protected: /** * Disallow construction of NonCopyable objects from outside of its hierarchy. @@ -204,6 +205,7 @@ private: */ NonCopyable &operator=(const NonCopyable &); #endif +#endif }; } // namespace mbed From 3fe42b6c0dcc929f517f4493b50f9abb46f76797 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Tue, 23 Oct 2018 14:34:43 +0100 Subject: [PATCH 04/63] NonCopyable: Rewrite of class documentation. --- platform/NonCopyable.h | 152 ++++++++++++++++++++++------------------- 1 file changed, 81 insertions(+), 71 deletions(-) diff --git a/platform/NonCopyable.h b/platform/NonCopyable.h index 3357aa358a..67b3d95d70 100644 --- a/platform/NonCopyable.h +++ b/platform/NonCopyable.h @@ -24,88 +24,96 @@ namespace mbed { /** - * Inheriting from this class autogeneration of copy construction and copy - * assignment operations. - * - * Classes which are not value type should inherit privately from this class - * to avoid generation of invalid copy constructor or copy assignment operator - * which can lead to unnoticeable programming errors. - * - * As an example consider the following signature: - * + * Prevents generation of copy constructor and copy assignment operator in + * derived classes. + * + * @par Usage + * + * To prevent generation of copy constructor and copy assignment operator simply + * inherit privately from the NonCopyable class. + * + * @code + * class Resource : NonCopyable { }; + * + * Resource r; + * // generates compile time error: + * Resource r2 = r; + * @endcode + * + * @par Background information + * + * Instances of polymorphic classes are not meant to be copied. Unfortunately, + * the C++ standards generates a default copy constructor and copy assignment + * function if these functions have not been defined in the class. + * + * Consider the following example: + * * @code - * class Resource; - * - * class Foo { + * // base class representing a connection + * struct Connection { + * Connection(); + * virtual ~Connection(); + * virtual void open() = 0; + * } + * + * class SerialConnection : public Connection { * public: - * Foo() : _resource(new Resource()) { } - * ~Foo() { delete _resource; } + * SerialConnection(Serial*); + * * private: - * Resource* _resource; + * Serial* _serial; + * }; + * + * Connection& get_connection() { + * static SerialConnection serial_connection; + * return serial_connection; * } * - * Foo get_foo(); - * - * Foo foo = get_foo(); + * Connection connection = get_connection(); * @endcode - * - * There is a bug in this function, it returns a temporary value which will be - * byte copied into foo then destroyed. Unfortunately, internally the Foo class - * manage a pointer to a Resource object. This pointer will be released when the - * temporary is destroyed and foo will manage a pointer to an already released - * Resource. - * - * Two issues has to be fixed in the example above: - * - Function signature has to be changed to reflect the fact that Foo - * instances cannot be copied. In that case accessor should return a - * reference to give access to objects already existing and managed. - * Generator on the other hand should return a pointer to the created object. - * + * + * There is a subtile bug in this code, the function get_connection returns a + * reference to a Connection which is captured by value instead of reference. + * + * When the reference returned by get_connection is copied into connection, the + * vtable and others members defined in Connection are copied but members defined + * in SerialConnection are left apart. This can cause severe crashes or bugs if + * the virtual functions captured uses members not present in the base + * declaration. + * + * To solve that problem, the copy constructor and assignment operator have to + * be declared (but doesn't need to be defined) in the private section of the + * Connection class: + * * @code - * // return a reference to an already managed Foo instance - * Foo& get_foo(); - * Foo& foo = get_foo(); - * - * // create a new Foo instance - * Foo* make_foo(); - * Foo* m = make_foo(); - * @endcode - * - * - Copy constructor and copy assignment operator has to be made private - * in the Foo class. It prevents unwanted copy of Foo objects. This can be - * done by declaring copy constructor and copy assignment in the private - * section of the Foo class. - * - * @code - * class Foo { - * public: - * Foo() : _resource(new Resource()) { } - * ~Foo() { delete _resource; } + * struct Connection { * private: - * // disallow copy operations - * Foo(const Foo&); - * Foo& operator=(const Foo&); - * // data members - * Resource* _resource; + * Connection(const Connection&); + * Connection& operator=(const Connection&); * } * @endcode - * - * Another solution is to inherit privately from the NonCopyable class. - * It reduces the boiler plate needed to avoid copy operations but more - * importantly it clarifies the programmer intent and the object semantic. - * - * class Foo : private NonCopyable { - * public: - * Foo() : _resource(new Resource()) { } - * ~Foo() { delete _resource; } - * private: - * Resource* _resource; + * + * While manually declaring private copy constructor and assignment functions + * works, it is not ideal as these declarations are usually not immediately + * visible, easy to forget and may be obscure for uninformed programmer. + * + * Using the NonCopyable class reduce the boilerplate required and express + * clearly the intent as class inheritance appears right after the class name + * declaration. + * + * @code + * struct Connection : private NonCopyable { + * // regular declarations * } - * - * @tparam T The type that should be made non copyable. It prevent cases where - * the empty base optimization cannot be applied and therefore ensure that the - * cost of this semantic sugar is null. - * + * @endcode + * + * + * @par Implementation details + * + * Using a template type prevents cases where the empty base optimization cannot + * be applied and therefore ensure that the cost of the NonCopyable semantic + * sugar is null. + * * As an example, the empty base optimization is prohibited if one of the empty * base class is also a base type of the first non static data member: * @@ -142,6 +150,8 @@ namespace mbed { * // kind of A. sizeof(C) == sizeof(B) == sizeof(int). * @endcode * + * @tparam T The type that should be made non copyable. + * * @note Compile time errors are disabled if the develop or the release profile * is used. To override this behavior and force compile time errors in all profile * set the configuration parameter "platform.force-non-copyable-error" to true. From 0d2a8e04170dac63e33d02380d46ae9b10fbf82a Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Tue, 23 Oct 2018 14:41:38 +0100 Subject: [PATCH 05/63] NonCopyable: Add into platform doc group. --- platform/NonCopyable.h | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/platform/NonCopyable.h b/platform/NonCopyable.h index 67b3d95d70..43b0e925b0 100644 --- a/platform/NonCopyable.h +++ b/platform/NonCopyable.h @@ -23,6 +23,13 @@ namespace mbed { +/** \addtogroup platform */ +/** @{*/ +/** + * \defgroup platform_NonCopyable NonCopyable class + * @{ + */ + /** * Prevents generation of copy constructor and copy assignment operator in * derived classes. @@ -218,6 +225,10 @@ private: #endif }; +/**@}*/ + +/**@}*/ + } // namespace mbed #endif /* MBED_NONCOPYABLE_H_ */ From c86ceb1bc1da33f5df5f8e162043ea2d82452816 Mon Sep 17 00:00:00 2001 From: Steve Cartmell Date: Tue, 23 Oct 2018 15:17:44 +0100 Subject: [PATCH 06/63] docs(api-condvar): Update documentation for the ConditionVariable API - Hide protected member structures from doxygen. - Add some more details/comments to the example. - Add some defined/undefined behaviours. - Add some additional details to function documentation --- rtos/ConditionVariable.h | 176 +++++++++++++++++++++++++++------------ 1 file changed, 124 insertions(+), 52 deletions(-) diff --git a/rtos/ConditionVariable.h b/rtos/ConditionVariable.h index 1a1c4576ea..18181adeab 100644 --- a/rtos/ConditionVariable.h +++ b/rtos/ConditionVariable.h @@ -35,26 +35,44 @@ namespace rtos { struct Waiter; -/** This class provides a safe way to wait for or send notifications of condition changes +/** The ConditionVariable class is a synchronization primitive that allows + * threads to wait until a particular condition occurs. * - * This class is used in conjunction with a mutex to safely wait for or - * notify waiters of condition changes to a resource accessible by multiple + * The condition variable is used in conjunction with a mutex to safely wait for + * or notify waiters of condition changes to a resource accessible by multiple * threads. * - * # Defined behavior - * - All threads waiting on the condition variable wake when - * ConditionVariable::notify_all is called. - * - If one or more threads are waiting on the condition variable at least - * one of them wakes when ConditionVariable::notify is called. + * The thread that intends to wait on a ConditionVariable must: + * - Acquire a lock on a mutex + * - Execute `wait`, `wait_for`, or `wait_until`. While the thread is waiting, + * the mutex will be unlocked. + * - When the condition variable has been notified, or in the case of `wait_for` + * and `wait_until` the timeout expires the thread is awakened. * - * # Undefined behavior + * The thread that intends to notify a ConditionVariable must: + * - Acquire a lock on the mutex used to construct the condition variable. + * - Execute `notify_one` or `notify_all` on the condition variable. + * + * ## Defined behavior + * - All threads that are waiting on the condition variable will wake when + * ConditionVariable::notify_all is called. + * - At least one thread that is waiting on the condition variable will wake + * when ConditionVariable::notify_one is called. + * - While waiting for a thread is waiting for notification of a + * ConditionVariable it will release the lock held on the mutex. + * - The ConditionVariable will reacquire the mutex lock before exiting the wait + * function. + * + * ## Undefined behavior * - The thread which is unblocked on ConditionVariable::notify_one is * undefined if there are multiple waiters. - * - The order which in which waiting threads acquire the condition variable's + * - Calling wait if the mutex is not locked by the current thread is undefined + * behavior. + * - The order in which waiting threads acquire the condition variable's * mutex after ConditionVariable::notify_all is called is undefined. * - When ConditionVariable::notify_one or ConditionVariable::notify_all is - * called and there are one or more waiters and one or more threads attempting - * to acquire the condition variable's mutex the order in which the mutex is + * called and there are one or more waiters, and one or more threads + * attempting to acquire the condition variable's mutex the order in which the mutex is * acquired is undefined. * - The behavior of ConditionVariable::wait and ConditionVariable::wait_for * is undefined if the condition variable's mutex is locked more than once by @@ -65,60 +83,74 @@ struct Waiter; * @note Synchronization level: Thread safe * * Example: + * * @code * #include "mbed.h" * * Mutex mutex; - * ConditionVariable cond(mutex); + * ConditionVariable cv(mutex); * * // These variables are protected by locking mutex - * uint32_t count = 0; + * uint32_t work_count = 0; * bool done = false; * * void worker_thread() * { - * mutex.lock(); - * do { - * printf("Worker: Count %lu\r\n", count); + * // Acquire lock on mutex before accessing protected variables and waiting. + * mutex.lock(); * - * // Wait for a condition to change - * cond.wait(); + * while (done == false) { + * printf("Worker thread: Count: %lu\r\n", work_count); * - * } while (!done); - * printf("Worker: Exiting\r\n"); - * mutex.unlock(); + * // Wait for main thread to notify the condition variable + * printf("Worker thread: Waiting\r\n"); + * cv.wait(); + * } + * + * printf("Worker: Exiting\r\n"); + * + * // The condition variable acquires the lock when exiting the `wait` function. + * // Unlock mutex when exiting the thread. + * mutex.unlock(); * } * - * int main() { - * Thread thread; - * thread.start(worker_thread); - * - * for (int i = 0; i < 5; i++) { - * - * mutex.lock(); - * // Change count and notify waiters of this - * count++; - * printf("Main: Set count to %lu\r\n", count); - * cond.notify_all(); - * mutex.unlock(); - * - * wait(1.0); - * } + * int main() + * { + * Thread thread; + * thread.start(worker_thread); * + * for (int i = 0; i < 5; i++) { + * // Acquire lock on mutex before modifying variables and notifying. * mutex.lock(); - * // Change done and notify waiters of this - * done = true; - * printf("Main: Set done\r\n"); - * cond.notify_all(); + * + * // Change count and notify waiters of this + * work_count++; + * printf("Main thread: Set count to: %lu\r\n", work_count); + * printf("Main thread: Notifying worker thread\r\n"); + * cv.notify_all(); + * + * // Mutex must be unlocked before the worker thread can acquire it. * mutex.unlock(); * - * thread.join(); + * wait(1.0); + * } + * + * // Change done and notify waiters of this + * mutex.lock(); + * done = true; + * cv.notify_all(); + * mutex.unlock(); + * + * thread.join(); + * + * printf("Main: Exiting\r\n"); * } * @endcode */ + class ConditionVariable : private mbed::NonCopyable { public: - /** Create and Initialize a ConditionVariable object + /** Create and initialize a ConditionVariable object * * @note You cannot call this function from ISR context. */ @@ -126,17 +158,23 @@ public: /** Wait for a notification * - * Wait until a notification occurs. + * Wait causes the current thread to block until the condition variable + * receives a notification from another thread. * * @note - The thread calling this function must be the owner of the - * ConditionVariable's mutex and it must be locked exactly once + * ConditionVariable's mutex and it must be locked exactly once. + * * @note - Spurious notifications can occur so the caller of this API * should check to make sure the condition they are waiting on has - * been met + * been met. + * + * @note - The current thread will release the lock while inside the wait + * function and reacquire it upon exiting the function. * * Example: * @code * mutex.lock(); + * * while (!condition_met) { * cond.wait(); * } @@ -151,15 +189,23 @@ public: void wait(); /** Wait for a notification until specified time + * + * Wait until causes the current thread to block until the condition + * variable is notified, or a specific time given by millisec parameter is + * reached. * * @param millisec absolute end time referenced to Kernel::get_ms_count() * @return true if a timeout occurred, false otherwise. * * @note - The thread calling this function must be the owner of the - * ConditionVariable's mutex and it must be locked exactly once + * ConditionVariable's mutex and it must be locked exactly once. + * * @note - Spurious notifications can occur so the caller of this API * should check to make sure the condition they are waiting on has - * been met + * been met. + * + * @note - The current thread will release the lock while inside the wait + * function and reacquire it upon exiting the function. * * Example: * @code @@ -184,15 +230,23 @@ public: bool wait_until(uint64_t millisec); /** Wait for a notification or timeout + * + * `Wait for` causes the current thread to block until the condition + * variable receives a notification from another thread, or the timeout + * specified by the millisec parameter is reached. * * @param millisec timeout value or osWaitForever in case of no time-out. * @return true if a timeout occurred, false otherwise. * * @note - The thread calling this function must be the owner of the - * ConditionVariable's mutex and it must be locked exactly once + * ConditionVariable's mutex and it must be locked exactly once. + * * @note - Spurious notifications can occur so the caller of this API * should check to make sure the condition they are waiting on has - * been met + * been met. + * + * @note - The current thread will release the lock while inside the wait + * function and reacquire it upon exiting the function. * * Example: * @code @@ -218,7 +272,14 @@ public: /** Notify one waiter on this condition variable that a condition changed. * - * @note - The thread calling this function must be the owner of the ConditionVariable's mutex + * This function will unblock one of the threads waiting for the condition + * variable. + * + * @note - The thread calling this function must be the owner of the + * ConditionVariable's mutex + * + * @note - The thread which is unblocked on ConditionVariable::notify_one is + * undefined if there are multiple waiters. * * @note You cannot call this function from ISR context. */ @@ -226,7 +287,15 @@ public: /** Notify all waiters on this condition variable that a condition changed. * - * @note - The thread calling this function must be the owner of the ConditionVariable's mutex + * This function will unblock all of the threads waiting for the condition + * variable. + * + * @note - The thread calling this function must be the owner of the + * ConditionVariable's mutex + * + * @note - If there are one or more waiters and one or more threads + * attempting to acquire the condition variable's mutex the order in which + * the mutex is acquired is undefined. * * @note You cannot call this function from ISR context. */ @@ -238,6 +307,7 @@ public: */ ~ConditionVariable(); +#if !defined(DOXYGEN_ONLY) protected: struct Waiter { Waiter(); @@ -247,10 +317,12 @@ protected: bool in_list; }; +private: static void _add_wait_list(Waiter **wait_list, Waiter *waiter); static void _remove_wait_list(Waiter **wait_list, Waiter *waiter); Mutex &_mutex; Waiter *_wait_list; +#endif // !defined(DOXYGEN_ONLY) }; } From 482f2b6d0792e0c2f547bdd7b69496dd8f7c902a Mon Sep 17 00:00:00 2001 From: paul-szczepanek-arm <33840200+paul-szczepanek-arm@users.noreply.github.com> Date: Tue, 23 Oct 2018 17:26:38 +0100 Subject: [PATCH 07/63] spi doxygen fixes --- drivers/SPI.h | 228 ++++++++++++++++++++++++++++---------------------- 1 file changed, 130 insertions(+), 98 deletions(-) diff --git a/drivers/SPI.h b/drivers/SPI.h index 7c8e7d6103..e267e48dde 100644 --- a/drivers/SPI.h +++ b/drivers/SPI.h @@ -36,39 +36,44 @@ namespace mbed { /** \addtogroup drivers */ -/** A SPI Master, used for communicating with SPI slave devices +/** A SPI Master, used for communicating with SPI slave devices. * - * The default format is set to 8-bits, mode 0, and a clock frequency of 1MHz + * The default format is set to 8-bits, mode 0, and a clock frequency of 1MHz. * * Most SPI devices will also require Chip Select and Reset signals. These - * can be controlled using DigitalOut pins + * can be controlled using DigitalOut pins. * * @note Synchronization level: Thread safe * - * Example: + * Example of how to send a byte to a SPI slave and record the response: * @code - * // Send a byte to a SPI slave, and record the response - * * #include "mbed.h" * - * // hardware ssel (where applicable) - * //SPI device(p5, p6, p7, p8); // mosi, miso, sclk, ssel + * SPI device(SPI_MOSI, SPI_MISO, SPI_SCLK) * - * // software ssel - * SPI device(p5, p6, p7); // mosi, miso, sclk - * DigitalOut cs(p8); // ssel + * DigitalOut chip_select(SPI_CS); * * int main() { - * // hardware ssel (where applicable) - * //int response = device.write(0xFF); - * * device.lock(); - * // software ssel - * cs = 0; - * int response = device.write(0xFF); - * cs = 1; - * device.unlock(); + * chip_select = 0; * + * int response = device.write(0xFF); + * + * chip_select = 1; + * device.unlock(); + * } + * @endcode + * + * Example using hardware Chip Select line: + * @code + * #include "mbed.h" + * + * SPI device(SPI_MOSI, SPI_MISO, SPI_SCLK, SPI_CS) + * + * int main() { + * device.lock(); + * int response = device.write(0xFF); + * device.unlock(); * } * @endcode * @ingroup drivers @@ -77,22 +82,22 @@ class SPI : private NonCopyable { public: - /** Create a SPI master connected to the specified pins + /** Create a SPI master connected to the specified pins. * - * mosi or miso can be specified as NC if not used + * @note Either mosi or miso can be specified as NC if not used. * - * @param mosi SPI Master Out, Slave In pin - * @param miso SPI Master In, Slave Out pin - * @param sclk SPI Clock pin - * @param ssel SPI chip select pin + * @param mosi SPI Master Out, Slave In pin. + * @param miso SPI Master In, Slave Out pin. + * @param sclk SPI Clock pin. + * @param ssel SPI Chip Select pin. */ SPI(PinName mosi, PinName miso, PinName sclk, PinName ssel = NC); virtual ~SPI(); - /** Configure the data transmission format + /** Configure the data transmission format. * - * @param bits Number of bits per SPI frame (4 - 16) - * @param mode Clock polarity and phase mode (0 - 3) + * @param bits Number of bits per SPI frame (4 - 16). + * @param mode Clock polarity and phase mode (0 - 3). * * @code * mode | POL PHA @@ -105,51 +110,50 @@ public: */ void format(int bits, int mode = 0); - /** Set the spi bus clock frequency + /** Set the SPI bus clock frequency. * - * @param hz SCLK frequency in hz (default = 1MHz) + * @param hz Clock frequency in Hz (default = 1MHz). */ void frequency(int hz = 1000000); - /** Write to the SPI Slave and return the response + /** Write to the SPI Slave and return the response. * - * @param value Data to be sent to the SPI slave + * @param value Data to be sent to the SPI slave. * - * @returns - * Response from the SPI slave + * @return Response from the SPI slave */ virtual int write(int value); - /** Write to the SPI Slave and obtain the response + /** Write to the SPI Slave and obtain the response. * * The total number of bytes sent and received will be the maximum of * tx_length and rx_length. The bytes written will be padded with the * value 0xff. * - * @param tx_buffer Pointer to the byte-array of data to write to the device - * @param tx_length Number of bytes to write, may be zero - * @param rx_buffer Pointer to the byte-array of data to read from the device - * @param rx_length Number of bytes to read, may be zero - * @returns + * @param tx_buffer Pointer to the byte-array of data to write to the device. + * @param tx_length Number of bytes to write, may be zero. + * @param rx_buffer Pointer to the byte-array of data to read from the device. + * @param rx_length Number of bytes to read, may be zero. + * @return * The number of bytes written and read from the device. This is * maximum of tx_length and rx_length. */ virtual int write(const char *tx_buffer, int tx_length, char *rx_buffer, int rx_length); - /** Acquire exclusive access to this SPI bus + /** Acquire exclusive access to this SPI bus. */ virtual void lock(void); - /** Release exclusive access to this SPI bus + /** Release exclusive access to this SPI bus. */ virtual void unlock(void); - /** Set default write data + /** Set default write data. * SPI requires the master to send some data during a read operation. * Different devices may require different default byte values. * For example: A SD Card requires default bytes to be 0xFF. * - * @param data Default character to be transmitted while read operation + * @param data Default character to be transmitted during a read operation. */ void set_default_write_value(char data); @@ -157,17 +161,20 @@ public: /** Start non-blocking SPI transfer using 8bit buffers. * - * This function locks the deep sleep until any event has occurred + * This function locks the deep sleep until any event has occurred. * * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed, - * the default SPI value is sent - * @param tx_length The length of TX buffer in bytes + * the default SPI value is sent. + * @param tx_length The length of TX buffer in bytes. * @param rx_buffer The RX buffer which is used for received data. If NULL is passed, - * received data are ignored - * @param rx_length The length of RX buffer in bytes - * @param callback The event callback function - * @param event The logical OR of events to modify. Look at spi hal header file for SPI events. - * @return Zero if the transfer has started, or -1 if SPI peripheral is busy + * received data are ignored. + * @param rx_length The length of RX buffer in bytes. + * @param callback The event callback function. + * @param event The event mask of events to modify. @see spi_api.h for SPI events. + * + * @return Operation result. + * @retval 0 If the transfer has started. + * @retval -1 If SPI peripheral is busy. */ template int transfer(const Type *tx_buffer, int tx_length, Type *rx_buffer, int rx_length, const event_callback_t &callback, int event = SPI_EVENT_COMPLETE) @@ -179,75 +186,85 @@ public: return 0; } - /** Abort the on-going SPI transfer, and continue with transfer's in the queue if any. + /** Abort the on-going SPI transfer, and continue with transfers in the queue if any. */ void abort_transfer(); - /** Clear the transaction buffer + /** Clear the queue of transfers. */ void clear_transfer_buffer(); - /** Clear the transaction buffer and abort on-going transfer. + /** Clear the queue of transfers and abort the on-going transfer. */ void abort_all_transfers(); - /** Configure DMA usage suggestion for non-blocking transfers + /** Configure DMA usage suggestion for non-blocking transfers. * - * @param usage The usage DMA hint for peripheral - * @return Zero if the usage was set, -1 if a transaction is on-going - */ + * @param usage The usage DMA hint for peripheral. + * + * @return Result of the operation. + * @retval 0 The usage was set. + * @retval -1 Usage cannot be set as there is an ongoing transaction. + */ int set_dma_usage(DMAUsage usage); protected: - /** SPI IRQ handler - * - */ + /** SPI interrupt handler. + */ void irq_handler_asynch(void); - /** Common transfer method + /** Starts transfer or puts the transfer on the queue. * * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed, * the default SPI value is sent - * @param tx_length The length of TX buffer in bytes + * @param tx_length The length of TX buffer in bytes. * @param rx_buffer The RX buffer which is used for received data. If NULL is passed, - * received data are ignored - * @param rx_length The length of RX buffer in bytes - * @param bit_width The buffers element width - * @param callback The event callback function - * @param event The logical OR of events to modify - * @return Zero if the transfer has started or was added to the queue, or -1 if SPI peripheral is busy/buffer is full - */ + * received data are ignored. + * @param rx_length The length of RX buffer in bytes. + * @param bit_width The buffers element width in bits. + * @param callback The event callback function. + * @param event The event mask of events to modify. + * + * @return Operation success. + * @retval 0 A transfer was started or added to the queue. + * @retval -1 Transfer can't be added because queue is full. + */ int transfer(const void *tx_buffer, int tx_length, void *rx_buffer, int rx_length, unsigned char bit_width, const event_callback_t &callback, int event); - /** + /** Put a transfer on the transfer queue. * * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed, - * the default SPI value is sent - * @param tx_length The length of TX buffer in bytes + * the default SPI value is sent. + * @param tx_length The length of TX buffer in bytes. * @param rx_buffer The RX buffer which is used for received data. If NULL is passed, - * received data are ignored - * @param rx_length The length of RX buffer in bytes - * @param bit_width The buffers element width - * @param callback The event callback function - * @param event The logical OR of events to modify - * @return Zero if a transfer was added to the queue, or -1 if the queue is full - */ + * received data are ignored. + * @param rx_length The length of RX buffer in bytes. + * @param bit_width The buffers element width in bits. + * @param callback The event callback function. + * @param event The event mask of events to modify. + * + * @return Operation success. + * @retval 0 A transfer was added to the queue. + * @retval -1 Transfer can't be added because queue is full. + */ int queue_transfer(const void *tx_buffer, int tx_length, void *rx_buffer, int rx_length, unsigned char bit_width, const event_callback_t &callback, int event); - /** Configures a callback, spi peripheral and initiate a new transfer + /** Configures a callback, spi peripheral and initiate a new transfer. * * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed, - * the default SPI value is sent - * @param tx_length The length of TX buffer in bytes + * the default SPI value is sent. + * @param tx_length The length of TX buffer in bytes. * @param rx_buffer The RX buffer which is used for received data. If NULL is passed, - * received data are ignored - * @param rx_length The length of RX buffer in bytes - * @param bit_width The buffers element width - * @param callback The event callback function - * @param event The logical OR of events to modify - */ + * received data are ignored. + * @param rx_length The length of RX buffer in bytes. + * @param bit_width The buffers element width. + * @param callback The event callback function. + * @param event The event mask of events to modify. + */ void start_transfer(const void *tx_buffer, int tx_length, void *rx_buffer, int rx_length, unsigned char bit_width, const event_callback_t &callback, int event); +#if !defined(DOXYGEN_ONLY) + private: /** Lock deep sleep only if it is not yet locked */ void lock_deep_sleep(); @@ -258,46 +275,61 @@ private: #if TRANSACTION_QUEUE_SIZE_SPI - /** Start a new transaction + /** Start a new transaction. * - * @param data Transaction data - */ + * @param data Transaction data. + */ void start_transaction(transaction_t *data); - /** Dequeue a transaction - * - */ + /** Dequeue a transaction and start the transfer if there was one pending. + */ void dequeue_transaction(); + + /* Queue of pending transfers */ static CircularBuffer, TRANSACTION_QUEUE_SIZE_SPI> _transaction_buffer; #endif #endif protected: + /* Internal SPI object identifying the resources */ spi_t _spi; #if DEVICE_SPI_ASYNCH + /* Interrupt */ CThunk _irq; + /* Interrupt handler callback */ event_callback_t _callback; + /* Current preferred DMA mode @see dma_api.h */ DMAUsage _usage; + /* Current sate of the sleep manager */ bool _deep_sleep_locked; #endif + /* Take over the physical SPI and apply our settings (thread safe) */ void aquire(void); + /* Current user of the SPI */ static SPI *_owner; + /* Used by lock and unlock for thread safety */ static SingletonPtr _mutex; + /* Size of the SPI frame */ int _bits; + /* Clock polairy and phase */ int _mode; + /* Clock frequency */ int _hz; + /* Default character used for NULL transfers */ char _write_fill; private: - /* Private acquire function without locking/unlocking - * Implemented in order to avoid duplicate locking and boost performance + /** Private acquire function without locking/unlocking. + * Implemented in order to avoid duplicate locking and boost performance. */ void _acquire(void); }; +#endif //!defined(DOXYGEN_ONLY) + } // namespace mbed #endif From 263f067da4b8503c2dfdd15fee6a812b0d8cb57d Mon Sep 17 00:00:00 2001 From: paul-szczepanek-arm <33840200+paul-szczepanek-arm@users.noreply.github.com> Date: Tue, 23 Oct 2018 17:32:03 +0100 Subject: [PATCH 08/63] imperative --- drivers/SPI.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/drivers/SPI.h b/drivers/SPI.h index e267e48dde..eea41c85c6 100644 --- a/drivers/SPI.h +++ b/drivers/SPI.h @@ -213,7 +213,7 @@ protected: */ void irq_handler_asynch(void); - /** Starts transfer or puts the transfer on the queue. + /** Start the transfer or put it on the queue. * * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed, * the default SPI value is sent @@ -249,7 +249,7 @@ protected: */ int queue_transfer(const void *tx_buffer, int tx_length, void *rx_buffer, int rx_length, unsigned char bit_width, const event_callback_t &callback, int event); - /** Configures a callback, spi peripheral and initiate a new transfer. + /** Configure a callback, spi peripheral and initiate a new transfer. * * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed, * the default SPI value is sent. From acaf96834ecb51535593894e23189ef1e2bb5deb Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 23 Oct 2018 14:50:37 -0500 Subject: [PATCH 09/63] Copy edit NonCopyable.h Make minor copy edits, mostly to existing text before this PR. --- platform/NonCopyable.h | 60 +++++++++++++++++++++--------------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/platform/NonCopyable.h b/platform/NonCopyable.h index 43b0e925b0..104b7fd0c8 100644 --- a/platform/NonCopyable.h +++ b/platform/NonCopyable.h @@ -36,7 +36,7 @@ namespace mbed { * * @par Usage * - * To prevent generation of copy constructor and copy assignment operator simply + * To prevent generation of copy constructor and copy assignment operator, * inherit privately from the NonCopyable class. * * @code @@ -49,8 +49,8 @@ namespace mbed { * * @par Background information * - * Instances of polymorphic classes are not meant to be copied. Unfortunately, - * the C++ standards generates a default copy constructor and copy assignment + * Instances of polymorphic classes are not meant to be copied. The + * C++ standards generate a default copy constructor and copy assignment * function if these functions have not been defined in the class. * * Consider the following example: @@ -79,18 +79,18 @@ namespace mbed { * Connection connection = get_connection(); * @endcode * - * There is a subtile bug in this code, the function get_connection returns a + * There is a subtle bug in this code, the function get_connection returns a * reference to a Connection which is captured by value instead of reference. * - * When the reference returned by get_connection is copied into connection, the - * vtable and others members defined in Connection are copied but members defined + * When the reference get_connection returns is copied into connection, the + * vtable and others members defined in Connection are copied, but members defined * in SerialConnection are left apart. This can cause severe crashes or bugs if - * the virtual functions captured uses members not present in the base - * declaration. + * the virtual functions captured use members not present in the base + * declaration. * * To solve that problem, the copy constructor and assignment operator have to - * be declared (but doesn't need to be defined) in the private section of the - * Connection class: + * be declared (but don't need to be defined) in the private section of the + * Connection class: * * @code * struct Connection { @@ -100,12 +100,12 @@ namespace mbed { * } * @endcode * - * While manually declaring private copy constructor and assignment functions - * works, it is not ideal as these declarations are usually not immediately - * visible, easy to forget and may be obscure for uninformed programmer. + * Although manually declaring private copy constructor and assignment functions + * works, it is not ideal because these declarations are usually easy to forget, + * not immediately visible and may be obscure for uninformed programmers. * - * Using the NonCopyable class reduce the boilerplate required and express - * clearly the intent as class inheritance appears right after the class name + * Using the NonCopyable class reduces the boilerplate required and expresses + * the intent because class inheritance appears right after the class name * declaration. * * @code @@ -118,11 +118,11 @@ namespace mbed { * @par Implementation details * * Using a template type prevents cases where the empty base optimization cannot - * be applied and therefore ensure that the cost of the NonCopyable semantic + * be applied and therefore ensures that the cost of the NonCopyable semantic * sugar is null. * * As an example, the empty base optimization is prohibited if one of the empty - * base class is also a base type of the first non static data member: + * base classes is also a base type of the first nonstatic data member: * * @code * struct A { }; @@ -136,11 +136,11 @@ namespace mbed { * }; * * // empty base optimization cannot be applied here because A from C and A from - * // B shall have a different address. In that case, with the alignment + * // B have a different address. In that case, with the alignment * // sizeof(C) == 2* sizeof(int) * @endcode * - * The solution to that problem is to templatize the empty class to makes it + * The solution to that problem is to templatize the empty class to make it * unique to the type it is applied to: * * @code @@ -157,10 +157,10 @@ namespace mbed { * // kind of A. sizeof(C) == sizeof(B) == sizeof(int). * @endcode * - * @tparam T The type that should be made non copyable. + * @tparam T The type that should be made noncopyable. * - * @note Compile time errors are disabled if the develop or the release profile - * is used. To override this behavior and force compile time errors in all profile + * @note Compile time errors are disabled if you use the develop or the release profile. + * To override this behavior and force compile time errors in all profiles, * set the configuration parameter "platform.force-non-copyable-error" to true. */ template @@ -180,11 +180,11 @@ protected: /** * NonCopyable copy constructor. * - * A compile time warning is issued when this function is used and a runtime - * warning is printed when the copy construction of the non copyable happens. + * A compile time warning is issued when this function is used, and a runtime + * warning is printed when the copy construction of the noncopyable happens. * * If you see this warning, your code is probably doing something unspecified. - * Copy of non copyable resources can lead to resource leak and random error. + * Copying of noncopyable resources can lead to resource leak and random error. */ MBED_DEPRECATED("Invalid copy construction of a NonCopyable resource.") NonCopyable(const NonCopyable &) @@ -195,11 +195,11 @@ protected: /** * NonCopyable copy assignment operator. * - * A compile time warning is issued when this function is used and a runtime - * warning is printed when the copy construction of the non copyable happens. + * A compile time warning is issued when this function is used, and a runtime + * warning is printed when the copy construction of the noncopyable happens. * * If you see this warning, your code is probably doing something unspecified. - * Copy of non copyable resources can lead to resource leak and random error. + * Copying of noncopyable resources can lead to resource leak and random error. */ MBED_DEPRECATED("Invalid copy assignment of a NonCopyable resource.") NonCopyable &operator=(const NonCopyable &) @@ -211,13 +211,13 @@ protected: #else private: /** - * Declare copy constructor as private, any attempt to copy construct + * Declare copy constructor as private. Any attempt to copy construct * a NonCopyable will fail at compile time. */ NonCopyable(const NonCopyable &); /** - * Declare copy assignment operator as private, any attempt to copy assign + * Declare copy assignment operator as private. Any attempt to copy assign * a NonCopyable will fail at compile time. */ NonCopyable &operator=(const NonCopyable &); From 8ddfdf5b2f0b059a60dfdd8b2ce14882b98908ab Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 23 Oct 2018 15:34:16 -0500 Subject: [PATCH 10/63] Copy edit ConditionVariable.h Copy edit file, including existing text. --- rtos/ConditionVariable.h | 50 ++++++++++++++++++++-------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/rtos/ConditionVariable.h b/rtos/ConditionVariable.h index 18181adeab..3d2d016246 100644 --- a/rtos/ConditionVariable.h +++ b/rtos/ConditionVariable.h @@ -44,10 +44,10 @@ struct Waiter; * * The thread that intends to wait on a ConditionVariable must: * - Acquire a lock on a mutex - * - Execute `wait`, `wait_for`, or `wait_until`. While the thread is waiting, + * - Execute `wait`, `wait_for` or `wait_until`. While the thread is waiting, * the mutex will be unlocked. * - When the condition variable has been notified, or in the case of `wait_for` - * and `wait_until` the timeout expires the thread is awakened. + * and `wait_until` the timeout expires, the thread is awakened. * * The thread that intends to notify a ConditionVariable must: * - Acquire a lock on the mutex used to construct the condition variable. @@ -58,13 +58,13 @@ struct Waiter; * ConditionVariable::notify_all is called. * - At least one thread that is waiting on the condition variable will wake * when ConditionVariable::notify_one is called. - * - While waiting for a thread is waiting for notification of a - * ConditionVariable it will release the lock held on the mutex. + * - While a thread is waiting for notification of a + * ConditionVariable, it will release the lock held on the mutex. * - The ConditionVariable will reacquire the mutex lock before exiting the wait * function. * * ## Undefined behavior - * - The thread which is unblocked on ConditionVariable::notify_one is + * - The thread that is unblocked on ConditionVariable::notify_one is * undefined if there are multiple waiters. * - Calling wait if the mutex is not locked by the current thread is undefined * behavior. @@ -72,12 +72,12 @@ struct Waiter; * mutex after ConditionVariable::notify_all is called is undefined. * - When ConditionVariable::notify_one or ConditionVariable::notify_all is * called and there are one or more waiters, and one or more threads - * attempting to acquire the condition variable's mutex the order in which the mutex is + * attempting to acquire the condition variable's mutex, the order in which the mutex is * acquired is undefined. * - The behavior of ConditionVariable::wait and ConditionVariable::wait_for * is undefined if the condition variable's mutex is locked more than once by * the calling thread. - * - Spurious notifications (not triggered by the application) can occur + * - Spurious notifications (not triggered by the application) can occur, * and it is not defined when these occur. * * @note Synchronization level: Thread safe @@ -123,7 +123,7 @@ struct Waiter; * // Acquire lock on mutex before modifying variables and notifying. * mutex.lock(); * - * // Change count and notify waiters of this + * // Change count and notify waiters of this. * work_count++; * printf("Main thread: Set count to: %lu\r\n", work_count); * printf("Main thread: Notifying worker thread\r\n"); @@ -135,7 +135,7 @@ struct Waiter; * wait(1.0); * } * - * // Change done and notify waiters of this + * // Change done and notify waiters of this. * mutex.lock(); * done = true; * cv.notify_all(); @@ -150,22 +150,22 @@ struct Waiter; class ConditionVariable : private mbed::NonCopyable { public: - /** Create and initialize a ConditionVariable object + /** Create and initialize a ConditionVariable object. * * @note You cannot call this function from ISR context. */ ConditionVariable(Mutex &mutex); - /** Wait for a notification + /** Wait for a notification. * * Wait causes the current thread to block until the condition variable * receives a notification from another thread. * * @note - The thread calling this function must be the owner of the - * ConditionVariable's mutex and it must be locked exactly once. + * ConditionVariable's mutex, and it must be locked exactly once. * - * @note - Spurious notifications can occur so the caller of this API - * should check to make sure the condition they are waiting on has + * @note - Spurious notifications can occur, so the caller of this API + * should check to make sure the condition the caller is waiting on has * been met. * * @note - The current thread will release the lock while inside the wait @@ -188,7 +188,7 @@ public: */ void wait(); - /** Wait for a notification until specified time + /** Wait for a notification until the specified time. * * Wait until causes the current thread to block until the condition * variable is notified, or a specific time given by millisec parameter is @@ -198,10 +198,10 @@ public: * @return true if a timeout occurred, false otherwise. * * @note - The thread calling this function must be the owner of the - * ConditionVariable's mutex and it must be locked exactly once. + * ConditionVariable's mutex, and it must be locked exactly once. * - * @note - Spurious notifications can occur so the caller of this API - * should check to make sure the condition they are waiting on has + * @note - Spurious notifications can occur, so the caller of this API + * should check to make sure the condition the caller is waiting on has * been met. * * @note - The current thread will release the lock while inside the wait @@ -235,14 +235,14 @@ public: * variable receives a notification from another thread, or the timeout * specified by the millisec parameter is reached. * - * @param millisec timeout value or osWaitForever in case of no time-out. + * @param millisec timeout value or osWaitForever in case of no timeout. * @return true if a timeout occurred, false otherwise. * * @note - The thread calling this function must be the owner of the - * ConditionVariable's mutex and it must be locked exactly once. + * ConditionVariable's mutex, and it must be locked exactly once. * - * @note - Spurious notifications can occur so the caller of this API - * should check to make sure the condition they are waiting on has + * @note - Spurious notifications can occur, so the caller of this API + * should check to make sure the condition the caller is waiting on has * been met. * * @note - The current thread will release the lock while inside the wait @@ -276,9 +276,9 @@ public: * variable. * * @note - The thread calling this function must be the owner of the - * ConditionVariable's mutex + * ConditionVariable's mutex. * - * @note - The thread which is unblocked on ConditionVariable::notify_one is + * @note - The thread that is unblocked on ConditionVariable::notify_one is * undefined if there are multiple waiters. * * @note You cannot call this function from ISR context. @@ -291,7 +291,7 @@ public: * variable. * * @note - The thread calling this function must be the owner of the - * ConditionVariable's mutex + * ConditionVariable's mutex. * * @note - If there are one or more waiters and one or more threads * attempting to acquire the condition variable's mutex the order in which From 394df128fb0336dbfa8f08f7d3dea5b5c43752ff Mon Sep 17 00:00:00 2001 From: Maciej Bocianski Date: Wed, 24 Oct 2018 08:46:53 +0200 Subject: [PATCH 11/63] MbedCRC doxygen fix --- drivers/MbedCRC.h | 1 + 1 file changed, 1 insertion(+) diff --git a/drivers/MbedCRC.h b/drivers/MbedCRC.h index fd4fa1c7f0..66dc98091d 100644 --- a/drivers/MbedCRC.h +++ b/drivers/MbedCRC.h @@ -258,6 +258,7 @@ public: * This API is used to perform final computation to get correct CRC value. * * @param crc CRC result + * @return 0 on success or a negative in case of failure */ int32_t compute_partial_stop(uint32_t *crc) { From abeab68729cacfc517427d8f5ec0f119de0863b4 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Wed, 24 Oct 2018 08:35:10 +0100 Subject: [PATCH 12/63] NonCopyable: Fix edit. --- platform/NonCopyable.h | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/platform/NonCopyable.h b/platform/NonCopyable.h index 104b7fd0c8..00b78a353a 100644 --- a/platform/NonCopyable.h +++ b/platform/NonCopyable.h @@ -82,11 +82,11 @@ namespace mbed { * There is a subtle bug in this code, the function get_connection returns a * reference to a Connection which is captured by value instead of reference. * - * When the reference get_connection returns is copied into connection, the - * vtable and others members defined in Connection are copied, but members defined - * in SerialConnection are left apart. This can cause severe crashes or bugs if - * the virtual functions captured use members not present in the base - * declaration. + * When `get_connection` returns a reference to serial_connection it is copied into + * the local variable connection. The vtable and others members defined in Connection + * are copied, but members defined in SerialConnection are left apart. This can cause + * severe crashes or bugs if the virtual functions captured use members not present + * in the base declaration. * * To solve that problem, the copy constructor and assignment operator have to * be declared (but don't need to be defined) in the private section of the From 68628c1178a937869a036b2ef0aee1567641ee46 Mon Sep 17 00:00:00 2001 From: paul-szczepanek-arm <33840200+paul-szczepanek-arm@users.noreply.github.com> Date: Wed, 24 Oct 2018 08:49:07 +0100 Subject: [PATCH 13/63] fix syntax err from misplaced ifdef --- drivers/SPI.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/drivers/SPI.h b/drivers/SPI.h index eea41c85c6..faa8a4f29f 100644 --- a/drivers/SPI.h +++ b/drivers/SPI.h @@ -326,9 +326,9 @@ private: * Implemented in order to avoid duplicate locking and boost performance. */ void _acquire(void); -}; #endif //!defined(DOXYGEN_ONLY) +}; } // namespace mbed From d4b6fdc1ecd2ca6bd4fff2322d6c319229ad4396 Mon Sep 17 00:00:00 2001 From: paul-szczepanek-arm <33840200+paul-szczepanek-arm@users.noreply.github.com> Date: Wed, 24 Oct 2018 09:26:10 +0100 Subject: [PATCH 14/63] SPI capitalisation --- drivers/SPI.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/drivers/SPI.h b/drivers/SPI.h index faa8a4f29f..5720834ec6 100644 --- a/drivers/SPI.h +++ b/drivers/SPI.h @@ -249,7 +249,7 @@ protected: */ int queue_transfer(const void *tx_buffer, int tx_length, void *rx_buffer, int rx_length, unsigned char bit_width, const event_callback_t &callback, int event); - /** Configure a callback, spi peripheral and initiate a new transfer. + /** Configure a callback, SPI peripheral and initiate a new transfer. * * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed, * the default SPI value is sent. From efdcdd54509916f99945b3ffe1e0e97e7d28e8a8 Mon Sep 17 00:00:00 2001 From: paul-szczepanek-arm <33840200+paul-szczepanek-arm@users.noreply.github.com> Date: Wed, 24 Oct 2018 09:56:53 +0100 Subject: [PATCH 15/63] active voice --- drivers/SPI.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/drivers/SPI.h b/drivers/SPI.h index 5720834ec6..afd056a7b5 100644 --- a/drivers/SPI.h +++ b/drivers/SPI.h @@ -84,7 +84,7 @@ public: /** Create a SPI master connected to the specified pins. * - * @note Either mosi or miso can be specified as NC if not used. + * @note You can specify mosi or miso as NC if not used. * * @param mosi SPI Master Out, Slave In pin. * @param miso SPI Master In, Slave Out pin. From 85bd15ce6e7b7a116b5d12fefb98a583e7561f8a Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Wed, 24 Oct 2018 14:42:29 +0100 Subject: [PATCH 16/63] Doxygen: Move free standing HAL tests module inside their related HAL module. --- TESTS/mbed_hal/critical_section/critical_section_test.h | 7 +++++-- TESTS/mbed_hal/qspi/qspi_test.h | 6 +++++- TESTS/mbed_hal/sleep/sleep_test_utils.h | 6 +++++- 3 files changed, 15 insertions(+), 4 deletions(-) diff --git a/TESTS/mbed_hal/critical_section/critical_section_test.h b/TESTS/mbed_hal/critical_section/critical_section_test.h index 3a85684d98..4b0e5878ee 100644 --- a/TESTS/mbed_hal/critical_section/critical_section_test.h +++ b/TESTS/mbed_hal/critical_section/critical_section_test.h @@ -14,8 +14,11 @@ * limitations under the License. */ -/** \addtogroup hal_critical_tests +/** \addtogroup hal_critical * @{ + * \defgroup hal_critical_test Tests + * Tests definitions of the HAL Critical module. + * @{ */ #ifndef MBED_CRITICAL_SECTION_TEST_H @@ -45,7 +48,7 @@ template void test_critical_section(); - +/**@}*/ /**@}*/ #endif // MBED_CRITICAL_SECTION_TEST_H diff --git a/TESTS/mbed_hal/qspi/qspi_test.h b/TESTS/mbed_hal/qspi/qspi_test.h index 9ab3076d74..ca9458ccc9 100644 --- a/TESTS/mbed_hal/qspi/qspi_test.h +++ b/TESTS/mbed_hal/qspi/qspi_test.h @@ -14,8 +14,11 @@ * limitations under the License. */ -/** \addtogroup hal_qspi_tests +/** \addtogroup hal_qspi * @{ + * \defgroup hal_qspi_tests Tests + * QSPI tests of the HAL. + * @{ */ #ifndef MBED_QSPI_TEST_H #define MBED_QSPI_TEST_H @@ -96,3 +99,4 @@ void qspi_write_read_test(void); #endif /** @}*/ +/** @}*/ diff --git a/TESTS/mbed_hal/sleep/sleep_test_utils.h b/TESTS/mbed_hal/sleep/sleep_test_utils.h index bf5a522d03..bc886e6747 100644 --- a/TESTS/mbed_hal/sleep/sleep_test_utils.h +++ b/TESTS/mbed_hal/sleep/sleep_test_utils.h @@ -15,8 +15,11 @@ */ /** - * @addtogroup hal_sleep_test_utils + * @addtogroup hal_sleep * @{ + * @defgroup hal_sleep_test_util Tests + * Tests of the sleep HAL. + * @{ */ #ifndef MBED_SLEEP_TEST_UTILS_H @@ -112,3 +115,4 @@ void lp_ticker_isr(const ticker_data_t * const ticker_data) #endif /** @}*/ +/** @}*/ From fd0612b763d819d5aaeb53389785b26109b57e90 Mon Sep 17 00:00:00 2001 From: paul-szczepanek-arm <33840200+paul-szczepanek-arm@users.noreply.github.com> Date: Wed, 24 Oct 2018 16:50:35 +0100 Subject: [PATCH 17/63] update internetsocket docs --- features/netsocket/InternetSocket.h | 138 +++++++++++++--------------- features/netsocket/Socket.h | 4 +- 2 files changed, 66 insertions(+), 76 deletions(-) diff --git a/features/netsocket/InternetSocket.h b/features/netsocket/InternetSocket.h index 511ff34b24..57f5e03b41 100644 --- a/features/netsocket/InternetSocket.h +++ b/features/netsocket/InternetSocket.h @@ -32,164 +32,150 @@ */ class InternetSocket : public Socket { public: - /** Destroy a socket + /** Destroy the socket. * - * Closes socket if the socket is still open + * @note Closes socket if it's still open. */ virtual ~InternetSocket() {} - /** Opens a socket + /** Open a network socket on the network stack of the given + * network interface. * - * Creates a network socket on the network stack of the given - * network interface. Not needed if stack is passed to the - * socket's constructor. + * @note Not needed if stack is passed to the socket's constructor. * - * @param stack Network stack as target for socket - * @return 0 on success, negative error code on failure + * @param stack Network stack as target for socket. + * @return 0 on success, negative error code on failure (@see nsapi_types.h). */ nsapi_error_t open(NetworkStack *stack); +#if !defined(DOXYGEN_ONLY) template nsapi_error_t open(S *stack) { return open(nsapi_create_stack(stack)); } +#endif //!defined(DOXYGEN_ONLY) - /** Close the socket - * - * Closes any open connection and deallocates any memory associated + /** Close any open connection and deallocate any memory associated * with the socket. Called from destructor if socket is not closed. * - * @return 0 on success, negative error code on failure + * @return 0 on success, negative error code on failure (@see nsapi_types.h). */ virtual nsapi_error_t close(); - /** Subscribes to an IP multicast group + /** Subscribe to an IP multicast group. * - * @param address Multicast group IP address - * @return Negative error code on failure + * @param address Multicast group IP address. + * @return 0 on success, negative error code on failure (@see nsapi_types.h). */ int join_multicast_group(const SocketAddress &address); - /** Leave an IP multicast group + /** Leave an IP multicast group. * - * @param address Multicast group IP address - * @return Negative error code on failure + * @param address Multicast group IP address. + * @return 0 on success, negative error code on failure (@see nsapi_types.h). */ int leave_multicast_group(const SocketAddress &address); - - /** Bind a specific address to a socket + /** Bind the socket to a port on which to receive data. * - * Binding a socket specifies the address and port on which to receive - * data. - * - * @param port Local port to bind - * @return 0 on success, negative error code on failure. + * @param port Local port to bind. + * @return 0 on success, negative error code on failure (@see nsapi_types.h). */ nsapi_error_t bind(uint16_t port); - /** Bind a specific address to a socket + /** Bind the socket to a specific address and port on which to receive + * data. If the IP address is zeroed only the port is bound. * - * Binding a socket specifies the address and port on which to receive - * data. If the IP address is zeroed, only the port is bound. - * - * @param address Null-terminated local address to bind - * @param port Local port to bind - * @return 0 on success, negative error code on failure. + * @param address Null-terminated local address to bind. + * @param port Local port to bind. + * @return 0 on success, negative error code on failure (@see nsapi_types.h). */ nsapi_error_t bind(const char *address, uint16_t port); - /** Bind a specific address to a socket - * - * Binding a socket specifies the address and port on which to receive + /** Bind the socket to a specific address and port on which to receive * data. If the IP address is zeroed, only the port is bound. * - * @param address Local address to bind - * @return 0 on success, negative error code on failure. + * @param address Local SocketAddress to bind which includes the address and port. + * @return 0 on success, negative error code on failure (@see nsapi_types.h). */ virtual nsapi_error_t bind(const SocketAddress &address); - /** Set blocking or non-blocking mode of the socket + /** Set blocking or non-blocking mode of the socket. * * Initially all sockets are in blocking mode. In non-blocking mode * blocking operations such as send/recv/accept return * NSAPI_ERROR_WOULD_BLOCK if they can not continue. * - * set_blocking(false) is equivalent to set_timeout(-1) - * set_blocking(true) is equivalent to set_timeout(0) + * @note set_blocking(false) is equivalent to set_timeout(-1) and + * set_blocking(true) is equivalent to set_timeout(0). * - * @param blocking true for blocking mode, false for non-blocking mode. + * @param blocking Use true for blocking mode, false for non-blocking mode. */ virtual void set_blocking(bool blocking); - /** Set timeout on blocking socket operations + /** Set timeout on blocking socket operations. * * Initially all sockets have unbounded timeouts. NSAPI_ERROR_WOULD_BLOCK * is returned if a blocking operation takes longer than the specified * timeout. A timeout of 0 removes the timeout from the socket. A negative * value give the socket an unbounded timeout. * - * set_timeout(0) is equivalent to set_blocking(false) - * set_timeout(-1) is equivalent to set_blocking(true) + * @note set_timeout(0) is equivalent to set_blocking(false) and + * set_timeout(-1) is equivalent to set_blocking(true). * - * @param timeout Timeout in milliseconds + * @param timeout Timeout in milliseconds. */ virtual void set_timeout(int timeout); - /* Set socket options - * - * setsockopt allows an application to pass stack-specific options - * to the underlying stack using stack-specific level and option names, - * or to request generic options using levels from nsapi_socket_level_t. + /** Pass stack-specific options to the underlying stack using stack-specific + * level and option names, or request generic options using levels from nsapi_socket_level_t. * * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned * and the socket is unmodified. * - * @param level Stack-specific protocol level or nsapi_socket_level_t - * @param optname Level-specific option name - * @param optval Option value - * @param optlen Length of the option value - * @return 0 on success, negative error code on failure + * @param level Stack-specific protocol level or nsapi_socket_level_t. + * @param optname Level-specific option name. + * @param optval Option value. + * @param optlen Length of the option value. + * @return 0 on success, negative error code on failure (@see nsapi_types.h). */ virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen); - /* Get socket options - * - * getsockopt allows an application to retrieve stack-specific options - * from the underlying stack using stack-specific level and option names, - * or to request generic options using levels from nsapi_socket_level_t. + /** Retrieve stack-specific options from the underlying stack using + * stack-specific level and option names, or request generic options + * using levels from nsapi_socket_level_t. * * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned * and the socket is unmodified. * - * @param level Stack-specific protocol level or nsapi_socket_level_t - * @param optname Level-specific option name - * @param optval Destination for option value - * @param optlen Length of the option value - * @return 0 on success, negative error code on failure + * @param level Stack-specific protocol level or nsapi_socket_level_t. + * @param optname Level-specific option name. + * @param optval Destination for option value. + * @param optlen Length of the option value. + * @return 0 on success, negative error code on failure (@see nsapi_types.h). */ virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen); - /** Register a callback on state change of the socket + /** Register a callback on state change of the socket. * * The specified callback will be called on state changes such as when - * the socket can recv/send/accept successfully and on when an error - * occurs. The callback may also be called spuriously without reason. + * the socket can recv/send/accept successfully and when an error + * occurs. The callback may also be called spuriously without a reason. * * The callback may be called in an interrupt context and should not * perform expensive operations such as recv/send calls. * - * Note! This is not intended as a replacement for a poll or attach-like - * asynchronous api, but rather as a building block for constructing + * @note This is not intended as a replacement for a poll or attach-like + * asynchronous API, but rather as a building block for constructing * such functionality. The exact timing of when the registered function - * is called is not guaranteed and susceptible to change. + * is called is not guaranteed and is susceptible to change. * - * @param func Function to call on state change + * @param func Function to call on state change. */ virtual void sigio(mbed::Callback func); - /** Register a callback on state change of the socket + /** Register a callback on state change of the socket. * * @see Socket::sigio * @deprecated @@ -201,7 +187,7 @@ public: "mbed OS and has been known to cause confusion. Replaced by Socket::sigio.") void attach(mbed::Callback func); - /** Register a callback on state change of the socket + /** Register a callback on state change of the socket. * * @see Socket::sigio * @deprecated @@ -217,6 +203,8 @@ public: attach(mbed::callback(obj, method)); } +#if !defined(DOXYGEN_ONLY) + protected: InternetSocket(); virtual nsapi_protocol_t get_proto() = 0; @@ -240,6 +228,8 @@ protected: static const int READ_FLAG = 0x1u; static const int WRITE_FLAG = 0x2u; static const int FINISHED_FLAG = 0x3u; + +#endif //!defined(DOXYGEN_ONLY) }; #endif // INTERNETSOCKET_H diff --git a/features/netsocket/Socket.h b/features/netsocket/Socket.h index fe560b4be7..8b53b067fa 100644 --- a/features/netsocket/Socket.h +++ b/features/netsocket/Socket.h @@ -194,7 +194,7 @@ public: */ virtual void sigio(mbed::Callback func) = 0; - /* Set socket options. + /** Set socket options. * * setsockopt() allows an application to pass stack-specific options * to the underlying stack using stack-specific level and option names, @@ -211,7 +211,7 @@ public: */ virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen) = 0; - /* Get socket options. + /** Get socket options. * * getsockopt() allows an application to retrieve stack-specific options * from the underlying stack using stack-specific level and option names, From 650d8dc355fd471b618cb8d83c2bc17046d884f5 Mon Sep 17 00:00:00 2001 From: Simon Butcher Date: Wed, 24 Oct 2018 17:07:02 +0100 Subject: [PATCH 18/63] Improve Mbed TLS README.md Improves the language, formatting and clarity of the Mbed TLS README.md. --- features/mbedtls/README.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/features/mbedtls/README.md b/features/mbedtls/README.md index 3e27766b35..309eedef06 100644 --- a/features/mbedtls/README.md +++ b/features/mbedtls/README.md @@ -10,8 +10,7 @@ This edition of Mbed TLS has been adapted for Mbed OS and imported from its stan Getting Started --------------- -Several example programs are available that demonstrate the use of Mbed TLS with -Mbed OS. These are a great way of getting to know the library. +Several example programs are available that demonstrate the use of Mbed TLS with Mbed OS. These are a great way of getting to know the library. 1. [**TLS Client:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/tls-client) TLS Client demonstrates the use of Mbed TLS to establish a TLS connection to a remote server. @@ -36,7 +35,7 @@ If you need to adjust those flags, you can provide your own supplementary config For example, if you wanted to enable the options, `MBEDTLS_PEM_WRITE_C` and `MBEDTLS_CMAC_C`, and provide your own additional configuration file for Mbed TLS named `my_config.h`, you could define these in a top level `mbed_app.json` configuration file in the root directory of your project. -The Mbed TLS configuration file would be specified in the `.json` file as follows. +The Mbed TLS configuration file would be specified in the `.json` file as: ``` { @@ -65,7 +64,7 @@ This can be used to change any configuration normally configured in the `config. ## Getting Mbed TLS from GitHub -Mbed TLS is maintained and developed in the open, independently of Mbed OS, and its source can be found on GitHub here: [ARMmbed/mbedtls](https://github.com/ARMmbed/mbedtls). To import into an instance of Mbed OS a different version of Mbed TLS, a `Makefile` script is provided to update the local git repository, extract a specific version, and to modify the configuration files to those used for the Mbed OS defaults. +Mbed TLS is maintained and developed in the open, independently of Mbed OS, and its source can be found on GitHub here: [ARMmbed/mbedtls](https://github.com/ARMmbed/mbedtls). To import into an instance of Mbed OS a different version of Mbed TLS, a `Makefile` script is provided to update the local Git repository, extract a specific version, and to modify the configuration files to those used for the Mbed OS defaults. To use the `Makefile`, you can either set `MBED_TLS_RELEASE` environment variable to the git tag or commit id of the Mbed TLS Release or version you want to use, or alternatively you can modify the `Makefile` itself. If `MBED_TLS_RELEASE` is unset, the HEAD of the main development branch will be extracted. @@ -83,7 +82,7 @@ Once these steps are complete, you can make your Mbed OS build normally with the ## Differences between the standalone and Mbed OS editions -While the two editions share the same code base, there are still a number of differences, mainly in configuration and integration. You should keep in mind those differences when reading some articles in our [knowledge base](https://tls.mbed.org/kb), as currently all the articles are about the standalone edition. +While the two editions share the same code base, there are still a number of differences, mainly in configuration and integration. You should keep those differences in mind if you consult our [knowledge base](https://tls.mbed.org/kb), as these refer to the standalone edition. * The Mbed OS edition has a smaller set of features enabled by default in `config.h`, in order to reduce footprint. While the default configuration of the standalone edition puts more emphasis on maintaining interoperability with old peers, the Mbed OS edition only enables the most modern ciphers and the latest version of (D)TLS. @@ -93,7 +92,7 @@ While the two editions share the same code base, there are still a number of dif Help and Support ---------------- -The [Mbed TLS website](https://tls.mbed.org/) contains full documentation for the library, including function by function descriptions, knowledge base articles and blogs. In addition there is a [support forum](https://forums.mbed.com/c/mbed-tls) for questions to the community. +For further documentation and help, you can visit the [Mbed TLS website](https://tls.mbed.org/) which contains full documentation of the library, including function-by-function descriptions, knowledge base articles and blogs. Additionally you can join our [support forum](https://forums.mbed.com/c/mbed-tls) for questions to the community or to help others. Contributing to the Project @@ -104,4 +103,4 @@ We gratefully accept bug reports and contributions from the community. There are - Simple bug fixes to existing code do not contain copyright themselves and we can integrate without issue. The same is true of trivial contributions. - For larger contributions, such as a new feature, the code can possibly fall under copyright law. We then need your consent to share in the ownership of the copyright. We have a form for this, which we will send to you in case you submit a contribution or pull request that we deem this necessary for. -Contributions should be submitted to the [standalone Mbed TLS project](https://github.com/ARMmbed/mbedtls), not to the version of Mbed TLS embedded within Mbed OS. +Please submit contributions to the [standalone Mbed TLS project](https://github.com/ARMmbed/mbedtls), not to the version of Mbed TLS embedded within Mbed OS. From e095c78c6632c3068951c6b12e8d72dd3dfe89e8 Mon Sep 17 00:00:00 2001 From: Filip Jagodzinski Date: Wed, 24 Oct 2018 18:07:09 +0200 Subject: [PATCH 19/63] PlatformMutex docs update --- platform/PlatformMutex.h | 58 +++++++++++++++++++++++++++++----------- 1 file changed, 43 insertions(+), 15 deletions(-) diff --git a/platform/PlatformMutex.h b/platform/PlatformMutex.h index 855d098aee..f2128119de 100644 --- a/platform/PlatformMutex.h +++ b/platform/PlatformMutex.h @@ -1,10 +1,3 @@ - -/** \addtogroup platform */ -/** @{*/ -/** - * \defgroup platform_PlatformMutex PlatformMutex class - * @{ - */ /* mbed Microcontroller Library * Copyright (c) 2006-2013 ARM Limited * @@ -25,32 +18,67 @@ #include "platform/NonCopyable.h" +/** \addtogroup platform + * @{ + */ + +/** \defgroup platform_PlatformMutex PlatformMutex class + * @{ + */ + +/** The PlatformMutex class is used to synchronize the execution of threads. + * + * The PlatformMutex class is used by Mbed OS drivers instead of rtos::Mutex. + * This enables the use of drivers when the Mbed OS is compiled without the RTOS. + * + * @note + * - When the RTOS is present, the PlatformMutex becomes a typedef for rtos::Mutex. + * - When the RTOS is absent, all methods are defined as noop. + */ + #ifdef MBED_CONF_RTOS_PRESENT + #include "rtos/Mutex.h" typedef rtos::Mutex PlatformMutex; + #else -/** A stub mutex for when an RTOS is not present -*/ -class PlatformMutex : private mbed::NonCopyable { + +class PlatformMutex: private mbed::NonCopyable { public: + /** Create a PlatformMutex object. + * + * @note When the RTOS is present, this is an alias for rtos::Mutex::Mutex(). + */ PlatformMutex() { - // Stub - } + + /** PlatformMutex destructor. + * + * @note When the RTOS is present, this is an alias for rtos::Mutex::~Mutex(). + */ ~PlatformMutex() { - // Stub } + /** Wait until a PlatformMutex becomes available. + * + * @note + * - When the RTOS is present, this is an alias for rtos::Mutex::lock(). + * - When the RTOS is absent, this is a noop. + */ void lock() { - // Do nothing } + /** Unlock a PlatformMutex that has previously been locked by the same thread. + * + * @note + * - When the RTOS is present, this is an alias for rtos::Mutex::unlock(). + * - When the RTOS is absent, this is a noop. + */ void unlock() { - // Do nothing } }; From 836a6fc6c68f4fa726f5b0f42cb01c603ce20e29 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Wed, 24 Oct 2018 17:36:27 +0100 Subject: [PATCH 20/63] Doxygen: Hide friend declarations in dox. --- doxyfile_options | 2 +- doxygen_options.json | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/doxyfile_options b/doxyfile_options index e2ee325811..b8c8b17065 100644 --- a/doxyfile_options +++ b/doxyfile_options @@ -491,7 +491,7 @@ HIDE_UNDOC_CLASSES = YES # included in the documentation. # The default value is: NO. -HIDE_FRIEND_COMPOUNDS = NO +HIDE_FRIEND_COMPOUNDS = YES # If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any # documentation blocks found inside the body of a function. If set to NO, these diff --git a/doxygen_options.json b/doxygen_options.json index 1895c35972..900f10160a 100644 --- a/doxygen_options.json +++ b/doxygen_options.json @@ -27,6 +27,7 @@ "HIDE_SCOPE_NAMES": "YES", "HIDE_UNDOC_CLASSES": "YES", "HIDE_UNDOC_MEMBERS": "YES", + "HIDE_FRIEND_COMPOUNDS": "YES", "INLINE_INFO": "NO", "INLINE_INHERITED_MEMB": "YES", "JAVADOC_AUTOBRIEF": "YES", From 8a7d96c75f80bcae192cc9122d83fde56fa1f4a4 Mon Sep 17 00:00:00 2001 From: paul-szczepanek-arm <33840200+paul-szczepanek-arm@users.noreply.github.com> Date: Wed, 24 Oct 2018 17:45:52 +0100 Subject: [PATCH 21/63] doxy cleanup --- features/netsocket/UDPSocket.h | 113 +++++++++++++++------------------ 1 file changed, 52 insertions(+), 61 deletions(-) diff --git a/features/netsocket/UDPSocket.h b/features/netsocket/UDPSocket.h index 087bb8932d..71e7e4a6e3 100644 --- a/features/netsocket/UDPSocket.h +++ b/features/netsocket/UDPSocket.h @@ -26,22 +26,21 @@ #include "rtos/EventFlags.h" -/** UDP socket +/** UDP socket implementation. */ class UDPSocket : public InternetSocket { public: - /** Create an uninitialized socket + /** Create an uninitialized socket. * - * Must call open to initialize the socket on a network stack. + * @note Must call open to initialize the socket on a network stack. */ UDPSocket(); - /** Create a socket on a network interface - * - * Creates and opens a socket on the network stack of the given + /** Create and open a socket on the network stack of the given * network interface. * - * @param stack Network stack as target for socket + * @tparam S Type of the Network stack. + * @param stack Network stack as target for socket. */ template UDPSocket(S *stack) @@ -49,96 +48,84 @@ public: open(stack); } - /** Destroy a socket + /** Destroy a socket. * - * Closes socket if the socket is still open + * @note Closes socket if the socket is still open. */ virtual ~UDPSocket(); - /** Send a packet over a UDP socket - * - * Sends data to the specified address specified by either a domain name - * or an IP address and port. Returns the number of bytes sent from the - * buffer. + /** Send data to the specified host and port. * * By default, sendto blocks until data is sent. If socket is set to * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned * immediately. * - * @param host Hostname of the remote host - * @param port Port of the remote host - * @param data Buffer of data to send to the host - * @param size Size of the buffer in bytes + * @param host Domain name of the remote host or a dotted notation IP address. + * @param port Port of the remote host. + * @param data Buffer of data to send to the host. + * @param size Size of the buffer in bytes. * @return Number of sent bytes on success, negative error - * code on failure + * code on failure. */ virtual nsapi_size_or_error_t sendto(const char *host, uint16_t port, const void *data, nsapi_size_t size); - /** Send a packet over a UDP socket - * - * Sends data to the specified address. Returns the number of bytes - * sent from the buffer. + /** Send data to the specified address. * * By default, sendto blocks until data is sent. If socket is set to * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned * immediately. * - * @param address The SocketAddress of the remote host - * @param data Buffer of data to send to the host - * @param size Size of the buffer in bytes + * @param address The SocketAddress of the remote host. + * @param data Buffer of data to send to the host. + * @param size Size of the buffer in bytes. * @return Number of sent bytes on success, negative error - * code on failure + * code on failure. */ virtual nsapi_size_or_error_t sendto(const SocketAddress &address, const void *data, nsapi_size_t size); - /** Receive a datagram over a UDP socket - * - * Receives a datagram and stores the source address in address if address - * is not NULL. Returns the number of bytes written into the buffer. If the - * datagram is larger than the buffer, the excess data is silently discarded. - * - * If socket is connected, only packets coming from connected peer address - * are accepted. - * - * @note recvfrom() is allowed write to address and data buffers even if error occurs. + /** Receive a datagram and store the source address in address if it's not NULL. * * By default, recvfrom blocks until a datagram is received. If socket is set to * non-blocking or times out with no datagram, NSAPI_ERROR_WOULD_BLOCK * is returned. * - * @param address Destination for the source address or NULL - * @param data Destination buffer for datagram received from the host - * @param size Size of the buffer in bytes + * @note If the datagram is larger than the buffer, the excess data is silently discarded. + * + * @note If socket is connected, only packets coming from connected peer address + * are accepted. + * + * @note recvfrom() is allowed write to address and data buffers even if error occurs. + * + * @param address Destination for the source address or NULL. + * @param data Destination buffer for datagram received from the host. + * @param size Size of the buffer in bytes. * @return Number of received bytes on success, negative error - * code on failure + * code on failure. */ virtual nsapi_size_or_error_t recvfrom(SocketAddress *address, void *data, nsapi_size_t size); - /** Set remote peer address - * - * Set the remote address for next send() call and filtering - * for incomming packets. To reset the address, zero initialised + /** Set the remote address for next send() call and filtering + * of incoming packets. To reset the address, zero initialised * SocketAddress must be in the address parameter. * - * @param address The SocketAddress of the remote host - * @return 0 on success, negative error code on failure + * @param address The SocketAddress of the remote host. + * @return 0 on success, negative error code on failure. */ virtual nsapi_error_t connect(const SocketAddress &address); - /** Send a datagram to pre-specified remote. - * - * The socket must be connected to a remote host before send() call. - * Returns the number of bytes sent from the buffer. + /** Send a datagram to connected remote address. * * By default, send blocks until all data is sent. If socket is set to * non-blocking or times out, a partial amount can be written. * NSAPI_ERROR_WOULD_BLOCK is returned if no data was written. * - * @param data Buffer of data to send to the host - * @param size Size of the buffer in bytes + * @note The socket must be connected to a remote host before send() call. + * + * @param data Buffer of data to send to the host. + * @param size Size of the buffer in bytes. * @return Number of sent bytes on success, negative error * code on failure. */ @@ -151,35 +138,39 @@ public: * If socket is connected, only packets coming from connected peer address * are accepted. * - * @note recv() is allowed write to data buffer even if error occurs. - * * By default, recv blocks until some data is received. If socket is set to * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK can be returned to * indicate no data. * - * @param data Destination buffer for data received from the host - * @param size Size of the buffer in bytes + * @note recv() is allowed write to data buffer even if error occurs. + * + * @param data Pointer to buffer for data received from the host. + * @param size Size of the buffer in bytes. * @return Number of received bytes on success, negative error * code on failure. */ virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size); - /** Not implemented for UDP + /** Not implemented for UDP. * - * @param error unused + * @param error Not used. * @return NSAPI_ERROR_UNSUPPORTED */ virtual Socket *accept(nsapi_error_t *error = NULL); - /** Not implemented for UDP + /** Not implemented for UDP. * - * @param backlog unused + * @param backlog Not used. * @return NSAPI_ERROR_UNSUPPORTED */ virtual nsapi_error_t listen(int backlog = 1); +#if !defined(DOXYGEN_ONLY) + protected: virtual nsapi_protocol_t get_proto(); + +#endif //!defined(DOXYGEN_ONLY) }; From 6cdda58cec754ce9d1c8f685ed199022ab3b5bd2 Mon Sep 17 00:00:00 2001 From: paul-szczepanek-arm <33840200+paul-szczepanek-arm@users.noreply.github.com> Date: Wed, 24 Oct 2018 20:24:33 +0100 Subject: [PATCH 22/63] doxygen fixes --- features/netsocket/CellularBase.h | 71 +++++++------- features/netsocket/EthInterface.h | 13 ++- features/netsocket/EthernetInterface.h | 9 +- features/netsocket/MeshInterface.h | 14 +-- features/netsocket/NetworkInterface.h | 131 ++++++++++++++----------- features/netsocket/WiFiInterface.h | 71 +++++++------- 6 files changed, 161 insertions(+), 148 deletions(-) diff --git a/features/netsocket/CellularBase.h b/features/netsocket/CellularBase.h index 348324020b..455f91bf84 100644 --- a/features/netsocket/CellularBase.h +++ b/features/netsocket/CellularBase.h @@ -18,105 +18,102 @@ #include "netsocket/NetworkInterface.h" -/** CellularBase class - * - * Common interface that is shared between Cellular interfaces +/** Common interface that is shared between Cellular interfaces + * @addtogroup netsocket */ class CellularBase: public NetworkInterface { public: - /** Get the default Cellular interface. * * This is provided as a weak method so applications can override. * Default behaviour is to get the target's default interface, if * any. * - * @return pointer to interface, if any + * @return pointer to interface, if any. */ - static CellularBase *get_default_instance(); - /** Set the Cellular network credentials + /** Set the Cellular network credentials. * * Please check documentation of connect() for default behaviour of APN settings. * - * @param apn Access point name - * @param uname optionally, Username - * @param pwd optionally, password + * @param apn Access point name. + * @param uname Username (optional). + * @param pwd Password (optional). */ virtual void set_credentials(const char *apn, const char *uname = 0, const char *pwd = 0) = 0; - /** Set the pin code for SIM card + /** Set the pin code for SIM card. * - * @param sim_pin PIN for the SIM card + * @param sim_pin PIN for the SIM card. */ virtual void set_sim_pin(const char *sim_pin) = 0; - /** Start the interface + /** Attempt to connect to a Cellular network with a pin and credentials. * - * Attempts to connect to a Cellular network. - * - * @param sim_pin PIN for the SIM card - * @param apn optionally, access point name - * @param uname optionally, Username - * @param pwd optionally, password - * @return NSAPI_ERROR_OK on success, or negative error code on failure + * @param sim_pin PIN for the SIM card. + * @param apn Access point name (optional). + * @param uname Username (optional). + * @param pwd Password (optional). + * @return NSAPI_ERROR_OK on success, or negative error code on failure. */ virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0, const char *uname = 0, const char *pwd = 0) = 0; - /** Start the interface + /** Attempt to connect to a Cellular network. * - * Attempts to connect to a Cellular network. - * If the SIM requires a PIN, and it is not set/invalid, NSAPI_ERROR_AUTH_ERROR is returned. + * If the SIM requires a PIN, and it is invalid or is not set, NSAPI_ERROR_AUTH_ERROR is returned. * - * @return NSAPI_ERROR_OK on success, or negative error code on failure + * @return NSAPI_ERROR_OK on success, or negative error code on failure. */ virtual nsapi_error_t connect() = 0; - /** Stop the interface + /** Stop the interface. * - * @return 0 on success, or error code on failure + * @return NSAPI_ERROR_OK on success, or error code on failure. */ virtual nsapi_error_t disconnect() = 0; - /** Check if the connection is currently established or not + /** Check if the connection is currently established or not. * - * @return true/false If the cellular module have successfully acquired a carrier and is - * connected to an external packet data network using PPP, isConnected() - * API returns true and false otherwise. + * @return True if the cellular module have successfully acquired a carrier and is + * connected to an external packet data network using PPP, false otherwise. */ virtual bool is_connected() = 0; - /** Get the local IP address + /** Get the local IP address. * * @return Null-terminated representation of the local IP address - * or null if no IP address has been received + * or null if no IP address has been received. */ virtual const char *get_ip_address() = 0; - /** Get the local network mask + /** Get the local network mask. * * @return Null-terminated representation of the local network mask - * or null if no network mask has been received + * or null if no network mask has been received. */ virtual const char *get_netmask() = 0; - /** Get the local gateways + /** Get the local gateways. * * @return Null-terminated representation of the local gateway - * or null if no network mask has been received + * or null if no network mask has been received. */ virtual const char *get_gateway() = 0; + /** @copydoc NetworkInterface::cellularBase + */ virtual CellularBase *cellularBase() { return this; } +#if !defined(DOXYGEN_ONLY) + protected: /** Get the target's default Cellular interface. * @@ -127,6 +124,8 @@ protected: * @return pointer to interface, if any */ static CellularBase *get_target_default_instance(); + +#endif //!defined(DOXYGEN_ONLY) }; #endif //CELLULAR_BASE_H diff --git a/features/netsocket/EthInterface.h b/features/netsocket/EthInterface.h index ed7a0de818..a508faa460 100644 --- a/features/netsocket/EthInterface.h +++ b/features/netsocket/EthInterface.h @@ -23,13 +23,14 @@ #include "netsocket/NetworkInterface.h" -/** EthInterface class - * - * Common interface that is shared between ethernet hardware. +/** Common interface that is shared between Ethernet hardware. + * @addtogroup netsocket */ class EthInterface : public virtual NetworkInterface { public: + /** @copydoc NetworkInterface::ethInterface + */ virtual EthInterface *ethInterface() { return this; @@ -41,10 +42,11 @@ public: * Default behaviour is to get the target's default interface, if * any. * - * @return pointer to interface, if any + * @return Pointer to interface, if one exists. */ static EthInterface *get_default_instance(); +#if !defined(DOXYGEN_ONLY) protected: /** Get the target's default Ethernet interface. @@ -53,9 +55,10 @@ protected: * default implementation will invoke EthernetInterface with the * default EMAC and default network stack, if DEVICE_EMAC is set. * - * @return pointer to interface, if any + * @return Pointer to interface, if one exists. */ static EthInterface *get_target_default_instance(); +#endif //!defined(DOXYGEN_ONLY) }; diff --git a/features/netsocket/EthernetInterface.h b/features/netsocket/EthernetInterface.h index 616419baa2..08b158dd49 100644 --- a/features/netsocket/EthernetInterface.h +++ b/features/netsocket/EthernetInterface.h @@ -21,12 +21,11 @@ #include "EMACInterface.h" -/** EthernetInterface class - * Implementation of the NetworkStack for an EMAC-based Ethernet driver +/** Implementation of the NetworkStack for an EMAC-based Ethernet driver. */ class EthernetInterface : public EMACInterface, public EthInterface { public: - /** Create an EMAC-based ethernet interface. + /** Create an EMAC-based Ethernet interface. * * The default arguments obtain the default EMAC, which will be target- * dependent (and the target may have some JSON option to choose which @@ -36,8 +35,8 @@ public: * Due to inability to return errors from the constructor, no real * work is done until the first call to connect(). * - * @param emac Reference to EMAC to use - * @param stack Reference to onboard-network stack to use + * @param emac Reference to EMAC to use. + * @param stack Reference to onboard-network stack to use. */ EthernetInterface(EMAC &emac = EMAC::get_default_instance(), OnboardNetworkStack &stack = OnboardNetworkStack::get_default_instance()) : EMACInterface(emac, stack) { } diff --git a/features/netsocket/MeshInterface.h b/features/netsocket/MeshInterface.h index e6f4efb673..4cfcb20733 100644 --- a/features/netsocket/MeshInterface.h +++ b/features/netsocket/MeshInterface.h @@ -23,13 +23,13 @@ #include "netsocket/NetworkInterface.h" -/** MeshInterface class - * - * Common interface that is shared between mesh hardware +/** Common interface that is shared between mesh hardware + * @addtogroup netsocket */ class MeshInterface : public virtual NetworkInterface { public: - + /** @copydoc NetworkInterface::meshInterface + */ virtual MeshInterface *meshInterface() { return this; @@ -41,10 +41,11 @@ public: * Default behaviour is to get the target's default interface, if * any. * - * @return pointer to interface, if any + * @return pointer to interface, if any. */ static MeshInterface *get_default_instance(); +#if !defined(DOXYGEN_ONLY) protected: /** Get the target's default Mesh interface. @@ -53,9 +54,10 @@ protected: * default implementation will invoke LoWPANNDInterface or ThreadInterface * with the default NanostackRfPhy. * - * @return pointer to interface, if any + * @return pointer to interface, if any. */ static MeshInterface *get_target_default_instance(); +#endif //!defined(DOXYGEN_ONLY) }; diff --git a/features/netsocket/NetworkInterface.h b/features/netsocket/NetworkInterface.h index 7eb674df13..524a67b0ed 100644 --- a/features/netsocket/NetworkInterface.h +++ b/features/netsocket/NetworkInterface.h @@ -31,9 +31,8 @@ class MeshInterface; class CellularBase; class EMACInterface; -/** NetworkInterface class +/** Common interface that is shared between network devices. * - * Common interface that is shared between network devices * @addtogroup netsocket */ class NetworkInterface: public DNS { @@ -41,13 +40,14 @@ public: virtual ~NetworkInterface() {}; - /** Return the default network interface + /** Return the default network interface. * * Returns the default network interface, as determined by JSON option * target.network-default-interface-type or other overrides. * - * The type of the interface returned can be tested via the ethInterface() - * etc downcasts. + * The type of the interface returned can be tested by calling ethInterface(), + * wifiInterface(), meshInterface(), cellularBase(), emacInterface() and checking + * for NULL pointers. * * The default behaviour is to return the default interface for the * interface type specified by target.network-default-interface-type. Targets @@ -79,41 +79,39 @@ public: */ static NetworkInterface *get_default_instance(); - /** Get the local MAC address + /** Get the local MAC address. * * Provided MAC address is intended for info or debug purposes and - * may not be provided if the underlying network interface does not - * provide a MAC address + * may be not provided if the underlying network interface does not + * provide a MAC address. * * @return Null-terminated representation of the local MAC address - * or null if no MAC address is available + * or null if no MAC address is available. */ virtual const char *get_mac_address(); - /** Get the local IP address + /** Get the local IP address. * * @return Null-terminated representation of the local IP address - * or null if no IP address has been received + * or null if no IP address has been received. */ virtual const char *get_ip_address(); - /** Get the local network mask + /** Get the local network mask. * * @return Null-terminated representation of the local network mask - * or null if no network mask has been received + * or null if no network mask has been received. */ virtual const char *get_netmask(); - /** Get the local gateway + /** Get the local gateway. * * @return Null-terminated representation of the local gateway - * or null if no network mask has been received + * or null if no network mask has been received. */ virtual const char *get_gateway(); - /** Set a static IP address - * - * Configures this network interface to use a static IP address. + /** Configure this network interface to use a static IP address. * Implicitly disables DHCP, which can be enabled in set_dhcp. * Requires that the network is disconnected. * @@ -124,30 +122,29 @@ public: */ virtual nsapi_error_t set_network(const char *ip_address, const char *netmask, const char *gateway); - /** Enable or disable DHCP on the network + /** Enable or disable DHCP on connecting the network. * - * Enables DHCP on connecting the network. Defaults to enabled unless - * a static IP address has been assigned. Requires that the network is - * disconnected. + * Enabled by default unless a static IP address has been assigned. Requires + * that the network is disconnected. * - * @param dhcp True to enable DHCP - * @return 0 on success, negative error code on failure + * @param dhcp True to enable DHCP. + * @return 0 on success, negative error code on failure. */ virtual nsapi_error_t set_dhcp(bool dhcp); - /** Start the interface + /** Start the interface. * - * @return 0 on success, negative error code on failure + * @return 0 on success, negative error code on failure. */ virtual nsapi_error_t connect() = 0; - /** Stop the interface + /** Stop the interface. * - * @return 0 on success, negative error code on failure + * @return 0 on success, negative error code on failure. */ virtual nsapi_error_t disconnect() = 0; - /** Translates a hostname to an IP address with specific version + /** Translate a hostname to an IP address with specific version. * * The hostname may be either a domain name or an IP address. If the * hostname is an IP address, no network transactions will be performed. @@ -155,33 +152,33 @@ public: * If no stack-specific DNS resolution is provided, the hostname * will be resolve using a UDP socket on the stack. * - * @param host Hostname to resolve - * @param address Destination for the host SocketAddress + * @param host Hostname to resolve. + * @param address Destination for the host SocketAddress. * @param version IP version of address to resolve, NSAPI_UNSPEC indicates - * version is chosen by the stack (defaults to NSAPI_UNSPEC) - * @return 0 on success, negative error code on failure + * version is chosen by the stack (defaults to NSAPI_UNSPEC). + * @return 0 on success, negative error code on failure. */ virtual nsapi_error_t gethostbyname(const char *host, SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC); - /** Hostname translation callback (asynchronous) + /** Hostname translation callback (for use with gethostbyname_async()). * * Callback will be called after DNS resolution completes or a failure occurs. * - * Callback should not take more than 10ms to execute, otherwise it might + * @note Callback should not take more than 10ms to execute, otherwise it might * prevent underlying thread processing. A portable user of the callback * should not make calls to network operations due to stack size limitations. * The callback should not perform expensive operations such as socket recv/send * calls or blocking operations. * - * @param status 0 on success, negative error code on failure - * @param address On success, destination for the host SocketAddress + * @param result 0 on success, negative error code on failure. + * @param address On success, destination for the host SocketAddress. */ typedef mbed::Callback hostbyname_cb_t; - /** Translates a hostname to an IP address (asynchronous) + /** Translate a hostname to an IP address (asynchronous). * - * The hostname may be either a domain name or an IP address. If the + * The hostname may be either a domain name or a dotted IP address. If the * hostname is an IP address, no network transactions will be performed. * * If no stack-specific DNS resolution is provided, the hostname @@ -192,87 +189,100 @@ public: * is success (IP address was found from DNS cache), callback will be called * before function returns. * - * @param host Hostname to resolve - * @param callback Callback that is called for result + * @param host Hostname to resolve. + * @param callback Callback that is called for result. * @param version IP version of address to resolve, NSAPI_UNSPEC indicates - * version is chosen by the stack (defaults to NSAPI_UNSPEC) + * version is chosen by the stack (defaults to NSAPI_UNSPEC). * @return 0 on immediate success, * negative error code on immediate failure or * a positive unique id that represents the hostname translation operation - * and can be passed to cancel + * and can be passed to cancel. */ virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback, nsapi_version_t version = NSAPI_UNSPEC); - /** Cancels asynchronous hostname translation + /** Cancel asynchronous hostname translation. * * When translation is cancelled, callback will not be called. * - * @param id Unique id of the hostname translation operation - * @return 0 on success, negative error code on failure + * @param id Unique id of the hostname translation operation (returned + * by gethostbyname_async) + * @return 0 on success, negative error code on failure. */ virtual nsapi_error_t gethostbyname_async_cancel(int id); /** Add a domain name server to list of servers to query * - * @param address Destination for the host address - * @return 0 on success, negative error code on failure + * @param address Address for the dns host. + * @return 0 on success, negative error code on failure. */ virtual nsapi_error_t add_dns_server(const SocketAddress &address); - /** Register callback for status reporting + /** Register callback for status reporting. * * The specified status callback function will be called on status changes * on the network. The parameters on the callback are the event type and * event-type dependent reason parameter. * - * @param status_cb The callback for status changes + * @param status_cb The callback for status changes. */ virtual void attach(mbed::Callback status_cb); - /** Get the connection status + /** Get the connection status. * - * @return The connection status according to ConnectionStatusType + * @return The connection status (@see nsapi_types.h). */ virtual nsapi_connection_status_t get_connection_status() const; - /** Set blocking status of connect() which by default should be blocking + /** Set blocking status of connect() which by default should be blocking. * - * @param blocking true if connect is blocking - * @return 0 on success, negative error code on failure + * @param blocking Use true to make connect() blocking. + * @return 0 on success, negative error code on failure. */ virtual nsapi_error_t set_blocking(bool blocking); - /** Dynamic downcast to an EthInterface */ + /** Return pointer to an EthInterface. + * @return Pointer to requested interface type or NULL if this class doesn't implement the interface. + */ virtual EthInterface *ethInterface() { return 0; } - /** Dynamic downcast to a WiFiInterface */ + /** Return pointer to a WiFiInterface. + * @return Pointer to requested interface type or NULL if this class doesn't implement the interface. + */ virtual WiFiInterface *wifiInterface() { return 0; } - /** Dynamic downcast to a MeshInterface */ + /** Return pointer to a MeshInterface. + * @return Pointer to requested interface type or NULL if this class doesn't implement the interface. + */ virtual MeshInterface *meshInterface() { return 0; } - /** Dynamic downcast to a CellularBase */ + /** Return pointer to a CellularBase. + * @return Pointer to requested interface type or NULL if this class doesn't implement the interface. + */ virtual CellularBase *cellularBase() { return 0; } - /** Dynamic downcast to an EMACInterface */ + /** Return pointer to an EMACInterface. + * @return Pointer to requested interface type or NULL if this class doesn't implement the interface. + */ virtual EMACInterface *emacInterface() { return 0; } +#if !defined(DOXYGEN_ONLY) + protected: friend class InternetSocket; friend class UDPSocket; @@ -318,6 +328,7 @@ protected: * performs the search described by get_default_instance. */ static NetworkInterface *get_target_default_instance(); +#endif //!defined(DOXYGEN_ONLY) }; diff --git a/features/netsocket/WiFiInterface.h b/features/netsocket/WiFiInterface.h index 1b876d7e65..fc7352aa84 100644 --- a/features/netsocket/WiFiInterface.h +++ b/features/netsocket/WiFiInterface.h @@ -22,9 +22,8 @@ #include "netsocket/NetworkInterface.h" #include "netsocket/WiFiAccessPoint.h" -/** WiFiInterface class +/** Common interface that is shared between WiFi devices. * - * Common interface that is shared between WiFi devices * @addtogroup netsocket */ class WiFiInterface: public virtual NetworkInterface { @@ -35,81 +34,80 @@ public: * Default behaviour is to get the target's default interface, if * any. * - * @return pointer to interface, if any + * @return pointer to interface, if any. */ static WiFiInterface *get_default_instance(); - /** Set the WiFi network credentials + /** Set the WiFi network credentials. * - * @param ssid Name of the network to connect to - * @param pass Security passphrase to connect to the network + * @param ssid Name of the network to connect to. + * @param pass Security passphrase to connect to the network. * @param security Type of encryption for connection - * (defaults to NSAPI_SECURITY_NONE) - * @return 0 on success, or error code on failure + * (defaults to NSAPI_SECURITY_NONE). + * @return NSAPI_ERROR_OK on success, or error code on failure. */ virtual nsapi_error_t set_credentials(const char *ssid, const char *pass, nsapi_security_t security = NSAPI_SECURITY_NONE) = 0; - /** Set the WiFi network channel + /** Set the WiFi network channel. * - * @param channel Channel on which the connection is to be made, or 0 for any (Default: 0) - * @return 0 on success, or error code on failure + * @param channel Channel on which the connection is to be made, or 0 for any (Default: 0). + * @return NSAPI_ERROR_OK on success, or error code on failure. */ virtual nsapi_error_t set_channel(uint8_t channel) = 0; - /** Gets the current radio signal strength for active connection + /** Get the current radio signal strength for active connection. * * @return Connection strength in dBm (negative value), - * or 0 if measurement impossible + * or 0 if measurement impossible. */ virtual int8_t get_rssi() = 0; - /** Start the interface + /** Attempt to connect to a WiFi network. * - * Attempts to connect to a WiFi network. - * - * @param ssid Name of the network to connect to - * @param pass Security passphrase to connect to the network - * @param security Type of encryption for connection (Default: NSAPI_SECURITY_NONE) - * @param channel Channel on which the connection is to be made, or 0 for any (Default: 0) - * @return 0 on success, or error code on failure + * @param ssid Name of the network to connect to. + * @param pass Security passphrase to connect to the network. + * @param security Type of encryption for connection (Default: NSAPI_SECURITY_NONE). + * @param channel Channel on which the connection is to be made, or 0 for any (Default: 0). + * @return NSAPI_ERROR_OK on success, or error code on failure. */ virtual nsapi_error_t connect(const char *ssid, const char *pass, nsapi_security_t security = NSAPI_SECURITY_NONE, uint8_t channel = 0) = 0; - /** Start the interface - * - * Attempts to connect to a WiFi network. Requires ssid and passphrase to be set. + /** Attempt to connect to a WiFi network. Requires ssid and passphrase to be set. * If passphrase is invalid, NSAPI_ERROR_AUTH_ERROR is returned. * - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t connect() = 0; - /** Stop the interface + /** Stop the interface. * - * @return 0 on success, or error code on failure + * @return NSAPI_ERROR_OK on success, or error code on failure. */ virtual nsapi_error_t disconnect() = 0; - /** Scan for available networks + /** Scan for available networks. * - * This function will block. If the @a count is 0, function will only return count of available networks, so that - * user can allocated necessary memory. If the \p count is grater than 0 and the a \p res is not NULL it'll be populated - * with discovered networks up to value of \p count. + * This function will block. If the count is 0, function will only return count of available networks, so that + * user can allocated necessary memory. If the count is grater than 0 and the a \p res is not NULL it'll be populated + * with discovered networks up to value of count. * - * @param res Pointer to allocated array to store discovered AP - * @param count Size of allocated @a res array, or 0 to only count available AP - * @return Number of entries in \p count, or if \p count was 0 number of available networks, - * negative on error see @a nsapi_error + * @param res Pointer to allocated array to store discovered APs. + * @param count Size of allocated res array, or 0 to only count available APs. + * @return Number of entries in res, or if count was 0 number of available networks. + * Negative on error (@see nsapi_types.h for nsapi_error). */ virtual nsapi_size_or_error_t scan(WiFiAccessPoint *res, nsapi_size_t count) = 0; + /** @copydoc NetworkInterface::wifiInterface + */ virtual WiFiInterface *wifiInterface() { return this; } +#if !defined(DOXYGEN_ONLY) protected: /** Get the target's default WiFi interface. @@ -117,9 +115,10 @@ protected: * This is provided as a weak method so targets can override. The * default implementation returns NULL. * - * @return pointer to interface, if any + * @return pointer to interface, if any. */ static WiFiInterface *get_target_default_instance(); +#endif //!defined(DOXYGEN_ONLY) }; #endif From 5837e3771ef064a59b67180f453aa77930348cf9 Mon Sep 17 00:00:00 2001 From: paul-szczepanek-arm <33840200+paul-szczepanek-arm@users.noreply.github.com> Date: Wed, 24 Oct 2018 20:35:53 +0100 Subject: [PATCH 23/63] return codes --- features/netsocket/DNS.h | 38 +++++++++++++-------------- features/netsocket/NetworkInterface.h | 20 +++++++------- features/netsocket/NetworkStack.h | 34 ++++++++++++------------ 3 files changed, 46 insertions(+), 46 deletions(-) diff --git a/features/netsocket/DNS.h b/features/netsocket/DNS.h index 9e74744b6b..2bed8c26dc 100644 --- a/features/netsocket/DNS.h +++ b/features/netsocket/DNS.h @@ -20,7 +20,7 @@ class DNS { public: - /** Translates a hostname to an IP address with specific version + /** Translate a hostname to an IP address with specific version. * * The hostname may be either a domain name or an IP address. If the * hostname is an IP address, no network transactions will be performed. @@ -28,16 +28,16 @@ public: * If no stack-specific DNS resolution is provided, the hostname * will be resolve using a UDP socket on the stack. * - * @param host Hostname to resolve - * @param address Destination for the host SocketAddress + * @param host Hostname to resolve. + * @param address Pointer to a SocketAddress to store the result. * @param version IP version of address to resolve, NSAPI_UNSPEC indicates - * version is chosen by the stack (defaults to NSAPI_UNSPEC) - * @return 0 on success, negative error code on failure + * version is chosen by the stack (defaults to NSAPI_UNSPEC). + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t gethostbyname(const char *host, SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC) = 0; - /** Hostname translation callback (asynchronous) + /** Hostname translation callback for gethostbyname_async. * * Callback will be called after DNS resolution completes or a failure occurs. * @@ -47,12 +47,12 @@ public: * The callback should not perform expensive operations such as socket recv/send * calls or blocking operations. * - * @param status 0 on success, negative error code on failure - * @param address On success, destination for the host SocketAddress + * @param result NSAPI_ERROR_OK on success, negative error code on failure. + * @param address On success, destination for the host SocketAddress. */ typedef mbed::Callback hostbyname_cb_t; - /** Translates a hostname to an IP address (asynchronous) + /** Translate a hostname to an IP address (asynchronous) * * The hostname may be either a domain name or an IP address. If the * hostname is an IP address, no network transactions will be performed. @@ -65,31 +65,31 @@ public: * is success (IP address was found from DNS cache), callback will be called * before function returns. * - * @param host Hostname to resolve - * @param callback Callback that is called for result + * @param host Hostname to resolve. + * @param callback Callback that is called to return the result. * @param version IP version of address to resolve, NSAPI_UNSPEC indicates - * version is chosen by the stack (defaults to NSAPI_UNSPEC) - * @return 0 on immediate success, + * version is chosen by the stack (defaults to NSAPI_UNSPEC). + * @return NSAPI_ERROR_OK on immediate success, * negative error code on immediate failure or * a positive unique id that represents the hostname translation operation - * and can be passed to cancel + * and can be passed to cancel. */ virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback, nsapi_version_t version = NSAPI_UNSPEC) = 0; - /** Cancels asynchronous hostname translation + /** Cancel asynchronous hostname translation. * * When translation is cancelled, callback will not be called. * - * @param id Unique id of the hostname translation operation - * @return 0 on success, negative error code on failure + * @param id Unique id of the hostname translation operation returned by gethostbyname_async. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t gethostbyname_async_cancel(int id) = 0; /** Add a domain name server to list of servers to query * - * @param address Destination for the host address - * @return 0 on success, negative error code on failure + * @param address DNS server host address. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t add_dns_server(const SocketAddress &address) = 0; }; diff --git a/features/netsocket/NetworkInterface.h b/features/netsocket/NetworkInterface.h index 524a67b0ed..2c357a57a1 100644 --- a/features/netsocket/NetworkInterface.h +++ b/features/netsocket/NetworkInterface.h @@ -118,7 +118,7 @@ public: * @param ip_address Null-terminated representation of the local IP address * @param netmask Null-terminated representation of the local network mask * @param gateway Null-terminated representation of the local gateway - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t set_network(const char *ip_address, const char *netmask, const char *gateway); @@ -128,19 +128,19 @@ public: * that the network is disconnected. * * @param dhcp True to enable DHCP. - * @return 0 on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t set_dhcp(bool dhcp); /** Start the interface. * - * @return 0 on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t connect() = 0; /** Stop the interface. * - * @return 0 on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t disconnect() = 0; @@ -153,10 +153,10 @@ public: * will be resolve using a UDP socket on the stack. * * @param host Hostname to resolve. - * @param address Destination for the host SocketAddress. + * @param address Pointer to a SocketAddress to store the result. * @param version IP version of address to resolve, NSAPI_UNSPEC indicates * version is chosen by the stack (defaults to NSAPI_UNSPEC). - * @return 0 on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t gethostbyname(const char *host, SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC); @@ -171,7 +171,7 @@ public: * The callback should not perform expensive operations such as socket recv/send * calls or blocking operations. * - * @param result 0 on success, negative error code on failure. + * @param result NSAPI_ERROR_OK on success, negative error code on failure. * @param address On success, destination for the host SocketAddress. */ typedef mbed::Callback hostbyname_cb_t; @@ -207,14 +207,14 @@ public: * * @param id Unique id of the hostname translation operation (returned * by gethostbyname_async) - * @return 0 on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t gethostbyname_async_cancel(int id); /** Add a domain name server to list of servers to query * * @param address Address for the dns host. - * @return 0 on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t add_dns_server(const SocketAddress &address); @@ -237,7 +237,7 @@ public: /** Set blocking status of connect() which by default should be blocking. * * @param blocking Use true to make connect() blocking. - * @return 0 on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t set_blocking(bool blocking); diff --git a/features/netsocket/NetworkStack.h b/features/netsocket/NetworkStack.h index 2ea7757dca..945b8d53d4 100644 --- a/features/netsocket/NetworkStack.h +++ b/features/netsocket/NetworkStack.h @@ -54,10 +54,10 @@ public: * will be resolve using a UDP socket on the stack. * * @param host Hostname to resolve - * @param address Destination for the host SocketAddress + * @param address Pointer to a SocketAddress to store the result. * @param version IP version of address to resolve, NSAPI_UNSPEC indicates * version is chosen by the stack (defaults to NSAPI_UNSPEC) - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t gethostbyname(const char *host, SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC); @@ -72,7 +72,7 @@ public: * The callback should not perform expensive operations such as socket recv/send * calls or blocking operations. * - * @param status 0 on success, negative error code on failure + * @param status NSAPI_ERROR_OK on success, negative error code on failure * @param address On success, destination for the host SocketAddress */ typedef mbed::Callback hostbyname_cb_t; @@ -107,14 +107,14 @@ public: * When translation is cancelled, callback will not be called. * * @param id Unique id of the hostname translation operation - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t gethostbyname_async_cancel(int id); /** Add a domain name server to list of servers to query * * @param address Destination for the host address - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t add_dns_server(const SocketAddress &address); @@ -125,7 +125,7 @@ public: * * @param index Index of the DNS server, starts from zero * @param address Destination for the host address - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t get_dns_server(int index, SocketAddress *address); @@ -142,7 +142,7 @@ public: * @param optname Level-specific option name * @param optval Option value * @param optlen Length of the option value - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t setstackopt(int level, int optname, const void *optval, unsigned optlen); @@ -156,7 +156,7 @@ public: * @param optname Level-specific option name * @param optval Destination for option value * @param optlen Length of the option value - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t getstackopt(int level, int optname, void *optval, unsigned *optlen); @@ -182,7 +182,7 @@ protected: * * @param handle Destination for the handle to a newly created socket * @param proto Protocol of socket to open, NSAPI_TCP or NSAPI_UDP - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t socket_open(nsapi_socket_t *handle, nsapi_protocol_t proto) = 0; @@ -192,7 +192,7 @@ protected: * with the socket. * * @param handle Socket handle - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t socket_close(nsapi_socket_t handle) = 0; @@ -203,7 +203,7 @@ protected: * * @param handle Socket handle * @param address Local address to bind - * @return 0 on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t socket_bind(nsapi_socket_t handle, const SocketAddress &address) = 0; @@ -215,7 +215,7 @@ protected: * @param handle Socket handle * @param backlog Number of pending connections that can be queued * simultaneously - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t socket_listen(nsapi_socket_t handle, int backlog) = 0; @@ -226,7 +226,7 @@ protected: * * @param handle Socket handle * @param address The SocketAddress of the remote host - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t socket_connect(nsapi_socket_t handle, const SocketAddress &address) = 0; @@ -246,7 +246,7 @@ protected: * @param server Socket handle to server to accept from * @param handle Destination for a handle to the newly created socket * @param address Destination for the remote address or NULL - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t socket_accept(nsapi_socket_t server, nsapi_socket_t *handle, SocketAddress *address = 0) = 0; @@ -347,7 +347,7 @@ protected: * @param optname Stack-specific option identifier * @param optval Option value * @param optlen Length of the option value - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level, int optname, const void *optval, unsigned optlen); @@ -363,7 +363,7 @@ protected: * @param optname Stack-specific option identifier * @param optval Destination for option value * @param optlen Length of the option value - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level, int optname, void *optval, unsigned *optlen); @@ -397,7 +397,7 @@ private: * * @param delay Delay in milliseconds * @param func Callback to be called - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t call_in(int delay, mbed::Callback func); }; From e31337dab7cffae68fc4a491b824f3d405fd0628 Mon Sep 17 00:00:00 2001 From: paul-szczepanek-arm <33840200+paul-szczepanek-arm@users.noreply.github.com> Date: Wed, 24 Oct 2018 20:49:28 +0100 Subject: [PATCH 24/63] remove redundancy and maintainance overhead --- features/netsocket/InternetSocket.h | 77 +++-------------------------- features/netsocket/Socket.h | 37 +++++++------- 2 files changed, 25 insertions(+), 89 deletions(-) diff --git a/features/netsocket/InternetSocket.h b/features/netsocket/InternetSocket.h index 511ff34b24..8294fa1912 100644 --- a/features/netsocket/InternetSocket.h +++ b/features/netsocket/InternetSocket.h @@ -100,92 +100,27 @@ public: */ nsapi_error_t bind(const char *address, uint16_t port); - /** Bind a specific address to a socket - * - * Binding a socket specifies the address and port on which to receive - * data. If the IP address is zeroed, only the port is bound. - * - * @param address Local address to bind - * @return 0 on success, negative error code on failure. + /** @copydoc Socket::bind */ virtual nsapi_error_t bind(const SocketAddress &address); - /** Set blocking or non-blocking mode of the socket - * - * Initially all sockets are in blocking mode. In non-blocking mode - * blocking operations such as send/recv/accept return - * NSAPI_ERROR_WOULD_BLOCK if they can not continue. - * - * set_blocking(false) is equivalent to set_timeout(-1) - * set_blocking(true) is equivalent to set_timeout(0) - * - * @param blocking true for blocking mode, false for non-blocking mode. + /** @copydoc Socket::set_blocking */ virtual void set_blocking(bool blocking); - /** Set timeout on blocking socket operations - * - * Initially all sockets have unbounded timeouts. NSAPI_ERROR_WOULD_BLOCK - * is returned if a blocking operation takes longer than the specified - * timeout. A timeout of 0 removes the timeout from the socket. A negative - * value give the socket an unbounded timeout. - * - * set_timeout(0) is equivalent to set_blocking(false) - * set_timeout(-1) is equivalent to set_blocking(true) - * - * @param timeout Timeout in milliseconds + /** @copydoc Socket::set_timeout */ virtual void set_timeout(int timeout); - /* Set socket options - * - * setsockopt allows an application to pass stack-specific options - * to the underlying stack using stack-specific level and option names, - * or to request generic options using levels from nsapi_socket_level_t. - * - * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned - * and the socket is unmodified. - * - * @param level Stack-specific protocol level or nsapi_socket_level_t - * @param optname Level-specific option name - * @param optval Option value - * @param optlen Length of the option value - * @return 0 on success, negative error code on failure + /** @copydoc Socket::setsockopt */ virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen); - /* Get socket options - * - * getsockopt allows an application to retrieve stack-specific options - * from the underlying stack using stack-specific level and option names, - * or to request generic options using levels from nsapi_socket_level_t. - * - * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned - * and the socket is unmodified. - * - * @param level Stack-specific protocol level or nsapi_socket_level_t - * @param optname Level-specific option name - * @param optval Destination for option value - * @param optlen Length of the option value - * @return 0 on success, negative error code on failure + /** @copydoc Socket::getsockopt */ virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen); - /** Register a callback on state change of the socket - * - * The specified callback will be called on state changes such as when - * the socket can recv/send/accept successfully and on when an error - * occurs. The callback may also be called spuriously without reason. - * - * The callback may be called in an interrupt context and should not - * perform expensive operations such as recv/send calls. - * - * Note! This is not intended as a replacement for a poll or attach-like - * asynchronous api, but rather as a building block for constructing - * such functionality. The exact timing of when the registered function - * is called is not guaranteed and susceptible to change. - * - * @param func Function to call on state change + /** @copydoc Socket::sigio */ virtual void sigio(mbed::Callback func); diff --git a/features/netsocket/Socket.h b/features/netsocket/Socket.h index fe560b4be7..cc6b8f5152 100644 --- a/features/netsocket/Socket.h +++ b/features/netsocket/Socket.h @@ -38,7 +38,7 @@ public: * Closes any open connection and deallocates any memory associated * with the socket. Called from destructor if socket is not closed. * - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t close() = 0; @@ -54,7 +54,7 @@ public: * object have to be in the address parameter. * * @param address The SocketAddress of the remote peer - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t connect(const SocketAddress &address) = 0; @@ -142,10 +142,11 @@ public: /** Bind a specific address to a socket. * - * Binding assigns a local address to a socket. + * Binding a socket specifies the address and port on which to receive + * data. If the IP address is zeroed, only the port is bound. * * @param address Local address to bind - * @return 0 on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t bind(const SocketAddress &address) = 0; @@ -190,11 +191,11 @@ public: * such functionality. The exact timing of when the registered function * is called is not guaranteed and susceptible to change. * - * @param func Function to call on state change + * @param func Function to call on state change. */ virtual void sigio(mbed::Callback func) = 0; - /* Set socket options. + /** Set socket options. * * setsockopt() allows an application to pass stack-specific options * to the underlying stack using stack-specific level and option names, @@ -203,15 +204,15 @@ public: * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned * and the socket is unmodified. * - * @param level Stack-specific protocol level or nsapi_socket_level_t - * @param optname Level-specific option name - * @param optval Option value - * @param optlen Length of the option value - * @return 0 on success, negative error code on failure + * @param level Stack-specific protocol level or nsapi_socket_level_t. + * @param optname Level-specific option name. + * @param optval Option value. + * @param optlen Length of the option value. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen) = 0; - /* Get socket options. + /** Get socket options. * * getsockopt() allows an application to retrieve stack-specific options * from the underlying stack using stack-specific level and option names, @@ -220,11 +221,11 @@ public: * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned * and the socket is unmodified. * - * @param level Stack-specific protocol level or nsapi_socket_level_t - * @param optname Level-specific option name - * @param optval Destination for option value - * @param optlen Length of the option value - * @return 0 on success, negative error code on failure + * @param level Stack-specific protocol level or nsapi_socket_level_t. + * @param optname Level-specific option name. + * @param optval Destination for option value. + * @param optlen Length of the option value. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen) = 0; @@ -250,7 +251,7 @@ public: * * @param backlog Number of pending connections that can be queued * simultaneously, defaults to 1 - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t listen(int backlog = 1) = 0; }; From 3929f5630bbd63e72dd34db8d3722572ad97c143 Mon Sep 17 00:00:00 2001 From: paul-szczepanek-arm <33840200+paul-szczepanek-arm@users.noreply.github.com> Date: Wed, 24 Oct 2018 20:54:08 +0100 Subject: [PATCH 25/63] missing doxy --- features/netsocket/NetworkStack.h | 4 ++-- features/netsocket/nsapi_types.h | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/features/netsocket/NetworkStack.h b/features/netsocket/NetworkStack.h index 945b8d53d4..cf0ea24b18 100644 --- a/features/netsocket/NetworkStack.h +++ b/features/netsocket/NetworkStack.h @@ -336,7 +336,7 @@ protected: */ virtual void socket_attach(nsapi_socket_t handle, void (*callback)(void *), void *data) = 0; - /* Set stack-specific socket options + /** Set stack-specific socket options * * The setsockopt allow an application to pass stack-specific hints * to the underlying stack. For unsupported options, @@ -352,7 +352,7 @@ protected: virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level, int optname, const void *optval, unsigned optlen); - /* Get stack-specific socket options + /** Get stack-specific socket options * * The getstackopt allow an application to retrieve stack-specific hints * from the underlying stack. For unsupported options, diff --git a/features/netsocket/nsapi_types.h b/features/netsocket/nsapi_types.h index 232236b6c6..7f701d0de5 100644 --- a/features/netsocket/nsapi_types.h +++ b/features/netsocket/nsapi_types.h @@ -351,7 +351,7 @@ typedef struct nsapi_stack_api { */ nsapi_error_t (*add_dns_server)(nsapi_stack_t *stack, nsapi_addr_t addr); - /* Set stack-specific stack options + /** Set stack-specific stack options * * The setstackopt allow an application to pass stack-specific hints * to the underlying stack. For unsupported options, @@ -367,7 +367,7 @@ typedef struct nsapi_stack_api { nsapi_error_t (*setstackopt)(nsapi_stack_t *stack, int level, int optname, const void *optval, unsigned optlen); - /* Get stack-specific stack options + /** Get stack-specific stack options * * The getstackopt allow an application to retrieve stack-specific hints * from the underlying stack. For unsupported options, @@ -567,7 +567,7 @@ typedef struct nsapi_stack_api { void (*socket_attach)(nsapi_stack_t *stack, nsapi_socket_t socket, void (*callback)(void *), void *data); - /* Set stack-specific socket options + /** Set stack-specific socket options * * The setsockopt allow an application to pass stack-specific hints * to the underlying stack. For unsupported options, @@ -584,7 +584,7 @@ typedef struct nsapi_stack_api { nsapi_error_t (*setsockopt)(nsapi_stack_t *stack, nsapi_socket_t socket, int level, int optname, const void *optval, unsigned optlen); - /* Get stack-specific socket options + /** Get stack-specific socket options * * The getstackopt allow an application to retrieve stack-specific hints * from the underlying stack. For unsupported options, From 4f2645b3fc7dbf014aa5631c70e16bf1ebab518f Mon Sep 17 00:00:00 2001 From: paul-szczepanek-arm <33840200+paul-szczepanek-arm@users.noreply.github.com> Date: Wed, 24 Oct 2018 20:57:25 +0100 Subject: [PATCH 26/63] incorrect doc was copy pasted replaced with copydoc instead --- .../wifi/esp8266-driver/ESP8266Interface.h | 28 ++----------------- features/netsocket/NetworkStack.h | 28 +++++++++---------- 2 files changed, 16 insertions(+), 40 deletions(-) diff --git a/components/wifi/esp8266-driver/ESP8266Interface.h b/components/wifi/esp8266-driver/ESP8266Interface.h index 4d19dd60e7..a8dae7bb98 100644 --- a/components/wifi/esp8266-driver/ESP8266Interface.h +++ b/components/wifi/esp8266-driver/ESP8266Interface.h @@ -153,36 +153,12 @@ public: */ using NetworkInterface::add_dns_server; - /** Set socket options - * - * The setsockopt allow an application to pass stack-specific hints - * to the underlying stack. For unsupported options, - * NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified. - * - * @param handle Socket handle - * @param level Stack-specific protocol level - * @param optname Stack-specific option identifier - * @param optval Option value - * @param optlen Length of the option value - * @return 0 on success, negative error code on failure + /** @copydoc NetworkStack::setsockopt */ virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level, int optname, const void *optval, unsigned optlen); - /** Get socket options - * - * getsockopt allows an application to retrieve stack-specific options - * from the underlying stack using stack-specific level and option names, - * or to request generic options using levels from nsapi_socket_level_t. - * - * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned - * and the socket is unmodified. - * - * @param level Stack-specific protocol level or nsapi_socket_level_t - * @param optname Level-specific option name - * @param optval Destination for option value - * @param optlen Length of the option value - * @return 0 on success, negative error code on failure + /** @copydoc NetworkStack::getsockopt */ virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level, int optname, void *optval, unsigned *optlen); diff --git a/features/netsocket/NetworkStack.h b/features/netsocket/NetworkStack.h index cf0ea24b18..8edb9e0645 100644 --- a/features/netsocket/NetworkStack.h +++ b/features/netsocket/NetworkStack.h @@ -336,34 +336,34 @@ protected: */ virtual void socket_attach(nsapi_socket_t handle, void (*callback)(void *), void *data) = 0; - /** Set stack-specific socket options + /** Set stack-specific socket options. * * The setsockopt allow an application to pass stack-specific hints * to the underlying stack. For unsupported options, * NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified. * - * @param handle Socket handle - * @param level Stack-specific protocol level - * @param optname Stack-specific option identifier - * @param optval Option value - * @param optlen Length of the option value - * @return NSAPI_ERROR_OK on success, negative error code on failure + * @param handle Socket handle. + * @param level Stack-specific protocol level. + * @param optname Stack-specific option identifier. + * @param optval Option value. + * @param optlen Length of the option value. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level, int optname, const void *optval, unsigned optlen); - /** Get stack-specific socket options + /** Get stack-specific socket options. * * The getstackopt allow an application to retrieve stack-specific hints * from the underlying stack. For unsupported options, * NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified. * - * @param handle Socket handle - * @param level Stack-specific protocol level - * @param optname Stack-specific option identifier - * @param optval Destination for option value - * @param optlen Length of the option value - * @return NSAPI_ERROR_OK on success, negative error code on failure + * @param handle Socket handle. + * @param level Stack-specific protocol level. + * @param optname Stack-specific option identifier. + * @param optval Destination for option value. + * @param optlen Length of the option value. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level, int optname, void *optval, unsigned *optlen); From 1131d844c9393703fa85b56f3afd22387fb70f05 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Wed, 24 Oct 2018 16:39:45 -0500 Subject: [PATCH 27/63] Edit PlatformMutex.h Change passive to active voice. --- platform/PlatformMutex.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/platform/PlatformMutex.h b/platform/PlatformMutex.h index f2128119de..ac06a81855 100644 --- a/platform/PlatformMutex.h +++ b/platform/PlatformMutex.h @@ -28,7 +28,7 @@ /** The PlatformMutex class is used to synchronize the execution of threads. * - * The PlatformMutex class is used by Mbed OS drivers instead of rtos::Mutex. + * Mbed drivers use the PlatformMutex class instead of rtos::Mutex. * This enables the use of drivers when the Mbed OS is compiled without the RTOS. * * @note @@ -71,7 +71,7 @@ public: { } - /** Unlock a PlatformMutex that has previously been locked by the same thread. + /** Unlock a PlatformMutex that the same thread has previously locked. * * @note * - When the RTOS is present, this is an alias for rtos::Mutex::unlock(). From 8c2bd401d2edd20ceabb5fe60165be5aff7150b6 Mon Sep 17 00:00:00 2001 From: Melinda Weed Date: Thu, 25 Oct 2018 10:35:05 +0300 Subject: [PATCH 28/63] editorial changes, passive to active, removing redundancy --- features/mbedtls/README.md | 55 ++++++++++++++++---------------------- 1 file changed, 23 insertions(+), 32 deletions(-) diff --git a/features/mbedtls/README.md b/features/mbedtls/README.md index 309eedef06..68e309dd5a 100644 --- a/features/mbedtls/README.md +++ b/features/mbedtls/README.md @@ -1,39 +1,35 @@ -README for Mbed TLS -=================== +## README for Mbed TLS Mbed TLS for Mbed OS -------------------- -This edition of Mbed TLS has been adapted for Mbed OS and imported from its standalone release, which you can find on [github here](https://github.com/ARMmbed/mbedtls). This edition of Mbed TLS does not include the test code or the scripts used in the development of the library. These can be found in the standalone release. - +This edition of Mbed TLS has been adapted for Mbed OS and imported from its standalone release, which you can find on [Github](https://github.com/ARMmbed/mbedtls). This edition of Mbed TLS does not include the test code or scripts used in the development of the library. These can be found in the standalone release. Getting Started --------------- -Several example programs are available that demonstrate the use of Mbed TLS with Mbed OS. These are a great way of getting to know the library. +Several example programs are available that demonstrate Mbed TLS with Mbed OS. These can help you become familiar with the library: -1. [**TLS Client:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/tls-client) TLS Client demonstrates the use of Mbed TLS to establish a TLS connection to a remote server. +* [**TLS Client:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/tls-client) TLS Client demonstrates the use of Mbed TLS to establish a TLS connection to a remote server. -2. [**Benchmark:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/benchmark) Benchmark measures the time taken to perform basic cryptographic functions used in the library. +* [**Benchmark:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/benchmark) Benchmark measures the time taken to perform basic cryptographic functions used in the library. -3. [**Hashing:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/hashing) Hashing demonstrates the various APIs for computing hashes of data (also known as message digests) with SHA-256. - -4. [**Authenticated encryption:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/authcrypt) Authcrypt demonstrates usage of the cipher API for encrypting and authenticating data with AES-CCM. +* [**Hashing:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/hashing) Hashing demonstrates the various APIs for computing hashes of data (also known as message digests) with SHA-256. +* [**Authenticated encryption:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/authcrypt) Authcrypt demonstrates usage of the cipher API for encrypting and authenticating data with AES-CCM. These examples are fully integrated into Mbed OS. Each of them comes with complete usage instructions as a `README.md` file. - Configuring Mbed TLS features ----------------------------- -Mbed TLS makes it easy to disable any feature during compilation, if that feature isn't required for a particular project. The default configuration enables all modern and widely-used features of the TLS protocol, which should meet the needs of most projects. It also disables all older and less common features, to minimize the code footprint. +Mbed TLS makes it easy to disable any unneeded features during compilation for a particular project. The default configuration enables all modern and widely-used features of the TLS protocol, which should meet the needs of most projects. It also disables all older and less common features, to minimize the code footprint. The list of available compilation flags is available in the fully documented [`config.h` file](https://github.com/ARMmbed/mbedtls/blob/development/include/mbedtls/config.h). -If you need to adjust those flags, you can provide your own supplementary configuration adjustment file with suitable `#define` and `#undef` statements. These will be included between the default definitions and the sanity checks. Your configuration file should be in your application's include directory, and can be named freely; you just need to let Mbed TLS know the file's name. To do that, you can use the [Mbed OS Configuration system](https://docs.mbed.com/docs/mbed-os-api/en/latest/api/md_docs_config_system.html) +If you need to adjust these flags, you can provide your own supplementary configuration adjustment file with suitable `#define` and `#undef` statements. These are included between the default definitions and the sanity checks. Your configuration file should be in your application's include directory, and can be named freely, but you then need to tell Mbed TLS the file's name. To do that, you can use the [Mbed OS Configuration system](https://docs.mbed.com/docs/mbed-os-api/en/latest/api/md_docs_config_system.html). -For example, if you wanted to enable the options, `MBEDTLS_PEM_WRITE_C` and `MBEDTLS_CMAC_C`, and provide your own additional configuration file for Mbed TLS named `my_config.h`, you could define these in a top level `mbed_app.json` configuration file in the root directory of your project. +For example, if you wanted to enable the options `MBEDTLS_PEM_WRITE_C` and `MBEDTLS_CMAC_C`, and provide your own additional configuration file for Mbed TLS named `my_config.h`, you could define these in a top level `mbed_app.json` configuration file in the root directory of your project. The Mbed TLS configuration file would be specified in the `.json` file as: @@ -50,7 +46,7 @@ The Mbed TLS configuration file would be specified in the `.json` file as: } ``` -The additional configuration file, `my_config.h`, can then be used as a normal configuration header file to include or exclude configurations. For example, it could include the following lines to include ECJPAKE, and to disable the CBC block mode: +You can then use the additional configuration file `my_config.h` as a normal configuration header file to include or exclude configurations. For example, it could include the following lines to include ECJPAKE, and to disable the CBC block mode: ``` #define MBEDTLS_ECJPAKE_C @@ -59,28 +55,26 @@ The additional configuration file, `my_config.h`, can then be used as a normal c #undef MBEDTLS_CIPHER_MODE_CBC ``` -This can be used to change any configuration normally configured in the `config.h` file. +You can use this to change any configuration normally in the `config.h` file. +### Getting Mbed TLS from GitHub -## Getting Mbed TLS from GitHub +Mbed TLS is maintained and developed in the open, independently of Mbed OS, and its source can be found on GitHub here: [ARMmbed/mbedtls](https://github.com/ARMmbed/mbedtls). To import a different version of Mbed TLS into an instance of Mbed OS, there is a `Makefile` script to update the local Git repository, extract a specific version, and modify the configuration files to Mbed OS defaults. -Mbed TLS is maintained and developed in the open, independently of Mbed OS, and its source can be found on GitHub here: [ARMmbed/mbedtls](https://github.com/ARMmbed/mbedtls). To import into an instance of Mbed OS a different version of Mbed TLS, a `Makefile` script is provided to update the local Git repository, extract a specific version, and to modify the configuration files to those used for the Mbed OS defaults. +To use the `Makefile`, you can either set `MBED_TLS_RELEASE` environment variable to the Git tag or commit ID of the Mbed TLS release or version you want to use, or modify the `Makefile` itself. If `MBED_TLS_RELEASE` is unset, the HEAD of the main development branch will be extracted. -To use the `Makefile`, you can either set `MBED_TLS_RELEASE` environment variable to the git tag or commit id of the Mbed TLS Release or version you want to use, or alternatively you can modify the `Makefile` itself. If `MBED_TLS_RELEASE` is unset, the HEAD of the main development branch will be extracted. - -You should then run the following commands in the `importer` directory in the Mbed TLS directory: +Run the following commands in the `importer` directory in the Mbed TLS directory: ``` make update make ``` -`make update` will pull the specified version of Mbed TLS into the local `importer/TARGET_IGNORE` directory and `make` will transform it into the `src` directory, modifying its configuration file as necessary. +The `make update` command pulls the specified version of Mbed TLS into the local `importer/TARGET_IGNORE` directory, and `make` transforms it into the `src` directory, modifying its configuration file as necessary. -Once these steps are complete, you can make your Mbed OS build normally with the new version of Mbed TLS. +Once these steps are complete, you can build Mbed OS normally with the new version of Mbed TLS. - -## Differences between the standalone and Mbed OS editions +### Differences between the standalone and Mbed OS editions While the two editions share the same code base, there are still a number of differences, mainly in configuration and integration. You should keep those differences in mind if you consult our [knowledge base](https://tls.mbed.org/kb), as these refer to the standalone edition. @@ -88,19 +82,16 @@ While the two editions share the same code base, there are still a number of dif * The following components of Mbed TLS are disabled in the Mbed OS edition: `net_sockets.c` and `timing.c`. This is because Mbed OS includes its own equivalents. - -Help and Support +### Help and Support ---------------- For further documentation and help, you can visit the [Mbed TLS website](https://tls.mbed.org/) which contains full documentation of the library, including function-by-function descriptions, knowledge base articles and blogs. Additionally you can join our [support forum](https://forums.mbed.com/c/mbed-tls) for questions to the community or to help others. - Contributing to the Project --------------------------- -We gratefully accept bug reports and contributions from the community. There are some requirements we need to fulfill in order to be able to integrate contributions: - -- Simple bug fixes to existing code do not contain copyright themselves and we can integrate without issue. The same is true of trivial contributions. -- For larger contributions, such as a new feature, the code can possibly fall under copyright law. We then need your consent to share in the ownership of the copyright. We have a form for this, which we will send to you in case you submit a contribution or pull request that we deem this necessary for. +We are happy to accept bug reports and contributions from the community. There are some requirements to integrate contributions: +* Simple bug fixes to existing code do not contain copyright themselves, and we can integrate without issue. The same is true of trivial contributions. +* For larger contributions, such as a new feature, the code can possibly fall under copyright law. We then need your consent to share in the ownership of the copyright. We have a form for this, which we will send to you in case you submit a contribution or pull request that we deem this necessary for. Please submit contributions to the [standalone Mbed TLS project](https://github.com/ARMmbed/mbedtls), not to the version of Mbed TLS embedded within Mbed OS. From de261a467338c85bc92c4ce7174e7c1ec51029eb Mon Sep 17 00:00:00 2001 From: Paul Szczepanek Date: Thu, 25 Oct 2018 11:22:13 +0100 Subject: [PATCH 29/63] Update CellularBase.h --- features/netsocket/CellularBase.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/features/netsocket/CellularBase.h b/features/netsocket/CellularBase.h index 455f91bf84..406f58edf9 100644 --- a/features/netsocket/CellularBase.h +++ b/features/netsocket/CellularBase.h @@ -18,7 +18,7 @@ #include "netsocket/NetworkInterface.h" -/** Common interface that is shared between Cellular interfaces +/** Common interface that is shared between cellular interfaces. * @addtogroup netsocket */ class CellularBase: public NetworkInterface { From 5241c3b38da1ba5cf7f517d2fb1c990a88b13843 Mon Sep 17 00:00:00 2001 From: Paul Szczepanek Date: Thu, 25 Oct 2018 11:24:11 +0100 Subject: [PATCH 30/63] Update WiFiInterface.h --- features/netsocket/WiFiInterface.h | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/features/netsocket/WiFiInterface.h b/features/netsocket/WiFiInterface.h index fc7352aa84..f9fff47c12 100644 --- a/features/netsocket/WiFiInterface.h +++ b/features/netsocket/WiFiInterface.h @@ -22,13 +22,13 @@ #include "netsocket/NetworkInterface.h" #include "netsocket/WiFiAccessPoint.h" -/** Common interface that is shared between WiFi devices. +/** Common interface that is shared between Wi-Fi devices. * * @addtogroup netsocket */ class WiFiInterface: public virtual NetworkInterface { public: - /** Get the default WiFi interface. + /** Get the default Wi-Fi interface. * * This is provided as a weak method so applications can override. * Default behaviour is to get the target's default interface, if @@ -38,7 +38,7 @@ public: */ static WiFiInterface *get_default_instance(); - /** Set the WiFi network credentials. + /** Set the Wi-Fi network credentials. * * @param ssid Name of the network to connect to. * @param pass Security passphrase to connect to the network. @@ -49,7 +49,7 @@ public: virtual nsapi_error_t set_credentials(const char *ssid, const char *pass, nsapi_security_t security = NSAPI_SECURITY_NONE) = 0; - /** Set the WiFi network channel. + /** Set the Wi-Fi network channel. * * @param channel Channel on which the connection is to be made, or 0 for any (Default: 0). * @return NSAPI_ERROR_OK on success, or error code on failure. @@ -63,7 +63,7 @@ public: */ virtual int8_t get_rssi() = 0; - /** Attempt to connect to a WiFi network. + /** Attempt to connect to a Wi-Fi network. * * @param ssid Name of the network to connect to. * @param pass Security passphrase to connect to the network. @@ -74,7 +74,7 @@ public: virtual nsapi_error_t connect(const char *ssid, const char *pass, nsapi_security_t security = NSAPI_SECURITY_NONE, uint8_t channel = 0) = 0; - /** Attempt to connect to a WiFi network. Requires ssid and passphrase to be set. + /** Attempt to connect to a Wi-Fi network. Requires ssid and passphrase to be set. * If passphrase is invalid, NSAPI_ERROR_AUTH_ERROR is returned. * * @return NSAPI_ERROR_OK on success, negative error code on failure @@ -110,7 +110,7 @@ public: #if !defined(DOXYGEN_ONLY) protected: - /** Get the target's default WiFi interface. + /** Get the target's default Wi-Fi interface. * * This is provided as a weak method so targets can override. The * default implementation returns NULL. From 85b9b237119e5bd4b2c5ff64fa83674df5b0cb7b Mon Sep 17 00:00:00 2001 From: Paul Szczepanek Date: Thu, 25 Oct 2018 11:30:59 +0100 Subject: [PATCH 31/63] capitalisation --- features/netsocket/CellularBase.h | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/features/netsocket/CellularBase.h b/features/netsocket/CellularBase.h index 406f58edf9..303b10017a 100644 --- a/features/netsocket/CellularBase.h +++ b/features/netsocket/CellularBase.h @@ -24,7 +24,7 @@ class CellularBase: public NetworkInterface { public: - /** Get the default Cellular interface. + /** Get the default cellular interface. * * This is provided as a weak method so applications can override. * Default behaviour is to get the target's default interface, if @@ -34,7 +34,7 @@ public: */ static CellularBase *get_default_instance(); - /** Set the Cellular network credentials. + /** Set the cellular network credentials. * * Please check documentation of connect() for default behaviour of APN settings. * @@ -51,7 +51,7 @@ public: */ virtual void set_sim_pin(const char *sim_pin) = 0; - /** Attempt to connect to a Cellular network with a pin and credentials. + /** Attempt to connect to a cellular network with a pin and credentials. * * @param sim_pin PIN for the SIM card. * @param apn Access point name (optional). @@ -63,7 +63,7 @@ public: const char *uname = 0, const char *pwd = 0) = 0; - /** Attempt to connect to a Cellular network. + /** Attempt to connect to a cellular network. * * If the SIM requires a PIN, and it is invalid or is not set, NSAPI_ERROR_AUTH_ERROR is returned. * @@ -115,7 +115,7 @@ public: #if !defined(DOXYGEN_ONLY) protected: - /** Get the target's default Cellular interface. + /** Get the target's default cellular interface. * * This is provided as a weak method so targets can override. The * default implementation configures and returns the OnBoardModemInterface From 889a98e4f59a5127e579eb411214ae48b5caf04e Mon Sep 17 00:00:00 2001 From: Paul Szczepanek Date: Thu, 25 Oct 2018 11:34:30 +0100 Subject: [PATCH 32/63] Update SPI.h --- drivers/SPI.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/drivers/SPI.h b/drivers/SPI.h index afd056a7b5..92a22ca109 100644 --- a/drivers/SPI.h +++ b/drivers/SPI.h @@ -120,7 +120,7 @@ public: * * @param value Data to be sent to the SPI slave. * - * @return Response from the SPI slave + * @return Response from the SPI slave. */ virtual int write(int value); @@ -186,7 +186,7 @@ public: return 0; } - /** Abort the on-going SPI transfer, and continue with transfers in the queue if any. + /** Abort the on-going SPI transfer, and continue with transfers in the queue, if any. */ void abort_transfer(); @@ -249,7 +249,7 @@ protected: */ int queue_transfer(const void *tx_buffer, int tx_length, void *rx_buffer, int rx_length, unsigned char bit_width, const event_callback_t &callback, int event); - /** Configure a callback, SPI peripheral and initiate a new transfer. + /** Configure a callback, SPI peripheral, and initiate a new transfer. * * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed, * the default SPI value is sent. From 5cc5e47929a9f3880f70181f763390c9f4e23fee Mon Sep 17 00:00:00 2001 From: Melinda Weed Date: Thu, 25 Oct 2018 14:25:43 +0300 Subject: [PATCH 33/63] future to present tense --- rtos/ConditionVariable.h | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/rtos/ConditionVariable.h b/rtos/ConditionVariable.h index 3d2d016246..fb89fc7b3d 100644 --- a/rtos/ConditionVariable.h +++ b/rtos/ConditionVariable.h @@ -1,5 +1,5 @@ -/* mbed Microcontroller Library - * Copyright (c) 2017-2017 ARM Limited +/* Mbed Microcontroller Library + * Copyright (c) 2017-2018 ARM Limited * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -38,14 +38,14 @@ struct Waiter; /** The ConditionVariable class is a synchronization primitive that allows * threads to wait until a particular condition occurs. * - * The condition variable is used in conjunction with a mutex to safely wait for + * Use the condition variable in conjunction with a mutex to safely wait for * or notify waiters of condition changes to a resource accessible by multiple * threads. * * The thread that intends to wait on a ConditionVariable must: * - Acquire a lock on a mutex * - Execute `wait`, `wait_for` or `wait_until`. While the thread is waiting, - * the mutex will be unlocked. + * the mutex is unlocked. * - When the condition variable has been notified, or in the case of `wait_for` * and `wait_until` the timeout expires, the thread is awakened. * @@ -53,17 +53,17 @@ struct Waiter; * - Acquire a lock on the mutex used to construct the condition variable. * - Execute `notify_one` or `notify_all` on the condition variable. * - * ## Defined behavior - * - All threads that are waiting on the condition variable will wake when - * ConditionVariable::notify_all is called. - * - At least one thread that is waiting on the condition variable will wake - * when ConditionVariable::notify_one is called. + * ### Defined behavior + * - All threads waiting on the condition variable wake when + * `ConditionVariable::notify_all` is called. + * - At least one thread waiting on the condition variable wakes + * when `ConditionVariable::notify_one` is called. * - While a thread is waiting for notification of a - * ConditionVariable, it will release the lock held on the mutex. - * - The ConditionVariable will reacquire the mutex lock before exiting the wait + * ConditionVariable, it releases the lock held on the mutex. + * - The ConditionVariable reacquires the mutex lock before exiting the wait * function. * - * ## Undefined behavior + * ### Undefined behavior * - The thread that is unblocked on ConditionVariable::notify_one is * undefined if there are multiple waiters. * - Calling wait if the mutex is not locked by the current thread is undefined @@ -167,8 +167,8 @@ public: * @note - Spurious notifications can occur, so the caller of this API * should check to make sure the condition the caller is waiting on has * been met. - * - * @note - The current thread will release the lock while inside the wait + * + * @note - The current thread releases the lock while inside the wait * function and reacquire it upon exiting the function. * * Example: @@ -204,7 +204,7 @@ public: * should check to make sure the condition the caller is waiting on has * been met. * - * @note - The current thread will release the lock while inside the wait + * @note - The current thread releases the lock while inside the wait * function and reacquire it upon exiting the function. * * Example: @@ -245,7 +245,7 @@ public: * should check to make sure the condition the caller is waiting on has * been met. * - * @note - The current thread will release the lock while inside the wait + * @note - The current thread releases the lock while inside the wait * function and reacquire it upon exiting the function. * * Example: @@ -272,7 +272,7 @@ public: /** Notify one waiter on this condition variable that a condition changed. * - * This function will unblock one of the threads waiting for the condition + * This function unblocks one of the threads waiting for the condition * variable. * * @note - The thread calling this function must be the owner of the @@ -287,7 +287,7 @@ public: /** Notify all waiters on this condition variable that a condition changed. * - * This function will unblock all of the threads waiting for the condition + * This function unblocks all of the threads waiting for the condition * variable. * * @note - The thread calling this function must be the owner of the From 9539e41d95c1f4c84058c69107e13a7826a9f8ec Mon Sep 17 00:00:00 2001 From: adbridge Date: Thu, 25 Oct 2018 13:39:18 +0100 Subject: [PATCH 34/63] Add warning about deviating from the template format Detail the fact that the issue header is automatically parsed. --- .github/issue_template.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/.github/issue_template.md b/.github/issue_template.md index 5d8594d402..bbca470232 100644 --- a/.github/issue_template.md +++ b/.github/issue_template.md @@ -1,3 +1,19 @@ + + ### Description