RIOT-OS/RIOT
RIOT-OS/RIOT
1
0
Fork 0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2024-12-29 04:50:03 +01:00
Code Releases Activity

Merge pull request #17472 from chrysn-pull-requests/doc-flags-msgs

Browse Source 
core (largely doc): Differentiate message types from thread flags
This commit is contained in:
Kaspar Schleiser 2022-02-27 21:10:47 +01:00 committed by GitHub
commit 7c0ddbd1d8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 31 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
core/include/msg.h
View File

@ -15,9 +15,20 @@
* ========
* IPC messages consist of a sender PID, a type, and some content. The sender
* PID will be set by the IPC internally and is not required to be set by the
* user. The type helps the receiver to multiplex different message types and
* should be set to a system-wide unique value. The content can either be
* provided as a 32-bit integer or a pointer.
* user. The type helps the receiver to multiplex different message types.
* The content can either be provided as a 32-bit integer or a pointer.
*
* Some message types are predefined; for example, @ref
* GNRC_NETAPI_MSG_TYPE_RCV & co are defined. These are fixed in the sense that
* registering for a particular set of messages (for the above, e.g. @ref
* gnrc_netreg_register) will use these message types. Threads that do nothing
* to receive such messages can safely use the same numbers for other purposes.
* The predefined types use non-conflicting ranges (e.g. `0x02NN`) to avoid
* ruling out simultaneous use of different components in the same thread.
*
* In general, threads may consider it an error to send them a message they did
* not request. Best practice is to log (but otherwise ignore) unexpected
* messages.
*
* Blocking vs non-blocking
* ========================

18
core/include/thread_flags.h
View File

@ -39,8 +39,11 @@
* Usually, if it is only of interest that an event occurred, but not how many
* of them, thread flags should be considered.
*
* Note that some flags (currently the three most significant bits) are used by
* Note that some flags (currently the two most significant bits) are used by
* core functions and should not be set by the user. They can be waited for.
* Unlike @ref core_msg "messages" (which are only ever sent when requested),
* these flags can be set unprompted. (For example, @ref THREAD_FLAG_MSG_WAITING
* is set on a thread automatically with every message sent there).
*
* This API is optional and must be enabled by adding "core_thread_flags" to USEMODULE.
*
@ -98,6 +101,19 @@ extern "C" {
* @see xtimer_set_timeout_flag
*/
#define THREAD_FLAG_TIMEOUT (1u << 14)
/**
* @brief Comprehensive set of all predefined flags
*
* This bit mask is set for all thread flag bits that are predefined in RIOT.
* Flags within this set may be set on a thread by the operating system without
* the thread soliciting them (though not all are; for example, @ref
* THREAD_FLAG_TIMEOUT is not).
*
* When using custom flags, asserting that they are not in this set can help
* avoid conflict with future additions to the predefined flags.
*/
#define THREAD_FLAG_PREDEFINED_MASK (THREAD_FLAG_MSG_WAITING | THREAD_FLAG_TIMEOUT)
/** @} */
/**