USB public APIs cleanup (#11034)

The contents of the usb directory were moved to appropriate locations and the usb directory removed.

* Public USB headers moved under drivers/
* Internal USB headers moved under drivers/internal/
* USB Source code moved under drivers/source/usb/
* Moved usb/device/hal/ under hal/usb/
* Moved usb/device/USBPhy/ under hal/usb/
* Merged usb/device/targets/ into targets/
* Separated public and private USB API documentation under Doxygen groups drivers-public-api and drivers-internal-api.

.travis.yml

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2018 Arm Limited. All rights reserved.
+# Copyright (c) 2013-2019 Arm Limited. All rights reserved.
 #
 # SPDX-License-Identifier: Apache-2.0
 #
@@ -222,7 +222,7 @@ matrix:
         # Check that example compiles without rtos
         - sed -n '/``` cpp/,/```/{/```$/Q;/```/d;p;}' ${EVENTS}/README.md > main.cpp
         - |
-          rm -r rtos usb features/cellular features/netsocket features/nanostack \
+          rm -r rtos drivers/source/usb features/cellular features/netsocket features/nanostack \
             features/lwipstack features/frameworks/greentea-client \
             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

TESTS/usb_device/hid/main.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, ARM Limited, All Rights Reserved
+ * Copyright (c) 2018-2019, ARM Limited, All Rights Reserved
  * SPDX-License-Identifier: Apache-2.0
  *
  * Licensed under the Apache License, Version 2.0 (the "License"); you may

TESTS/usb_device/serial/main.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, ARM Limited, All Rights Reserved
+ * Copyright (c) 2018-2019, ARM Limited, All Rights Reserved
  * SPDX-License-Identifier: Apache-2.0
  *
  * Licensed under the Apache License, Version 2.0 (the "License"); you may

drivers/USBAudio.h

@@ -28,6 +28,15 @@
 #include "ByteBuffer.h"
 #include "rtos/EventFlags.h"
 
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_USBAudio USBAudio class
+ * @{
+ */
+
+
 /**
 * USBAudio example
 *
@@ -373,4 +382,7 @@ private:
 
 };
 
+/** @}*/
+/** @}*/
+
 #endif

drivers/USBCDC.h

@@ -27,6 +27,14 @@
 
 class AsyncOp;
 
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_USBCDC USBCDC class
+ * @{
+ */
+
 class USBCDC: public USBDevice {
 public:
 
@@ -224,4 +232,7 @@ protected:
     uint32_t _rx_size;
 };
 
+/** @}*/
+/** @}*/
+
 #endif

drivers/USBCDC_ECM.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, Arm Limited and affiliates.
+ * Copyright (c) 2018-2019, Arm Limited and affiliates.
  * SPDX-License-Identifier: Apache-2.0
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -38,6 +38,14 @@
 #define PACKET_TYPE_BROADCAST       (1<<3)
 #define PACKET_TYPE_MULTICAST       (1<<4)
 
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_USBCDC_ECM USBCDC_ECM class
+ * @{
+ */
+
 class USBCDC_ECM: public USBDevice {
 public:
 
@@ -267,4 +275,7 @@ private:
     void _notify_connect();
 };
 
+/** @}*/
+/** @}*/
+
 #endif

drivers/USBHID.h

@@ -26,6 +26,13 @@
 #include "OperationList.h"
 
 
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_USBHID USBHID class
+ * @{
+ */
 
 /**
  * USBHID example
@@ -268,4 +275,7 @@ private:
 
 };
 
+/** @}*/
+/** @}*/
+
 #endif

drivers/USBKeyboard.h

@@ -74,6 +74,14 @@ enum FUNCTION_KEY {
     UP_ARROW,           /* Up arrow */
 };
 
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_USBKeyboard USBKeyboard class
+ * @{
+ */
+
 /**
  * USBKeyboard example
  * @code
@@ -181,7 +189,7 @@ public:
     virtual void report_rx();
 
     /**
-    * Read status of lock keys. Useful to switch-on/off leds according to key pressed. Only the first three bits of the result is important:
+    * Read status of lock keys. Useful to switch-on/off LEDs according to key pressed. Only the first three bits of the result is important:
     *   - First bit: NUM_LOCK
     *   - Second bit: CAPS_LOCK
     *   - Third bit: SCROLL_LOCK
@@ -209,4 +217,7 @@ private:
 
 };
 
+/** @}*/
+/** @}*/
+
 #endif

drivers/USBMIDI.h

@@ -30,6 +30,14 @@
 
 #define DEFAULT_CONFIGURATION (1)
 
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_USBMIDI USBMIDI class
+ * @{
+ */
+
 /**
 * USBMIDI example
 *
@@ -182,4 +190,7 @@ private:
     bool _next_message();
 };
 
+/** @}*/
+/** @}*/
+
 #endif

drivers/USBMSD.h

@@ -22,19 +22,27 @@
 #include "USBDescriptor.h"
 #include "USBDevice_Types.h"
 #include "platform/Callback.h"
-#include "events/PolledQueue.h"
-#include "events/Task.h"
+#include "drivers/internal/PolledQueue.h"
+#include "drivers/internal/Task.h"
 #include "BlockDevice.h"
 #include "Mutex.h"
 
 #include "USBDevice.h"
 
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_USBMSD USBMSD class
+ * @{
+ */
+
 /**
  * USBMSD class: generic class in order to use all kinds of blocks storage chip
  *
  * Introduction
  *
- * USBMSD implements the MSD protocol. It permits to access a block device (flash, sdcard,...)
+ * USBMSD implements the MSD protocol. It permits to access a block device (flash, SD Card,...)
  * from a computer over USB.
  *
  * @code
@@ -304,4 +312,7 @@ private:
     void fail();
 };
 
+/** @}*/
+/** @}*/
+
 #endif

drivers/USBMouse.h

@@ -49,6 +49,14 @@ enum MOUSE_TYPE {
     REL_MOUSE,
 };
 
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_USBMouse USBMouse class
+ * @{
+ */
+
 /**
  *
  * USBMouse example
@@ -232,4 +240,7 @@ private:
     bool mouse_send(int8_t x, int8_t y, uint8_t buttons, int8_t z);
 };
 
+/** @}*/
+/** @}*/
+
 #endif

drivers/USBMouseKeyboard.h

@@ -28,6 +28,14 @@
 #include "USBHID.h"
 #include "PlatformMutex.h"
 
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_USBMouseKeyboard USBMouseKeyboard class
+ * @{
+ */
+
 /**
  * USBMouseKeyboard example
  * @code
@@ -207,7 +215,7 @@ public:
     bool media_control(MEDIA_KEY key);
 
     /**
-    * Read status of lock keys. Useful to switch-on/off leds according to key pressed. Only the first three bits of the result is important:
+    * Read status of lock keys. Useful to switch-on/off LEDs according to key pressed. Only the first three bits of the result is important:
     *   - First bit: NUM_LOCK
     *   - Second bit: CAPS_LOCK
     *   - Third bit: SCROLL_LOCK
@@ -243,4 +251,7 @@ private:
     virtual int _getc();
 };
 
+/** @}*/
+/** @}*/
+
 #endif

drivers/USBSerial.h

@@ -22,6 +22,14 @@
 #include "Stream.h"
 #include "Callback.h"
 
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_USBSerial USBSerial class
+ * @{
+ */
+
 /**
 * USBSerial example
 *
@@ -216,4 +224,7 @@ private:
     void (*_settings_changed_callback)(int baud, int bits, int parity, int stop);
 };
 
+/** @}*/
+/** @}*/
+
 #endif

drivers/internal/AsyncOp.h

@@ -25,6 +25,13 @@
 #include "LinkEntry.h"
 #include "OperationListBase.h"
 
+/** \ingroup drivers */
+/** \addtogroup drivers-internal-api */
+/** @{*/
+/**
+ * \defgroup drivers_AsyncOp AsyncOp class
+ * @{
+ */
 class AsyncOp: public LinkEntry {
 public:
 
@@ -109,4 +116,7 @@ private:
     static void _host_unlock(rtos::Mutex *host_mutex);
 };
 
+/** @}*/
+/** @}*/
+
 #endif

drivers/internal/ByteBuffer.h

@@ -20,6 +20,13 @@
 
 #include <stdint.h>
 
+/** \ingroup drivers */
+/** \addtogroup drivers-internal-api */
+/** @{*/
+/**
+ * \defgroup drivers_ByteBuffer ByteBuffer class
+ * @{
+ */
 class ByteBuffer {
 public:
 
@@ -116,5 +123,7 @@ private:
     uint8_t *_buf;
 };
 
+/** @}*/
+/** @}*/
 
 #endif

drivers/internal/EndpointResolver.h

@@ -29,7 +29,14 @@
  * to check if the device has enough resources for the
  * given configuration.
  *
- * @ingroup usb_device_core
+ */
+
+/** \ingroup drivers */
+/** \addtogroup drivers-internal-api */
+/** @{*/
+/**
+ * \defgroup drivers_EndpointResolver EndpointResolver class
+ * @{
  */
 class EndpointResolver {
 public:
@@ -89,5 +96,7 @@ private:
     bool _valid;
 };
 
+/** @}*/
+/** @}*/
 
 #endif

drivers/internal/LinkEntry.h

@@ -20,6 +20,13 @@
 
 #include <cstddef>
 
+/** \ingroup drivers */
+/** \addtogroup drivers-internal-api */
+/** @{*/
+/**
+ * \defgroup drivers_LinkEntry LinkEntry class
+ * @{
+ */
 class LinkEntry {
 public:
     LinkEntry(): _next(NULL)
@@ -32,5 +39,7 @@ private:
     LinkEntry *_next;
 };
 
+/** @}*/
+/** @}*/
 
 #endif

drivers/internal/LinkedList.h

@@ -21,6 +21,13 @@
 #include "LinkEntry.h"
 #include "LinkedListBase.h"
 
+/** \ingroup drivers */
+/** \addtogroup drivers-internal-api */
+/** @{*/
+/**
+ * \defgroup drivers_LinkedList LinkedList class
+ * @{
+ */
 template<class T>
 class LinkedList: public LinkedListBase {
 public:
@@ -58,4 +65,7 @@ public:
     }
 };
 
+/** @}*/
+/** @}*/
+
 #endif

drivers/internal/LinkedListBase.h

@@ -20,6 +20,13 @@
 
 #include "LinkEntry.h"
 
+/** \ingroup drivers */
+/** \addtogroup drivers-internal-api */
+/** @{*/
+/**
+ * \defgroup drivers_LinkedListBase LinkedListBase class
+ * @{
+ */
 class LinkedListBase {
 public:
     LinkedListBase();
@@ -58,4 +65,7 @@ private:
     LinkEntry *_tail;
 };
 
+/** @}*/
+/** @}*/
+
 #endif

drivers/internal/MIDIMessage.h

@@ -40,6 +40,14 @@
 
 #define CABLE_NUM (0<<4)
 
+/** \ingroup drivers */
+/** \addtogroup drivers-internal-api */
+/** @{*/
+/**
+ * \defgroup drivers_MIDIMessage MIDIMessage class
+ * @{
+ */
+
 /** A MIDI message container */
 class MIDIMessage {
 public:
@@ -472,4 +480,7 @@ public:
     uint16_t length;
 };
 
+/** @}*/
+/** @}*/
+
 #endif

drivers/internal/OperationList.h

@@ -75,7 +75,7 @@ public:
      * Additionally process() must be called on this object
      * if there are still elements in the list.
      *
-     * @return The async op at the head of the list
+     * @return The asynchronous op at the head of the list
      */
     T *dequeue_raw()
     {

drivers/internal/OperationListBase.h

@@ -18,8 +18,7 @@
 #ifndef MBED_OPERATION_LIST_BASE_H
 #define MBED_OPERATION_LIST_BASE_H
 
-#include "LinkedListBase.h"
-#include "Mutex.h"
+#include "drivers/internal/LinkedListBase.h"
 
 class AsyncOp;
 
@@ -72,7 +71,7 @@ public:
      * Additionally process() must be called on this object
      * if there are still elements in the list.
      *
-     * @return The async op at the head of the list
+     * @return The asynchronous op at the head of the list
      */
     AsyncOp *dequeue_raw();
 

drivers/internal/PolledQueue.h

@@ -18,7 +18,7 @@
 #ifndef POLLED_QUEUE_H
 #define POLLED_QUEUE_H
 
-#include "events/TaskQueue.h"
+#include "drivers/internal/TaskQueue.h"
 #include "platform/Callback.h"
 #include "LinkedList.h"
 namespace events {

drivers/internal/Task.h

@@ -19,7 +19,7 @@
 #define MBED_TASK_H
 
 #include "events/EventQueue.h"
-#include "events/TaskBase.h"
+#include "drivers/internal/TaskBase.h"
 #include "platform/mbed_assert.h"
 #include "platform/Callback.h"
 

drivers/internal/TaskQueue.h

@@ -18,7 +18,7 @@
 #ifndef TASK_QUEUE_H
 #define TASK_QUEUE_H
 
-#include "events/TaskBase.h"
+#include "drivers/internal/TaskBase.h"
 #include "platform/Callback.h"
 #include "mbed_critical.h"
 
@@ -68,7 +68,7 @@ public:
      *
      *  Cancels the given event so the event's memory can be reused.
      *
-     *  The cancel function is irq safe.
+     *  The cancel function is IRQ safe.
      *
      *  If called while the event queue's dispatch loop is active, the cancel
      *  function does not guarantee that the event will not execute after it

drivers/internal/USBDevice.h

@@ -23,23 +23,18 @@
 #include "USBPhy.h"
 #include "mbed_critical.h"
 
+/** \ingroup drivers */
+/** \addtogroup drivers-internal-api */
+/** @{*/
 /**
- * \defgroup usb_device USB Device
- *
- */
-
-/**
- * \defgroup usb_device_core Core
- *
- * @ingroup usb_device
+ * \defgroup drivers_USBDevice USBDevice class
+ * @{
  */
 
 /**
  * Core USB Device driver
  *
  * USB driver which wraps and provides synchronization for a USBPhy object.
- *
- * @ingroup usb_device_core
  */
 class USBDevice: public  USBPhyEvents {
 public:
@@ -189,13 +184,13 @@ public:
     void endpoint_stall(usb_ep_t endpoint);
 
     /**
-    * Unstall an endpoint
+    * Un-stall an endpoint
     *
-    * Unstalling an endpoint resets data toggle back to DATA0.
+    * Un-stalling an endpoint resets data toggle back to DATA0.
     * Additionally, if there is an ongoing transfer on this endpoint
     * it will be aborted.
     *
-    * @param endpoint Endpoint to unstall
+    * @param endpoint Endpoint to un-stall
     * @note This endpoint must already have been setup with endpoint_add
     */
     void endpoint_unstall(usb_ep_t endpoint);
@@ -617,4 +612,7 @@ private:
     uint32_t _locked;
 };
 
+/** @}*/
+/** @}*/
+
 #endif

drivers/source/usb/device/USBAudio.cpp

@@ -998,4 +998,3 @@ void USBAudio::_send_isr()
         _tx_done.call(Transfer);
     }
 }
-

drivers/source/usb/device/utilities/ByteBuffer.cpp

@@ -149,4 +149,3 @@ bool ByteBuffer::empty()
 {
     return _head == _tail;
 }
-

drivers/source/usb/device/utilities/events/PolledQueue.cpp

@@ -15,7 +15,7 @@
  * limitations under the License.
  */
 
-#include "events/PolledQueue.h"
+#include "drivers/internal/PolledQueue.h"
 
 #include "events/mbed_events.h"
 #include "platform/Callback.h"

drivers/source/usb/device/utilities/events/TaskBase.cpp

@@ -15,8 +15,8 @@
  * limitations under the License.
  */
 
-#include "events/TaskBase.h"
-#include "events/TaskQueue.h"
+#include "drivers/internal/TaskBase.h"
+#include "drivers/internal/TaskQueue.h"
 #include "events/mbed_events.h"
 #include "rtos/Semaphore.h"
 #include "platform/mbed_critical.h"

hal/usb/USBPhy.h

@@ -259,7 +259,7 @@ public:
     virtual void endpoint_stall(usb_ep_t endpoint) = 0;
 
     /**
-     * Unstall the endpoint
+     * Un-stall the endpoint
      *
      * Clear the HALT feature on this endpoint so communication can
      * resume.

targets/TARGET_RENESAS/TARGET_RZ_A1XX/USBPhy_RZ_A1_Def.h

@@ -498,7 +498,7 @@
 /* Host L1 Control Register 1 */
 /* HL1CTRL1 */
 #define USB_L1STATUS            (0x0006u)   /* b2-1: L1 request completion state */
-#define USB_L1REQ               (0x0001u)   /* b0: L1 changes request bit 
+#define USB_L1REQ               (0x0001u)   /* b0: L1 changes request bit
  */
 
 /* Host L1 Control Register 2 */

tools/test/travis-ci/doxy-spellchecker/ignore.en.pws

@@ -99,4 +99,5 @@ TCPSocket
 UDPSocket
 Socket
 unregister
-_doxy_
+deinit
+_doxy_

usb/mbed_lib.json

@@ -1,3 +0,0 @@
-{
-    "name": "usb"
-}