When a Doxygen group has been defined (created), all its needed to add
documentation to that group is `\addtogroup`. Since all the information
about the group is preserved, it is not necessary to mention the group
hierarchy again with `\ingroup`. This PR removes unnecessary Doxygen lines
across the `drivers`, `events`, `platform` and `rtos` directories.
It also ensures that new groups are created with `\defgroup` once and
referenced with `\addtogroup` whenever documentation needs to be added to
an existing group.
* Change Doxygen groups structure, splitting first by Public/Internal
This commit also does the following:
* groups the documentation of related API
* moves `events/internal/equeue.h` to `events/equeue.h`
* merges `events/source/README.md` to `events/README.md`
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"
Provide partial RTOS API for bare metal builds - things that
can be done in a single threaded environment.
Allows more code to work in both RTOS and bare metal builds without
change, and in particular gives easy access to the ability to
efficiently wait for something occurring in interrupt.
Available in bare-metal:
* ThisThread
* osThreadFlagsSet to set flags on main thread (can be set from IRQ)
* EventFlags (can be set from IRQ)
* Semaphores (can be released from IRQ)
* Mutex (dummy implementation)
Not useful:
* ConditionVariable (could only be signalled from 2nd thread)
* RtosTimer (calls in a second thread context)
* Thread
Unimplemented:
* Mail, Queue, MemoryPool
Possible future work:
* ConditionVariableCS to act as IRQ signalled ConditionVariable
Give C++ access to the RTOS's absolute timebase, reducing the need to
run private Timers and similar. Allows wait_until functionality, and
makes it easier to avoid time drift.
Place it in a new header and namespace in case we want more kernel
functions in future.
Try to cover over the breaking API change potentially upcoming in
CMSIS-RTOS 2.1.1, when it reduces the tick count from 64-bit to 32-bit.
(See https://github.com/ARM-software/CMSIS_5/issues/277)
Explicitly state that ticks are milliseconds in mbed OS, despite CMSIS
RTOS 2 permitting different tick rates.
See also https://github.com/ARMmbed/mbed-os/pull/3648 (wait_until
for condition variables) and
https://github.com/ARMmbed/mbed-os/issues/5378 (EventQueue should
use RTOS tick count).
Rajkumar Kanagaraj
Martin Kojtal
Hugues Kamba
Kevin Bracey
Amanda Butler
Senthil Ramakrishnan