From 5e7d65fc1fa053ef475a6d4b0dda44d278e06d38 Mon Sep 17 00:00:00 2001 From: chrysn Date: Wed, 5 Jan 2022 19:04:35 +0100 Subject: [PATCH 1/4] core/thread: Fix documentation This has been wrong since 317b0133 when a third predefined flag was removed. --- core/include/thread_flags.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/core/include/thread_flags.h b/core/include/thread_flags.h index 7ee41e19d6..1b3ee3bfa4 100644 --- a/core/include/thread_flags.h +++ b/core/include/thread_flags.h @@ -39,7 +39,7 @@ * 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. * * This API is optional and must be enabled by adding "core_thread_flags" to USEMODULE. From 79e0e9431295543d8c320fa5790e6f2308c86ecc Mon Sep 17 00:00:00 2001 From: chrysn Date: Wed, 5 Jan 2022 19:33:51 +0100 Subject: [PATCH 2/4] core/thread doc: Contrast to messages --- core/include/thread_flags.h | 3 +++ 1 file changed, 3 insertions(+) diff --git a/core/include/thread_flags.h b/core/include/thread_flags.h index 1b3ee3bfa4..e5c378b28f 100644 --- a/core/include/thread_flags.h +++ b/core/include/thread_flags.h @@ -41,6 +41,9 @@ * * 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. * From 4bbe0ec42d89b16bf13771fa8da31e068f6de5f6 Mon Sep 17 00:00:00 2001 From: chrysn Date: Wed, 5 Jan 2022 19:34:15 +0100 Subject: [PATCH 3/4] core/msg doc: No need for system-wide uniqueness --- core/include/msg.h | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/core/include/msg.h b/core/include/msg.h index f9f663fcde..b4cf4991f5 100644 --- a/core/include/msg.h +++ b/core/include/msg.h @@ -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 * ======================== From b923fec95270f9138525803882bfb0b65752b55b Mon Sep 17 00:00:00 2001 From: chrysn Date: Wed, 5 Jan 2022 19:40:49 +0100 Subject: [PATCH 4/4] core/thread: Add constant value to check custom flags against Co-authored-by: benpicco --- core/include/thread_flags.h | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/core/include/thread_flags.h b/core/include/thread_flags.h index e5c378b28f..846fcb64e4 100644 --- a/core/include/thread_flags.h +++ b/core/include/thread_flags.h @@ -101,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) /** @} */ /**