[nat64] implement nat64 translator (ot::Nat64::Translator) (#7836)

This commit:

- implements the core logic for translating packets for NAT64,
  including the public APIs exposed to platform daemons.

- includes changes for POSIX platform, use `OT_POSIX_NAT64_CIDR`,
  `OPENTHREAD_POSIX_CONFIG_NAT64_CIDR` for setting the CIDR for NAT64
  during build time.

- exposes `otNat64Send(otInstance *aInstance, otMessage *aMessage)`
  and `void otNat64SetReceiveIp4Callback(otInstance *aInstance,
  otNat64ReceiveIp4Callback aCallback, void *aContext)`.

include/openthread/instance.h

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

include/openthread/nat64.h

@@ -88,6 +88,92 @@ typedef struct otIp4Cidr
     uint8_t      mLength;
 } otIp4Cidr;
 
+/**
+ * Allocate a new message buffer for sending an IPv4 message to the NAT64 translator.
+ *
+ * Message buffers allocated by this function will have 20 bytes (difference between the size of IPv6 headers
+ * and IPv4 header sizes) reserved.
+ *
+ * This function is available only when `OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE` is enabled.
+ *
+ * @note If @p aSettings is `NULL`, the link layer security is enabled and the message priority is set to
+ * OT_MESSAGE_PRIORITY_NORMAL by default.
+ *
+ * @param[in]  aInstance  A pointer to an OpenThread instance.
+ * @param[in]  aSettings  A pointer to the message settings or NULL to set default settings.
+ *
+ * @returns A pointer to the message buffer or NULL if no message buffers are available or parameters are invalid.
+ *
+ * @sa otNat64Send
+ *
+ */
+otMessage *otIp4NewMessage(otInstance *aInstance, const otMessageSettings *aSettings);
+
+/**
+ * Sets the CIDR used when setting the source address of the outgoing translated IPv4 packets.
+ *
+ * This function is available only when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE is enabled.
+ *
+ * @note A valid CIDR must have a non-zero prefix length. The actual addresses pool is limited by the size of the
+ * mapping pool and the number of addresses available in the CIDR block.
+ *
+ * @note This function can be called at any time, but the NAT64 translator will be reset and all existing sessions will
+ * be expired when updating the configured CIDR.
+ *
+ * @param[in] aInstance  A pointer to an OpenThread instance.
+ * @param[in] aCidr      A pointer to an otIp4Cidr for the IPv4 CIDR block for NAT64.
+ *
+ * @retval  OT_ERROR_INVALID_ARGS   The given CIDR is not a valid IPv4 CIDR for NAT64.
+ * @retval  OT_ERROR_NONE           Successfully set the CIDR for NAT64.
+ *
+ * @sa otBorderRouterSend
+ * @sa otBorderRouterSetReceiveCallback
+ *
+ */
+otError otNat64SetIp4Cidr(otInstance *aInstance, const otIp4Cidr *aCidr);
+
+/**
+ * Translates an IPv4 datagram to an IPv6 datagram and sends via the Thread interface.
+ *
+ * The caller transfers ownership of @p aMessage when making this call. OpenThread will free @p aMessage when
+ * processing is complete, including when a value other than `OT_ERROR_NONE` is returned.
+ *
+ * @param[in]  aInstance A pointer to an OpenThread instance.
+ * @param[in]  aMessage  A pointer to the message buffer containing the IPv4 datagram.
+ *
+ * @retval OT_ERROR_NONE                    Successfully processed the message.
+ * @retval OT_ERROR_DROP                    Message was well-formed but not fully processed due to packet processing
+ *                                          rules.
+ * @retval OT_ERROR_NO_BUFS                 Could not allocate necessary message buffers when processing the datagram.
+ * @retval OT_ERROR_NO_ROUTE                No route to host.
+ * @retval OT_ERROR_INVALID_SOURCE_ADDRESS  Source address is invalid, e.g. an anycast address or a multicast address.
+ * @retval OT_ERROR_PARSE                   Encountered a malformed header when processing the message.
+ *
+ */
+otError otNat64Send(otInstance *aInstance, otMessage *aMessage);
+
+/**
+ * This function pointer is called when an IPv4 datagram (translated by NAT64 translator) is received.
+ *
+ * @param[in]  aMessage  A pointer to the message buffer containing the received IPv6 datagram. This function transfers
+ *                       the ownership of the @p aMessage to the receiver of the callback. The message should be
+ *                       freed by the receiver of the callback after it is processed.
+ * @param[in]  aContext  A pointer to application-specific context.
+ *
+ */
+typedef void (*otNat64ReceiveIp4Callback)(otMessage *aMessage, void *aContext);
+
+/**
+ * Registers a callback to provide received IPv4 datagrams.
+ *
+ * @param[in]  aInstance         A pointer to an OpenThread instance.
+ * @param[in]  aCallback         A pointer to a function that is called when an IPv4 datagram is received or
+ *                               NULL to disable the callback.
+ * @param[in]  aCallbackContext  A pointer to application-specific context.
+ *
+ */
+void otNat64SetReceiveIp4Callback(otInstance *aInstance, otNat64ReceiveIp4Callback aCallback, void *aContext);
+
 /**
  * Test if two IPv4 addresses are the same.
  *