diff --git a/core/include/msg.h b/core/include/msg.h index e81204d97821..72f7ca51fed4 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 * ======================== diff --git a/core/include/thread_flags.h b/core/include/thread_flags.h index 7ee41e19d659..846fcb64e4f8 100644 --- a/core/include/thread_flags.h +++ b/core/include/thread_flags.h @@ -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) /** @} */ /**