Drivers/Events/RTOS Public and internal APIs cleanup (#10955)

Separate drivers, events, and rtos internal APIs from public APIs.

* Move source files to source subdirs
* Move internal headers to internal subdirs
* Add Doxygen comments for documenting internal and public APIs
* Remove source code from header files in order to remove include pre-processor directives
that included header files not directly used by said header files
* Explicitly include header files instead of implicit inclusions via third-party header files.

Release Notes

This will break user code that was using an internal API as the internal header files have been moved.
This will only break if the user was including the header file using a namespace (i.e #include "foo/bar.h" instead of #include "bar.h"

Author: hugueskamba

.travis.yml

@@ -227,9 +227,9 @@ matrix:
             features/frameworks/utest features/frameworks/unity components BUILD
         - python tools/make.py -t GCC_ARM -m DISCO_F401VC --source=. --build=BUILD/DISCO_F401VC/GCC_ARM -j0
         # Run local equeue tests
-        - make -C ${EVENTS}/equeue test
+        - make -C ${EVENTS}/source test
         # Run profiling tests
-        - make -C ${EVENTS}/equeue prof | tee prof
+        - make -C ${EVENTS}/source prof | tee prof
       after_success:
         # Update status, comparing with master if possible.
         - |

UNITTESTS/CMakeLists.txt

@@ -105,7 +105,8 @@ set(unittest-includes-base
   "${PROJECT_SOURCE_DIR}/../drivers"
   "${PROJECT_SOURCE_DIR}/../hal"
   "${PROJECT_SOURCE_DIR}/../events"
-  "${PROJECT_SOURCE_DIR}/../events/equeue"
+  "${PROJECT_SOURCE_DIR}/../events/source"
+  "${PROJECT_SOURCE_DIR}/../events/internal"
   "${PROJECT_SOURCE_DIR}/../rtos"
   "${PROJECT_SOURCE_DIR}/../rtos/TARGET_CORTEX"
   "${PROJECT_SOURCE_DIR}/../rtos/TARGET_CORTEX/rtx5/Include"

UNITTESTS/stubs/SerialBase_stub.cpp

@@ -15,7 +15,7 @@
  * limitations under the License.
  */
 
-#include "SerialBase.h"
+#include "drivers/SerialBase.h"
 
 namespace mbed {
 

components/802.15.4_RF/atmel-rf-driver/source/NanostackRfPhyAtmel.cpp

@@ -32,6 +32,7 @@
 #include "SPI.h"
 #include "inttypes.h"
 #include "Timeout.h"
+#include "platform/mbed_error.h"
 
 #define TRACE_GROUP "AtRF"
 

components/802.15.4_RF/mcr20a-rf-driver/source/NanostackRfPhyMcr20a.cpp

@@ -23,6 +23,7 @@
 #include <string.h>
 #include "rtos.h"
 #include "mbed_interface.h"
+#include "platform/mbed_error.h"
 
 using namespace mbed;
 using namespace rtos;

components/802.15.4_RF/stm-s2lp-rf-driver/source/NanostackRfPhys2lp.cpp

@@ -29,6 +29,7 @@
 #include "Timeout.h"
 #include "Thread.h"
 #include "mbed_wait_api.h"
+#include "platform/mbed_error.h"
 
 using namespace mbed;
 using namespace rtos;

drivers/AnalogIn.h

@@ -1,5 +1,5 @@
 /* mbed Microcontroller Library
- * Copyright (c) 2006-2013 ARM Limited
+ * Copyright (c) 2006-2019 ARM Limited
  * SPDX-License-Identifier: Apache-2.0
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -26,7 +26,13 @@
 #include "platform/PlatformMutex.h"
 
 namespace mbed {
-/** \addtogroup drivers */
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api Public API */
+/** @{*/
+/**
+ * \defgroup drivers_AnalogIn AnalogIn class
+ * @{
+ */
 
 /** An analog input, used for reading the voltage on a pin
  *
@@ -48,7 +54,6 @@ namespace mbed {
  *     }
  * }
  * @endcode
- * @ingroup drivers
  */
 class AnalogIn {
 
@@ -58,37 +63,20 @@ class AnalogIn {
      *
      * @param pin AnalogIn pin to connect to
      */
-    AnalogIn(PinName pin)
-    {
-        lock();
-        analogin_init(&_adc, pin);
-        unlock();
-    }
+    AnalogIn(PinName pin);
 
     /** Read the input voltage, represented as a float in the range [0.0, 1.0]
      *
      * @returns A floating-point value representing the current input voltage, measured as a percentage
      */
-    float read()
-    {
-        lock();
-        float ret = analogin_read(&_adc);
-        unlock();
-        return ret;
-    }
+    float read();
 
     /** Read the input voltage, represented as an unsigned short in the range [0x0, 0xFFFF]
      *
      * @returns
      *   16-bit unsigned short representing the current input voltage, normalized to a 16-bit value
      */
-    unsigned short read_u16()
-    {
-        lock();
-        unsigned short ret = analogin_read_u16(&_adc);
-        unlock();
-        return ret;
-    }
+    unsigned short read_u16();
 
     /** An operator shorthand for read()
      *
@@ -129,8 +117,12 @@ class AnalogIn {
     analogin_t _adc;
     static SingletonPtr<PlatformMutex> _mutex;
 #endif //!defined(DOXYGEN_ONLY)
+
 };
 
+/** @}*/
+/** @}*/
+
 } // namespace mbed
 
 #endif

drivers/AnalogOut.h

@@ -1,5 +1,5 @@
 /* mbed Microcontroller Library
- * Copyright (c) 2006-2013 ARM Limited
+ * Copyright (c) 2006-2019 ARM Limited
  * SPDX-License-Identifier: Apache-2.0
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -25,7 +25,13 @@
 #include "platform/PlatformMutex.h"
 
 namespace mbed {
-/** \addtogroup drivers */
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_AnalogOut AnalogOut class
+ * @{
+ */
 
 /** An analog output, used for setting the voltage on a pin
  *
@@ -48,7 +54,6 @@ namespace mbed {
  *     }
  * }
  * @endcode
- * @ingroup drivers
  */
 class AnalogOut {
 
@@ -70,24 +75,14 @@ class AnalogOut {
      *    0.0f (representing 0v / 0%) and 1.0f (representing 3.3v / 100%).
      *    Values outside this range will be saturated to 0.0f or 1.0f.
      */
-    void write(float value)
-    {
-        lock();
-        analogout_write(&_dac, value);
-        unlock();
-    }
+    void write(float value);
 
     /** Set the output voltage, represented as an unsigned short in the range [0x0, 0xFFFF]
      *
      *  @param value 16-bit unsigned short representing the output voltage,
      *            normalized to a 16-bit value (0x0000 = 0v, 0xFFFF = 3.3v)
      */
-    void write_u16(unsigned short value)
-    {
-        lock();
-        analogout_write_u16(&_dac, value);
-        unlock();
-    }
+    void write_u16(unsigned short value);
 
     /** Return the current output voltage setting, measured as a percentage (float)
      *
@@ -99,13 +94,7 @@ class AnalogOut {
      *  @note
      *    This value may not match exactly the value set by a previous write().
      */
-    float read()
-    {
-        lock();
-        float ret = analogout_read(&_dac);
-        unlock();
-        return ret;
-    }
+    float read();
 
     /** An operator shorthand for write()
      * \sa AnalogOut::write()
@@ -158,6 +147,9 @@ class AnalogOut {
 #endif //!defined(DOXYGEN_ONLY)
 };
 
+/** @}*/
+/** @}*/
+
 } // namespace mbed
 
 #endif

drivers/BusIn.h

@@ -23,12 +23,17 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \addtogroup drivers */
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_BusIn BusIn class
+ * @{
+ */
 
 /** A digital input bus, used for reading the state of a collection of pins
  *
  * @note Synchronization level: Thread safe
- * @ingroup drivers
  */
 class BusIn : private NonCopyable<BusIn> {
 
@@ -125,6 +130,9 @@ class BusIn : private NonCopyable<BusIn> {
 #endif
 };
 
+/** @}*/
+/** @}*/
+
 } // namespace mbed
 
 #endif

drivers/BusInOut.h

@@ -22,15 +22,20 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \addtogroup drivers */
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_BusInOut BusInOut class
+ * @{
+ */
 
 /** A digital input output bus, used for setting the state of a collection of pins.
  *  Implemented as an array of DigitalInOut pins, the bus can be constructed by any
  *  pins without restriction other than being capable of digital input or output
  *  capabilities
  *
  * @note Synchronization level: Thread safe
- * @ingroup drivers
  */
 class BusInOut : private NonCopyable<BusInOut> {
 
@@ -147,6 +152,9 @@ class BusInOut : private NonCopyable<BusInOut> {
 #endif //!defined(DOXYGEN_ONLY)
 };
 
+/** @}*/
+/** @}*/
+
 } // namespace mbed
 
 #endif

drivers/BusOut.h

@@ -22,10 +22,15 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \addtogroup drivers */
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_BusOut BusOut class
+ * @{
+ */
 
 /** A digital output bus, used for setting the state of a collection of pins
- * @ingroup drivers
  */
 class BusOut : private NonCopyable<BusOut> {
 
@@ -125,6 +130,9 @@ class BusOut : private NonCopyable<BusOut> {
 #endif
 };
 
+/** @}*/
+/** @}*/
+
 } // namespace mbed
 
 #endif

drivers/CAN.h

@@ -1,5 +1,5 @@
 /* mbed Microcontroller Library
- * Copyright (c) 2006-2013 ARM Limited
+ * Copyright (c) 2006-2019 ARM Limited
  * SPDX-License-Identifier: Apache-2.0
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -27,12 +27,17 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \addtogroup drivers */
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_CANMessage CANMessage class
+ * @{
+ */
 
 /** CANMessage class
  *
  * @note Synchronization level: Thread safe
- * @ingroup drivers
  */
 class CANMessage : public CAN_Message {
 
@@ -98,8 +103,14 @@ class CANMessage : public CAN_Message {
     }
 };
 
+/** @}*/
+
+/**
+ * \defgroup drivers_CAN CAN class
+ * @{
+ */
+
 /** A can bus client, used for communicating with can devices
- * @ingroup drivers
  */
 class CAN : private NonCopyable<CAN> {
 
@@ -315,12 +326,16 @@ class CAN : private NonCopyable<CAN> {
 protected:
     virtual void lock();
     virtual void unlock();
+
     can_t               _can;
     Callback<void()>    _irq[IrqCnt];
     PlatformMutex       _mutex;
 #endif
 };
 
+/** @}*/
+/** @}*/
+
 } // namespace mbed
 
 #endif