[mlr] add MulticastListenersTable on BBR (#5292)

This commit adds the Multicast Listener Table for BBR:

- Implements Multicast Listener Table on BBR
  - Adds registered MAs to MulticastListenerTable
  - Reject when the table is full or the multicast address is invalid
    and return failed status
  - Respond with unsuccessful status along with failed addresses
  - Expire Listeners from MulticastListenerTable per second (using
    MinHeap for better performance)
- MLR enhancement
  - Re-register only failed multicast addresses (used to register all
    registering multicast addresses)
- Reference Device only APIs
  - Some APIs are defined for reference devices and tests.
- Add tests
  - Add unit test: test_multicast_listener_table.cpp (runs for 1.2-bbr
    only)
  - Add functional tests

include/openthread/backbone_router_ftd.h

@@ -193,6 +193,114 @@ void otBackboneRouterConfigNextDuaRegistrationResponse(otInstance *
                                                        const otIp6InterfaceIdentifier *aMlIid,
                                                        uint8_t                         aStatus);
 
+/**
+ * Represents the Multicast Listener events.
+ *
+ */
+typedef enum
+{
+    OT_BACKBONE_ROUTER_MULTICAST_LISTENER_ADDED   = 0, ///< Multicast Listener was added.
+    OT_BACKBONE_ROUTER_MULTICAST_LISTENER_REMOVED = 1, ///< Multicast Listener was removed or expired.
+} otBackboneRouterMulticastListenerEvent;
+
+/**
+ * This function pointer is called whenever the Multicast Listeners change.
+ *
+ * @param[in] aContext  The user context pointer.
+ * @param[in] aEvent    The Multicast Listener event.
+ * @param[in] aAddress  The Ip6 multicast address of the Multicast Listener.
+ *
+ */
+typedef void (*otBackboneRouterMulticastListenerCallback)(void *                                 aContext,
+                                                          otBackboneRouterMulticastListenerEvent aEvent,
+                                                          const otIp6Address *                   aAddress);
+
+/**
+ * This method sets the Backbone Router Multicast Listener callback.
+ *
+ * @param[in] aInstance  A pointer to an OpenThread instance.
+ * @param[in] aCallback  A pointer to the Multicast Listener callback.
+ * @param[in] aContext   A user context pointer.
+ *
+ */
+void otBackboneRouterSetMulticastListenerCallback(otInstance *                              aInstance,
+                                                  otBackboneRouterMulticastListenerCallback aCallback,
+                                                  void *                                    aContext);
+
+/**
+ * This method clears the Multicast Listeners.
+ *
+ * Note: available only when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled.
+ *       Only used for test and certification.
+ *
+ * @param[in] aInstance A pointer to an OpenThread instance.
+ *
+ * @sa otBackboneRouterMulticastListenerAdd
+ * @sa otBackboneRouterMulticastListenerGetNext
+ *
+ */
+void otBackboneRouterMulticastListenerClear(otInstance *aInstance);
+
+/**
+ * This method adds a Multicast Listener.
+ *
+ * Note: available only when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled.
+ *       Only used for test and certification.
+ *
+ * @param[in] aInstance  A pointer to an OpenThread instance.
+ * @param[in] aAddress   The Multicast Listener address.
+ * @param[in] aTimeout   The timeout (in seconds) of the Multicast Listener, or 0 to use the default MLR timeout.
+ *
+ * @retval OT_ERROR_NONE          If the Multicast Listener was successfully added.
+ * @retval OT_ERROR_INVALID_ARGS  If the Multicast Listener address was invalid.
+ * @retval OT_ERROR_NO_BUFS       No space available to save the Multicast Listener.
+ *
+ * @sa otBackboneRouterMulticastListenerClear
+ * @sa otBackboneRouterMulticastListenerGetNext
+ *
+ */
+otError otBackboneRouterMulticastListenerAdd(otInstance *aInstance, const otIp6Address *aAddress, uint32_t aTimeout);
+
+#define OT_BACKBONE_ROUTER_MULTICAST_LISTENER_ITERATOR_INIT \
+    0 ///< Initializer for otBackboneRouterMulticastListenerIterator
+
+typedef uint16_t otBackboneRouterMulticastListenerIterator; ///< Used to iterate through Multicast Listeners.
+
+/**
+ * This structure represents a Backbone Router Multicast Listener info.
+ *
+ */
+typedef struct otBackboneRouterMulticastListenerInfo
+{
+    otIp6Address mAddress; // Multicast Listener address.
+    uint32_t     mTimeout; // Timeout (in seconds).
+} otBackboneRouterMulticastListenerInfo;
+
+/**
+ * This function gets the next Multicast Listener info (using an iterator).
+ *
+ * Note: available only when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled.
+ *       Only used for test and certification.
+ *
+ * @param[in]     aInstance    A pointer to an OpenThread instance.
+ * @param[inout]  aIterator    A pointer to the iterator. On success the iterator will be updated to point to next
+ *                             Multicast Listener. To get the first entry the iterator should be set to
+ *                             OT_BACKBONE_ROUTER_MULTICAST_LISTENER_ITERATOR_INIT.
+ * @param[out]    aListenerInfo  A pointer to an `otBackboneRouterMulticastListenerInfo` where information of next
+ *                               Multicast Listener is placed (on success).
+ *
+ * @retval OT_ERROR_NONE       Successfully found the next Multicast Listener info (@p aListenerInfo was successfully
+ *                             updated).
+ * @retval OT_ERROR_NOT_FOUND  No subsequent Multicast Listener info was found.
+ *
+ * @sa otBackboneRouterMulticastListenerClear
+ * @sa otBackboneRouterMulticastListenerAdd
+ *
+ */
+otError otBackboneRouterMulticastListenerGetNext(otInstance *                               aInstance,
+                                                 otBackboneRouterMulticastListenerIterator *aIterator,
+                                                 otBackboneRouterMulticastListenerInfo *    aListenerInfo);
+
 /**
  * @}
  *

include/openthread/instance.h

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