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

core (largely doc): Differentiate message types from thread flags

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
  * ========================

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)
 /** @} */
 
 /**