[message] use opaque 'otMessage' and add 'otMessageBuffer' (#6221)

This commit defines `otMessage` to be an opaque public `struct`. This
change ensures users of OpenThread APIs can only get `otMessage`
instances through OpenThread public APIs and callbacks. It also hides
the `mNext` field which is not intended for use/access by OT API users
(OT users may assume `mNext` is pointing to the next message when the
message is placed in an `otMessageQueue` which is not correct since
`mNext` is used to chain the fixed-size `Buffer` instances of the same
`Message` instance).

This commit adds `otMessageBuffer` in `platform/messagepool.h` which
is then used when the platform is configured to manage the buffer pool.
The `otMessageBuffer` struct defines `mNext` to ensure the returned
`otMessageBuffer` instances from platform layer are aligned correctly
in memory (i.e., they can be safely cast to `ot::Buffer`).

include/openthread/instance.h

@@ -53,7 +53,7 @@ extern "C" {
  * @note This number versions both OpenThread platform and user APIs.
  *
  */
-#define OPENTHREAD_API_VERSION (80)
+#define OPENTHREAD_API_VERSION (81)
 
 /**
  * @addtogroup api-instance

include/openthread/message.h

@@ -53,12 +53,10 @@ extern "C" {
  */
 
 /**
- * This structure points to an OpenThread message buffer.
+ * This type is an opaque representation of an OpenThread message buffer.
+ *
  */
-typedef struct otMessage
-{
-    struct otMessage *mNext; ///< A pointer to the next Message buffer.
-} otMessage;
+typedef struct otMessage otMessage;
 
 /**
  * This structure represents the message buffer information.

include/openthread/platform/messagepool.h

@@ -53,12 +53,23 @@
 extern "C" {
 #endif
 
+/**
+ * This struct represents an OpenThread message buffer.
+ *
+ */
+typedef struct otMessageBuffer
+{
+    struct otMessageBuffer *mNext; ///< Pointer to the next buffer.
+} otMessageBuffer;
+
 /**
  * Initialize the platform implemented message pool.
  *
+ * This function is used when `OPENTHREAD_CONFIG_PLATFORM_MESSAGE_MANAGEMENT` is enabled.
+ *
  * @param[in] aInstance            A pointer to the OpenThread instance.
  * @param[in] aMinNumFreeBuffers   An uint16 containing the minimum number of free buffers desired by OpenThread.
- * @param[in] aBufferSize          The size in bytes of a Buffer object.
+ * @param[in] aBufferSize          The size in bytes of a buffer object.
  *
  */
 void otPlatMessagePoolInit(otInstance *aInstance, uint16_t aMinNumFreeBuffers, size_t aBufferSize);
@@ -66,25 +77,33 @@ void otPlatMessagePoolInit(otInstance *aInstance, uint16_t aMinNumFreeBuffers, s
 /**
  * Allocate a buffer from the platform managed buffer pool.
  *
+ * This function is used when `OPENTHREAD_CONFIG_PLATFORM_MESSAGE_MANAGEMENT` is enabled.
+ *
+ * The returned buffer instance MUST have at least `aBufferSize` bytes (as specified in `otPlatMessagePoolInit()`).
+ *
  * @param[in] aInstance            A pointer to the OpenThread instance.
  *
- * @returns A pointer to the Buffer or NULL if no Buffers are available.
+ * @returns A pointer to the buffer or NULL if no buffers are available.
  *
  */
-otMessage *otPlatMessagePoolNew(otInstance *aInstance);
+otMessageBuffer *otPlatMessagePoolNew(otInstance *aInstance);
 
 /**
- * This function is used to free a Buffer back to the platform managed buffer pool.
+ * This function is used to free a buffer back to the platform managed buffer pool.
+ *
+ * This function is used when `OPENTHREAD_CONFIG_PLATFORM_MESSAGE_MANAGEMENT` is enabled.
  *
  * @param[in]  aInstance  A pointer to the OpenThread instance.
- * @param[in]  aBuffer    The Buffer to free.
+ * @param[in]  aBuffer    The buffer to free.
  *
  */
-void otPlatMessagePoolFree(otInstance *aInstance, otMessage *aBuffer);
+void otPlatMessagePoolFree(otInstance *aInstance, otMessageBuffer *aBuffer);
 
 /**
  * Get the number of free buffers.
  *
+ * This function is used when `OPENTHREAD_CONFIG_PLATFORM_MESSAGE_MANAGEMENT` is enabled.
+ *
  * @param[in]  aInstance  A pointer to the OpenThread instance.
  *
  * @returns The number of buffers currently free and available to OpenThread.

src/core/common/message.hpp

@@ -52,6 +52,14 @@
 #include "thread/child_mask.hpp"
 #include "thread/link_quality.hpp"
 
+/**
+ * This struct represents an opaque (and empty) type for an OpenThread message buffer.
+ *
+ */
+struct otMessage
+{
+};
+
 namespace ot {
 
 namespace Crypto {
@@ -198,9 +206,10 @@ struct MessageMetadata
  * This class represents a Message buffer.
  *
  */
-class Buffer : public otMessage, public LinkedListEntry<Buffer>
+class Buffer : public otMessageBuffer, public LinkedListEntry<Buffer>
 {
     friend class Message;
+    friend class LinkedListEntry<Buffer>;
 
 public:
     /**
@@ -278,7 +287,7 @@ private:
 
     enum
     {
-        kBufferDataSize     = kBufferSize - sizeof(otMessage),
+        kBufferDataSize     = kBufferSize - sizeof(otMessageBuffer),
         kHeadBufferDataSize = kBufferDataSize - sizeof(MessageMetadata),
     };
 
@@ -298,7 +307,7 @@ protected:
  * This class represents a message.
  *
  */
-class Message : public Buffer
+class Message : public otMessage, public Buffer
 {
     friend class Checksum;
     friend class Crypto::HmacSha256;