USB public APIs cleanup (ARMmbed#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.

Author: gpsimenos

.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

usb/device/USBAudio/USBAudio.h 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 @@ class USBAudio: protected USBDevice {
 
 };
 
+/** @}*/
+/** @}*/
+
 #endif

usb/device/USBSerial/USBCDC.h 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 @@ class USBCDC: public USBDevice {
     uint32_t _rx_size;
 };
 
+/** @}*/
+/** @}*/
+
 #endif

usb/device/USBCDC_ECM/USBCDC_ECM.h 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 @@ class USBCDC_ECM: public USBDevice {
     void _notify_connect();
 };
 
+/** @}*/
+/** @}*/
+
 #endif

usb/device/USBHID/USBHID.h 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 @@ class USBHID: public USBDevice {
 
 };
 
+/** @}*/
+/** @}*/
+
 #endif

usb/device/USBHID/USBKeyboard.h 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 @@ class USBKeyboard: public USBHID, public mbed::Stream {
     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 @@ class USBKeyboard: public USBHID, public mbed::Stream {
 
 };
 
+/** @}*/
+/** @}*/
+
 #endif

usb/device/USBMIDI/USBMIDI.h 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 @@ class USBMIDI: public USBDevice {
     bool _next_message();
 };
 
+/** @}*/
+/** @}*/
+
 #endif

usb/device/USBMSD/USBMSD.h 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 @@ class USBMSD: public USBDevice {
     void fail();
 };
 
+/** @}*/
+/** @}*/
+
 #endif

usb/device/USBHID/USBMouse.h 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 @@ class USBMouse: public USBHID {
     bool mouse_send(int8_t x, int8_t y, uint8_t buttons, int8_t z);
 };
 
+/** @}*/
+/** @}*/
+
 #endif

usb/device/USBHID/USBMouseKeyboard.h 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 @@ class USBMouseKeyboard: public USBHID, public mbed::Stream {
     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 @@ class USBMouseKeyboard: public USBHID, public mbed::Stream {
     virtual int _getc();
 };
 
+/** @}*/
+/** @}*/
+
 #endif

usb/device/USBSerial/USBSerial.h 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 @@ class USBSerial: public USBCDC, public mbed::Stream {
     void (*_settings_changed_callback)(int baud, int bits, int parity, int stop);
 };
 
+/** @}*/
+/** @}*/
+
 #endif

usb/device/utilities/AsyncOp.h 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 @@ class AsyncOp: public LinkEntry {
     static void _host_unlock(rtos::Mutex *host_mutex);
 };
 
+/** @}*/
+/** @}*/
+
 #endif

usb/device/utilities/ByteBuffer.h 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 @@ class ByteBuffer {
     uint8_t *_buf;
 };
 
+/** @}*/
+/** @}*/
 
 #endif

usb/device/USBDevice/EndpointResolver.h 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 @@ class EndpointResolver {
     bool _valid;
 };
 
+/** @}*/
+/** @}*/
 
 #endif

usb/device/utilities/LinkEntry.h 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 @@ class LinkEntry {
     LinkEntry *_next;
 };
 
+/** @}*/
+/** @}*/
 
 #endif