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`
Also includes:
* rename `mbed_sleep_manager.c` to `mbed_power_mgmt.c` to match its
header file
* create Doxygen groups for public and internal APIs
* use relative path to include header files where inconsistent
* update references to internal APIs throughout libraries
* update the copyright year for all modified files
Reimplement atomic code in inline assembly. This can improve
optimisation, and avoids potential architectural problems with using
LDREX/STREX intrinsics.
API further extended:
* Bitwise operations (fetch_and/fetch_or/fetch_xor)
* fetch_add and fetch_sub (like incr/decr, but returning old value -
aligning with C++11)
* compare_exchange_weak
* Explicit memory order specification
* Basic freestanding template overloads for C++
This gives our existing C implementation essentially all the functionality
needed by C++11.
An actual Atomic<T> template based upon these C functions could follow.
As barriers were added in #9247, review comments pointed out that atomic
stores needed a second barrier, and they got one. But atomic_flag_clear
was missed.
Add atomic load and store functions, and add barriers to the existing atomic
functions.
File currently has no explicit barriers - we don't support SMP, so don't
need CPU barriers.
But we do need to worry about compiler barriers - particularly if link time
optimisation is activated so that the compiler can see inside these
functions. The assembler or intrinsics that access PRIMASK for
enter/exit critical act as barriers, but LDREX, STREX and simple
volatile pointer loads and stores do not.
An atomic flag primitive is sometimes wanted, and it is cumbersome to
create it from the compare-and-swap operation - cumbersome enough that
people often don't bother.
Put in a core_util_atomic_flag that follows the C11/C++11 atomic_flag
API, such that it could be mapped to it with #define later.
The atomic functions preserve volatile semantics - they only perform the
accesses specified. Add the volatile qualifier to the value pointer to
reflect this. This does not change existing caller code - it's
equivalent to adding a const qualifier to indicate we don't write to
a pointer - it means people can pass us qualified pointers without
casts, letting the compile check const- or volatile-correctness.
This is consistent with C11 <stdatomic.h>, which volatile-qualifies its
equivalent functions.
Note that this useage of volatile has nothing to do with the atomicity -
objects accessed via the atomic functions do not need to be volatile.
But it does permit these calls to be used on objects which have been
declared volatile.
- Define header functions for Critical Section HAL API
- hal_critical_section_enter()
- hal_critical_section_exit()
- Add weak default implementation for HAL API. The default implementation
matches the previous behaviour stored in mbed_critical:
- The first call to enter a critical section stores the state of interrupts
before disabling and each successive call re-disables interrupts.
- The last call (non-nested) will restore the IRQ state that was set on the
enter to the critical section. Nested calls are ignored.
- Add function 'core_util_in_critical_section' to User facing API to determine
if the program is currently in a critical section, instead of depending on
'core_util_interrupts_enabled'.
Add a note to each CAS making explicit that the functions are strong.
Minor wording change to expectedCurrentValue - use of "still updated"
about the failure case suggested that it might be written to on success.
For some uses it's critically important that expectedCurrentValue only
be written on failure, so change wording to "instead updated".
Hugues Kamba
Kevin Bracey
kegilbert
Martin Kojtal
Steven Cartmell
Senthil Ramakrishnan
Russ Butler
Sam Grove
Christopher Haster