* Modify Doxygen grouping of `drivers` Public/Internal APIs
* Correct classification of `mbed_events.h`
* Amend name of Doxygen group containing Device Key API
* Classify `CallChain.h` as public API and relocate file
* Remove Doxygen group from `equeue_platform.h` as it has no Doxygen compliant documentation
* Move USB target specific code back to `usb/device/targets`
* 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"
Previous fix assumed OsTimer is in use - it is for tickless RTOS builds
and non-RTOS builds, but non-tickless RTOS builds avoid it altogether
and use the SysTick peripheral.
Restore previous behaviour for those builds, and just always read the
tick count - there is no downside to this when ticking.
While in the code, make equeue_tick initialisation explicit. This was
problem if the OsTimer is not yet initialised when th
done while debugging - turns out not to be part of the fix, but it
speeds up the runtime code.
Kernel::get_ms_count is documented as not working from IRQ.
In RTOS builds it can return misleading answers - see
https://github.com/ARM-software/CMSIS_5/issues/625
In non-RTOS builds, it can trigger an assert, as it upsets the
sleep logic.
Modified code is still not ideal - could be improved further if
there was a fast path for "post now" that didn't bother looking
at timers (both at post time and dispatch time).
Unwind previous commit and restore original behaviour for binding,
pending further investigation.
Some functions like `EventQueue::call` require precisely matching
argument types to get the correct overload, as before.
Others like `EventQueue::event` permit compatible types for binding, and
those handle the 0-5 bound arguments non-variadically in order to
correctly locate the free arguments in deduction.
Previous commit just replaced instances of "class B0, class B1, class
C0, class C1" with "class... BoundArgs, class... ContextArgs".
This loses the requirement that the numbers must match.
Now, the original code was also inconsistent as to whether it used
separate types for the target function and the call input parameters.
Some forms just used B0, B1 as parameters rather than separate C0, C1.
I believe the separate parameters would have been primarily to avoid
template deduction confusion - eg if int was supplied to a B0 parameter
but the function took char as B0, there would be an ambiguity. But the
fix didn't seem to be fully applied.
Rewritten all templates parameterising on function pointer type and
input arguments so that they use `type_identity_t<BoundArgTs>...` as
input parameters to match the target function.
This has the subtle effect that any conversion happens at invocation,
before storing to the context, rather than when the context calls the
target.
Variadic templates can reduce Event.h from 4,100 lines to 300, and
EventQueue.h from 3,400 to 1,000, so 6,000 lines saved total.
End result isn't totally variadic, as we still need specialisations
for storing 0-5 values in contexts, but that specialisation is now
in exactly one place.
Only change other from switching to variadic templates is using
delegating constructors instead of the `new (this)` trick. That trick is
still used in the assignment operator.
Minor documentation correction. It's possible that the separate
simplified variadic Doxygen version not be needed now, but I've left it.
Make equeue_create_inplace align the passed-in buffer and size to
sizeof(void *).
Really we should be aiming to align more for ARM, as blocks should be
8-byte aligned, but the internal heap mechanisms only work to 4-byte
alignment at the moment. More work would be needed to ensure 8-byte
alignment of allocated blocks.
Original value was too small once both ESP8266 driver and
asynchronous DNS started to use shared event queue. An assumption is
made that once shared event queue is taken into use there are going to
be multiple users instead of one, for which the original value would
have been sufficient.
ESP8266 driver started to use global event queue to handle some AT
parsing and call Socket::sigio() events. It turned out that when
running DNS tests, or Pelion Client, the stack space (1kB) is not
enough for the purpose.
Therefore we propose that this is raised to 2kB, as the assumption
is that event loop should allow as equivalently complex code than
any other threads.
In Mbed OS, the default Thread stack size is 4kB, but we assume 2kB
to be enough for non-blocking event purposes.
In `equeue_destroy` the external loop was for main events linked
list and internal loop for siblings.
Siblings start was not initialized correctly for each main link
When adding sibling at the head of linked list, the head if pointing
to something in linked list was not updated, hence a loop was formed
in linked list
Element0 - First addition to linked list
Element1 - Has higher delay hence added to back
0 ->(next) 1
Element2 - Delay is same as Element0, hence should be sibling of 0
Shall be added at head
Expected:
2 ------------->(next) 1
|(sibling)
0
Bug: (Resolved with this)
2 ------------->(next) 1
|(sibling)
0 ------------->(next) 1
If we add more elements and next pointer of sibling is updated, old
references will cause issues
Element3 added
Expected:
2 ------------->(next) 3 ------------->(next) 1
|(sibling)
0
Bug: (Resolved with this)
2 ------------->(next) 3 ------------->(next) 1
|(sibling)
0 ------------->(next) 1
***Both siblings here point to different next***
Issue was seen with below example
EventQueue q1;
EventQueue q2;
void main() {
while( true ) {
q1.chain( &q2 ); // Chain q2 to q1
q1.chain( NULL ); // Remove chain from q1
//This second step should free the memory from the chained q2 event.
}
}
Memory allocated from q1 slab was freed for q2, which will result in
memory leak.
If user has initiated a delayed event (either with call_in or call_every),
user might need to know how much time is left until the event is
due to be dispatched.
Added time_left() function can be used to get the remaining time.
Event queue was using its own Timer or LowPowerTimer objects to derive
millisecond tick counts. This is unnecessary in RTOS builds, where the
RTOS is maintaining a tick count.
It also makes more sense to use the actual RTOS tick count, as the
values are being used to compute tick timeouts for RTOS calls. Computing
these RTOS tick delays with a separate timer could conceivably lead to
rounding errors.
Fixes: #5378
Teppo Järvelin
Hugues Kamba
Seppo Takalo
Kevin Bracey
Veijo Pesonen
Amanda Butler
Martin Kojtal
deepikabhavnani
Cruz Monrreal
Jeroen de Bruijn
kegilbert
Jaakko Korhonen
Christopher Haster
Kimmo Vaisanen
Cruz Monrreal
Martin Kojtal
Jasper de Winkel