USB public APIs cleanup

[gpsimenos]

Description

This PR refactors the usb directory according to https://jira.arm.com/browse/IOTCLOUDPR-3296.

• 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.

Pull request type

[ ] Fix
[X] Refactor
[ ] Target update
[ ] Functionality change
[ ] Docs update
[ ] Test update
[ ] Breaking change

Reviewers

@evedon
@hugueskamba

[40Grit]

@AGlass0fMilk

[ciarmcom]

@gpsimenos, thank you for your changes.
@hugueskamba @evedon @ARMmbed/mbed-os-maintainers please review.

[evedon]

@gpsimenos ResetReason.cpp needs to move to source
Please also update 3rd bullet in PR description

[evedon]

Some rework needed.

In drivers/internal/Task.h, there is #include "events/TaskBase.h"
TaskBase.h is under drivers/source/usb/device/utilities/events/. It should be in drivers/internal

Same for TaskQueue.h AsyncOp.h etc.

[hugueskamba]

@gpsimenos
The doxy-spellcheck CI test fails because some words in the content now part of Doxygen has incorrect spelling/case.

The incorrect words are:

• sdcard
• leds
• async
• Unstall
• Unstalling
• irq
• deinit

You can fix the issue by replacing the first six words with:

• SD card
• LEDs
• asynchronous
• Un-stall
• Un-stalling
• IRQ

Note: You cannot just do a replace all as it might change content that is not part of the Doxygen comments (i.e c/cpp code).

For deinit, you cannot change it as the Doxygen comment refers to a function name deinit(). Instead, do what the script suggests at the bottom of the failure.

If any of the failed words should be considered valid please add them to the ignore.en.pws file
found in tools/test/scripts/doxy-spellchecker between the _code_ and _doxy_ tags.

So add deinit to that file.

[gpsimenos]

@gpsimenos ResetReason.cpp needs to move to source
Please also update 3rd bullet in PR description

That's not part of USB. Should I move it regardless?

[evedon]

@gpsimenos ResetReason.cpp needs to move to source
Please also update 3rd bullet in PR description

That's not part of USB. Should I move it regardless?

Hugues already did it. Rebase your PR to pick up the change.

[gpsimenos]

Some rework needed.

In drivers/internal/Task.h, there is #include "events/TaskBase.h"
TaskBase.h is under drivers/source/usb/device/utilities/events/. It should be in drivers/internal

Same for TaskQueue.h AsyncOp.h etc.

Fixed

[hugueskamba]

@gpsimenos
8e84d9a does not fix the Doxygen spelling. You missed out async and irq.
Run ./tools/test/travis-ci/doxy-spellchecker/spell.sh drivers/ to make sure all is fixed.

@gpsimenos
The doxy-spellcheck CI test fails because some words in the content now part of Doxygen has incorrect spelling/case.

The incorrect words are:

• sdcard
• leds
• async
• Unstall
• Unstalling
• irq
• deinit

You can fix the issue by replacing the first six words with:

• SD card
• LEDs
• asynchronous
• Un-stall
• Un-stalling
• IRQ

Note: You cannot just do a replace all as it might change content that is not part of the Doxygen comments (i.e c/cpp code).

For deinit, you cannot change it as the Doxygen comment refers to a function name deinit(). Instead, do what the script suggests at the bottom of the failure.

If any of the failed words should be considered valid please add them to the ignore.en.pws file
found in tools/test/scripts/doxy-spellchecker between the _code_ and _doxy_ tags.

So add deinit to that file.

[hugueskamba]

The unit tests fails with the following error:

[Fatal Error] TaskQueue.h@21,10: events/TaskBase.h: No such file or directory
[DEBUG] Return: 1
[DEBUG] Output: In file included from ./drivers/internal/PolledQueue.h:21,
[DEBUG] Output:                  from ./drivers/USBMSD.h:25,
[DEBUG] Output:                  from ./drivers/source/usb/device/USBMSD.cpp:20:
[DEBUG] Output: ./drivers/internal/TaskQueue.h:21:10: fatal error: events/TaskBase.h: No such file or directory
[DEBUG] Output:  #include "events/TaskBase.h"
[DEBUG] Output:           ^~~~~~~~~~~~~~~~~~~
[DEBUG] Output: compilation terminated.
Failed to build library
Memory map breakdown for built projects (values in Bytes):
| name | target | toolchain | static_ram | total_flash |
|------|--------|-----------|------------|-------------|


Build failures:
  * K64F::GCC_ARM::MBED-BUILD
        
[mbed] ERROR: "/usr/bin/python" returned error.
       Code: 1
       Path: "/home/hugkam01/projects/mbed-os-projects/mbed-os"
       Command: "/usr/bin/python -u /home/hugkam01/projects/mbed-os-projects/mbed-os/tools/test.py -D MBED_TEST_MODE -t GCC_ARM -m k64f -c --source . --build ./BUILD/tests/K64F/GCC_ARM --test-spec ./BUILD/tests/K64F/GCC_ARM/test_spec.json --build-data ./BUILD/tests/K64F/GCC_ARM/build_data.json -n mbed-os-tests-usb* -v --greentea"
       Tip: You could retry the last command with "-v" flag for verbose output

Basically there is still references to events/TaskBase.h instead of drivers/internal/TaskBase.h

$ grep -ir 'TaskBase.h' .
./drivers/internal/TaskQueue.h:#include "events/TaskBase.h"
./drivers/internal/Task.h:#include "drivers/internal/TaskBase.h"
./drivers/source/usb/device/utilities/events/TaskBase.cpp:#include "events/TaskBase.h"

[evedon]

Please make sure that all greentea tests are passing.
And check with tools team if they need some refactoring due to removal of usb/mbed_lib.json file.

Other than that I am okay with the PR.

[hugueskamba]

Please make sure that all greentea tests are passing.
And check with tools team if they need some refactoring due to removal of usb/mbed_lib.json file.

Other than that I am okay with the PR.

The Greentea tests are failing.

[hugueskamba]

The copyright year for modified files need to be updated.

[mark-edgeworth]

Looks like there are some issues with tools/tests.py at least: the USB tests at line 672- in this file refer to a directory TESTS/usb/device/... but this seems to be TESTS/usb_device/... However, this change does not appear to have been introduced here, so I question the testing...

[hugueskamba]

Looks like there are some issues with tools/tests.py at least: the USB tests at line 672- in this file refer to a directory TESTS/usb/device/... but this seems to be TESTS/usb_device/... However, this change does not appear to have been introduced here, so I question the testing...

@jamesbeyond Any comment?