diff --git a/openthread/include/openthread-system.h b/openthread/include/openthread-system.h index de8b2d13b3..90503ecd3d 100644 --- a/openthread/include/openthread-system.h +++ b/openthread/include/openthread-system.h @@ -42,7 +42,7 @@ extern "C" { #endif /** - * This function performs all platform-specific initialization of OpenThread's drivers. + * Performs all platform-specific initialization of OpenThread's drivers. * * @note This function is not called by the OpenThread library. Instead, the system/RTOS should call this function * when initialization of OpenThread's drivers is most appropriate. @@ -54,7 +54,7 @@ extern "C" { void otSysInit(int argc, char *argv[]); /** - * This function performs all platform-specific deinitialization for OpenThread's drivers. + * Performs all platform-specific deinitialization for OpenThread's drivers. * * @note This function is not called by the OpenThread library. Instead, the system/RTOS should call this function * when deinitialization of OpenThread's drivers is most appropriate. @@ -63,7 +63,7 @@ void otSysInit(int argc, char *argv[]); void otSysDeinit(void); /** - * This function returns true if a pseudo-reset was requested. + * Returns true if a pseudo-reset was requested. * * In such a case, the main loop should shut down and re-initialize the OpenThread instance. * @@ -74,7 +74,7 @@ void otSysDeinit(void); bool otSysPseudoResetWasRequested(void); /** - * This function performs all platform-specific processing for OpenThread's example applications. + * Performs all platform-specific processing for OpenThread's example applications. * * @note This function is not called by the OpenThread library. Instead, the system/RTOS should call this function * in the main loop when processing OpenThread's drivers is most appropriate. @@ -85,7 +85,7 @@ bool otSysPseudoResetWasRequested(void); void otSysProcessDrivers(otInstance *aInstance); /** - * This function is called whenever platform drivers needs processing. + * Is called whenever platform drivers needs processing. * * @note This function is not handled by the OpenThread library. Instead, the system/RTOS should handle this function * and schedule a call to `otSysProcessDrivers()`. diff --git a/openthread/include/openthread/backbone_router.h b/openthread/include/openthread/backbone_router.h index 23cb4d426a..a057dc4edb 100644 --- a/openthread/include/openthread/backbone_router.h +++ b/openthread/include/openthread/backbone_router.h @@ -52,7 +52,7 @@ extern "C" { */ /** - * This structure represents Backbone Router configuration. + * Represents Backbone Router configuration. * */ typedef struct otBackboneRouterConfig @@ -64,7 +64,7 @@ typedef struct otBackboneRouterConfig } otBackboneRouterConfig; /** - * This function gets the Primary Backbone Router information in the Thread Network. + * Gets the Primary Backbone Router information in the Thread Network. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[out] aConfig A pointer to where to put Primary Backbone Router information. diff --git a/openthread/include/openthread/backbone_router_ftd.h b/openthread/include/openthread/backbone_router_ftd.h index d4041d68af..88cfe0a387 100644 --- a/openthread/include/openthread/backbone_router_ftd.h +++ b/openthread/include/openthread/backbone_router_ftd.h @@ -161,7 +161,7 @@ otError otBackboneRouterSetConfig(otInstance *aInstance, const otBackboneRouterC otError otBackboneRouterRegister(otInstance *aInstance); /** - * This method returns the Backbone Router registration jitter value. + * Returns the Backbone Router registration jitter value. * * @returns The Backbone Router registration jitter value. * @@ -171,7 +171,7 @@ otError otBackboneRouterRegister(otInstance *aInstance); uint8_t otBackboneRouterGetRegistrationJitter(otInstance *aInstance); /** - * This method sets the Backbone Router registration jitter value. + * Sets the Backbone Router registration jitter value. * * @param[in] aJitter the Backbone Router registration jitter value to set. * @@ -181,7 +181,7 @@ uint8_t otBackboneRouterGetRegistrationJitter(otInstance *aInstance); void otBackboneRouterSetRegistrationJitter(otInstance *aInstance, uint8_t aJitter); /** - * This method gets the local Domain Prefix configuration. + * Gets the local Domain Prefix configuration. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[out] aConfig A pointer to the Domain Prefix configuration. @@ -193,7 +193,7 @@ void otBackboneRouterSetRegistrationJitter(otInstance *aInstance, uint8_t aJitte otError otBackboneRouterGetDomainPrefix(otInstance *aInstance, otBorderRouterConfig *aConfig); /** - * This method configures response status for next DUA registration. + * Configures response status for next DUA registration. * * Note: available only when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. * Only used for test and certification. @@ -235,7 +235,7 @@ typedef enum } otBackboneRouterMulticastListenerEvent; /** - * This function pointer is called whenever the Multicast Listeners change. + * Pointer is called whenever the Multicast Listeners change. * * @param[in] aContext The user context pointer. * @param[in] aEvent The Multicast Listener event. @@ -247,7 +247,7 @@ typedef void (*otBackboneRouterMulticastListenerCallback)(void const otIp6Address *aAddress); /** - * This method sets the Backbone Router Multicast Listener callback. + * 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. @@ -302,7 +302,7 @@ otError otBackboneRouterMulticastListenerAdd(otInstance *aInstance, const otIp6A typedef uint16_t otBackboneRouterMulticastListenerIterator; ///< Used to iterate through Multicast Listeners. /** - * This structure represents a Backbone Router Multicast Listener info. + * Represents a Backbone Router Multicast Listener info. * */ typedef struct otBackboneRouterMulticastListenerInfo @@ -312,7 +312,7 @@ typedef struct otBackboneRouterMulticastListenerInfo } otBackboneRouterMulticastListenerInfo; /** - * This function gets the next Multicast Listener info (using an iterator). + * Gets the next Multicast Listener info (using an iterator). * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in,out] aIterator A pointer to the iterator. On success the iterator will be updated to point to next @@ -346,7 +346,7 @@ typedef enum } otBackboneRouterNdProxyEvent; /** - * This function pointer is called whenever the Nd Proxy changed. + * Pointer is called whenever the Nd Proxy changed. * * @param[in] aContext The user context pointer. * @param[in] aEvent The ND Proxy event. @@ -359,7 +359,7 @@ typedef void (*otBackboneRouterNdProxyCallback)(void *aCo const otIp6Address *aDua); /** - * This method sets the Backbone Router ND Proxy callback. + * Sets the Backbone Router ND Proxy callback. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aCallback A pointer to the ND Proxy callback. @@ -382,7 +382,7 @@ typedef struct otBackboneRouterNdProxyInfo } otBackboneRouterNdProxyInfo; /** - * This method gets the Backbone Router ND Proxy info. + * Gets the Backbone Router ND Proxy info. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aDua The Domain Unicast Address. @@ -408,7 +408,7 @@ typedef enum } otBackboneRouterDomainPrefixEvent; /** - * This function pointer is called whenever the Domain Prefix changed. + * Pointer is called whenever the Domain Prefix changed. * * @param[in] aContext The user context pointer. * @param[in] aEvent The Domain Prefix event. @@ -419,7 +419,7 @@ typedef void (*otBackboneRouterDomainPrefixCallback)(void otBackboneRouterDomainPrefixEvent aEvent, const otIp6Prefix *aDomainPrefix); /** - * This method sets the Backbone Router Domain Prefix callback. + * Sets the Backbone Router Domain Prefix callback. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aCallback A pointer to the Domain Prefix callback. diff --git a/openthread/include/openthread/border_agent.h b/openthread/include/openthread/border_agent.h index 83babfa142..1c7a535370 100644 --- a/openthread/include/openthread/border_agent.h +++ b/openthread/include/openthread/border_agent.h @@ -52,7 +52,31 @@ extern "C" { */ /** - * This enumeration defines the Border Agent state. + * The length of Border Agent/Router ID in bytes. + * + */ +#define OT_BORDER_AGENT_ID_LENGTH (16) + +/** + * @struct otBorderAgentId + * + * Represents a Border Agent ID. + * + */ +OT_TOOL_PACKED_BEGIN +struct otBorderAgentId +{ + uint8_t mId[OT_BORDER_AGENT_ID_LENGTH]; +} OT_TOOL_PACKED_END; + +/** + * Represents a Border Agent ID. + * + */ +typedef struct otBorderAgentId otBorderAgentId; + +/** + * Defines the Border Agent state. * */ typedef enum otBorderAgentState @@ -82,6 +106,42 @@ otBorderAgentState otBorderAgentGetState(otInstance *aInstance); */ uint16_t otBorderAgentGetUdpPort(otInstance *aInstance); +/** + * Gets the randomly generated Border Agent ID. + * + * The ID is saved in persistent storage and survives reboots. The typical use case of the ID is to + * be published in the MeshCoP mDNS service as the `id` TXT value for the client to identify this + * Border Router/Agent device. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[out] aId A pointer to buffer to receive the ID. + * + * @retval OT_ERROR_NONE If successfully retrieved the Border Agent ID. + * @retval ... If failed to retrieve the Border Agent ID. + * + * @sa otBorderAgentSetId + * + */ +otError otBorderAgentGetId(otInstance *aInstance, otBorderAgentId *aId); + +/** + * Sets the Border Agent ID. + * + * The Border Agent ID will be saved in persistent storage and survive reboots. It's required to + * set the ID only once after factory reset. If the ID has never been set by calling this function, + * a random ID will be generated and returned when `otBorderAgentGetId` is called. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[out] aId A pointer to the Border Agent ID. + * + * @retval OT_ERROR_NONE If successfully set the Border Agent ID. + * @retval ... If failed to set the Border Agent ID. + * + * @sa otBorderAgentGetId + * + */ +otError otBorderAgentSetId(otInstance *aInstance, const otBorderAgentId *aId); + /** * @} * diff --git a/openthread/include/openthread/border_router.h b/openthread/include/openthread/border_router.h index a945f91fb2..d07febac07 100644 --- a/openthread/include/openthread/border_router.h +++ b/openthread/include/openthread/border_router.h @@ -54,7 +54,7 @@ extern "C" { */ /** - * This method provides a full or stable copy of the local Thread Network Data. + * Provides a full or stable copy of the local Thread Network Data. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aStable TRUE when copying the stable version, FALSE when copying the full version. @@ -94,7 +94,7 @@ otError otBorderRouterAddOnMeshPrefix(otInstance *aInstance, const otBorderRoute otError otBorderRouterRemoveOnMeshPrefix(otInstance *aInstance, const otIp6Prefix *aPrefix); /** - * This function gets the next On Mesh Prefix in the local Network Data. + * Gets the next On Mesh Prefix in the local Network Data. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in,out] aIterator A pointer to the Network Data iterator context. To get the first on-mesh entry @@ -139,7 +139,7 @@ otError otBorderRouterAddRoute(otInstance *aInstance, const otExternalRouteConfi otError otBorderRouterRemoveRoute(otInstance *aInstance, const otIp6Prefix *aPrefix); /** - * This function gets the next external route in the local Network Data. + * Gets the next external route in the local Network Data. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in,out] aIterator A pointer to the Network Data iterator context. To get the first external route entry @@ -168,6 +168,35 @@ otError otBorderRouterGetNextRoute(otInstance *aInstance, */ otError otBorderRouterRegister(otInstance *aInstance); +/** + * Function pointer callback which is invoked when Network Data (local or leader) gets full. + * + * @param[in] aContext A pointer to arbitrary context information. + * + */ +typedef void (*otBorderRouterNetDataFullCallback)(void *aContext); + +/** + * Sets the callback to indicate when Network Data gets full. + * + * Requires `OPENTHREAD_CONFIG_BORDER_ROUTER_SIGNAL_NETWORK_DATA_FULL`. + * + * The callback is invoked whenever: + * - The device is acting as a leader and receives a Network Data registration from a Border Router (BR) that it cannot + * add to Network Data (running out of space). + * - The device is acting as a BR and new entries cannot be added to its local Network Data. + * - The device is acting as a BR and tries to register its local Network Data entries with the leader, but determines + * that its local entries will not fit. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aCallback The callback. + * @param[in] aContext A pointer to arbitrary context information used with @p aCallback. + * + */ +void otBorderRouterSetNetDataFullCallback(otInstance *aInstance, + otBorderRouterNetDataFullCallback aCallback, + void *aContext); + /** * @} * diff --git a/openthread/include/openthread/border_routing.h b/openthread/include/openthread/border_routing.h index 79be8e167a..36e83a6d0c 100644 --- a/openthread/include/openthread/border_routing.h +++ b/openthread/include/openthread/border_routing.h @@ -73,7 +73,7 @@ extern "C" { */ /** - * This structure represents an iterator to iterate through the Border Router's discovered prefix table. + * Represents an iterator to iterate through the Border Router's discovered prefix table. * * The fields in this type are opaque (intended for use by OpenThread core only) and therefore should not be * accessed or used by caller. @@ -89,7 +89,7 @@ typedef struct otBorderRoutingPrefixTableIterator } otBorderRoutingPrefixTableIterator; /** - * This structure represents an entry from the discovered prefix table. + * Represents an entry from the discovered prefix table. * * The entries in the discovered table track the Prefix/Route Info Options in the received Router Advertisement messages * from other routers on infrastructure link. @@ -107,9 +107,34 @@ typedef struct otBorderRoutingPrefixTableEntry } otBorderRoutingPrefixTableEntry; /** - * This method initializes the Border Routing Manager on given infrastructure interface. + * Represents the state of Border Routing Manager. + * + */ +typedef enum +{ + OT_BORDER_ROUTING_STATE_UNINITIALIZED, ///< Routing Manager is uninitialized. + OT_BORDER_ROUTING_STATE_DISABLED, ///< Routing Manager is initialized but disabled. + OT_BORDER_ROUTING_STATE_STOPPED, ///< Routing Manager in initialized and enabled but currently stopped. + OT_BORDER_ROUTING_STATE_RUNNING, ///< Routing Manager is initialized, enabled, and running. +} otBorderRoutingState; + +/** + * This enumeration represents the state of DHCPv6 Prefix Delegation State. + * + */ +typedef enum +{ + OT_BORDER_ROUTING_DHCP6_PD_STATE_DISABLED, ///< DHCPv6 PD is disabled on the border router. + OT_BORDER_ROUTING_DHCP6_PD_STATE_STOPPED, ///< DHCPv6 PD in enabled but won't try to request and publish a prefix. + OT_BORDER_ROUTING_DHCP6_PD_STATE_RUNNING, ///< DHCPv6 PD is enabled and will try to request and publish a prefix. +} otBorderRoutingDhcp6PdState; + +/** + * Initializes the Border Routing Manager on given infrastructure interface. * * @note This method MUST be called before any other otBorderRouting* APIs. + * @note This method can be re-called to change the infrastructure interface, but the Border Routing Manager should be + * disabled first, and re-enabled after. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aInfraIfIndex The infrastructure interface index. @@ -117,11 +142,12 @@ typedef struct otBorderRoutingPrefixTableEntry * interface is running. * * @retval OT_ERROR_NONE Successfully started the Border Routing Manager on given infrastructure. - * @retval OT_ERROR_INVALID_STATE The Border Routing Manager has already been initialized. + * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is in a state other than disabled or uninitialized. * @retval OT_ERROR_INVALID_ARGS The index of the infrastructure interface is not valid. * @retval OT_ERROR_FAILED Internal failure. Usually due to failure in generating random prefixes. * * @sa otPlatInfraIfStateChanged. + * @sa otBorderRoutingSetEnabled. * */ otError otBorderRoutingInit(otInstance *aInstance, uint32_t aInfraIfIndex, bool aInfraIfIsRunning); @@ -141,7 +167,17 @@ otError otBorderRoutingInit(otInstance *aInstance, uint32_t aInfraIfIndex, bool otError otBorderRoutingSetEnabled(otInstance *aInstance, bool aEnabled); /** - * This function gets the current preference used when advertising Route Info Options (RIO) in Router Advertisement + * Gets the current state of Border Routing Manager. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * + * @returns The current state of Border Routing Manager. + * + */ +otBorderRoutingState otBorderRoutingGetState(otInstance *aInstance); + +/** + * Gets the current preference used when advertising Route Info Options (RIO) in Router Advertisement * messages sent over the infrastructure link. * * The RIO preference is determined as follows: @@ -157,7 +193,7 @@ otError otBorderRoutingSetEnabled(otInstance *aInstance, bool aEnabled); otRoutePreference otBorderRoutingGetRouteInfoOptionPreference(otInstance *aInstance); /** - * This function explicitly sets the preference to use when advertising Route Info Options (RIO) in Router + * Explicitly sets the preference to use when advertising Route Info Options (RIO) in Router * Advertisement messages sent over the infrastructure link. * * After a call to this function, BR will use the given preference for all its advertised RIOs. The preference can be @@ -170,7 +206,7 @@ otRoutePreference otBorderRoutingGetRouteInfoOptionPreference(otInstance *aInsta void otBorderRoutingSetRouteInfoOptionPreference(otInstance *aInstance, otRoutePreference aPreference); /** - * This function clears a previously set preference value for advertised Route Info Options. + * Clears a previously set preference value for advertised Route Info Options. * * After a call to this function, BR will use device's role to determine the RIO preference: Medium preference when * in router/leader role and low preference when in child role. @@ -180,6 +216,44 @@ void otBorderRoutingSetRouteInfoOptionPreference(otInstance *aInstance, otRouteP */ void otBorderRoutingClearRouteInfoOptionPreference(otInstance *aInstance); +/** + * Gets the current preference used for published routes in Network Data. + * + * The preference is determined as follows: + * + * - If explicitly set by user by calling `otBorderRoutingSetRoutePreference()`, the given preference is used. + * - Otherwise, it is determined automatically by `RoutingManager` based on the device's role and link quality. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * + * @returns The current published route preference. + * + */ +otRoutePreference otBorderRoutingGetRoutePreference(otInstance *aInstance); + +/** + * Explicitly sets the preference of published routes in Network Data. + * + * After a call to this function, BR will use the given preference. The preference can be cleared by calling + * `otBorderRoutingClearRoutePreference()`. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aPreference The route preference to use. + * + */ +void otBorderRoutingSetRoutePreference(otInstance *aInstance, otRoutePreference aPreference); + +/** + * Clears a previously set preference value for published routes in Network Data. + * + * After a call to this function, BR will determine the preference automatically based on the device's role and + * link quality (to the parent when acting as end-device). + * + * @param[in] aInstance A pointer to an OpenThread instance. + * + */ +void otBorderRoutingClearRoutePreference(otInstance *aInstance); + /** * Gets the local Off-Mesh-Routable (OMR) Prefix, for example `fdfc:1ff5:1512:5622::/64`. * @@ -187,15 +261,40 @@ void otBorderRoutingClearRouteInfoOptionPreference(otInstance *aInstance); * Thread network if there isn't already an OMR prefix. This prefix can be reached * from the local Wi-Fi or Ethernet network. * + * Note: When DHCPv6 PD is enabled, the border router may publish the prefix from + * DHCPv6 PD. + * * @param[in] aInstance A pointer to an OpenThread instance. * @param[out] aPrefix A pointer to where the prefix will be output to. * * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. * @retval OT_ERROR_NONE Successfully retrieved the OMR prefix. * + * @sa otBorderRoutingGetPdOmrPrefix + * */ otError otBorderRoutingGetOmrPrefix(otInstance *aInstance, otIp6Prefix *aPrefix); +/** + * Gets the DHCPv6 Prefix Delegation (PD) provided off-mesh-routable (OMR) prefix. + * + * Only mPrefix, mValidLifetime and mPreferredLifetime fields are used in the returned prefix info. + * + * `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE` must be enabled. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[out] aPrefixInfo A pointer to where the prefix info will be output to. + * + * @retval OT_ERROR_NONE Successfully retrieved the OMR prefix. + * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. + * @retval OT_ERROR_NOT_FOUND There are no valid PD prefix on this BR. + * + * @sa otBorderRoutingGetOmrPrefix + * @sa otPlatBorderRoutingProcessIcmp6Ra + * + */ +otError otBorderRoutingGetPdOmrPrefix(otInstance *aInstance, otBorderRoutingPrefixTableEntry *aPrefixInfo); + /** * Gets the currently favored Off-Mesh-Routable (OMR) Prefix. * @@ -212,20 +311,34 @@ otError otBorderRoutingGetOmrPrefix(otInstance *aInstance, otIp6Prefix *aPrefix) otError otBorderRoutingGetFavoredOmrPrefix(otInstance *aInstance, otIp6Prefix *aPrefix, otRoutePreference *aPreference); /** - * Gets the On-Link Prefix for the adjacent infrastructure link, for example `fd41:2650:a6f5:0::/64`. + * Gets the local On-Link Prefix for the adjacent infrastructure link. * - * An On-Link Prefix is a 64-bit prefix that's advertised on the infrastructure link if there isn't already a usable - * on-link prefix being advertised on the link. + * The local On-Link Prefix is a 64-bit prefix that's advertised on the infrastructure link if there isn't already a + * usable on-link prefix being advertised on the link. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[out] aPrefix A pointer to where the prefix will be output to. * * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. - * @retval OT_ERROR_NONE Successfully retrieved the on-link prefix. + * @retval OT_ERROR_NONE Successfully retrieved the local on-link prefix. * */ otError otBorderRoutingGetOnLinkPrefix(otInstance *aInstance, otIp6Prefix *aPrefix); +/** + * Gets the currently favored On-Link Prefix. + * + * The favored prefix is either a discovered on-link prefix on the infrastructure link or the local on-link prefix. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[out] aPrefix A pointer to where the prefix will be output to. + * + * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. + * @retval OT_ERROR_NONE Successfully retrieved the favored on-link prefix. + * + */ +otError otBorderRoutingGetFavoredOnLinkPrefix(otInstance *aInstance, otIp6Prefix *aPrefix); + /** * Gets the local NAT64 Prefix of the Border Router. * @@ -260,7 +373,7 @@ otError otBorderRoutingGetFavoredNat64Prefix(otInstance *aInstance, otRoutePreference *aPreference); /** - * This function initializes an `otBorderRoutingPrefixTableIterator`. + * Initializes an `otBorderRoutingPrefixTableIterator`. * * An iterator MUST be initialized before it is used. * @@ -276,7 +389,7 @@ otError otBorderRoutingGetFavoredNat64Prefix(otInstance *aInstance, void otBorderRoutingPrefixTableInitIterator(otInstance *aInstance, otBorderRoutingPrefixTableIterator *aIterator); /** - * This function iterates over the entries in the Border Router's discovered prefix table. + * Iterates over the entries in the Border Router's discovered prefix table. * * @param[in] aInstance The OpenThread instance. * @param[in,out] aIterator A pointer to the iterator. @@ -290,6 +403,17 @@ otError otBorderRoutingGetNextPrefixTableEntry(otInstance otBorderRoutingPrefixTableIterator *aIterator, otBorderRoutingPrefixTableEntry *aEntry); +/** + * Enables / Disables DHCPv6 Prefix Delegation. + * + * `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE` must be enabled. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aEnabled Whether to accept platform generated RA messages. + * + */ +void otBorderRoutingDhcp6PdSetEnabled(otInstance *aInstance, bool aEnabled); + /** * @} * diff --git a/openthread/include/openthread/channel_manager.h b/openthread/include/openthread/channel_manager.h index 7307458068..6afe3a4aa7 100644 --- a/openthread/include/openthread/channel_manager.h +++ b/openthread/include/openthread/channel_manager.h @@ -69,7 +69,7 @@ extern "C" { void otChannelManagerRequestChannelChange(otInstance *aInstance, uint8_t aChannel); /** - * This function gets the channel from the last successful call to `otChannelManagerRequestChannelChange()` + * Gets the channel from the last successful call to `otChannelManagerRequestChannelChange()` * * @returns The last requested channel or zero if there has been no channel change request yet. * @@ -77,7 +77,7 @@ void otChannelManagerRequestChannelChange(otInstance *aInstance, uint8_t aChanne uint8_t otChannelManagerGetRequestedChannel(otInstance *aInstance); /** - * This function gets the delay (in seconds) used by Channel Manager for a channel change. + * Gets the delay (in seconds) used by Channel Manager for a channel change. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -102,7 +102,7 @@ uint16_t otChannelManagerGetDelay(otInstance *aInstance); otError otChannelManagerSetDelay(otInstance *aInstance, uint16_t aDelay); /** - * This function requests that `ChannelManager` checks and selects a new channel and starts a channel change. + * Requests that `ChannelManager` checks and selects a new channel and starts a channel change. * * Unlike the `otChannelManagerRequestChannelChange()` where the channel must be given as a parameter, this function * asks the `ChannelManager` to select a channel by itself (based on collected channel quality info). @@ -144,7 +144,7 @@ otError otChannelManagerRequestChannelSelect(otInstance *aInstance, bool aSkipQu void otChannelManagerSetAutoChannelSelectionEnabled(otInstance *aInstance, bool aEnabled); /** - * This function indicates whether the auto-channel-selection functionality is enabled or not. + * Indicates whether the auto-channel-selection functionality is enabled or not. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -166,7 +166,7 @@ bool otChannelManagerGetAutoChannelSelectionEnabled(otInstance *aInstance); otError otChannelManagerSetAutoChannelSelectionInterval(otInstance *aInstance, uint32_t aInterval); /** - * This function gets the period interval (in seconds) used by auto-channel-selection functionality. + * Gets the period interval (in seconds) used by auto-channel-selection functionality. * * @param[in] aInstance A pointer to an OpenThread instance. * diff --git a/openthread/include/openthread/channel_monitor.h b/openthread/include/openthread/channel_monitor.h index 12fa92af16..d69033ad15 100644 --- a/openthread/include/openthread/channel_monitor.h +++ b/openthread/include/openthread/channel_monitor.h @@ -82,7 +82,7 @@ extern "C" { otError otChannelMonitorSetEnabled(otInstance *aInstance, bool aEnabled); /** - * This function indicates whether the Channel Monitoring operation is enabled and running. + * Indicates whether the Channel Monitoring operation is enabled and running. * * @param[in] aInstance A pointer to an OpenThread instance. * diff --git a/openthread/include/openthread/child_supervision.h b/openthread/include/openthread/child_supervision.h index 3d47ba1d68..dbfd859deb 100644 --- a/openthread/include/openthread/child_supervision.h +++ b/openthread/include/openthread/child_supervision.h @@ -29,7 +29,7 @@ /** * @file * @brief - * This file includes the OpenThread API for child supervision feature + * This file includes the OpenThread API for child supervision feature. */ #ifndef OPENTHREAD_CHILD_SUPERVISION_H_ @@ -45,40 +45,37 @@ extern "C" { * @addtogroup api-child-supervision * * @brief - * This module includes functions for child supervision feature. - * - * The functions in this module are available when child supervision feature - * (`OPENTHREAD_CONFIG_CHILD_SUPERVISION_ENABLE`) is enabled. + * This module includes functions for Child Supervision feature. * * @{ * */ /** - * Gets the child supervision interval (in seconds). + * Gets the Child Supervision interval (in seconds) on a child. * - * Child supervision feature provides a mechanism for parent to ensure that a message is sent to each sleepy child - * within the supervision interval. If there is no transmission to the child within the supervision interval, - * OpenThread enqueues and sends a supervision message (a data message with empty payload) to the child. + * Child Supervision feature provides a mechanism for parent to ensure that a message is sent to each sleepy child + * within the supervision interval. If there is no transmission to the child within the supervision interval, OpenThread + * enqueues and sends a Child Supervision Message to the child. * * @param[in] aInstance A pointer to an OpenThread instance. * - * @returns The child supervision interval. Zero indicates that child supervision is disabled. + * @returns The child supervision interval. Zero indicates that supervision is disabled. * */ uint16_t otChildSupervisionGetInterval(otInstance *aInstance); /** - * Sets the child supervision interval (in seconds). + * Sets the child supervision interval (in seconds) on the child. * * @param[in] aInstance A pointer to an OpenThread instance. - * @param[in] aInterval The supervision interval (in seconds). Zero to disable supervision on parent. + * @param[in] aInterval The supervision interval (in seconds). Zero to disable supervision. * */ void otChildSupervisionSetInterval(otInstance *aInstance, uint16_t aInterval); /** - * Gets the supervision check timeout interval (in seconds). + * Gets the supervision check timeout interval (in seconds) on the child. * * If the device is a sleepy child and it does not hear from its parent within the specified check timeout, it initiates * the re-attach process (MLE Child Update Request/Response exchange with its parent). @@ -91,7 +88,7 @@ void otChildSupervisionSetInterval(otInstance *aInstance, uint16_t aInterval); uint16_t otChildSupervisionGetCheckTimeout(otInstance *aInstance); /** - * Sets the supervision check timeout interval (in seconds). + * Sets the supervision check timeout interval (in seconds) on the child. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aTimeout The check timeout (in seconds). Zero to disable supervision check on the child. @@ -99,6 +96,21 @@ uint16_t otChildSupervisionGetCheckTimeout(otInstance *aInstance); */ void otChildSupervisionSetCheckTimeout(otInstance *aInstance, uint16_t aTimeout); +/** + * Get the value of supervision check timeout failure counter. + * + * The counter tracks the number of supervision check failures on the child. It is incremented when the child does + * not hear from its parent within the specified check timeout interval. + * + */ +uint16_t otChildSupervisionGetCheckFailureCounter(otInstance *aInstance); + +/** + * Reset the supervision check timeout failure counter to zero. + * + */ +void otChildSupervisionResetCheckFailureCounter(otInstance *aInstance); + /** * @} * diff --git a/openthread/include/openthread/cli.h b/openthread/include/openthread/cli.h index 4a80c9e145..07bd92a373 100644 --- a/openthread/include/openthread/cli.h +++ b/openthread/include/openthread/cli.h @@ -46,7 +46,7 @@ extern "C" { #endif /** - * This structure represents a CLI command. + * Represents a CLI command. * */ typedef struct otCliCommand @@ -68,7 +68,7 @@ typedef struct otCliCommand */ /** - * This function pointer is called to notify about Console output. + * Pointer is called to notify about Console output. * * @param[out] aContext A user context pointer. * @param[in] aFormat The format string. @@ -90,7 +90,7 @@ typedef int (*otCliOutputCallback)(void *aContext, const char *aFormat, va_list void otCliInit(otInstance *aInstance, otCliOutputCallback aCallback, void *aContext); /** - * This method is called to feed in a console input line. + * Is called to feed in a console input line. * * @param[in] aBuf A pointer to a null-terminated string. * @@ -104,8 +104,10 @@ void otCliInputLine(char *aBuf); * @param[in] aLength @p aUserCommands length. * @param[in] aContext @p The context passed to the handler. * + * @retval OT_ERROR_NONE Successfully updated command table with commands from @p aUserCommands. + * @retval OT_ERROR_FAILED Maximum number of command entries have already been set. */ -void otCliSetUserCommands(const otCliCommand *aUserCommands, uint8_t aLength, void *aContext); +otError otCliSetUserCommands(const otCliCommand *aUserCommands, uint8_t aLength, void *aContext); /** * Write a number of bytes to the CLI console as a hex string. @@ -146,6 +148,15 @@ void otCliAppendResult(otError aError); */ void otCliPlatLogv(otLogLevel aLogLevel, otLogRegion aLogRegion, const char *aFormat, va_list aArgs); +/** + * Callback to allow vendor specific commands to be added to the user command table. + * + * Available when `OPENTHREAD_CONFIG_CLI_VENDOR_COMMANDS_ENABLE` is enabled and + * `OPENTHREAD_CONFIG_CLI_MAX_USER_CMD_ENTRIES` is greater than 1. + * + */ +extern void otCliVendorSetUserCommands(void); + /** * @} * diff --git a/openthread/include/openthread/coap.h b/openthread/include/openthread/coap.h index 30faca6f8a..4b7149adbe 100644 --- a/openthread/include/openthread/coap.h +++ b/openthread/include/openthread/coap.h @@ -151,7 +151,7 @@ typedef enum otCoapOptionType } otCoapOptionType; /** - * This structure represents a CoAP option. + * Represents a CoAP option. * */ typedef struct otCoapOption @@ -161,7 +161,7 @@ typedef struct otCoapOption } otCoapOption; /** - * This structure acts as an iterator for CoAP options + * Acts as an iterator for CoAP options * */ typedef struct otCoapOptionIterator @@ -329,7 +329,7 @@ typedef enum otCoapBlockSzx } otCoapBlockSzx; /** - * This function pointer is called when a CoAP response is received or on the request timeout. + * Pointer is called when a CoAP response is received or on the request timeout. * * @param[in] aContext A pointer to application-specific context. * @param[in] aMessage A pointer to the message buffer containing the response. NULL if no response was received. @@ -347,7 +347,7 @@ typedef void (*otCoapResponseHandler)(void *aContext, otError aResult); /** - * This function pointer is called when a CoAP request with a given Uri-Path is received. + * Pointer is called when a CoAP request with a given Uri-Path is received. * * @param[in] aContext A pointer to arbitrary context information. * @param[in] aMessage A pointer to the message. @@ -357,9 +357,9 @@ typedef void (*otCoapResponseHandler)(void *aContext, typedef void (*otCoapRequestHandler)(void *aContext, otMessage *aMessage, const otMessageInfo *aMessageInfo); /** - * This function pointer is called when a CoAP message with an block-wise transfer option is received. + * Pointer is called when a CoAP message with an block-wise transfer option is received. * - * This function is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration + * Is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration * is enabled. * * @param[in] aContext A pointer to application-specific context. @@ -383,9 +383,9 @@ typedef otError (*otCoapBlockwiseReceiveHook)(void *aContext, uint32_t aTotalLength); /** - * This function pointer is called before the next block in a block-wise transfer is sent. + * Pointer is called before the next block in a block-wise transfer is sent. * - * This function is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration + * Is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration * is enabled. * * @param[in] aContext A pointer to application-specific context. @@ -409,7 +409,7 @@ typedef otError (*otCoapBlockwiseTransmitHook)(void *aContext, bool *aMore); /** - * This structure represents a CoAP resource. + * Represents a CoAP resource. * */ typedef struct otCoapResource @@ -421,7 +421,7 @@ typedef struct otCoapResource } otCoapResource; /** - * This structure represents a CoAP resource with block-wise transfer. + * Represents a CoAP resource with block-wise transfer. * */ typedef struct otCoapBlockwiseResource @@ -445,7 +445,7 @@ typedef struct otCoapBlockwiseResource } otCoapBlockwiseResource; /** - * This structure represents the CoAP transmission parameters. + * Represents the CoAP transmission parameters. * * @note mAckTimeout * ((2 ** (mMaxRetransmit + 1)) - 1) * (mAckRandomFactorNumerator / mAckRandomFactorDenominator) * must not exceed what can be represented by a uint32_t (0xffffffff). This limitation allows OpenThread to @@ -483,7 +483,7 @@ typedef struct otCoapTxParameters } otCoapTxParameters; /** - * This function initializes the CoAP header. + * Initializes the CoAP header. * * @param[in,out] aMessage A pointer to the CoAP message to initialize. * @param[in] aType CoAP message type. @@ -493,7 +493,7 @@ typedef struct otCoapTxParameters void otCoapMessageInit(otMessage *aMessage, otCoapType aType, otCoapCode aCode); /** - * This function initializes a response message. + * Initializes a response message. * * @note Both message ID and token are set according to @p aRequest. * @@ -509,7 +509,7 @@ void otCoapMessageInit(otMessage *aMessage, otCoapType aType, otCoapCode aCode); otError otCoapMessageInitResponse(otMessage *aResponse, const otMessage *aRequest, otCoapType aType, otCoapCode aCode); /** - * This function sets the Token value and length in a header. + * Sets the Token value and length in a header. * * @param[in,out] aMessage A pointer to the CoAP message. * @param[in] aToken A pointer to the Token value. @@ -522,7 +522,7 @@ otError otCoapMessageInitResponse(otMessage *aResponse, const otMessage *aReques otError otCoapMessageSetToken(otMessage *aMessage, const uint8_t *aToken, uint8_t aTokenLength); /** - * This function sets the Token length and randomizes its value. + * Sets the Token length and randomizes its value. * * @param[in,out] aMessage A pointer to the CoAP message. * @param[in] aTokenLength The Length of a Token to set. @@ -531,7 +531,7 @@ otError otCoapMessageSetToken(otMessage *aMessage, const uint8_t *aToken, uint8_ void otCoapMessageGenerateToken(otMessage *aMessage, uint8_t aTokenLength); /** - * This function appends the Content Format CoAP option as specified in + * Appends the Content Format CoAP option as specified in * https://tools.ietf.org/html/rfc7252#page-92. This *must* be called before * setting otCoapMessageSetPayloadMarker if a payload is to be included in the * message. @@ -552,7 +552,7 @@ void otCoapMessageGenerateToken(otMessage *aMessage, uint8_t aTokenLength); otError otCoapMessageAppendContentFormatOption(otMessage *aMessage, otCoapOptionContentFormat aContentFormat); /** - * This function appends a CoAP option in a header. + * Appends a CoAP option in a header. * * @param[in,out] aMessage A pointer to the CoAP message. * @param[in] aNumber The CoAP Option number. @@ -567,7 +567,7 @@ otError otCoapMessageAppendContentFormatOption(otMessage *aMessage, otCoapOption otError otCoapMessageAppendOption(otMessage *aMessage, uint16_t aNumber, uint16_t aLength, const void *aValue); /** - * This function appends an unsigned integer CoAP option as specified in + * Appends an unsigned integer CoAP option as specified in * https://tools.ietf.org/html/rfc7252#section-3.2 * * @param[in,out] aMessage A pointer to the CoAP message. @@ -583,7 +583,7 @@ otError otCoapMessageAppendOption(otMessage *aMessage, uint16_t aNumber, uint16_ otError otCoapMessageAppendUintOption(otMessage *aMessage, uint16_t aNumber, uint32_t aValue); /** - * This function appends an Observe option. + * Appends an Observe option. * * @param[in,out] aMessage A pointer to the CoAP message. * @param[in] aObserve Observe field value. @@ -596,7 +596,7 @@ otError otCoapMessageAppendUintOption(otMessage *aMessage, uint16_t aNumber, uin otError otCoapMessageAppendObserveOption(otMessage *aMessage, uint32_t aObserve); /** - * This function appends a Uri-Path option. + * Appends a Uri-Path option. * * @param[in,out] aMessage A pointer to the CoAP message. * @param[in] aUriPath A pointer to a NULL-terminated string. @@ -609,7 +609,7 @@ otError otCoapMessageAppendObserveOption(otMessage *aMessage, uint32_t aObserve) otError otCoapMessageAppendUriPathOptions(otMessage *aMessage, const char *aUriPath); /** - * This function converts a CoAP Block option SZX field to the actual block size + * Converts a CoAP Block option SZX field to the actual block size * * @param[in] aSize Block size exponent. * @@ -619,7 +619,7 @@ otError otCoapMessageAppendUriPathOptions(otMessage *aMessage, const char *aUriP uint16_t otCoapBlockSizeFromExponent(otCoapBlockSzx aSize); /** - * This function appends a Block2 option + * Appends a Block2 option * * @param[in,out] aMessage A pointer to the CoAP message. * @param[in] aNum Current block number. @@ -634,7 +634,7 @@ uint16_t otCoapBlockSizeFromExponent(otCoapBlockSzx aSize); otError otCoapMessageAppendBlock2Option(otMessage *aMessage, uint32_t aNum, bool aMore, otCoapBlockSzx aSize); /** - * This function appends a Block1 option + * Appends a Block1 option * * @param[in,out] aMessage A pointer to the CoAP message. * @param[in] aNum Current block number. @@ -649,7 +649,7 @@ otError otCoapMessageAppendBlock2Option(otMessage *aMessage, uint32_t aNum, bool otError otCoapMessageAppendBlock1Option(otMessage *aMessage, uint32_t aNum, bool aMore, otCoapBlockSzx aSize); /** - * This function appends a Proxy-Uri option. + * Appends a Proxy-Uri option. * * @param[in,out] aMessage A pointer to the CoAP message. * @param[in] aUriPath A pointer to a NULL-terminated string. @@ -662,7 +662,7 @@ otError otCoapMessageAppendBlock1Option(otMessage *aMessage, uint32_t aNum, bool otError otCoapMessageAppendProxyUriOption(otMessage *aMessage, const char *aUriPath); /** - * This function appends a Max-Age option. + * Appends a Max-Age option. * * @param[in,out] aMessage A pointer to the CoAP message. * @param[in] aMaxAge The Max-Age value. @@ -675,7 +675,7 @@ otError otCoapMessageAppendProxyUriOption(otMessage *aMessage, const char *aUriP otError otCoapMessageAppendMaxAgeOption(otMessage *aMessage, uint32_t aMaxAge); /** - * This function appends a single Uri-Query option. + * Appends a single Uri-Query option. * * @param[in,out] aMessage A pointer to the CoAP message. * @param[in] aUriQuery A pointer to NULL-terminated string, which should contain a single key=value pair. @@ -687,7 +687,7 @@ otError otCoapMessageAppendMaxAgeOption(otMessage *aMessage, uint32_t aMaxAge); otError otCoapMessageAppendUriQueryOption(otMessage *aMessage, const char *aUriQuery); /** - * This function adds Payload Marker indicating beginning of the payload to the CoAP header. + * Adds Payload Marker indicating beginning of the payload to the CoAP header. * * @param[in,out] aMessage A pointer to the CoAP message. * @@ -698,7 +698,7 @@ otError otCoapMessageAppendUriQueryOption(otMessage *aMessage, const char *aUriQ otError otCoapMessageSetPayloadMarker(otMessage *aMessage); /** - * This function returns the Type value. + * Returns the Type value. * * @param[in] aMessage A pointer to the CoAP message. * @@ -708,7 +708,7 @@ otError otCoapMessageSetPayloadMarker(otMessage *aMessage); otCoapType otCoapMessageGetType(const otMessage *aMessage); /** - * This function returns the Code value. + * Returns the Code value. * * @param[in] aMessage A pointer to the CoAP message. * @@ -718,7 +718,7 @@ otCoapType otCoapMessageGetType(const otMessage *aMessage); otCoapCode otCoapMessageGetCode(const otMessage *aMessage); /** - * This function sets the Code value. + * Sets the Code value. * * @param[in,out] aMessage A pointer to the CoAP message to initialize. * @param[in] aCode CoAP message code. @@ -727,7 +727,7 @@ otCoapCode otCoapMessageGetCode(const otMessage *aMessage); void otCoapMessageSetCode(otMessage *aMessage, otCoapCode aCode); /** - * This method returns the CoAP Code as human readable string. + * Returns the CoAP Code as human readable string. * * @param[in] aMessage A pointer to the CoAP message. * @@ -737,7 +737,7 @@ void otCoapMessageSetCode(otMessage *aMessage, otCoapCode aCode); const char *otCoapMessageCodeToString(const otMessage *aMessage); /** - * This function returns the Message ID value. + * Returns the Message ID value. * * @param[in] aMessage A pointer to the CoAP message. * @@ -747,7 +747,7 @@ const char *otCoapMessageCodeToString(const otMessage *aMessage); uint16_t otCoapMessageGetMessageId(const otMessage *aMessage); /** - * This function returns the Token length. + * Returns the Token length. * * @param[in] aMessage A pointer to the CoAP message. * @@ -757,7 +757,7 @@ uint16_t otCoapMessageGetMessageId(const otMessage *aMessage); uint8_t otCoapMessageGetTokenLength(const otMessage *aMessage); /** - * This function returns a pointer to the Token value. + * Returns a pointer to the Token value. * * @param[in] aMessage A pointer to the CoAP message. * @@ -767,7 +767,7 @@ uint8_t otCoapMessageGetTokenLength(const otMessage *aMessage); const uint8_t *otCoapMessageGetToken(const otMessage *aMessage); /** - * This function initialises an iterator for the options in the given message. + * Initialises an iterator for the options in the given message. * * @param[in,out] aIterator A pointer to the CoAP message option iterator. * @param[in] aMessage A pointer to the CoAP message. @@ -779,7 +779,7 @@ const uint8_t *otCoapMessageGetToken(const otMessage *aMessage); otError otCoapOptionIteratorInit(otCoapOptionIterator *aIterator, const otMessage *aMessage); /** - * This function returns a pointer to the first option matching the specified option number. + * Returns a pointer to the first option matching the specified option number. * * @param[in] aIterator A pointer to the CoAP message option iterator. * @param[in] aOption The option number sought. @@ -790,7 +790,7 @@ otError otCoapOptionIteratorInit(otCoapOptionIterator *aIterator, const otMessag const otCoapOption *otCoapOptionIteratorGetFirstOptionMatching(otCoapOptionIterator *aIterator, uint16_t aOption); /** - * This function returns a pointer to the first option. + * Returns a pointer to the first option. * * @param[in,out] aIterator A pointer to the CoAP message option iterator. * @@ -800,7 +800,7 @@ const otCoapOption *otCoapOptionIteratorGetFirstOptionMatching(otCoapOptionItera const otCoapOption *otCoapOptionIteratorGetFirstOption(otCoapOptionIterator *aIterator); /** - * This function returns a pointer to the next option matching the specified option number. + * Returns a pointer to the next option matching the specified option number. * * @param[in] aIterator A pointer to the CoAP message option iterator. * @param[in] aOption The option number sought. @@ -811,7 +811,7 @@ const otCoapOption *otCoapOptionIteratorGetFirstOption(otCoapOptionIterator *aIt const otCoapOption *otCoapOptionIteratorGetNextOptionMatching(otCoapOptionIterator *aIterator, uint16_t aOption); /** - * This function returns a pointer to the next option. + * Returns a pointer to the next option. * * @param[in,out] aIterator A pointer to the CoAP message option iterator. * @@ -821,7 +821,7 @@ const otCoapOption *otCoapOptionIteratorGetNextOptionMatching(otCoapOptionIterat const otCoapOption *otCoapOptionIteratorGetNextOption(otCoapOptionIterator *aIterator); /** - * This function fills current option value into @p aValue assuming the current value is an unsigned integer encoded + * Fills current option value into @p aValue assuming the current value is an unsigned integer encoded * according to https://tools.ietf.org/html/rfc7252#section-3.2 * * @param[in,out] aIterator A pointer to the CoAP message option iterator. @@ -836,7 +836,7 @@ const otCoapOption *otCoapOptionIteratorGetNextOption(otCoapOptionIterator *aIte otError otCoapOptionIteratorGetOptionUintValue(otCoapOptionIterator *aIterator, uint64_t *aValue); /** - * This function fills current option value into @p aValue. + * Fills current option value into @p aValue. * * @param[in,out] aIterator A pointer to the CoAP message option iterator. * @param[out] aValue A pointer to a buffer to receive the option value. @@ -848,7 +848,7 @@ otError otCoapOptionIteratorGetOptionUintValue(otCoapOptionIterator *aIterator, otError otCoapOptionIteratorGetOptionValue(otCoapOptionIterator *aIterator, void *aValue); /** - * This function creates a new CoAP message. + * Creates a new CoAP message. * * @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. @@ -862,7 +862,7 @@ otError otCoapOptionIteratorGetOptionValue(otCoapOptionIterator *aIterator, void otMessage *otCoapNewMessage(otInstance *aInstance, const otMessageSettings *aSettings); /** - * This function sends a CoAP request with custom transmission parameters. + * Sends a CoAP request with custom transmission parameters. * * If a response for a request is expected, respective function and context information should be provided. * If no response is expected, these arguments should be NULL pointers. @@ -878,9 +878,9 @@ otMessage *otCoapNewMessage(otInstance *aInstance, const otMessageSettings *aSet * 2. mAckRandomFactorNumerator / mAckRandomFactorDenominator must not be below 1.0. * 3. The calculated exchange life time must not overflow uint32_t. * - * @retval OT_ERROR_INVALID_ARGS @p aTxParameters is invalid. * @retval OT_ERROR_NONE Successfully sent CoAP message. * @retval OT_ERROR_NO_BUFS Failed to allocate retransmission data. + * @retval OT_ERROR_INVALID_ARGS Invalid arguments are given. * */ otError otCoapSendRequestWithParameters(otInstance *aInstance, @@ -891,9 +891,9 @@ otError otCoapSendRequestWithParameters(otInstance *aInstance, const otCoapTxParameters *aTxParameters); /** - * This function sends a CoAP request block-wise with custom transmission parameters. + * Sends a CoAP request block-wise with custom transmission parameters. * - * This function is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration + * Is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration * is enabled. * * If a response for a request is expected, respective function and context information should be provided. @@ -909,8 +909,9 @@ otError otCoapSendRequestWithParameters(otInstance *aInstance, * @param[in] aTransmitHook A pointer to a hook function for outgoing block-wise transfer. * @param[in] aReceiveHook A pointer to a hook function for incoming block-wise transfer. * - * @retval OT_ERROR_NONE Successfully sent CoAP message. - * @retval OT_ERROR_NO_BUFS Failed to allocate retransmission data. + * @retval OT_ERROR_NONE Successfully sent CoAP message. + * @retval OT_ERROR_NO_BUFS Failed to allocate retransmission data. + * @retval OT_ERROR_INVALID_ARGS Invalid arguments are given. * */ otError otCoapSendRequestBlockWiseWithParameters(otInstance *aInstance, @@ -923,9 +924,9 @@ otError otCoapSendRequestBlockWiseWithParameters(otInstance *aIn otCoapBlockwiseReceiveHook aReceiveHook); /** - * This function sends a CoAP request block-wise. + * Sends a CoAP request block-wise. * - * This function is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration + * Is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration * is enabled. * * If a response for a request is expected, respective function and context information should be provided. @@ -958,7 +959,7 @@ static inline otError otCoapSendRequestBlockWise(otInstance *aIn } /** - * This function sends a CoAP request. + * Sends a CoAP request. * * If a response for a request is expected, respective function and context information should be provided. * If no response is expected, these arguments should be NULL pointers. @@ -984,7 +985,7 @@ static inline otError otCoapSendRequest(otInstance *aInstance, } /** - * This function starts the CoAP server. + * Starts the CoAP server. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aPort The local UDP port to bind to. @@ -996,7 +997,7 @@ static inline otError otCoapSendRequest(otInstance *aInstance, otError otCoapStart(otInstance *aInstance, uint16_t aPort); /** - * This function stops the CoAP server. + * Stops the CoAP server. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -1006,7 +1007,7 @@ otError otCoapStart(otInstance *aInstance, uint16_t aPort); otError otCoapStop(otInstance *aInstance); /** - * This function adds a resource to the CoAP server. + * Adds a resource to the CoAP server. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aResource A pointer to the resource. @@ -1015,7 +1016,7 @@ otError otCoapStop(otInstance *aInstance); void otCoapAddResource(otInstance *aInstance, otCoapResource *aResource); /** - * This function removes a resource from the CoAP server. + * Removes a resource from the CoAP server. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aResource A pointer to the resource. @@ -1024,7 +1025,7 @@ void otCoapAddResource(otInstance *aInstance, otCoapResource *aResource); void otCoapRemoveResource(otInstance *aInstance, otCoapResource *aResource); /** - * This function adds a block-wise resource to the CoAP server. + * Adds a block-wise resource to the CoAP server. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aResource A pointer to the resource. @@ -1033,7 +1034,7 @@ void otCoapRemoveResource(otInstance *aInstance, otCoapResource *aResource); void otCoapAddBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource); /** - * This function removes a block-wise resource from the CoAP server. + * Removes a block-wise resource from the CoAP server. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aResource A pointer to the resource. @@ -1042,7 +1043,7 @@ void otCoapAddBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource * void otCoapRemoveBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource); /** - * This function sets the default handler for unhandled CoAP requests. + * Sets the default handler for unhandled CoAP requests. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aHandler A function pointer that shall be called when an unhandled request arrives. @@ -1052,15 +1053,16 @@ void otCoapRemoveBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResourc void otCoapSetDefaultHandler(otInstance *aInstance, otCoapRequestHandler aHandler, void *aContext); /** - * This function sends a CoAP response from the server with custom transmission parameters. + * Sends a CoAP response from the server with custom transmission parameters. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aMessage A pointer to the CoAP response to send. * @param[in] aMessageInfo A pointer to the message info associated with @p aMessage. * @param[in] aTxParameters A pointer to transmission parameters for this response. Use NULL for defaults. * - * @retval OT_ERROR_NONE Successfully enqueued the CoAP response message. - * @retval OT_ERROR_NO_BUFS Insufficient buffers available to send the CoAP response. + * @retval OT_ERROR_NONE Successfully enqueued the CoAP response message. + * @retval OT_ERROR_NO_BUFS Insufficient buffers available to send the CoAP response. + * @retval OT_ERROR_INVALID_ARGS Invalid arguments are given. * */ otError otCoapSendResponseWithParameters(otInstance *aInstance, @@ -1069,9 +1071,9 @@ otError otCoapSendResponseWithParameters(otInstance *aInstance, const otCoapTxParameters *aTxParameters); /** - * This function sends a CoAP response block-wise from the server with custom transmission parameters. + * Sends a CoAP response block-wise from the server with custom transmission parameters. * - * This function is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration + * Is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration * is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. @@ -1081,8 +1083,9 @@ otError otCoapSendResponseWithParameters(otInstance *aInstance, * @param[in] aContext A pointer to arbitrary context information. May be NULL if not used. * @param[in] aTransmitHook A pointer to a hook function for outgoing block-wise transfer. * - * @retval OT_ERROR_NONE Successfully enqueued the CoAP response message. - * @retval OT_ERROR_NO_BUFS Insufficient buffers available to send the CoAP response. + * @retval OT_ERROR_NONE Successfully enqueued the CoAP response message. + * @retval OT_ERROR_NO_BUFS Insufficient buffers available to send the CoAP response. + * @retval OT_ERROR_INVALID_ARGS Invalid arguments are given. * */ otError otCoapSendResponseBlockWiseWithParameters(otInstance *aInstance, @@ -1093,9 +1096,9 @@ otError otCoapSendResponseBlockWiseWithParameters(otInstance *aI otCoapBlockwiseTransmitHook aTransmitHook); /** - * This function sends a CoAP response block-wise from the server. + * Sends a CoAP response block-wise from the server. * - * This function is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration + * Is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration * is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. @@ -1119,7 +1122,7 @@ static inline otError otCoapSendResponseBlockWise(otInstance *aI } /** - * This function sends a CoAP response from the server. + * Sends a CoAP response from the server. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aMessage A pointer to the CoAP response to send. diff --git a/openthread/include/openthread/coap_secure.h b/openthread/include/openthread/coap_secure.h index 6f424096a5..6a96ea3d75 100644 --- a/openthread/include/openthread/coap_secure.h +++ b/openthread/include/openthread/coap_secure.h @@ -68,7 +68,7 @@ extern "C" { #define OT_DEFAULT_COAP_SECURE_PORT 5684 ///< Default CoAP Secure port, as specified in RFC 7252 /** - * This function pointer is called when the DTLS connection state changes. + * Pointer is called when the DTLS connection state changes. * * @param[in] aConnected true, if a connection was established, false otherwise. * @param[in] aContext A pointer to arbitrary context information. @@ -77,7 +77,7 @@ extern "C" { typedef void (*otHandleCoapSecureClientConnect)(bool aConnected, void *aContext); /** - * This function starts the CoAP Secure service. + * Starts the CoAP Secure service. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aPort The local UDP port to bind to. @@ -88,7 +88,7 @@ typedef void (*otHandleCoapSecureClientConnect)(bool aConnected, void *aContext) otError otCoapSecureStart(otInstance *aInstance, uint16_t aPort); /** - * This function stops the CoAP Secure server. + * Stops the CoAP Secure server. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -96,7 +96,7 @@ otError otCoapSecureStart(otInstance *aInstance, uint16_t aPort); void otCoapSecureStop(otInstance *aInstance); /** - * This method sets the Pre-Shared Key (PSK) and cipher suite + * Sets the Pre-Shared Key (PSK) and cipher suite * DTLS_PSK_WITH_AES_128_CCM_8. * * @note This function requires the build-time feature `MBEDTLS_KEY_EXCHANGE_PSK_ENABLED` to be enabled. @@ -115,7 +115,7 @@ void otCoapSecureSetPsk(otInstance *aInstance, uint16_t aPskIdLength); /** - * This method returns the peer x509 certificate base64 encoded. + * Returns the peer x509 certificate base64 encoded. * * @note This function requires the build-time features `MBEDTLS_BASE64_C` and * `MBEDTLS_SSL_KEEP_PEER_CERTIFICATE` to be enabled. @@ -136,7 +136,7 @@ otError otCoapSecureGetPeerCertificateBase64(otInstance *aInstance, size_t aCertBufferSize); /** - * This method sets the authentication mode for the coap secure connection. + * Sets the authentication mode for the coap secure connection. * * Disable or enable the verification of peer certificate. * Must be called before start. @@ -148,7 +148,7 @@ otError otCoapSecureGetPeerCertificateBase64(otInstance *aInstance, void otCoapSecureSetSslAuthMode(otInstance *aInstance, bool aVerifyPeerCertificate); /** - * This method sets the local device's X509 certificate with corresponding private key for + * Sets the local device's X509 certificate with corresponding private key for * DTLS session with DTLS_ECDHE_ECDSA_WITH_AES_128_CCM_8. * * @note This function requires `MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED=1`. @@ -167,7 +167,7 @@ void otCoapSecureSetCertificate(otInstance *aInstance, uint32_t aPrivateKeyLength); /** - * This method sets the trusted top level CAs. It is needed for validating the + * Sets the trusted top level CAs. It is needed for validating the * certificate of the peer. * * DTLS mode "ECDHE ECDSA with AES 128 CCM 8" for Application CoAPS. @@ -184,7 +184,7 @@ void otCoapSecureSetCaCertificateChain(otInstance *aInstance, uint32_t aX509CaCertChainLength); /** - * This method initializes DTLS session with a peer. + * Initializes DTLS session with a peer. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aSockAddr A pointer to the remote socket address. @@ -201,7 +201,7 @@ otError otCoapSecureConnect(otInstance *aInstance, void *aContext); /** - * This method stops the DTLS connection. + * Stops the DTLS connection. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -209,7 +209,7 @@ otError otCoapSecureConnect(otInstance *aInstance, void otCoapSecureDisconnect(otInstance *aInstance); /** - * This method indicates whether or not the DTLS session is connected. + * Indicates whether or not the DTLS session is connected. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -220,7 +220,7 @@ void otCoapSecureDisconnect(otInstance *aInstance); bool otCoapSecureIsConnected(otInstance *aInstance); /** - * This method indicates whether or not the DTLS session is active. + * Indicates whether or not the DTLS session is active. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -231,9 +231,9 @@ bool otCoapSecureIsConnected(otInstance *aInstance); bool otCoapSecureIsConnectionActive(otInstance *aInstance); /** - * This method sends a CoAP request block-wise over secure DTLS connection. + * Sends a CoAP request block-wise over secure DTLS connection. * - * This function is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration + * Is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration * is enabled. * * If a response for a request is expected, respective function and context information should be provided. @@ -260,7 +260,7 @@ otError otCoapSecureSendRequestBlockWise(otInstance *aInstance, otCoapBlockwiseReceiveHook aReceiveHook); /** - * This method sends a CoAP request over secure DTLS connection. + * Sends a CoAP request over secure DTLS connection. * * If a response for a request is expected, respective function and context information should be provided. * If no response is expected, these arguments should be NULL pointers. @@ -282,7 +282,7 @@ otError otCoapSecureSendRequest(otInstance *aInstance, void *aContext); /** - * This function adds a resource to the CoAP Secure server. + * Adds a resource to the CoAP Secure server. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aResource A pointer to the resource. @@ -291,7 +291,7 @@ otError otCoapSecureSendRequest(otInstance *aInstance, void otCoapSecureAddResource(otInstance *aInstance, otCoapResource *aResource); /** - * This function removes a resource from the CoAP Secure server. + * Removes a resource from the CoAP Secure server. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aResource A pointer to the resource. @@ -300,7 +300,7 @@ void otCoapSecureAddResource(otInstance *aInstance, otCoapResource *aResource); void otCoapSecureRemoveResource(otInstance *aInstance, otCoapResource *aResource); /** - * This function adds a block-wise resource to the CoAP Secure server. + * Adds a block-wise resource to the CoAP Secure server. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aResource A pointer to the resource. @@ -309,7 +309,7 @@ void otCoapSecureRemoveResource(otInstance *aInstance, otCoapResource *aResource void otCoapSecureAddBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource); /** - * This function removes a block-wise resource from the CoAP Secure server. + * Removes a block-wise resource from the CoAP Secure server. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aResource A pointer to the resource. @@ -318,7 +318,7 @@ void otCoapSecureAddBlockWiseResource(otInstance *aInstance, otCoapBlockwiseReso void otCoapSecureRemoveBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource); /** - * This function sets the default handler for unhandled CoAP Secure requests. + * Sets the default handler for unhandled CoAP Secure requests. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aHandler A function pointer that shall be called when an unhandled request arrives. @@ -328,7 +328,7 @@ void otCoapSecureRemoveBlockWiseResource(otInstance *aInstance, otCoapBlockwiseR void otCoapSecureSetDefaultHandler(otInstance *aInstance, otCoapRequestHandler aHandler, void *aContext); /** - * This method sets the connected callback to indicate, when + * Sets the connected callback to indicate, when * a Client connect to the CoAP Secure server. * * @param[in] aInstance A pointer to an OpenThread instance. @@ -341,9 +341,9 @@ void otCoapSecureSetClientConnectedCallback(otInstance *aIns void *aContext); /** - * This function sends a CoAP response block-wise from the CoAP Secure server. + * Sends a CoAP response block-wise from the CoAP Secure server. * - * This function is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration + * Is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration * is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. @@ -363,7 +363,7 @@ otError otCoapSecureSendResponseBlockWise(otInstance *aInstance, otCoapBlockwiseTransmitHook aTransmitHook); /** - * This function sends a CoAP response from the CoAP Secure server. + * Sends a CoAP response from the CoAP Secure server. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aMessage A pointer to the CoAP response to send. diff --git a/openthread/include/openthread/commissioner.h b/openthread/include/openthread/commissioner.h index 9bf09b814b..9f714b389d 100644 --- a/openthread/include/openthread/commissioner.h +++ b/openthread/include/openthread/commissioner.h @@ -56,7 +56,7 @@ extern "C" { */ /** - * This enumeration defines the Commissioner State. + * Defines the Commissioner State. * */ typedef enum otCommissionerState @@ -67,7 +67,7 @@ typedef enum otCommissionerState } otCommissionerState; /** - * This enumeration defines a Joiner Event on the Commissioner. + * Defines a Joiner Event on the Commissioner. * */ typedef enum otCommissionerJoinerEvent @@ -87,7 +87,7 @@ typedef enum otCommissionerJoinerEvent #define OT_STEERING_DATA_MAX_LENGTH 16 ///< Max steering data length (bytes) /** - * This structure represents the steering data. + * Represents the steering data. * */ typedef struct otSteeringData @@ -97,7 +97,7 @@ typedef struct otSteeringData } otSteeringData; /** - * This structure represents a Commissioning Dataset. + * Represents a Commissioning Dataset. * */ typedef struct otCommissioningDataset @@ -116,7 +116,7 @@ typedef struct otCommissioningDataset #define OT_JOINER_MAX_PSKD_LENGTH 32 ///< Maximum string length of a Joiner PSKd (does not include null char). /** - * This structure represents a Joiner PSKd. + * Represents a Joiner PSKd. * */ typedef struct otJoinerPskd @@ -125,7 +125,7 @@ typedef struct otJoinerPskd } otJoinerPskd; /** - * This enumeration defines a Joiner Info Type. + * Defines a Joiner Info Type. * */ typedef enum otJoinerInfoType @@ -136,7 +136,7 @@ typedef enum otJoinerInfoType } otJoinerInfoType; /** - * This structure represents a Joiner Info. + * Represents a Joiner Info. * */ typedef struct otJoinerInfo @@ -152,7 +152,7 @@ typedef struct otJoinerInfo } otJoinerInfo; /** - * This function pointer is called whenever the commissioner state changes. + * Pointer is called whenever the commissioner state changes. * * @param[in] aState The Commissioner state. * @param[in] aContext A pointer to application-specific context. @@ -161,7 +161,7 @@ typedef struct otJoinerInfo typedef void (*otCommissionerStateCallback)(otCommissionerState aState, void *aContext); /** - * This function pointer is called whenever the joiner state changes. + * Pointer is called whenever the joiner state changes. * * @param[in] aEvent The joiner event type. * @param[in] aJoinerInfo A pointer to the Joiner Info. @@ -175,7 +175,7 @@ typedef void (*otCommissionerJoinerCallback)(otCommissionerJoinerEvent aEvent, void *aContext); /** - * This function enables the Thread Commissioner role. + * Enables the Thread Commissioner role. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aStateCallback A pointer to a function that is called when the commissioner state changes. @@ -193,7 +193,7 @@ otError otCommissionerStart(otInstance *aInstance, void *aCallbackContext); /** - * This function disables the Thread Commissioner role. + * Disables the Thread Commissioner role. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -204,7 +204,7 @@ otError otCommissionerStart(otInstance *aInstance, otError otCommissionerStop(otInstance *aInstance); /** - * This function returns the Commissioner Id. + * Returns the Commissioner Id. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -214,7 +214,7 @@ otError otCommissionerStop(otInstance *aInstance); const char *otCommissionerGetId(otInstance *aInstance); /** - * This function sets the Commissioner Id. + * Sets the Commissioner Id. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aId A pointer to a string character array. Must be null terminated. @@ -227,7 +227,7 @@ const char *otCommissionerGetId(otInstance *aInstance); otError otCommissionerSetId(otInstance *aInstance, const char *aId); /** - * This function adds a Joiner entry. + * Adds a Joiner entry. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aEui64 A pointer to the Joiner's IEEE EUI-64 or NULL for any Joiner. @@ -248,7 +248,7 @@ otError otCommissionerAddJoiner(otInstance *aInstance, uint32_t aTimeout); /** - * This function adds a Joiner entry with a given Joiner Discerner value. + * Adds a Joiner entry with a given Joiner Discerner value. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aDiscerner A pointer to the Joiner Discerner. @@ -269,7 +269,7 @@ otError otCommissionerAddJoinerWithDiscerner(otInstance *aInstance, uint32_t aTimeout); /** - * This method get joiner info at aIterator position. + * Get joiner info at aIterator position. * * @param[in] aInstance A pointer to instance. * @param[in,out] aIterator A pointer to the Joiner Info iterator context. @@ -282,7 +282,7 @@ otError otCommissionerAddJoinerWithDiscerner(otInstance *aInstance, otError otCommissionerGetNextJoinerInfo(otInstance *aInstance, uint16_t *aIterator, otJoinerInfo *aJoiner); /** - * This function removes a Joiner entry. + * Removes a Joiner entry. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aEui64 A pointer to the Joiner's IEEE EUI-64 or NULL for any Joiner. @@ -298,7 +298,7 @@ otError otCommissionerGetNextJoinerInfo(otInstance *aInstance, uint16_t *aIterat otError otCommissionerRemoveJoiner(otInstance *aInstance, const otExtAddress *aEui64); /** - * This function removes a Joiner entry. + * Removes a Joiner entry. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aDiscerner A pointer to the Joiner Discerner. @@ -314,7 +314,7 @@ otError otCommissionerRemoveJoiner(otInstance *aInstance, const otExtAddress *aE otError otCommissionerRemoveJoinerWithDiscerner(otInstance *aInstance, const otJoinerDiscerner *aDiscerner); /** - * This function gets the Provisioning URL. + * Gets the Provisioning URL. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -324,7 +324,7 @@ otError otCommissionerRemoveJoinerWithDiscerner(otInstance *aInstance, const otJ const char *otCommissionerGetProvisioningUrl(otInstance *aInstance); /** - * This function sets the Provisioning URL. + * Sets the Provisioning URL. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aProvisioningUrl A pointer to the Provisioning URL (may be NULL to set as empty string). @@ -336,7 +336,7 @@ const char *otCommissionerGetProvisioningUrl(otInstance *aInstance); otError otCommissionerSetProvisioningUrl(otInstance *aInstance, const char *aProvisioningUrl); /** - * This function sends an Announce Begin message. + * Sends an Announce Begin message. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aChannelMask The channel mask value. @@ -358,7 +358,7 @@ otError otCommissionerAnnounceBegin(otInstance *aInstance, const otIp6Address *aAddress); /** - * This function pointer is called when the Commissioner receives an Energy Report. + * Pointer is called when the Commissioner receives an Energy Report. * * @param[in] aChannelMask The channel mask value. * @param[in] aEnergyList A pointer to the energy measurement list. @@ -372,7 +372,7 @@ typedef void (*otCommissionerEnergyReportCallback)(uint32_t aChannelMask, void *aContext); /** - * This function sends an Energy Scan Query message. + * Sends an Energy Scan Query message. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aChannelMask The channel mask value. @@ -400,7 +400,7 @@ otError otCommissionerEnergyScan(otInstance *aInstance, void *aContext); /** - * This function pointer is called when the Commissioner receives a PAN ID Conflict message. + * Pointer is called when the Commissioner receives a PAN ID Conflict message. * * @param[in] aPanId The PAN ID value. * @param[in] aChannelMask The channel mask value. @@ -410,7 +410,7 @@ otError otCommissionerEnergyScan(otInstance *aInstance, typedef void (*otCommissionerPanIdConflictCallback)(uint16_t aPanId, uint32_t aChannelMask, void *aContext); /** - * This function sends a PAN ID Query message. + * Sends a PAN ID Query message. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aPanId The PAN ID to query. @@ -434,7 +434,7 @@ otError otCommissionerPanIdQuery(otInstance *aInstance, void *aContext); /** - * This function sends MGMT_COMMISSIONER_GET. + * Sends MGMT_COMMISSIONER_GET. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aTlvs A pointer to TLVs. @@ -448,7 +448,7 @@ otError otCommissionerPanIdQuery(otInstance *aInstance, otError otCommissionerSendMgmtGet(otInstance *aInstance, const uint8_t *aTlvs, uint8_t aLength); /** - * This function sends MGMT_COMMISSIONER_SET. + * Sends MGMT_COMMISSIONER_SET. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aDataset A pointer to commissioning dataset. @@ -466,7 +466,7 @@ otError otCommissionerSendMgmtSet(otInstance *aInstance, uint8_t aLength); /** - * This function returns the Commissioner Session ID. + * Returns the Commissioner Session ID. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -476,7 +476,7 @@ otError otCommissionerSendMgmtSet(otInstance *aInstance, uint16_t otCommissionerGetSessionId(otInstance *aInstance); /** - * This function returns the Commissioner State. + * Returns the Commissioner State. * * @param[in] aInstance A pointer to an OpenThread instance. * diff --git a/openthread/include/openthread/crypto.h b/openthread/include/openthread/crypto.h index b2629267e9..414b4bae56 100644 --- a/openthread/include/openthread/crypto.h +++ b/openthread/include/openthread/crypto.h @@ -56,15 +56,13 @@ extern "C" { */ /** - * @struct otCryptoSha256Hash - * - * This structure represents a SHA-256 hash. + * Represents a SHA-256 hash. * */ typedef otPlatCryptoSha256Hash otCryptoSha256Hash; /** - * This function performs HMAC computation. + * Performs HMAC computation. * * @param[in] aKey A pointer to the key. * @param[in] aBuf A pointer to the input buffer. @@ -75,7 +73,7 @@ typedef otPlatCryptoSha256Hash otCryptoSha256Hash; void otCryptoHmacSha256(const otCryptoKey *aKey, const uint8_t *aBuf, uint16_t aBufLength, otCryptoSha256Hash *aHash); /** - * This method performs AES CCM computation. + * Performs AES CCM computation. * * @param[in] aKey A pointer to the key. * @param[in] aTagLength Length of tag in bytes. diff --git a/openthread/include/openthread/dataset.h b/openthread/include/openthread/dataset.h index af5884bb85..1cfc4cf7f4 100644 --- a/openthread/include/openthread/dataset.h +++ b/openthread/include/openthread/dataset.h @@ -58,7 +58,7 @@ extern "C" { /** * @struct otNetworkKey * - * This structure represents a Thread Network Key. + * Represents a Thread Network Key. * */ OT_TOOL_PACKED_BEGIN @@ -68,7 +68,7 @@ struct otNetworkKey } OT_TOOL_PACKED_END; /** - * This structure represents a Thread Network Key. + * Represents a Thread Network Key. * */ typedef struct otNetworkKey otNetworkKey; @@ -82,7 +82,7 @@ typedef otCryptoKeyRef otNetworkKeyRef; ///< Reference to Key #define OT_NETWORK_NAME_MAX_SIZE 16 ///< Maximum size of the Thread Network Name field (bytes) /** - * This structure represents a Network Name. + * Represents a Network Name. * * The `otNetworkName` is a null terminated C string (i.e., `m8` char array MUST end with null char `\0`). * @@ -95,7 +95,7 @@ typedef struct otNetworkName #define OT_EXT_PAN_ID_SIZE 8 ///< Size of a Thread PAN ID (bytes) /** - * This structure represents an Extended PAN ID. + * Represents an Extended PAN ID. * */ OT_TOOL_PACKED_BEGIN @@ -105,7 +105,7 @@ struct otExtendedPanId } OT_TOOL_PACKED_END; /** - * This structure represents an Extended PAN ID. + * Represents an Extended PAN ID. * */ typedef struct otExtendedPanId otExtendedPanId; @@ -113,7 +113,7 @@ typedef struct otExtendedPanId otExtendedPanId; #define OT_MESH_LOCAL_PREFIX_SIZE OT_IP6_PREFIX_SIZE ///< Size of the Mesh Local Prefix (bytes) /** - * This structure represents a Mesh Local Prefix. + * Represents a Mesh Local Prefix. * */ typedef otIp6NetworkPrefix otMeshLocalPrefix; @@ -121,7 +121,7 @@ typedef otIp6NetworkPrefix otMeshLocalPrefix; #define OT_PSKC_MAX_SIZE 16 ///< Maximum size of the PSKc (bytes) /** - * This structure represents PSKc. + * Represents PSKc. * */ OT_TOOL_PACKED_BEGIN @@ -131,7 +131,7 @@ struct otPskc } OT_TOOL_PACKED_END; /** - * This structure represents a PSKc. + * Represents a PSKc. * */ typedef struct otPskc otPskc; @@ -143,7 +143,7 @@ typedef struct otPskc otPskc; typedef otCryptoKeyRef otPskcRef; ///< Reference to Key /** - * This structure represent Security Policy. + * Represent Security Policy. * */ typedef struct otSecurityPolicy @@ -163,7 +163,7 @@ typedef struct otSecurityPolicy } otSecurityPolicy; /** - * This type represents Channel Mask. + * Represents Channel Mask. * */ typedef uint32_t otChannelMask; @@ -196,27 +196,27 @@ typedef uint32_t otChannelMask; #define OT_CHANNEL_26_MASK (1 << 26) ///< Channel 26 /** - * This structure represents presence of different components in Active or Pending Operational Dataset. + * Represents presence of different components in Active or Pending Operational Dataset. * */ typedef struct otOperationalDatasetComponents { - bool mIsActiveTimestampPresent : 1; ///< TRUE if Active Timestamp is present, FALSE otherwise. - bool mIsPendingTimestampPresent : 1; ///< TRUE if Pending Timestamp is present, FALSE otherwise. - bool mIsNetworkKeyPresent : 1; ///< TRUE if Network Key is present, FALSE otherwise. - bool mIsNetworkNamePresent : 1; ///< TRUE if Network Name is present, FALSE otherwise. - bool mIsExtendedPanIdPresent : 1; ///< TRUE if Extended PAN ID is present, FALSE otherwise. - bool mIsMeshLocalPrefixPresent : 1; ///< TRUE if Mesh Local Prefix is present, FALSE otherwise. - bool mIsDelayPresent : 1; ///< TRUE if Delay Timer is present, FALSE otherwise. - bool mIsPanIdPresent : 1; ///< TRUE if PAN ID is present, FALSE otherwise. - bool mIsChannelPresent : 1; ///< TRUE if Channel is present, FALSE otherwise. - bool mIsPskcPresent : 1; ///< TRUE if PSKc is present, FALSE otherwise. - bool mIsSecurityPolicyPresent : 1; ///< TRUE if Security Policy is present, FALSE otherwise. - bool mIsChannelMaskPresent : 1; ///< TRUE if Channel Mask is present, FALSE otherwise. + bool mIsActiveTimestampPresent; ///< TRUE if Active Timestamp is present, FALSE otherwise. + bool mIsPendingTimestampPresent; ///< TRUE if Pending Timestamp is present, FALSE otherwise. + bool mIsNetworkKeyPresent; ///< TRUE if Network Key is present, FALSE otherwise. + bool mIsNetworkNamePresent; ///< TRUE if Network Name is present, FALSE otherwise. + bool mIsExtendedPanIdPresent; ///< TRUE if Extended PAN ID is present, FALSE otherwise. + bool mIsMeshLocalPrefixPresent; ///< TRUE if Mesh Local Prefix is present, FALSE otherwise. + bool mIsDelayPresent; ///< TRUE if Delay Timer is present, FALSE otherwise. + bool mIsPanIdPresent; ///< TRUE if PAN ID is present, FALSE otherwise. + bool mIsChannelPresent; ///< TRUE if Channel is present, FALSE otherwise. + bool mIsPskcPresent; ///< TRUE if PSKc is present, FALSE otherwise. + bool mIsSecurityPolicyPresent; ///< TRUE if Security Policy is present, FALSE otherwise. + bool mIsChannelMaskPresent; ///< TRUE if Channel Mask is present, FALSE otherwise. } otOperationalDatasetComponents; /** - * This structure represents a Thread Dataset timestamp component. + * Represents a Thread Dataset timestamp component. * */ typedef struct otTimestamp @@ -227,9 +227,9 @@ typedef struct otTimestamp } otTimestamp; /** - * This structure represents an Active or Pending Operational Dataset. + * Represents an Active or Pending Operational Dataset. * - * Components in Dataset are optional. `mComponets` structure specifies which components are present in the Dataset. + * Components in Dataset are optional. `mComponents` structure specifies which components are present in the Dataset. * */ typedef struct otOperationalDataset @@ -256,7 +256,7 @@ typedef struct otOperationalDataset #define OT_OPERATIONAL_DATASET_MAX_LENGTH 254 /** - * This structure represents an Active or Pending Operational Dataset. + * Represents an Active or Pending Operational Dataset. * * The Operational Dataset is TLV encoded as specified by Thread. * @@ -268,7 +268,7 @@ typedef struct otOperationalDatasetTlvs } otOperationalDatasetTlvs; /** - * This enumeration represents meshcop TLV types. + * Represents meshcop TLV types. * */ typedef enum otMeshcopTlvType @@ -316,7 +316,7 @@ typedef enum otMeshcopTlvType } otMeshcopTlvType; /** - * This function pointer is called when a response to a MGMT_SET request is received or times out. + * Pointer is called when a response to a MGMT_SET request is received or times out. * * @param[in] aResult A result of the operation. * @param[in] aContext A pointer to application-specific context. @@ -331,7 +331,7 @@ typedef enum otMeshcopTlvType typedef void (*otDatasetMgmtSetCallback)(otError aResult, void *aContext); /** - * This function indicates whether a valid network is present in the Active Operational Dataset or not. + * Indicates whether a valid network is present in the Active Operational Dataset or not. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -353,7 +353,7 @@ bool otDatasetIsCommissioned(otInstance *aInstance); otError otDatasetGetActive(otInstance *aInstance, otOperationalDataset *aDataset); /** - * This function gets the Active Operational Dataset. + * Gets the Active Operational Dataset. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[out] aDataset A pointer to where the Active Operational Dataset will be placed. @@ -391,7 +391,7 @@ otError otDatasetGetActiveTlvs(otInstance *aInstance, otOperationalDatasetTlvs * otError otDatasetSetActive(otInstance *aInstance, const otOperationalDataset *aDataset); /** - * This function sets the Active Operational Dataset. + * Sets the Active Operational Dataset. * * If the dataset does not include an Active Timestamp, the dataset is only partially complete. * @@ -417,7 +417,7 @@ otError otDatasetSetActive(otInstance *aInstance, const otOperationalDataset *aD otError otDatasetSetActiveTlvs(otInstance *aInstance, const otOperationalDatasetTlvs *aDataset); /** - * This function gets the Pending Operational Dataset. + * Gets the Pending Operational Dataset. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[out] aDataset A pointer to where the Pending Operational Dataset will be placed. @@ -429,7 +429,7 @@ otError otDatasetSetActiveTlvs(otInstance *aInstance, const otOperationalDataset otError otDatasetGetPending(otInstance *aInstance, otOperationalDataset *aDataset); /** - * This function gets the Pending Operational Dataset. + * Gets the Pending Operational Dataset. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[out] aDataset A pointer to where the Pending Operational Dataset will be placed. @@ -454,7 +454,7 @@ otError otDatasetGetPendingTlvs(otInstance *aInstance, otOperationalDatasetTlvs otError otDatasetSetPending(otInstance *aInstance, const otOperationalDataset *aDataset); /** - * This function sets the Pending Operational Dataset. + * Sets the Pending Operational Dataset. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aDataset A pointer to the Pending Operational Dataset. @@ -549,7 +549,7 @@ otError otDatasetSendMgmtPendingSet(otInstance *aInstance, void *aContext); /** - * This function generates PSKc from a given pass-phrase, network name, and extended PAN ID. + * Generates PSKc from a given pass-phrase, network name, and extended PAN ID. * * PSKc is used to establish the Commissioner Session. * @@ -583,7 +583,7 @@ otError otDatasetGeneratePskc(const char *aPassPhrase, otError otNetworkNameFromString(otNetworkName *aNetworkName, const char *aNameString); /** - * This function parses an Operational Dataset from a `otOperationalDatasetTlvs`. + * Parses an Operational Dataset from a given `otOperationalDatasetTlvs`. * * @param[in] aDatasetTlvs A pointer to dataset TLVs. * @param[out] aDataset A pointer to where the dataset will be placed. @@ -594,6 +594,33 @@ otError otNetworkNameFromString(otNetworkName *aNetworkName, const char *aNameSt */ otError otDatasetParseTlvs(const otOperationalDatasetTlvs *aDatasetTlvs, otOperationalDataset *aDataset); +/** + * Converts a given Operational Dataset to `otOperationalDatasetTlvs`. + * + * @param[in] aDataset An Operational dataset to convert to TLVs. + * @param[out] aDatasetTlvs A pointer to dataset TLVs to return the result. + * + * @retval OT_ERROR_NONE Successfully converted @p aDataset and updated @p aDatasetTlvs. + * @retval OT_ERROR_INVALID_ARGS @p aDataset is invalid, does not contain active or pending timestamps. + * + */ +otError otDatasetConvertToTlvs(const otOperationalDataset *aDataset, otOperationalDatasetTlvs *aDatasetTlvs); + +/** + * Updates a given Operational Dataset. + * + * @p aDataset contains the fields to be updated and their new value. + * + * @param[in] aDataset Specifies the set of types and values to update. + * @param[in,out] aDatasetTlvs A pointer to dataset TLVs to update. + * + * @retval OT_ERROR_NONE Successfully updated @p aDatasetTlvs. + * @retval OT_ERROR_INVALID_ARGS @p aDataset contains invalid values. + * @retval OT_ERROR_NO_BUFS Not enough space space in @p aDatasetTlvs to apply the update. + * + */ +otError otDatasetUpdateTlvs(const otOperationalDataset *aDataset, otOperationalDatasetTlvs *aDatasetTlvs); + /** * @} * diff --git a/openthread/include/openthread/dataset_updater.h b/openthread/include/openthread/dataset_updater.h index cb16c33ac3..f9b7f64ae0 100644 --- a/openthread/include/openthread/dataset_updater.h +++ b/openthread/include/openthread/dataset_updater.h @@ -69,7 +69,7 @@ extern "C" { typedef void (*otDatasetUpdaterCallback)(otError aError, void *aContext); /** - * This function requests an update to Operational Dataset. + * Requests an update to Operational Dataset. * * Available when `OPENTHREAD_CONFIG_DATASET_UPDATER_ENABLE` is enabled. * @@ -94,7 +94,7 @@ otError otDatasetUpdaterRequestUpdate(otInstance *aInstance, void *aContext); /** - * This function cancels an ongoing (if any) Operational Dataset update request. + * Cancels an ongoing (if any) Operational Dataset update request. * * Available when `OPENTHREAD_CONFIG_DATASET_UPDATER_ENABLE` is enabled. * @@ -104,7 +104,7 @@ otError otDatasetUpdaterRequestUpdate(otInstance *aInstance, void otDatasetUpdaterCancelUpdate(otInstance *aInstance); /** - * This function indicates whether there is an ongoing Operation Dataset update request. + * Indicates whether there is an ongoing Operation Dataset update request. * * Available when `OPENTHREAD_CONFIG_DATASET_UPDATER_ENABLE` is enabled. * diff --git a/openthread/include/openthread/diag.h b/openthread/include/openthread/diag.h index 98c708e342..217abf6cb3 100644 --- a/openthread/include/openthread/diag.h +++ b/openthread/include/openthread/diag.h @@ -52,7 +52,7 @@ extern "C" { */ /** - * This function processes a factory diagnostics command line. + * Processes a factory diagnostics command line. * * The output of this function (the content written to @p aOutput) MUST terminate with `\0` and the `\0` is within the * output buffer. @@ -75,7 +75,7 @@ otError otDiagProcessCmd(otInstance *aInstance, size_t aOutputMaxLen); /** - * This function processes a factory diagnostics command line. + * Processes a factory diagnostics command line. * * The output of this function (the content written to @p aOutput) MUST terminate with `\0` and the `\0` is within the * output buffer. @@ -94,7 +94,7 @@ otError otDiagProcessCmd(otInstance *aInstance, otError otDiagProcessCmdLine(otInstance *aInstance, const char *aString, char *aOutput, size_t aOutputMaxLen); /** - * This function indicates whether or not the factory diagnostics mode is enabled. + * Indicates whether or not the factory diagnostics mode is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * diff --git a/openthread/include/openthread/dns.h b/openthread/include/openthread/dns.h index 22f3fc2b74..93fd287d71 100644 --- a/openthread/include/openthread/dns.h +++ b/openthread/include/openthread/dns.h @@ -63,7 +63,7 @@ extern "C" { #define OT_DNS_TXT_KEY_MAX_LENGTH 9 ///< Recommended maximum length of TXT record key string (RFC 6763 - section 6.4). /** - * This structure represents a TXT record entry representing a key/value pair (RFC 6763 - section 6.3). + * Represents a TXT record entry representing a key/value pair (RFC 6763 - section 6.3). * * The string buffers pointed to by `mKey` and `mValue` MUST persist and remain unchanged after an instance of such * structure is passed to OpenThread (as part of `otSrpClientService` instance). @@ -95,7 +95,7 @@ typedef struct otDnsTxtEntry } otDnsTxtEntry; /** - * This structure represents an iterator for TXT record entires (key/value pairs). + * Represents an iterator for TXT record entries (key/value pairs). * * The data fields in this structure are intended for use by OpenThread core and caller should not read or change them. * @@ -108,7 +108,7 @@ typedef struct otDnsTxtEntryIterator } otDnsTxtEntryIterator; /** - * This function initializes a TXT record iterator. + * Initializes a TXT record iterator. * * The buffer pointer @p aTxtData and its content MUST persist and remain unchanged while @p aIterator object * is being used. @@ -121,7 +121,7 @@ typedef struct otDnsTxtEntryIterator void otDnsInitTxtEntryIterator(otDnsTxtEntryIterator *aIterator, const uint8_t *aTxtData, uint16_t aTxtDataLength); /** - * This function parses the TXT data from an iterator and gets the next TXT record entry (key/value pair). + * Parses the TXT data from an iterator and gets the next TXT record entry (key/value pair). * * The @p aIterator MUST be initialized using `otDnsInitTxtEntryIterator()` before calling this function and the TXT * data buffer used to initialize the iterator MUST persist and remain unchanged. Otherwise the behavior of this @@ -142,7 +142,25 @@ void otDnsInitTxtEntryIterator(otDnsTxtEntryIterator *aIterator, const uint8_t * otError otDnsGetNextTxtEntry(otDnsTxtEntryIterator *aIterator, otDnsTxtEntry *aEntry); /** - * This function enables/disables the "DNS name compression" mode. + * Encodes a given list of TXT record entries (key/value pairs) into TXT data (following format specified by RFC 6763). + * + * @param[in] aTxtEntries Pointer to an array of `otDnsTxtEntry`. + * @param[in] aNumTxtEntries Number of entries in @p aTxtEntries array. + * @param[out] aTxtData A pointer to a buffer to output the encoded TXT data. + * @param[in,out] aTxtDataLength On input, size of buffer @p aTxtData. On output, length of the encoded TXT data. + * + * @retval OT_ERROR_NONE Encoded TXT data successfully, @p aTxtData and @p aTxtDataLength are updated. + * @retval OT_ERROR_INVALID_ARGS The @p aTxtEntries is not valid. + * @retval OT_ERROR_NO_BUS Could not fit the encoded data in @p aTxtData buffer with its @p aTxtDataLength. + * + */ +otError otDnsEncodeTxtData(const otDnsTxtEntry *aTxtEntries, + uint16_t aNumTxtEntries, + uint8_t *aTxtData, + uint16_t *aTxtDataLength); + +/** + * Enables/disables the "DNS name compression" mode. * * By default DNS name compression is enabled. When disabled, DNS names are appended as full and never compressed. This * is applicable to OpenThread's DNS and SRP client/server modules. @@ -158,7 +176,7 @@ otError otDnsGetNextTxtEntry(otDnsTxtEntryIterator *aIterator, otDnsTxtEntry *aE void otDnsSetNameCompressionEnabled(bool aEnabled); /** - * This function indicates whether the "DNS name compression" mode is enabled or not. + * Indicates whether the "DNS name compression" mode is enabled or not. * * This is intended for testing only and available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` config is enabled. * diff --git a/openthread/include/openthread/dns_client.h b/openthread/include/openthread/dns_client.h index 95da750b6d..0fd3458045 100644 --- a/openthread/include/openthread/dns_client.h +++ b/openthread/include/openthread/dns_client.h @@ -56,7 +56,7 @@ extern "C" { */ /** - * This enumeration type represents the "Recursion Desired" (RD) flag in an `otDnsQueryConfig`. + * Type represents the "Recursion Desired" (RD) flag in an `otDnsQueryConfig`. * */ typedef enum @@ -67,7 +67,7 @@ typedef enum } otDnsRecursionFlag; /** - * This enumeration type represents the NAT64 mode in an `otDnsQueryConfig`. + * Type represents the NAT64 mode in an `otDnsQueryConfig`. * * The NAT64 mode indicates whether to allow or disallow NAT64 address translation during DNS client address resolution. * This mode is only used when `OPENTHREAD_CONFIG_DNS_CLIENT_NAT64_ENABLE` is enabled. @@ -81,7 +81,37 @@ typedef enum } otDnsNat64Mode; /** - * This structure represents a DNS query configuration. + * Type represents the service resolution mode in an `otDnsQueryConfig`. + * + * This is only used during DNS client service resolution `otDnsClientResolveService()`. It determines which + * record types to query. + * + */ +typedef enum +{ + OT_DNS_SERVICE_MODE_UNSPECIFIED = 0, ///< Mode is not specified. Use default service mode. + OT_DNS_SERVICE_MODE_SRV = 1, ///< Query for SRV record only. + OT_DNS_SERVICE_MODE_TXT = 2, ///< Query for TXT record only. + OT_DNS_SERVICE_MODE_SRV_TXT = 3, ///< Query for both SRV and TXT records in same message. + OT_DNS_SERVICE_MODE_SRV_TXT_SEPARATE = 4, ///< Query in parallel for SRV and TXT using separate messages. + OT_DNS_SERVICE_MODE_SRV_TXT_OPTIMIZE = 5, ///< Query for TXT/SRV together first, if fails then query separately. +} otDnsServiceMode; + +/** + * Type represents the DNS transport protocol in an `otDnsQueryConfig`. + * + * This `OT_DNS_TRANSPORT_TCP` is only supported when `OPENTHREAD_CONFIG_DNS_CLIENT_OVER_TCP_ENABLE` is enabled. + * + */ +typedef enum +{ + OT_DNS_TRANSPORT_UNSPECIFIED = 0, /// DNS transport is unspecified. + OT_DNS_TRANSPORT_UDP = 1, /// DNS query should be sent via UDP. + OT_DNS_TRANSPORT_TCP = 2, /// DNS query should be sent via TCP. +} otDnsTransportProto; + +/** + * Represents a DNS query configuration. * * Any of the fields in this structure can be set to zero to indicate that it is not specified. How the unspecified * fields are treated is determined by the function which uses the instance of `otDnsQueryConfig`. @@ -89,15 +119,17 @@ typedef enum */ typedef struct otDnsQueryConfig { - otSockAddr mServerSockAddr; ///< Server address (IPv6 address/port). All zero or zero port for unspecified. - uint32_t mResponseTimeout; ///< Wait time (in msec) to rx response. Zero indicates unspecified value. - uint8_t mMaxTxAttempts; ///< Maximum tx attempts before reporting failure. Zero for unspecified value. - otDnsRecursionFlag mRecursionFlag; ///< Indicates whether the server can resolve the query recursively or not. - otDnsNat64Mode mNat64Mode; ///< Allow/Disallow NAT64 address translation during address resolution. + otSockAddr mServerSockAddr; ///< Server address (IPv6 addr/port). All zero or zero port for unspecified. + uint32_t mResponseTimeout; ///< Wait time (in msec) to rx response. Zero indicates unspecified value. + uint8_t mMaxTxAttempts; ///< Maximum tx attempts before reporting failure. Zero for unspecified value. + otDnsRecursionFlag mRecursionFlag; ///< Indicates whether the server can resolve the query recursively or not. + otDnsNat64Mode mNat64Mode; ///< Allow/Disallow NAT64 address translation during address resolution. + otDnsServiceMode mServiceMode; ///< Determines which records to query during service resolution. + otDnsTransportProto mTransportProto; ///< Select default transport protocol. } otDnsQueryConfig; /** - * This function gets the current default query config used by DNS client. + * Gets the current default query config used by DNS client. * * When OpenThread stack starts, the default DNS query config is determined from a set of OT config options such as * `OPENTHREAD_CONFIG_DNS_CLIENT_DEFAULT_SERVER_IP6_ADDRESS`, `_DEFAULT_SERVER_PORT`, `_DEFAULT_RESPONSE_TIMEOUT`, etc. @@ -111,7 +143,7 @@ typedef struct otDnsQueryConfig const otDnsQueryConfig *otDnsClientGetDefaultConfig(otInstance *aInstance); /** - * This function sets the default query config on DNS client. + * Sets the default query config on DNS client. * * @note Any ongoing query will continue to use the config from when it was started. The new default config will be * used for any future DNS queries. @@ -137,7 +169,7 @@ const otDnsQueryConfig *otDnsClientGetDefaultConfig(otInstance *aInstance); void otDnsClientSetDefaultConfig(otInstance *aInstance, const otDnsQueryConfig *aConfig); /** - * This type is an opaque representation of a response to an address resolution DNS query. + * An opaque representation of a response to an address resolution DNS query. * * Pointers to instance of this type are provided from callback `otDnsAddressCallback`. * @@ -145,7 +177,7 @@ void otDnsClientSetDefaultConfig(otInstance *aInstance, const otDnsQueryConfig * typedef struct otDnsAddressResponse otDnsAddressResponse; /** - * This function pointer is called when a DNS response is received for an address resolution query. + * Pointer is called when a DNS response is received for an address resolution query. * * Within this callback the user can use `otDnsAddressResponseGet{Item}()` functions along with the @p aResponse * pointer to get more info about the response. @@ -185,7 +217,7 @@ typedef struct otDnsAddressResponse otDnsAddressResponse; typedef void (*otDnsAddressCallback)(otError aError, const otDnsAddressResponse *aResponse, void *aContext); /** - * This function sends an address resolution DNS query for AAAA (IPv6) record(s) for a given host name. + * Sends an address resolution DNS query for AAAA (IPv6) record(s) for a given host name. * * The @p aConfig can be NULL. In this case the default config (from `otDnsClientGetDefaultConfig()`) will be used as * the config for this query. In a non-NULL @p aConfig, some of the fields can be left unspecified (value zero). The @@ -210,9 +242,9 @@ otError otDnsClientResolveAddress(otInstance *aInstance, const otDnsQueryConfig *aConfig); /** - * This function sends an address resolution DNS query for A (IPv4) record(s) for a given host name. + * Sends an address resolution DNS query for A (IPv4) record(s) for a given host name. * - * This function requires and is available when `OPENTHREAD_CONFIG_DNS_CLIENT_NAT64_ENABLE` is enabled. + * Requires and is available when `OPENTHREAD_CONFIG_DNS_CLIENT_NAT64_ENABLE` is enabled. * * When a successful response is received, the addresses are returned from @p aCallback as NAT64 IPv6 translated * versions of the IPv4 addresses from the query response. @@ -240,9 +272,9 @@ otError otDnsClientResolveIp4Address(otInstance *aInstance, const otDnsQueryConfig *aConfig); /** - * This function gets the full host name associated with an address resolution DNS response. + * Gets the full host name associated with an address resolution DNS response. * - * This function MUST only be used from `otDnsAddressCallback`. + * MUST only be used from `otDnsAddressCallback`. * * @param[in] aResponse A pointer to the response. * @param[out] aNameBuffer A buffer to char array to output the full host name (MUST NOT be NULL). @@ -257,9 +289,9 @@ otError otDnsAddressResponseGetHostName(const otDnsAddressResponse *aResponse, uint16_t aNameBufferSize); /** - * This function gets an IPv6 address associated with an address resolution DNS response. + * Gets an IPv6 address associated with an address resolution DNS response. * - * This function MUST only be used from `otDnsAddressCallback`. + * MUST only be used from `otDnsAddressCallback`. * * The response may include multiple IPv6 address records. @p aIndex can be used to iterate through the list of * addresses. Index zero gets the first address and so on. When we reach end of the list, `OT_ERROR_NOT_FOUND` is @@ -283,7 +315,7 @@ otError otDnsAddressResponseGetAddress(const otDnsAddressResponse *aResponse, uint32_t *aTtl); /** - * This type is an opaque representation of a response to a browse (service instance enumeration) DNS query. + * An opaque representation of a response to a browse (service instance enumeration) DNS query. * * Pointers to instance of this type are provided from callback `otDnsBrowseCallback`. * @@ -291,7 +323,7 @@ otError otDnsAddressResponseGetAddress(const otDnsAddressResponse *aResponse, typedef struct otDnsBrowseResponse otDnsBrowseResponse; /** - * This function pointer is called when a DNS response is received for a browse (service instance enumeration) query. + * Pointer is called when a DNS response is received for a browse (service instance enumeration) query. * * Within this callback the user can use `otDnsBrowseResponseGet{Item}()` functions along with the @p aResponse * pointer to get more info about the response. @@ -309,7 +341,7 @@ typedef struct otDnsBrowseResponse otDnsBrowseResponse; typedef void (*otDnsBrowseCallback)(otError aError, const otDnsBrowseResponse *aResponse, void *aContext); /** - * This structure provides info for a DNS service instance. + * Provides info for a DNS service instance. * */ typedef struct otDnsServiceInfo @@ -329,9 +361,9 @@ typedef struct otDnsServiceInfo } otDnsServiceInfo; /** - * This function sends a DNS browse (service instance enumeration) query for a given service name. + * Sends a DNS browse (service instance enumeration) query for a given service name. * - * This function is available when `OPENTHREAD_CONFIG_DNS_CLIENT_SERVICE_DISCOVERY_ENABLE` is enabled. + * Is available when `OPENTHREAD_CONFIG_DNS_CLIENT_SERVICE_DISCOVERY_ENABLE` is enabled. * * The @p aConfig can be NULL. In this case the default config (from `otDnsClientGetDefaultConfig()`) will be used as * the config for this query. In a non-NULL @p aConfig, some of the fields can be left unspecified (value zero). The @@ -354,9 +386,9 @@ otError otDnsClientBrowse(otInstance *aInstance, const otDnsQueryConfig *aConfig); /** - * This function gets the service name associated with a DNS browse (service instance enumeration) response. + * Gets the service name associated with a DNS browse (service instance enumeration) response. * - * This function MUST only be used from `otDnsBrowseCallback`. + * MUST only be used from `otDnsBrowseCallback`. * * @param[in] aResponse A pointer to the response. * @param[out] aNameBuffer A buffer to char array to output the service name (MUST NOT be NULL). @@ -371,9 +403,9 @@ otError otDnsBrowseResponseGetServiceName(const otDnsBrowseResponse *aResponse, uint16_t aNameBufferSize); /** - * This function gets a service instance associated with a DNS browse (service instance enumeration) response. + * Gets a service instance associated with a DNS browse (service instance enumeration) response. * - * This function MUST only be used from `otDnsBrowseCallback`. + * MUST only be used from `otDnsBrowseCallback`. * * The response may include multiple service instance records. @p aIndex can be used to iterate through the list. Index * zero gives the the first record. When we reach end of the list, `OT_ERROR_NOT_FOUND` is returned. @@ -398,15 +430,16 @@ otError otDnsBrowseResponseGetServiceInstance(const otDnsBrowseResponse *aRespon uint8_t aLabelBufferSize); /** - * This function gets info for a service instance from a DNS browse (service instance enumeration) response. + * Gets info for a service instance from a DNS browse (service instance enumeration) response. * - * This function MUST only be used from `otDnsBrowseCallback`. + * MUST only be used from `otDnsBrowseCallback`. * - * A browse DNS response should include the SRV, TXT, and AAAA records for the service instances that are enumerated - * (note that it is a SHOULD and not a MUST requirement). This function tries to retrieve this info for a given service - * instance when available. + * A browse DNS response can include SRV, TXT, and AAAA records for the service instances that are enumerated. This is + * a SHOULD and not a MUST requirement, and servers/resolvers are not required to provide this. This function attempts + * to retrieve this info for a given service instance when available. * - * - If no matching SRV record is found in @p aResponse, `OT_ERROR_NOT_FOUND` is returned. + * - If no matching SRV record is found in @p aResponse, `OT_ERROR_NOT_FOUND` is returned. In this case, no additional + * records (no TXT and/or AAAA) are read. * - If a matching SRV record is found in @p aResponse, @p aServiceInfo is updated and `OT_ERROR_NONE` is returned. * - If no matching TXT record is found in @p aResponse, `mTxtDataSize` in @p aServiceInfo is set to zero. * - If TXT data length is greater than `mTxtDataSize`, it is read partially and `mTxtDataTruncated` is set to true. @@ -429,9 +462,9 @@ otError otDnsBrowseResponseGetServiceInfo(const otDnsBrowseResponse *aResponse, otDnsServiceInfo *aServiceInfo); /** - * This function gets the host IPv6 address from a DNS browse (service instance enumeration) response. + * Gets the host IPv6 address from a DNS browse (service instance enumeration) response. * - * This function MUST only be used from `otDnsBrowseCallback`. + * MUST only be used from `otDnsBrowseCallback`. * * The response can include zero or more IPv6 address records. @p aIndex can be used to iterate through the list of * addresses. Index zero gets the first address and so on. When we reach end of the list, `OT_ERROR_NOT_FOUND` is @@ -456,7 +489,7 @@ otError otDnsBrowseResponseGetHostAddress(const otDnsBrowseResponse *aResponse, uint32_t *aTtl); /** - * This type is an opaque representation of a response to a service instance resolution DNS query. + * An opaque representation of a response to a service instance resolution DNS query. * * Pointers to instance of this type are provided from callback `otDnsAddressCallback`. * @@ -464,7 +497,7 @@ otError otDnsBrowseResponseGetHostAddress(const otDnsBrowseResponse *aResponse, typedef struct otDnsServiceResponse otDnsServiceResponse; /** - * This function pointer is called when a DNS response is received for a service instance resolution query. + * Pointer is called when a DNS response is received for a service instance resolution query. * * Within this callback the user can use `otDnsServiceResponseGet{Item}()` functions along with the @p aResponse * pointer to get more info about the response. @@ -482,14 +515,26 @@ typedef struct otDnsServiceResponse otDnsServiceResponse; typedef void (*otDnsServiceCallback)(otError aError, const otDnsServiceResponse *aResponse, void *aContext); /** - * This function sends a DNS service instance resolution query for a given service instance. + * Starts a DNS service instance resolution for a given service instance. * - * This function is available when `OPENTHREAD_CONFIG_DNS_CLIENT_SERVICE_DISCOVERY_ENABLE` is enabled. + * Is available when `OPENTHREAD_CONFIG_DNS_CLIENT_SERVICE_DISCOVERY_ENABLE` is enabled. * * The @p aConfig can be NULL. In this case the default config (from `otDnsClientGetDefaultConfig()`) will be used as * the config for this query. In a non-NULL @p aConfig, some of the fields can be left unspecified (value zero). The * unspecified fields are then replaced by the values from the default config. * + * The function sends queries for SRV and/or TXT records for the given service instance. The `mServiceMode` field in + * `otDnsQueryConfig` determines which records to query (SRV only, TXT only, or both SRV and TXT) and how to perform + * the query (together in the same message, separately in parallel, or in optimized mode where client will try in the + * same message first and then separately if it fails to get a response). + * + * The SRV record provides information about service port, priority, and weight along with the host name associated + * with the service instance. This function DOES NOT perform address resolution for the host name discovered from SRV + * record. The server/resolver may provide AAAA/A record(s) for the host name in the Additional Data section of the + * response to SRV/TXT query and this information can be retrieved using `otDnsServiceResponseGetServiceInfo()` in + * `otDnsServiceCallback`. Users of this API MUST NOT assume that host address will always be available from + * `otDnsServiceResponseGetServiceInfo()`. + * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aInstanceLabel The service instance label. * @param[in] aServiceName The service name (together with @p aInstanceLabel form full instance name). @@ -510,9 +555,46 @@ otError otDnsClientResolveService(otInstance *aInstance, const otDnsQueryConfig *aConfig); /** - * This function gets the service instance name associated with a DNS service instance resolution response. + * Starts a DNS service instance resolution for a given service instance, with a potential follow-up + * address resolution for the host name discovered for the service instance. + * + * Is available when `OPENTHREAD_CONFIG_DNS_CLIENT_SERVICE_DISCOVERY_ENABLE` is enabled. + * + * The @p aConfig can be NULL. In this case the default config (from `otDnsClientGetDefaultConfig()`) will be used as + * the config for this query. In a non-NULL @p aConfig, some of the fields can be left unspecified (value zero). The + * unspecified fields are then replaced by the values from the default config. This function cannot be used with + * `mServiceMode` in DNS config set to `OT_DNS_SERVICE_MODE_TXT` (i.e., querying for TXT record only) and will return + * `OT_ERROR_INVALID_ARGS`. + * + * Behaves similarly to `otDnsClientResolveService()` sending queries for SRV and TXT records. However, + * if the server/resolver does not provide AAAA/A records for the host name in the response to SRV query (in the + * Additional Data section), it will perform host name resolution (sending an AAAA query) for the discovered host name + * from the SRV record. The callback @p aCallback is invoked when responses for all queries are received (i.e., both + * service and host address resolutions are finished). + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aInstanceLabel The service instance label. + * @param[in] aServiceName The service name (together with @p aInstanceLabel form full instance name). + * @param[in] aCallback A function pointer that shall be called on response reception or time-out. + * @param[in] aContext A pointer to arbitrary context information. + * @param[in] aConfig A pointer to the config to use for this query. + * + * @retval OT_ERROR_NONE Query sent successfully. @p aCallback will be invoked to report the status. + * @retval OT_ERROR_NO_BUFS Insufficient buffer to prepare and send query. + * @retval OT_ERROR_INVALID_ARGS @p aInstanceLabel is NULL, or @p aConfig is invalid. + * + */ +otError otDnsClientResolveServiceAndHostAddress(otInstance *aInstance, + const char *aInstanceLabel, + const char *aServiceName, + otDnsServiceCallback aCallback, + void *aContext, + const otDnsQueryConfig *aConfig); + +/** + * Gets the service instance name associated with a DNS service instance resolution response. * - * This function MUST only be used from `otDnsServiceCallback`. + * MUST only be used from `otDnsServiceCallback`. * * @param[in] aResponse A pointer to the response. * @param[out] aLabelBuffer A buffer to char array to output the service instance label (MUST NOT be NULL). @@ -532,12 +614,23 @@ otError otDnsServiceResponseGetServiceName(const otDnsServiceResponse *aResponse uint16_t aNameBufferSize); /** - * This function gets info for a service instance from a DNS service instance resolution response. - * - * This function MUST only be used from `otDnsServiceCallback`. - * - * - If no matching SRV record is found in @p aResponse, `OT_ERROR_NOT_FOUND` is returned. - * - If a matching SRV record is found in @p aResponse, @p aServiceInfo is updated and `OT_ERROR_NONE` is returned. + * Gets info for a service instance from a DNS service instance resolution response. + * + * MUST only be used from a `otDnsServiceCallback` triggered from `otDnsClientResolveService()` or + * `otDnsClientResolveServiceAndHostAddress()`. + * + * When this is is used from a `otDnsClientResolveService()` callback, the DNS response from server/resolver may + * include AAAA records in its Additional Data section for the host name associated with the service instance that is + * resolved. This is a SHOULD and not a MUST requirement so servers/resolvers are not required to provide this. This + * function attempts to parse AAAA record(s) if included in the response. If it is not included `mHostAddress` is set + * to all zeros (unspecified address). To also resolve the host address, user can use the DNS client API function + * `otDnsClientResolveServiceAndHostAddress()` which will perform service resolution followed up by a host name + * address resolution query (when AAAA records are not provided by server/resolver in the SRV query response). + * + * - If a matching SRV record is found in @p aResponse, @p aServiceInfo is updated. + * - If no matching SRV record is found, `OT_ERROR_NOT_FOUND` is returned unless the query config for this query + * used `OT_DNS_SERVICE_MODE_TXT` for `mServiceMode` (meaning the request was only for TXT record). In this case, we + * still try to parse the SRV record from Additional Data Section of response (in case server provided the info). * - If no matching TXT record is found in @p aResponse, `mTxtDataSize` in @p aServiceInfo is set to zero. * - If TXT data length is greater than `mTxtDataSize`, it is read partially and `mTxtDataTruncated` is set to true. * - If no matching AAAA record is found in @p aResponse, `mHostAddress is set to all zero or unspecified address. @@ -548,7 +641,7 @@ otError otDnsServiceResponseGetServiceName(const otDnsServiceResponse *aResponse * @param[out] aServiceInfo A `ServiceInfo` to output the service instance information (MUST NOT be NULL). * * @retval OT_ERROR_NONE The service instance info was read. @p aServiceInfo is updated. - * @retval OT_ERROR_NOT_FOUND Could not find a matching SRV record in @p aResponse. + * @retval OT_ERROR_NOT_FOUND Could not find a required record in @p aResponse. * @retval OT_ERROR_NO_BUFS The host name and/or TXT data could not fit in the given buffers. * @retval OT_ERROR_PARSE Could not parse the records in the @p aResponse. * @@ -556,9 +649,9 @@ otError otDnsServiceResponseGetServiceName(const otDnsServiceResponse *aResponse otError otDnsServiceResponseGetServiceInfo(const otDnsServiceResponse *aResponse, otDnsServiceInfo *aServiceInfo); /** - * This function gets the host IPv6 address from a DNS service instance resolution response. + * Gets the host IPv6 address from a DNS service instance resolution response. * - * This function MUST only be used from `otDnsServiceCallback`. + * MUST only be used from `otDnsServiceCallback`. * * The response can include zero or more IPv6 address records. @p aIndex can be used to iterate through the list of * addresses. Index zero gets the first address and so on. When we reach end of the list, `OT_ERROR_NOT_FOUND` is diff --git a/openthread/include/openthread/dnssd_server.h b/openthread/include/openthread/dnssd_server.h index 2feb95e16d..98f83d6940 100644 --- a/openthread/include/openthread/dnssd_server.h +++ b/openthread/include/openthread/dnssd_server.h @@ -56,7 +56,7 @@ extern "C" { */ /** - * This function is called when a DNS-SD query subscribes one of: + * Is called when a DNS-SD query subscribes one of: * 1. a service name. * 2. a service instance name. * 3. a host name. @@ -83,7 +83,7 @@ extern "C" { typedef void (*otDnssdQuerySubscribeCallback)(void *aContext, const char *aFullName); /** - * This function is called when a DNS-SD query unsubscribes one of: + * Is called when a DNS-SD query unsubscribes one of: * 1. a service name. * 2. a service instance name. * 3. a host name. @@ -107,7 +107,7 @@ typedef void (*otDnssdQueryUnsubscribeCallback)(void *aContext, const char *aFul typedef void otDnssdQuery; /** - * This structure represents information of a discovered service instance for a DNS-SD query. + * Represents information of a discovered service instance for a DNS-SD query. * */ typedef struct otDnssdServiceInstanceInfo @@ -125,7 +125,7 @@ typedef struct otDnssdServiceInstanceInfo } otDnssdServiceInstanceInfo; /** - * This structure represents information of a discovered host for a DNS-SD query. + * Represents information of a discovered host for a DNS-SD query. * */ typedef struct otDnssdHostInfo @@ -136,7 +136,7 @@ typedef struct otDnssdHostInfo } otDnssdHostInfo; /** - * This enumeration specifies a DNS-SD query type. + * Specifies a DNS-SD query type. * */ typedef enum @@ -148,7 +148,7 @@ typedef enum } otDnssdQueryType; /** - * This structure contains the counters of DNS-SD server. + * Contains the counters of DNS-SD server. * */ typedef struct otDnssdCounters @@ -164,7 +164,7 @@ typedef struct otDnssdCounters } otDnssdCounters; /** - * This function sets DNS-SD server query callbacks. + * Sets DNS-SD server query callbacks. * * The DNS-SD server calls @p aSubscribe to subscribe to a service or service instance to resolve a DNS-SD query and @p * aUnsubscribe to unsubscribe when the query is resolved or timeout. @@ -183,7 +183,7 @@ void otDnssdQuerySetCallbacks(otInstance *aInstance, void *aContext); /** - * This function notifies a discovered service instance. + * Notifies a discovered service instance. * * The external query resolver (e.g. Discovery Proxy) should call this function to notify OpenThread core of the * subscribed services or service instances. @@ -199,7 +199,7 @@ void otDnssdQueryHandleDiscoveredServiceInstance(otInstance *aIn const char *aServiceFullName, otDnssdServiceInstanceInfo *aInstanceInfo); /** - * This function notifies a discovered host. + * Notifies a discovered host. * * The external query resolver (e.g. Discovery Proxy) should call this function to notify OpenThread core of the * subscribed hosts. @@ -214,7 +214,7 @@ void otDnssdQueryHandleDiscoveredServiceInstance(otInstance *aIn void otDnssdQueryHandleDiscoveredHost(otInstance *aInstance, const char *aHostFullName, otDnssdHostInfo *aHostInfo); /** - * This function acquires the next query in the DNS-SD server. + * Acquires the next query in the DNS-SD server. * * @param[in] aInstance The OpenThread instance structure. * @param[in] aQuery The query pointer. Pass NULL to get the first query. @@ -225,7 +225,7 @@ void otDnssdQueryHandleDiscoveredHost(otInstance *aInstance, const char *aHostFu const otDnssdQuery *otDnssdGetNextQuery(otInstance *aInstance, const otDnssdQuery *aQuery); /** - * This function acquires the DNS-SD query type and name for a specific query. + * Acquires the DNS-SD query type and name for a specific query. * * @param[in] aQuery The query pointer acquired from `otDnssdGetNextQuery`. * @param[out] aNameOutput The name output buffer, which should be `OT_DNS_MAX_NAME_SIZE` bytes long. @@ -236,7 +236,7 @@ const otDnssdQuery *otDnssdGetNextQuery(otInstance *aInstance, const otDnssdQuer otDnssdQueryType otDnssdGetQueryTypeAndName(const otDnssdQuery *aQuery, char (*aNameOutput)[OT_DNS_MAX_NAME_SIZE]); /** - * This function returns the counters of the DNS-SD server. + * Returns the counters of the DNS-SD server. * * @param[in] aInstance The OpenThread instance structure. * @@ -245,6 +245,35 @@ otDnssdQueryType otDnssdGetQueryTypeAndName(const otDnssdQuery *aQuery, char (*a */ const otDnssdCounters *otDnssdGetCounters(otInstance *aInstance); +/** + * Enable or disable forwarding DNS queries to platform DNS upstream API. + * + * Available when `OPENTHREAD_CONFIG_DNS_UPSTREAM_QUERY_ENABLE` is enabled. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aEnabled A boolean to enable/disable forwarding DNS queries to upstream. + * + * @sa otPlatDnsStartUpstreamQuery + * @sa otPlatDnsCancelUpstreamQuery + * @sa otPlatDnsUpstreamQueryDone + * + */ +void otDnssdUpstreamQuerySetEnabled(otInstance *aInstance, bool aEnabled); + +/** + * Returns whether the DNSSD server will forward DNS queries to the platform DNS upstream API. + * + * Available when `OPENTHREAD_CONFIG_DNS_UPSTREAM_QUERY_ENABLE` is enabled. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @retval TRUE If the DNSSD server will forward DNS queries. + * @retval FALSE If the DNSSD server will not forward DNS queries. + * + * @sa otDnssdUpstreamQuerySetEnabled + * + */ +bool otDnssdUpstreamQueryIsEnabled(otInstance *aInstance); + /** * @} * diff --git a/openthread/include/openthread/error.h b/openthread/include/openthread/error.h index 66cb3c5b55..d54d7bac66 100644 --- a/openthread/include/openthread/error.h +++ b/openthread/include/openthread/error.h @@ -52,7 +52,7 @@ extern "C" { */ /** - * This enumeration represents error codes used throughout OpenThread. + * Represents error codes used throughout OpenThread. * */ typedef enum OT_MUST_USE_RESULT otError @@ -251,7 +251,7 @@ typedef enum OT_MUST_USE_RESULT otError } otError; /** - * This function converts an otError enum into a string. + * Converts an otError enum into a string. * * @param[in] aError An otError enum. * diff --git a/openthread/include/openthread/history_tracker.h b/openthread/include/openthread/history_tracker.h index 02d72f2e5f..08dc8d9c28 100644 --- a/openthread/include/openthread/history_tracker.h +++ b/openthread/include/openthread/history_tracker.h @@ -43,7 +43,7 @@ extern "C" { * Records the history of different events, for example RX and TX messages or network info changes. All tracked * entries are timestamped. * - * The functions in this module are available when `OPENTHREAD_CONFIG_HISTOR_TRACKER_ENABLE` is enabled. + * The functions in this module are available when `OPENTHREAD_CONFIG_HISTORY_TRACKER_ENABLE` is enabled. * * @{ * @@ -60,7 +60,7 @@ extern "C" { #define OT_HISTORY_TRACKER_ENTRY_AGE_STRING_SIZE 21 ///< Recommended size for string representation of an entry age. /** - * This type represents an iterator to iterate through a history list. + * Represents an iterator to iterate through a history list. * * The fields in this type are opaque (intended for use by OpenThread core) and therefore should not be accessed/used * by caller. @@ -75,7 +75,7 @@ typedef struct otHistoryTrackerIterator } otHistoryTrackerIterator; /** - * This structure represents Thread network info. + * Represents Thread network info. * */ typedef struct otHistoryTrackerNetworkInfo @@ -87,7 +87,7 @@ typedef struct otHistoryTrackerNetworkInfo } otHistoryTrackerNetworkInfo; /** - * This enumeration defines the events for an IPv6 (unicast or multicast) address info (i.e., whether address is added + * Defines the events for an IPv6 (unicast or multicast) address info (i.e., whether address is added * or removed). * */ @@ -98,7 +98,7 @@ typedef enum } otHistoryTrackerAddressEvent; /** - * This structure represent a unicast IPv6 address info. + * Represent a unicast IPv6 address info. * */ typedef struct otHistoryTrackerUnicastAddressInfo @@ -114,7 +114,7 @@ typedef struct otHistoryTrackerUnicastAddressInfo } otHistoryTrackerUnicastAddressInfo; /** - * This structure represent an IPv6 multicast address info. + * Represent an IPv6 multicast address info. * */ typedef struct otHistoryTrackerMulticastAddressInfo @@ -137,7 +137,7 @@ enum }; /** - * This structure represents a RX/TX IPv6 message info. + * Represents a RX/TX IPv6 message info. * * Some of the fields in this struct are applicable to a RX message or a TX message only, e.g., `mAveRxRss` is the * average RSS of all fragment frames that form a received message and is only applicable for a RX message. @@ -152,7 +152,7 @@ typedef struct otHistoryTrackerMessageInfo uint16_t mChecksum; ///< Message checksum (valid only for UDP/TCP/ICMP6). uint8_t mIpProto; ///< IP Protocol number (`OT_IP6_PROTO_*` enumeration). uint8_t mIcmp6Type; ///< ICMP6 type if msg is ICMP6, zero otherwise (`OT_ICMP6_TYPE_*` enumeration). - int8_t mAveRxRss; ///< RSS of received message or OT_RADIO_INVALI_RSSI if not known. + int8_t mAveRxRss; ///< RSS of received message or OT_RADIO_INVALID_RSSI if not known. bool mLinkSecurity : 1; ///< Indicates whether msg used link security. bool mTxSuccess : 1; ///< Indicates TX success (e.g., ack received). Applicable for TX msg only. uint8_t mPriority : 2; ///< Message priority (`OT_HISTORY_TRACKER_MSG_PRIORITY_*` enumeration). @@ -161,7 +161,7 @@ typedef struct otHistoryTrackerMessageInfo } otHistoryTrackerMessageInfo; /** - * This enumeration defines the events in a neighbor info (i.e. whether neighbor is added, removed, or changed). + * Defines the events in a neighbor info (i.e. whether neighbor is added, removed, or changed). * * Event `OT_HISTORY_TRACKER_NEIGHBOR_EVENT_RESTORING` is applicable to child neighbors only. It is triggered after * the device (re)starts and when the previous children list is retrieved from non-volatile settings and the device @@ -177,7 +177,7 @@ typedef enum } otHistoryTrackerNeighborEvent; /** - * This structure represents a neighbor info. + * Represents a neighbor info. * */ typedef struct otHistoryTrackerNeighborInfo @@ -193,7 +193,7 @@ typedef struct otHistoryTrackerNeighborInfo } otHistoryTrackerNeighborInfo; /** - * This enumeration defines the events in a router info (i.e. whether router is added, removed, or changed). + * Defines the events in a router info (i.e. whether router is added, removed, or changed). * */ typedef enum @@ -209,7 +209,7 @@ typedef enum #define OT_HISTORY_TRACKER_INFINITE_PATH_COST 0 ///< Infinite path cost - used in `otHistoryTrackerRouterInfo`. /** - * This structure represents a router table entry event. + * Represents a router table entry event. * */ typedef struct otHistoryTrackerRouterInfo @@ -222,7 +222,7 @@ typedef struct otHistoryTrackerRouterInfo } otHistoryTrackerRouterInfo; /** - * This enumeration defines the events for a Network Data entry (i.e., whether an entry is added or removed). + * Defines the events for a Network Data entry (i.e., whether an entry is added or removed). * */ typedef enum @@ -232,7 +232,7 @@ typedef enum } otHistoryTrackerNetDataEvent; /** - * This structure represent a Network Data on mesh prefix info. + * Represent a Network Data on mesh prefix info. * */ typedef struct otHistoryTrackerOnMeshPrefixInfo @@ -242,7 +242,7 @@ typedef struct otHistoryTrackerOnMeshPrefixInfo } otHistoryTrackerOnMeshPrefixInfo; /** - * This structure represent a Network Data extern route info. + * Represent a Network Data extern route info. * */ typedef struct otHistoryTrackerExternalRouteInfo @@ -252,7 +252,7 @@ typedef struct otHistoryTrackerExternalRouteInfo } otHistoryTrackerExternalRouteInfo; /** - * This function initializes an `otHistoryTrackerIterator`. + * Initializes an `otHistoryTrackerIterator`. * * An iterator MUST be initialized before it is used. * @@ -268,7 +268,7 @@ typedef struct otHistoryTrackerExternalRouteInfo void otHistoryTrackerInitIterator(otHistoryTrackerIterator *aIterator); /** - * This function iterates over the entries in the network info history list. + * Iterates over the entries in the network info history list. * * @param[in] aInstance A pointer to the OpenThread instance. * @param[in,out] aIterator A pointer to an iterator. MUST be initialized or the behavior is undefined. @@ -285,7 +285,7 @@ const otHistoryTrackerNetworkInfo *otHistoryTrackerIterateNetInfoHistory(otInsta uint32_t *aEntryAge); /** - * This function iterates over the entries in the unicast address history list. + * Iterates over the entries in the unicast address history list. * * @param[in] aInstance A pointer to the OpenThread instance. * @param[in,out] aIterator A pointer to an iterator. MUST be initialized or the behavior is undefined. @@ -303,7 +303,7 @@ const otHistoryTrackerUnicastAddressInfo *otHistoryTrackerIterateUnicastAddressH uint32_t *aEntryAge); /** - * This function iterates over the entries in the multicast address history list. + * Iterates over the entries in the multicast address history list. * * @param[in] aInstance A pointer to the OpenThread instance. * @param[in,out] aIterator A pointer to an iterator. MUST be initialized or the behavior is undefined. @@ -321,7 +321,7 @@ const otHistoryTrackerMulticastAddressInfo *otHistoryTrackerIterateMulticastAddr uint32_t *aEntryAge); /** - * This function iterates over the entries in the RX message history list. + * Iterates over the entries in the RX message history list. * * @param[in] aInstance A pointer to the OpenThread instance. * @param[in,out] aIterator A pointer to an iterator. MUST be initialized or the behavior is undefined. @@ -338,7 +338,7 @@ const otHistoryTrackerMessageInfo *otHistoryTrackerIterateRxHistory(otInstance uint32_t *aEntryAge); /** - * This function iterates over the entries in the TX message history list. + * Iterates over the entries in the TX message history list. * * @param[in] aInstance A pointer to the OpenThread instance. * @param[in,out] aIterator A pointer to an iterator. MUST be initialized or the behavior is undefined. @@ -355,7 +355,7 @@ const otHistoryTrackerMessageInfo *otHistoryTrackerIterateTxHistory(otInstance uint32_t *aEntryAge); /** - * This function iterates over the entries in the neighbor history list. + * Iterates over the entries in the neighbor history list. * * @param[in] aInstance A pointer to the OpenThread instance. * @param[in,out] aIterator A pointer to an iterator. MUST be initialized or the behavior is undefined. @@ -372,7 +372,7 @@ const otHistoryTrackerNeighborInfo *otHistoryTrackerIterateNeighborHistory(otIns uint32_t *aEntryAge); /** - * This function iterates over the entries in the router history list. + * Iterates over the entries in the router history list. * * @param[in] aInstance A pointer to the OpenThread instance. * @param[in,out] aIterator A pointer to an iterator. MUST be initialized or the behavior is undefined. @@ -389,7 +389,7 @@ const otHistoryTrackerRouterInfo *otHistoryTrackerIterateRouterHistory(otInstanc uint32_t *aEntryAge); /** - * This function iterates over the entries in the Network Data on mesh prefix entry history list. + * Iterates over the entries in the Network Data on mesh prefix entry history list. * * @param[in] aInstance A pointer to the OpenThread instance. * @param[in,out] aIterator A pointer to an iterator. MUST be initialized or the behavior is undefined. @@ -406,7 +406,7 @@ const otHistoryTrackerOnMeshPrefixInfo *otHistoryTrackerIterateOnMeshPrefixHisto uint32_t *aEntryAge); /** - * This function iterates over the entries in the Network Data external route entry history list. + * Iterates over the entries in the Network Data external route entry history list. * * @param[in] aInstance A pointer to the OpenThread instance. * @param[in,out] aIterator A pointer to an iterator. MUST be initialized or the behavior is undefined. @@ -424,7 +424,7 @@ const otHistoryTrackerExternalRouteInfo *otHistoryTrackerIterateExternalRouteHis uint32_t *aEntryAge); /** - * This function converts a given entry age to a human-readable string. + * Converts a given entry age to a human-readable string. * * The entry age string follows the format "::." for hours, minutes, seconds and millisecond (if * shorter than one day) or "
days ::." (if longer than one day). diff --git a/openthread/include/openthread/icmp6.h b/openthread/include/openthread/icmp6.h index 38bd6a6a16..32f8c6a1b5 100644 --- a/openthread/include/openthread/icmp6.h +++ b/openthread/include/openthread/icmp6.h @@ -80,12 +80,13 @@ typedef enum otIcmp6Code OT_ICMP6_CODE_FRAGM_REAS_TIME_EX = 1, ///< Fragment Reassembly Time Exceeded } otIcmp6Code; -#define OT_ICMP6_HEADER_DATA_SIZE 4 ///< Size of an message specific data of ICMPv6 Header. +#define OT_ICMP6_HEADER_DATA_SIZE 4 ///< Size of ICMPv6 Header. +#define OT_ICMP6_ROUTER_ADVERT_MIN_SIZE 16 ///< Size of a Router Advertisement message without any options. /** * @struct otIcmp6Header * - * This structure represents an ICMPv6 header. + * Represents an ICMPv6 header. * */ OT_TOOL_PACKED_BEGIN @@ -103,7 +104,7 @@ struct otIcmp6Header } OT_TOOL_PACKED_END; /** - * This type represents an ICMPv6 header. + * Represents an ICMPv6 header. * */ typedef struct otIcmp6Header otIcmp6Header; @@ -123,7 +124,7 @@ typedef void (*otIcmp6ReceiveCallback)(void *aContext, const otIcmp6Header *aIcmpHeader); /** - * This structure implements ICMPv6 message handler. + * Implements ICMPv6 message handler. * */ typedef struct otIcmp6Handler @@ -146,7 +147,7 @@ typedef enum otIcmp6EchoMode } otIcmp6EchoMode; /** - * This function indicates whether or not ICMPv6 Echo processing is enabled. + * Indicates whether or not ICMPv6 Echo processing is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -159,7 +160,7 @@ typedef enum otIcmp6EchoMode otIcmp6EchoMode otIcmp6GetEchoMode(otInstance *aInstance); /** - * This function sets whether or not ICMPv6 Echo processing is enabled. + * Sets whether or not ICMPv6 Echo processing is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aMode The ICMPv6 Echo processing mode. @@ -168,7 +169,7 @@ otIcmp6EchoMode otIcmp6GetEchoMode(otInstance *aInstance); void otIcmp6SetEchoMode(otInstance *aInstance, otIcmp6EchoMode aMode); /** - * This function registers a handler to provide received ICMPv6 messages. + * Registers a handler to provide received ICMPv6 messages. * * @note A handler structure @p aHandler has to be stored in persistent (static) memory. * OpenThread does not make a copy of handler structure. @@ -181,7 +182,7 @@ void otIcmp6SetEchoMode(otInstance *aInstance, otIcmp6EchoMode aMode); otError otIcmp6RegisterHandler(otInstance *aInstance, otIcmp6Handler *aHandler); /** - * This function sends an ICMPv6 Echo Request via the Thread interface. + * Sends an ICMPv6 Echo Request via the Thread interface. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aMessage A pointer to the message buffer containing the ICMPv6 payload. diff --git a/openthread/include/openthread/instance.h b/openthread/include/openthread/instance.h index 85fb2d8e5f..d450a02186 100644 --- a/openthread/include/openthread/instance.h +++ b/openthread/include/openthread/instance.h @@ -53,7 +53,7 @@ extern "C" { * @note This number versions both OpenThread platform and user APIs. * */ -#define OPENTHREAD_API_VERSION (287) +#define OPENTHREAD_API_VERSION (363) /** * @addtogroup api-instance @@ -66,17 +66,17 @@ extern "C" { */ /** - * This structure represents the OpenThread instance structure. + * Represents the OpenThread instance structure. */ typedef struct otInstance otInstance; /** - * This function initializes the OpenThread library. + * Initializes the OpenThread library. * - * This function initializes OpenThread and prepares it for subsequent OpenThread API calls. This function must be + * Initializes OpenThread and prepares it for subsequent OpenThread API calls. This function must be * called before any other calls to OpenThread. * - * This function is available and can only be used when support for multiple OpenThread instances is enabled. + * Is available and can only be used when support for multiple OpenThread instances is enabled. * * @param[in] aInstanceBuffer The buffer for OpenThread to use for allocating the otInstance structure. * @param[in,out] aInstanceBufferSize On input, the size of aInstanceBuffer. On output, if not enough space for @@ -90,12 +90,12 @@ typedef struct otInstance otInstance; otInstance *otInstanceInit(void *aInstanceBuffer, size_t *aInstanceBufferSize); /** - * This function initializes the static single instance of the OpenThread library. + * Initializes the static single instance of the OpenThread library. * - * This function initializes OpenThread and prepares it for subsequent OpenThread API calls. This function must be + * Initializes OpenThread and prepares it for subsequent OpenThread API calls. This function must be * called before any other calls to OpenThread. * - * This function is available and can only be used when support for multiple OpenThread instances is disabled. + * Is available and can only be used when support for multiple OpenThread instances is disabled. * * @returns A pointer to the single OpenThread instance. * @@ -103,7 +103,18 @@ otInstance *otInstanceInit(void *aInstanceBuffer, size_t *aInstanceBufferSize); otInstance *otInstanceInitSingle(void); /** - * This function indicates whether or not the instance is valid/initialized. + * Gets the instance identifier. + * + * The instance identifier is set to a random value when the instance is constructed, and then its value will not + * change after initialization. + * + * @returns The instance identifier. + * + */ +uint32_t otInstanceGetId(otInstance *aInstance); + +/** + * Indicates whether or not the instance is valid/initialized. * * The instance is considered valid if it is acquired and initialized using either `otInstanceInitSingle()` (in single * instance case) or `otInstanceInit()` (in multi instance case). A subsequent call to `otInstanceFinalize()` causes @@ -117,7 +128,7 @@ otInstance *otInstanceInitSingle(void); bool otInstanceIsInitialized(otInstance *aInstance); /** - * This function disables the OpenThread library. + * Disables the OpenThread library. * * Call this function when OpenThread is no longer in use. * @@ -127,9 +138,9 @@ bool otInstanceIsInitialized(otInstance *aInstance); void otInstanceFinalize(otInstance *aInstance); /** - * This function returns the current instance uptime (in msec). + * Returns the current instance uptime (in msec). * - * This function requires `OPENTHREAD_CONFIG_UPTIME_ENABLE` to be enabled. + * Requires `OPENTHREAD_CONFIG_UPTIME_ENABLE` to be enabled. * * The uptime is given as number of milliseconds since OpenThread instance was initialized. * @@ -143,9 +154,9 @@ uint64_t otInstanceGetUptime(otInstance *aInstance); #define OT_UPTIME_STRING_SIZE 24 ///< Recommended size for string representation of uptime. /** - * This function returns the current instance uptime as a human-readable string. + * Returns the current instance uptime as a human-readable string. * - * This function requires `OPENTHREAD_CONFIG_UPTIME_ENABLE` to be enabled. + * Requires `OPENTHREAD_CONFIG_UPTIME_ENABLE` to be enabled. * * The string follows the format "::." for hours, minutes, seconds and millisecond (if uptime is * shorter than one day) or "
d.::." (if longer than a day). @@ -160,54 +171,48 @@ uint64_t otInstanceGetUptime(otInstance *aInstance); */ void otInstanceGetUptimeAsString(otInstance *aInstance, char *aBuffer, uint16_t aSize); -/** - * This enumeration defines flags that are passed as part of `otStateChangedCallback`. - * - */ -enum -{ - OT_CHANGED_IP6_ADDRESS_ADDED = 1 << 0, ///< IPv6 address was added - OT_CHANGED_IP6_ADDRESS_REMOVED = 1 << 1, ///< IPv6 address was removed - OT_CHANGED_THREAD_ROLE = 1 << 2, ///< Role (disabled, detached, child, router, leader) changed - OT_CHANGED_THREAD_LL_ADDR = 1 << 3, ///< The link-local address changed - OT_CHANGED_THREAD_ML_ADDR = 1 << 4, ///< The mesh-local address changed - OT_CHANGED_THREAD_RLOC_ADDED = 1 << 5, ///< RLOC was added - OT_CHANGED_THREAD_RLOC_REMOVED = 1 << 6, ///< RLOC was removed - OT_CHANGED_THREAD_PARTITION_ID = 1 << 7, ///< Partition ID changed - OT_CHANGED_THREAD_KEY_SEQUENCE_COUNTER = 1 << 8, ///< Thread Key Sequence changed - OT_CHANGED_THREAD_NETDATA = 1 << 9, ///< Thread Network Data changed - OT_CHANGED_THREAD_CHILD_ADDED = 1 << 10, ///< Child was added - OT_CHANGED_THREAD_CHILD_REMOVED = 1 << 11, ///< Child was removed - OT_CHANGED_IP6_MULTICAST_SUBSCRIBED = 1 << 12, ///< Subscribed to a IPv6 multicast address - OT_CHANGED_IP6_MULTICAST_UNSUBSCRIBED = 1 << 13, ///< Unsubscribed from a IPv6 multicast address - OT_CHANGED_THREAD_CHANNEL = 1 << 14, ///< Thread network channel changed - OT_CHANGED_THREAD_PANID = 1 << 15, ///< Thread network PAN Id changed - OT_CHANGED_THREAD_NETWORK_NAME = 1 << 16, ///< Thread network name changed - OT_CHANGED_THREAD_EXT_PANID = 1 << 17, ///< Thread network extended PAN ID changed - OT_CHANGED_NETWORK_KEY = 1 << 18, ///< Network key changed - OT_CHANGED_PSKC = 1 << 19, ///< PSKc changed - OT_CHANGED_SECURITY_POLICY = 1 << 20, ///< Security Policy changed - OT_CHANGED_CHANNEL_MANAGER_NEW_CHANNEL = 1 << 21, ///< Channel Manager new pending Thread channel changed - OT_CHANGED_SUPPORTED_CHANNEL_MASK = 1 << 22, ///< Supported channel mask changed - OT_CHANGED_COMMISSIONER_STATE = 1 << 23, ///< Commissioner state changed - OT_CHANGED_THREAD_NETIF_STATE = 1 << 24, ///< Thread network interface state changed - OT_CHANGED_THREAD_BACKBONE_ROUTER_STATE = 1 << 25, ///< Backbone Router state changed - OT_CHANGED_THREAD_BACKBONE_ROUTER_LOCAL = 1 << 26, ///< Local Backbone Router configuration changed - OT_CHANGED_JOINER_STATE = 1 << 27, ///< Joiner state changed - OT_CHANGED_ACTIVE_DATASET = 1 << 28, ///< Active Operational Dataset changed - OT_CHANGED_PENDING_DATASET = 1 << 29, ///< Pending Operational Dataset changed - OT_CHANGED_NAT64_TRANSLATOR_STATE = 1 << 30, ///< The state of NAT64 translator changed -}; +#define OT_CHANGED_IP6_ADDRESS_ADDED (1U << 0) ///< IPv6 address was added +#define OT_CHANGED_IP6_ADDRESS_REMOVED (1U << 1) ///< IPv6 address was removed +#define OT_CHANGED_THREAD_ROLE (1U << 2) ///< Role (disabled, detached, child, router, leader) changed +#define OT_CHANGED_THREAD_LL_ADDR (1U << 3) ///< The link-local address changed +#define OT_CHANGED_THREAD_ML_ADDR (1U << 4) ///< The mesh-local address changed +#define OT_CHANGED_THREAD_RLOC_ADDED (1U << 5) ///< RLOC was added +#define OT_CHANGED_THREAD_RLOC_REMOVED (1U << 6) ///< RLOC was removed +#define OT_CHANGED_THREAD_PARTITION_ID (1U << 7) ///< Partition ID changed +#define OT_CHANGED_THREAD_KEY_SEQUENCE_COUNTER (1U << 8) ///< Thread Key Sequence changed +#define OT_CHANGED_THREAD_NETDATA (1U << 9) ///< Thread Network Data changed +#define OT_CHANGED_THREAD_CHILD_ADDED (1U << 10) ///< Child was added +#define OT_CHANGED_THREAD_CHILD_REMOVED (1U << 11) ///< Child was removed +#define OT_CHANGED_IP6_MULTICAST_SUBSCRIBED (1U << 12) ///< Subscribed to a IPv6 multicast address +#define OT_CHANGED_IP6_MULTICAST_UNSUBSCRIBED (1U << 13) ///< Unsubscribed from a IPv6 multicast address +#define OT_CHANGED_THREAD_CHANNEL (1U << 14) ///< Thread network channel changed +#define OT_CHANGED_THREAD_PANID (1U << 15) ///< Thread network PAN Id changed +#define OT_CHANGED_THREAD_NETWORK_NAME (1U << 16) ///< Thread network name changed +#define OT_CHANGED_THREAD_EXT_PANID (1U << 17) ///< Thread network extended PAN ID changed +#define OT_CHANGED_NETWORK_KEY (1U << 18) ///< Network key changed +#define OT_CHANGED_PSKC (1U << 19) ///< PSKc changed +#define OT_CHANGED_SECURITY_POLICY (1U << 20) ///< Security Policy changed +#define OT_CHANGED_CHANNEL_MANAGER_NEW_CHANNEL (1U << 21) ///< Channel Manager new pending Thread channel changed +#define OT_CHANGED_SUPPORTED_CHANNEL_MASK (1U << 22) ///< Supported channel mask changed +#define OT_CHANGED_COMMISSIONER_STATE (1U << 23) ///< Commissioner state changed +#define OT_CHANGED_THREAD_NETIF_STATE (1U << 24) ///< Thread network interface state changed +#define OT_CHANGED_THREAD_BACKBONE_ROUTER_STATE (1U << 25) ///< Backbone Router state changed +#define OT_CHANGED_THREAD_BACKBONE_ROUTER_LOCAL (1U << 26) ///< Local Backbone Router configuration changed +#define OT_CHANGED_JOINER_STATE (1U << 27) ///< Joiner state changed +#define OT_CHANGED_ACTIVE_DATASET (1U << 28) ///< Active Operational Dataset changed +#define OT_CHANGED_PENDING_DATASET (1U << 29) ///< Pending Operational Dataset changed +#define OT_CHANGED_NAT64_TRANSLATOR_STATE (1U << 30) ///< The state of NAT64 translator changed +#define OT_CHANGED_PARENT_LINK_QUALITY (1U << 31) ///< Parent link quality changed /** - * This type represents a bit-field indicating specific state/configuration that has changed. See `OT_CHANGED_*` + * Represents a bit-field indicating specific state/configuration that has changed. See `OT_CHANGED_*` * definitions. * */ typedef uint32_t otChangedFlags; /** - * This function pointer is called to notify certain configuration or state changes within OpenThread. + * Pointer is called to notify certain configuration or state changes within OpenThread. * * @param[in] aFlags A bit-field indicating specific state that has changed. See `OT_CHANGED_*` definitions. * @param[in] aContext A pointer to application-specific context. @@ -216,7 +221,7 @@ typedef uint32_t otChangedFlags; typedef void (*otStateChangedCallback)(otChangedFlags aFlags, void *aContext); /** - * This function registers a callback to indicate when certain configuration or state changes within OpenThread. + * Registers a callback to indicate when certain configuration or state changes within OpenThread. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aCallback A pointer to a function that is called with certain configuration or state changes. @@ -230,7 +235,7 @@ typedef void (*otStateChangedCallback)(otChangedFlags aFlags, void *aContext); otError otSetStateChangedCallback(otInstance *aInstance, otStateChangedCallback aCallback, void *aContext); /** - * This function removes a callback to indicate when certain configuration or state changes within OpenThread. + * Removes a callback to indicate when certain configuration or state changes within OpenThread. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aCallback A pointer to a function that is called with certain configuration or state changes. @@ -240,7 +245,7 @@ otError otSetStateChangedCallback(otInstance *aInstance, otStateChangedCallback void otRemoveStateChangeCallback(otInstance *aInstance, otStateChangedCallback aCallback, void *aContext); /** - * This method triggers a platform reset. + * Triggers a platform reset. * * The reset process ensures that all the OpenThread state/info (stored in volatile memory) is erased. Note that the * `otPlatformReset` does not erase any persistent state/info saved in non-volatile memory. @@ -259,7 +264,7 @@ void otInstanceReset(otInstance *aInstance); void otInstanceFactoryReset(otInstance *aInstance); /** - * This method resets the internal states of the OpenThread radio stack. + * Resets the internal states of the OpenThread radio stack. * * Callbacks and configurations are preserved. * @@ -271,7 +276,7 @@ void otInstanceFactoryReset(otInstance *aInstance); void otInstanceResetRadioStack(otInstance *aInstance); /** - * This function erases all the OpenThread persistent info (network settings) stored on non-volatile memory. + * Erases all the OpenThread persistent info (network settings) stored on non-volatile memory. * Erase is successful only if the device is in `disabled` state/role. * * @param[in] aInstance A pointer to an OpenThread instance. @@ -283,7 +288,7 @@ void otInstanceResetRadioStack(otInstance *aInstance); otError otInstanceErasePersistentInfo(otInstance *aInstance); /** - * This function gets the OpenThread version string. + * Gets the OpenThread version string. * * @returns A pointer to the OpenThread version. * @@ -291,7 +296,7 @@ otError otInstanceErasePersistentInfo(otInstance *aInstance); const char *otGetVersionString(void); /** - * This function gets the OpenThread radio version string. + * Gets the OpenThread radio version string. * * @param[in] aInstance A pointer to an OpenThread instance. * diff --git a/openthread/include/openthread/ip6.h b/openthread/include/openthread/ip6.h index 5c38e3121f..35c11057e2 100644 --- a/openthread/include/openthread/ip6.h +++ b/openthread/include/openthread/ip6.h @@ -56,11 +56,13 @@ extern "C" { #define OT_IP6_PREFIX_BITSIZE (OT_IP6_PREFIX_SIZE * 8) ///< Size of an IPv6 prefix (bits) #define OT_IP6_IID_SIZE 8 ///< Size of an IPv6 Interface Identifier (bytes) #define OT_IP6_ADDRESS_SIZE 16 ///< Size of an IPv6 address (bytes) +#define OT_IP6_HEADER_SIZE 40 ///< Size of an IPv6 header (bytes) +#define OT_IP6_HEADER_PROTO_OFFSET 6 ///< Offset of the proto field in the IPv6 header (bytes) /** * @struct otIp6InterfaceIdentifier * - * This structure represents the Interface Identifier of an IPv6 address. + * Represents the Interface Identifier of an IPv6 address. * */ OT_TOOL_PACKED_BEGIN @@ -75,7 +77,7 @@ struct otIp6InterfaceIdentifier } OT_TOOL_PACKED_END; /** - * This structure represents the Interface Identifier of an IPv6 address. + * Represents the Interface Identifier of an IPv6 address. * */ typedef struct otIp6InterfaceIdentifier otIp6InterfaceIdentifier; @@ -83,7 +85,7 @@ typedef struct otIp6InterfaceIdentifier otIp6InterfaceIdentifier; /** * @struct otIp6NetworkPrefix * - * This structure represents the Network Prefix of an IPv6 address (most significant 64 bits of the address). + * Represents the Network Prefix of an IPv6 address (most significant 64 bits of the address). * */ OT_TOOL_PACKED_BEGIN @@ -93,7 +95,7 @@ struct otIp6NetworkPrefix } OT_TOOL_PACKED_END; /** - * This structure represents the Network Prefix of an IPv6 address (most significant 64 bits of the address). + * Represents the Network Prefix of an IPv6 address (most significant 64 bits of the address). * */ typedef struct otIp6NetworkPrefix otIp6NetworkPrefix; @@ -101,7 +103,7 @@ typedef struct otIp6NetworkPrefix otIp6NetworkPrefix; /** * @struct otIp6AddressComponents * - * This structure represents the components of an IPv6 address. + * Represents the components of an IPv6 address. * */ OT_TOOL_PACKED_BEGIN @@ -112,7 +114,7 @@ struct otIp6AddressComponents } OT_TOOL_PACKED_END; /** - * This structure represents the components of an IPv6 address. + * Represents the components of an IPv6 address. * */ typedef struct otIp6AddressComponents otIp6AddressComponents; @@ -120,7 +122,7 @@ typedef struct otIp6AddressComponents otIp6AddressComponents; /** * @struct otIp6Address * - * This structure represents an IPv6 address. + * Represents an IPv6 address. * */ OT_TOOL_PACKED_BEGIN @@ -136,13 +138,13 @@ struct otIp6Address } OT_TOOL_PACKED_END; /** - * This structure represents an IPv6 address. + * Represents an IPv6 address. * */ typedef struct otIp6Address otIp6Address; /** - * This structure represents an IPv6 prefix. + * Represents an IPv6 prefix. * */ OT_TOOL_PACKED_BEGIN @@ -153,7 +155,7 @@ struct otIp6Prefix } OT_TOOL_PACKED_END; /** - * This structure represents an IPv6 prefix. + * Represents an IPv6 prefix. * */ typedef struct otIp6Prefix otIp6Prefix; @@ -171,7 +173,7 @@ enum }; /** - * This structure represents an IPv6 network interface unicast address. + * Represents an IPv6 network interface unicast address. * */ typedef struct otNetifAddress @@ -188,7 +190,7 @@ typedef struct otNetifAddress } otNetifAddress; /** - * This structure represents an IPv6 network interface multicast address. + * Represents an IPv6 network interface multicast address. * */ typedef struct otNetifMulticastAddress @@ -198,7 +200,7 @@ typedef struct otNetifMulticastAddress } otNetifMulticastAddress; /** - * This structure represents an IPv6 socket address. + * Represents an IPv6 socket address. * */ typedef struct otSockAddr @@ -220,7 +222,7 @@ enum }; /** - * This structure represents the local and peer IPv6 socket addresses. + * Represents the local and peer IPv6 socket addresses. * */ typedef struct otMessageInfo @@ -420,7 +422,7 @@ otMessage *otIp6NewMessageFromBuffer(otInstance *aInstance, const otMessageSettings *aSettings); /** - * This function pointer is called when an IPv6 datagram is received. + * Pointer is called when an IPv6 datagram 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 @@ -431,7 +433,7 @@ otMessage *otIp6NewMessageFromBuffer(otInstance *aInstance, typedef void (*otIp6ReceiveCallback)(otMessage *aMessage, void *aContext); /** - * This function registers a callback to provide received IPv6 datagrams. + * Registers a callback to provide received IPv6 datagrams. * * By default, this callback does not pass Thread control traffic. See otIp6SetReceiveFilterEnabled() to * change the Thread control traffic filter setting. @@ -450,7 +452,7 @@ void otIp6SetReceiveCallback(otInstance *aInstance, otIp6ReceiveCallback aCallba /** * @struct otIp6AddressInfo * - * This structure represents IPv6 address information. + * Represents IPv6 address information. * */ typedef struct otIp6AddressInfo @@ -462,7 +464,7 @@ typedef struct otIp6AddressInfo } otIp6AddressInfo; /** - * This function pointer is called when an internal IPv6 address is added or removed. + * Pointer is called when an internal IPv6 address is added or removed. * * @param[in] aAddressInfo A pointer to the IPv6 address information. * @param[in] aIsAdded TRUE if the @p aAddress was added, FALSE if @p aAddress was removed. @@ -472,7 +474,7 @@ typedef struct otIp6AddressInfo typedef void (*otIp6AddressCallback)(const otIp6AddressInfo *aAddressInfo, bool aIsAdded, void *aContext); /** - * This function registers a callback to notify internal IPv6 address changes. + * Registers a callback to notify internal IPv6 address changes. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aCallback A pointer to a function that is called when an internal IPv6 address is added or @@ -483,7 +485,7 @@ typedef void (*otIp6AddressCallback)(const otIp6AddressInfo *aAddressInfo, bool void otIp6SetAddressCallback(otInstance *aInstance, otIp6AddressCallback aCallback, void *aCallbackContext); /** - * This function indicates whether or not Thread control traffic is filtered out when delivering IPv6 datagrams + * Indicates whether or not Thread control traffic is filtered out when delivering IPv6 datagrams * via the callback specified in otIp6SetReceiveCallback(). * * @param[in] aInstance A pointer to an OpenThread instance. @@ -497,7 +499,7 @@ void otIp6SetAddressCallback(otInstance *aInstance, otIp6AddressCallback aCallba bool otIp6IsReceiveFilterEnabled(otInstance *aInstance); /** - * This function sets whether or not Thread control traffic is filtered out when delivering IPv6 datagrams + * Sets whether or not Thread control traffic is filtered out when delivering IPv6 datagrams * via the callback specified in otIp6SetReceiveCallback(). * * @param[in] aInstance A pointer to an OpenThread instance. @@ -510,7 +512,7 @@ bool otIp6IsReceiveFilterEnabled(otInstance *aInstance); void otIp6SetReceiveFilterEnabled(otInstance *aInstance, bool aEnabled); /** - * This function sends an IPv6 datagram via the Thread interface. + * Sends an IPv6 datagram 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. @@ -525,12 +527,14 @@ void otIp6SetReceiveFilterEnabled(otInstance *aInstance, bool aEnabled); * @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. + * @retval OT_ERROR_INVALID_ARGS The message's metadata is invalid, e.g. the message uses + * `OT_MESSAGE_ORIGIN_THREAD_NETIF` as the origin. * */ otError otIp6Send(otInstance *aInstance, otMessage *aMessage); /** - * This function adds a port to the allowed unsecured port list. + * Adds a port to the allowed unsecured port list. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aPort The port value. @@ -543,7 +547,7 @@ otError otIp6Send(otInstance *aInstance, otMessage *aMessage); otError otIp6AddUnsecurePort(otInstance *aInstance, uint16_t aPort); /** - * This function removes a port from the allowed unsecure port list. + * Removes a port from the allowed unsecure port list. * * @note This function removes @p aPort by overwriting @p aPort with the element after @p aPort in the internal port * list. Be careful when calling otIp6GetUnsecurePorts() followed by otIp6RemoveUnsecurePort() to remove unsecure @@ -560,7 +564,7 @@ otError otIp6AddUnsecurePort(otInstance *aInstance, uint16_t aPort); otError otIp6RemoveUnsecurePort(otInstance *aInstance, uint16_t aPort); /** - * This function removes all ports from the allowed unsecure port list. + * Removes all ports from the allowed unsecure port list. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -568,7 +572,7 @@ otError otIp6RemoveUnsecurePort(otInstance *aInstance, uint16_t aPort); void otIp6RemoveAllUnsecurePorts(otInstance *aInstance); /** - * This function returns a pointer to the unsecure port list. + * Returns a pointer to the unsecure port list. * * @note Port value 0 is used to indicate an invalid entry. * @@ -605,21 +609,36 @@ bool otIp6IsAddressEqual(const otIp6Address *aFirst, const otIp6Address *aSecond bool otIp6ArePrefixesEqual(const otIp6Prefix *aFirst, const otIp6Prefix *aSecond); /** - * This function converts a human-readable IPv6 address string into a binary representation. + * Converts a human-readable IPv6 address string into a binary representation. * * @param[in] aString A pointer to a NULL-terminated string. * @param[out] aAddress A pointer to an IPv6 address. * - * @retval OT_ERROR_NONE Successfully parsed the string. - * @retval OT_ERROR_INVALID_ARGS Failed to parse the string. + * @retval OT_ERROR_NONE Successfully parsed @p aString and updated @p aAddress. + * @retval OT_ERROR_PARSE Failed to parse @p aString as an IPv6 address. * */ otError otIp6AddressFromString(const char *aString, otIp6Address *aAddress); +/** + * Converts a human-readable IPv6 prefix string into a binary representation. + * + * The @p aString parameter should be a string in the format "
/", where `
` is an IPv6 + * address and `` is a prefix length. + * + * @param[in] aString A pointer to a NULL-terminated string. + * @param[out] aPrefix A pointer to an IPv6 prefix. + * + * @retval OT_ERROR_NONE Successfully parsed the string as an IPv6 prefix and updated @p aPrefix. + * @retval OT_ERROR_PARSE Failed to parse @p aString as an IPv6 prefix. + * + */ +otError otIp6PrefixFromString(const char *aString, otIp6Prefix *aPrefix); + #define OT_IP6_ADDRESS_STRING_SIZE 40 ///< Recommended size for string representation of an IPv6 address. /** - * This function converts a given IPv6 address to a human-readable string. + * Converts a given IPv6 address to a human-readable string. * * The IPv6 address string is formatted as 16 hex values separated by ':' (i.e., "%x:%x:%x:...:%x"). * @@ -636,7 +655,7 @@ void otIp6AddressToString(const otIp6Address *aAddress, char *aBuffer, uint16_t #define OT_IP6_SOCK_ADDR_STRING_SIZE 48 ///< Recommended size for string representation of an IPv6 socket address. /** - * This function converts a given IPv6 socket address to a human-readable string. + * Converts a given IPv6 socket address to a human-readable string. * * The IPv6 socket address string is formatted as [`address`]:`port` where `address` is shown * as 16 hex values separated by `:` and `port` is the port number in decimal format, @@ -655,7 +674,7 @@ void otIp6SockAddrToString(const otSockAddr *aSockAddr, char *aBuffer, uint16_t #define OT_IP6_PREFIX_STRING_SIZE 45 ///< Recommended size for string representation of an IPv6 prefix. /** - * This function converts a given IPv6 prefix to a human-readable string. + * Converts a given IPv6 prefix to a human-readable string. * * The IPv6 address string is formatted as "%x:%x:%x:...[::]/plen". * @@ -670,7 +689,7 @@ void otIp6SockAddrToString(const otSockAddr *aSockAddr, char *aBuffer, uint16_t void otIp6PrefixToString(const otIp6Prefix *aPrefix, char *aBuffer, uint16_t aSize); /** - * This function returns the prefix match length (bits) for two IPv6 addresses. + * Returns the prefix match length (bits) for two IPv6 addresses. * * @param[in] aFirst A pointer to the first IPv6 address. * @param[in] aSecond A pointer to the second IPv6 address. @@ -681,7 +700,7 @@ void otIp6PrefixToString(const otIp6Prefix *aPrefix, char *aBuffer, uint16_t aSi uint8_t otIp6PrefixMatch(const otIp6Address *aFirst, const otIp6Address *aSecond); /** - * This method gets a prefix with @p aLength from @p aAddress. + * Gets a prefix with @p aLength from @p aAddress. * * @param[in] aAddress A pointer to an IPv6 address. * @param[in] aLength The length of prefix in bits. @@ -691,7 +710,7 @@ uint8_t otIp6PrefixMatch(const otIp6Address *aFirst, const otIp6Address *aSecond void otIp6GetPrefix(const otIp6Address *aAddress, uint8_t aLength, otIp6Prefix *aPrefix); /** - * This function indicates whether or not a given IPv6 address is the Unspecified Address. + * Indicates whether or not a given IPv6 address is the Unspecified Address. * * @param[in] aAddress A pointer to an IPv6 address. * @@ -702,7 +721,7 @@ void otIp6GetPrefix(const otIp6Address *aAddress, uint8_t aLength, otIp6Prefix * bool otIp6IsAddressUnspecified(const otIp6Address *aAddress); /** - * This function perform OpenThread source address selection. + * Perform OpenThread source address selection. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in,out] aMessageInfo A pointer to the message information. @@ -714,9 +733,9 @@ bool otIp6IsAddressUnspecified(const otIp6Address *aAddress); otError otIp6SelectSourceAddress(otInstance *aInstance, otMessageInfo *aMessageInfo); /** - * This function indicates whether the SLAAC module is enabled or not. + * Indicates whether the SLAAC module is enabled or not. * - * This function requires the build-time feature `OPENTHREAD_CONFIG_IP6_SLAAC_ENABLE` to be enabled. + * `OPENTHREAD_CONFIG_IP6_SLAAC_ENABLE` build-time feature must be enabled. * * @retval TRUE SLAAC module is enabled. * @retval FALSE SLAAC module is disabled. @@ -725,9 +744,9 @@ otError otIp6SelectSourceAddress(otInstance *aInstance, otMessageInfo *aMessageI bool otIp6IsSlaacEnabled(otInstance *aInstance); /** - * This function enables/disables the SLAAC module. + * Enables/disables the SLAAC module. * - * This function requires the build-time feature `OPENTHREAD_CONFIG_IP6_SLAAC_ENABLE` to be enabled. + * `OPENTHREAD_CONFIG_IP6_SLAAC_ENABLE` build-time feature must be enabled. * * When SLAAC module is enabled, SLAAC addresses (based on on-mesh prefixes in Network Data) are added to the interface. * When SLAAC module is disabled any previously added SLAAC address is removed. @@ -739,7 +758,7 @@ bool otIp6IsSlaacEnabled(otInstance *aInstance); void otIp6SetSlaacEnabled(otInstance *aInstance, bool aEnabled); /** - * This function pointer allows user to filter prefixes and not allow an SLAAC address based on a prefix to be added. + * Pointer allows user to filter prefixes and not allow an SLAAC address based on a prefix to be added. * * `otIp6SetSlaacPrefixFilter()` can be used to set the filter handler. The filter handler is invoked by SLAAC module * when it is about to add a SLAAC address based on a prefix. Its boolean return value determines whether the address @@ -755,9 +774,9 @@ void otIp6SetSlaacEnabled(otInstance *aInstance, bool aEnabled); typedef bool (*otIp6SlaacPrefixFilter)(otInstance *aInstance, const otIp6Prefix *aPrefix); /** - * This function sets the SLAAC module filter handler. + * Sets the SLAAC module filter handler. * - * This function requires the build-time feature `OPENTHREAD_CONFIG_IP6_SLAAC_ENABLE` to be enabled. + * `OPENTHREAD_CONFIG_IP6_SLAAC_ENABLE` build-time feature must be enabled. * * The filter handler is called by SLAAC module when it is about to add a SLAAC address based on a prefix to decide * whether the address should be added or not. @@ -773,7 +792,7 @@ typedef bool (*otIp6SlaacPrefixFilter)(otInstance *aInstance, const otIp6Prefix void otIp6SetSlaacPrefixFilter(otInstance *aInstance, otIp6SlaacPrefixFilter aFilter); /** - * This function pointer is called with results of `otIp6RegisterMulticastListeners`. + * Pointer is called with results of `otIp6RegisterMulticastListeners`. * * @param[in] aContext A pointer to the user context. * @param[in] aError OT_ERROR_NONE when successfully sent MLR.req and received MLR.rsp, @@ -795,10 +814,10 @@ typedef void (*otIp6RegisterMulticastListenersCallback)(void *aCon #define OT_IP6_MAX_MLR_ADDRESSES 15 ///< Max number of IPv6 addresses supported by Multicast Listener Registration. /** - * This function registers Multicast Listeners to Primary Backbone Router. + * Registers Multicast Listeners to Primary Backbone Router. * - * Note: only available when both `OPENTHREAD_CONFIG_TMF_PROXY_MLR_ENABLE` and - * `OPENTHREAD_CONFIG_COMMISSIONER_ENABLE` are enabled) + * `OPENTHREAD_CONFIG_TMF_PROXY_MLR_ENABLE` and `OPENTHREAD_CONFIG_COMMISSIONER_ENABLE` + * must be enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aAddresses A Multicast Address Array to register. @@ -828,9 +847,9 @@ otError otIp6RegisterMulticastListeners(otInstance * void *aContext); /** - * This function sets the Mesh Local IID (for test purpose). + * Sets the Mesh Local IID (for test purpose). * - * Only available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. + * `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` must be enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aIid A pointer to the Mesh Local IID to set. @@ -842,7 +861,7 @@ otError otIp6RegisterMulticastListeners(otInstance * otError otIp6SetMeshLocalIid(otInstance *aInstance, const otIp6InterfaceIdentifier *aIid); /** - * This function converts a given IP protocol number to a human-readable string. + * Converts a given IP protocol number to a human-readable string. * * @param[in] aIpProto An IP protocol number (`OT_IP6_PROTO_*` enumeration). * @@ -852,7 +871,7 @@ otError otIp6SetMeshLocalIid(otInstance *aInstance, const otIp6InterfaceIdentifi const char *otIp6ProtoToString(uint8_t aIpProto); /** - * This structure represents the counters for packets and bytes. + * Represents the counters for packets and bytes. * */ typedef struct otPacketsAndBytes @@ -862,7 +881,7 @@ typedef struct otPacketsAndBytes } otPacketsAndBytes; /** - * This structure represents the counters of packets forwarded via Border Routing. + * Represents the counters of packets forwarded via Border Routing. * */ typedef struct otBorderRoutingCounters @@ -882,7 +901,7 @@ typedef struct otBorderRoutingCounters /** * Gets the Border Routing counters. * - * This function requires the build-time feature `OPENTHREAD_CONFIG_IP6_BR_COUNTERS_ENABLE` to be enabled. + * `OPENTHREAD_CONFIG_IP6_BR_COUNTERS_ENABLE` build-time feature must be enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * diff --git a/openthread/include/openthread/jam_detection.h b/openthread/include/openthread/jam_detection.h index f27669ce00..e49f8b430e 100644 --- a/openthread/include/openthread/jam_detection.h +++ b/openthread/include/openthread/jam_detection.h @@ -55,7 +55,7 @@ extern "C" { */ /** - * This function pointer is called if signal jam detection is enabled and a jam is detected. + * Pointer is called if signal jam detection is enabled and a jam is detected. * * @param[in] aJamState Current jam state (`true` if jam is detected, `false` otherwise). * @param[in] aContext A pointer to application-specific context. diff --git a/openthread/include/openthread/joiner.h b/openthread/include/openthread/joiner.h index 586e88f548..7b8968455e 100644 --- a/openthread/include/openthread/joiner.h +++ b/openthread/include/openthread/joiner.h @@ -56,7 +56,7 @@ extern "C" { */ /** - * This enumeration defines the Joiner State. + * Defines the Joiner State. * */ typedef enum otJoinerState @@ -72,7 +72,7 @@ typedef enum otJoinerState #define OT_JOINER_MAX_DISCERNER_LENGTH 64 ///< Maximum length of a Joiner Discerner in bits. /** - * This structure represents a Joiner Discerner. + * Represents a Joiner Discerner. * */ typedef struct otJoinerDiscerner @@ -82,7 +82,7 @@ typedef struct otJoinerDiscerner } otJoinerDiscerner; /** - * This function pointer is called to notify the completion of a join operation. + * Pointer is called to notify the completion of a join operation. * * @param[in] aError OT_ERROR_NONE if the join process succeeded. * OT_ERROR_SECURITY if the join process failed due to security credentials. @@ -135,12 +135,7 @@ void otJoinerStop(otInstance *aInstance); * * @param[in] aInstance A pointer to an OpenThread instance. * - * @retval OT_JOINER_STATE_IDLE - * @retval OT_JOINER_STATE_DISCOVER - * @retval OT_JOINER_STATE_CONNECT - * @retval OT_JOINER_STATE_CONNECTED - * @retval OT_JOINER_STATE_ENTRUST - * @retval OT_JOINER_STATE_JOINED + * @returns The joiner state. * */ otJoinerState otJoinerGetState(otInstance *aInstance); @@ -188,7 +183,7 @@ otError otJoinerSetDiscerner(otInstance *aInstance, otJoinerDiscerner *aDiscerne const otJoinerDiscerner *otJoinerGetDiscerner(otInstance *aInstance); /** - * This function converts a given joiner state enumeration value to a human-readable string. + * Converts a given joiner state enumeration value to a human-readable string. * * @param[in] aState The joiner state. * diff --git a/openthread/include/openthread/link.h b/openthread/include/openthread/link.h index 289cf858ba..d48d5d4986 100644 --- a/openthread/include/openthread/link.h +++ b/openthread/include/openthread/link.h @@ -55,7 +55,7 @@ extern "C" { #define OT_US_PER_TEN_SYMBOLS OT_RADIO_TEN_SYMBOLS_TIME ///< Time for 10 symbols in units of microseconds /** - * This structure represents link-specific information for messages received from the Thread radio. + * Represents link-specific information for messages received from the Thread radio. * */ typedef struct otThreadLinkInfo @@ -97,7 +97,7 @@ typedef enum otMacFilterAddressMode } otMacFilterAddressMode; /** - * This structure represents a Mac Filter entry. + * Represents a Mac Filter entry. * */ typedef struct otMacFilterEntry @@ -107,7 +107,7 @@ typedef struct otMacFilterEntry } otMacFilterEntry; /** - * This structure represents the MAC layer counters. + * Represents the MAC layer counters. * */ typedef struct otMacCounters @@ -374,7 +374,7 @@ typedef struct otMacCounters } otMacCounters; /** - * This structure represents a received IEEE 802.15.4 Beacon. + * Represents a received IEEE 802.15.4 Beacon. * */ typedef struct otActiveScanResult @@ -398,7 +398,7 @@ typedef struct otActiveScanResult } otActiveScanResult; /** - * This structure represents an energy scan result. + * Represents an energy scan result. * */ typedef struct otEnergyScanResult @@ -408,7 +408,7 @@ typedef struct otEnergyScanResult } otEnergyScanResult; /** - * This function pointer is called during an IEEE 802.15.4 Active Scan when an IEEE 802.15.4 Beacon is received or + * Pointer is called during an IEEE 802.15.4 Active Scan when an IEEE 802.15.4 Beacon is received or * the scan completes. * * @param[in] aResult A valid pointer to the beacon information or NULL when the active scan completes. @@ -418,7 +418,7 @@ typedef struct otEnergyScanResult typedef void (*otHandleActiveScanResult)(otActiveScanResult *aResult, void *aContext); /** - * This function starts an IEEE 802.15.4 Active Scan + * Starts an IEEE 802.15.4 Active Scan * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aScanChannels A bit vector indicating which channels to scan (e.g. OT_CHANNEL_11_MASK). @@ -437,7 +437,7 @@ otError otLinkActiveScan(otInstance *aInstance, void *aCallbackContext); /** - * This function indicates whether or not an IEEE 802.15.4 Active Scan is currently in progress. + * Indicates whether or not an IEEE 802.15.4 Active Scan is currently in progress. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -446,7 +446,7 @@ otError otLinkActiveScan(otInstance *aInstance, bool otLinkIsActiveScanInProgress(otInstance *aInstance); /** - * This function pointer is called during an IEEE 802.15.4 Energy Scan when the result for a channel is ready or the + * Pointer is called during an IEEE 802.15.4 Energy Scan when the result for a channel is ready or the * scan completes. * * @param[in] aResult A valid pointer to the energy scan result information or NULL when the energy scan completes. @@ -456,7 +456,7 @@ bool otLinkIsActiveScanInProgress(otInstance *aInstance); typedef void (*otHandleEnergyScanResult)(otEnergyScanResult *aResult, void *aContext); /** - * This function starts an IEEE 802.15.4 Energy Scan + * Starts an IEEE 802.15.4 Energy Scan * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aScanChannels A bit vector indicating on which channels to perform energy scan. @@ -475,7 +475,7 @@ otError otLinkEnergyScan(otInstance *aInstance, void *aCallbackContext); /** - * This function indicates whether or not an IEEE 802.15.4 Energy Scan is currently in progress. + * Indicates whether or not an IEEE 802.15.4 Energy Scan is currently in progress. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -485,7 +485,7 @@ otError otLinkEnergyScan(otInstance *aInstance, bool otLinkIsEnergyScanInProgress(otInstance *aInstance); /** - * This function enqueues an IEEE 802.15.4 Data Request message for transmission. + * Enqueues an IEEE 802.15.4 Data Request message for transmission. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -497,7 +497,7 @@ bool otLinkIsEnergyScanInProgress(otInstance *aInstance); otError otLinkSendDataRequest(otInstance *aInstance); /** - * This function indicates whether or not an IEEE 802.15.4 MAC is in the transmit state. + * Indicates whether or not an IEEE 802.15.4 MAC is in the transmit state. * * MAC module is in the transmit state during CSMA/CA procedure, CCA, Data, Beacon or Data Request frame transmission * and receiving an ACK of a transmitted frame. MAC module is not in the transmit state during transmission of an ACK @@ -525,7 +525,7 @@ uint8_t otLinkGetChannel(otInstance *aInstance); /** * Set the IEEE 802.15.4 channel * - * This function succeeds only when Thread protocols are disabled. A successful call to this function invalidates the + * Succeeds only when Thread protocols are disabled. A successful call to this function invalidates the * Active and Pending Operational Datasets in non-volatile memory. * * @param[in] aInstance A pointer to an OpenThread instance. @@ -553,7 +553,7 @@ uint32_t otLinkGetSupportedChannelMask(otInstance *aInstance); /** * Set the supported channel mask of MAC layer. * - * This function succeeds only when Thread protocols are disabled. + * Succeeds only when Thread protocols are disabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aChannelMask The supported channel mask (bit 0 or lsb mapping to channel 0, and so on). @@ -613,7 +613,7 @@ otPanId otLinkGetPanId(otInstance *aInstance); /** * Set the IEEE 802.15.4 PAN ID. * - * This function succeeds only when Thread protocols are disabled. A successful call to this function also invalidates + * Succeeds only when Thread protocols are disabled. A successful call to this function also invalidates * the Active and Pending Operational Datasets in non-volatile memory. * * @param[in] aInstance A pointer to an OpenThread instance. @@ -674,7 +674,7 @@ otError otLinkSetPollPeriod(otInstance *aInstance, uint32_t aPollPeriod); otShortAddress otLinkGetShortAddress(otInstance *aInstance); /** - * This method returns the maximum number of frame retries during direct transmission. + * Returns the maximum number of frame retries during direct transmission. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -684,7 +684,7 @@ otShortAddress otLinkGetShortAddress(otInstance *aInstance); uint8_t otLinkGetMaxFrameRetriesDirect(otInstance *aInstance); /** - * This method sets the maximum number of frame retries during direct transmission. + * Sets the maximum number of frame retries during direct transmission. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aMaxFrameRetriesDirect The maximum number of retries during direct transmission. @@ -693,7 +693,7 @@ uint8_t otLinkGetMaxFrameRetriesDirect(otInstance *aInstance); void otLinkSetMaxFrameRetriesDirect(otInstance *aInstance, uint8_t aMaxFrameRetriesDirect); /** - * This method returns the maximum number of frame retries during indirect transmission. + * Returns the maximum number of frame retries during indirect transmission. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -703,7 +703,7 @@ void otLinkSetMaxFrameRetriesDirect(otInstance *aInstance, uint8_t aMaxFrameRetr uint8_t otLinkGetMaxFrameRetriesIndirect(otInstance *aInstance); /** - * This method sets the maximum number of frame retries during indirect transmission. + * Sets the maximum number of frame retries during indirect transmission. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aMaxFrameRetriesIndirect The maximum number of retries during indirect transmission. @@ -712,9 +712,9 @@ uint8_t otLinkGetMaxFrameRetriesIndirect(otInstance *aInstance); void otLinkSetMaxFrameRetriesIndirect(otInstance *aInstance, uint8_t aMaxFrameRetriesIndirect); /** - * This function gets the address mode of MAC filter. + * Gets the address mode of MAC filter. * - * This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -724,9 +724,9 @@ void otLinkSetMaxFrameRetriesIndirect(otInstance *aInstance, uint8_t aMaxFrameRe otMacFilterAddressMode otLinkFilterGetAddressMode(otInstance *aInstance); /** - * This function sets the address mode of MAC filter. + * Sets the address mode of MAC filter. * - * This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aMode The address mode to set. @@ -735,9 +735,9 @@ otMacFilterAddressMode otLinkFilterGetAddressMode(otInstance *aInstance); void otLinkFilterSetAddressMode(otInstance *aInstance, otMacFilterAddressMode aMode); /** - * This method adds an Extended Address to MAC filter. + * Adds an Extended Address to MAC filter. * - * This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aExtAddress A pointer to the Extended Address (MUST NOT be NULL). @@ -749,9 +749,9 @@ void otLinkFilterSetAddressMode(otInstance *aInstance, otMacFilterAddressMode aM otError otLinkFilterAddAddress(otInstance *aInstance, const otExtAddress *aExtAddress); /** - * This method removes an Extended Address from MAC filter. + * Removes an Extended Address from MAC filter. * - * This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * No action is performed if there is no existing entry in Filter matching the given Extended Address. * @@ -762,9 +762,9 @@ otError otLinkFilterAddAddress(otInstance *aInstance, const otExtAddress *aExtAd void otLinkFilterRemoveAddress(otInstance *aInstance, const otExtAddress *aExtAddress); /** - * This method clears all the Extended Addresses from MAC filter. + * Clears all the Extended Addresses from MAC filter. * - * This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -772,9 +772,9 @@ void otLinkFilterRemoveAddress(otInstance *aInstance, const otExtAddress *aExtAd void otLinkFilterClearAddresses(otInstance *aInstance); /** - * This method gets an in-use address filter entry. + * Gets an in-use address filter entry. * - * This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in,out] aIterator A pointer to the MAC filter iterator context. To get the first in-use address filter @@ -788,10 +788,14 @@ void otLinkFilterClearAddresses(otInstance *aInstance); otError otLinkFilterGetNextAddress(otInstance *aInstance, otMacFilterIterator *aIterator, otMacFilterEntry *aEntry); /** - * This method adds a fixed received signal strength (in dBm) entry for the messages from a given Extended Address in - * MAC Filter. + * Adds the specified Extended Address to the `RssIn` list (or modifies an existing + * address in the `RssIn` list) and sets the received signal strength (in dBm) entry + * for messages from that address. The Extended Address does not necessarily have + * to be in the `address allowlist/denylist` filter to set the `rss`. + * @note The `RssIn` list contains Extended Addresses whose `rss` or link quality indicator (`lqi`) + * values have been set to be different from the defaults. * - * This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aExtAddress A pointer to the IEEE 802.15.4 Extended Address. MUST NOT be NULL. @@ -804,11 +808,14 @@ otError otLinkFilterGetNextAddress(otInstance *aInstance, otMacFilterIterator *a otError otLinkFilterAddRssIn(otInstance *aInstance, const otExtAddress *aExtAddress, int8_t aRss); /** - * This method removes a MAC Filter entry for fixed received signal strength setting for a given Extended Address. + * Removes the specified Extended Address from the `RssIn` list. Once removed + * from the `RssIn` list, this MAC address will instead use the default `rss` + * and `lqi` settings, assuming defaults have been set. + * (If no defaults have been set, the over-air signal is used.) * - * This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * - * No action is performed if there is no existing entry in Filter matching the given Extended Address. + * No action is performed if there is no existing entry in the `RssIn` list matching the specified Extended Address. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aExtAddress A pointer to the IEEE 802.15.4 Extended Address. MUST NOT be NULL. @@ -817,9 +824,9 @@ otError otLinkFilterAddRssIn(otInstance *aInstance, const otExtAddress *aExtAddr void otLinkFilterRemoveRssIn(otInstance *aInstance, const otExtAddress *aExtAddress); /** - * This method sets the default received signal strength (in dBm) on MAC Filter. + * Sets the default received signal strength (in dBm) on MAC Filter. * - * This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * The default RSS value is used for all received frames from addresses for which there is no explicit RSS-IN entry * in the Filter list (added using `otLinkFilterAddRssIn()`). @@ -831,9 +838,9 @@ void otLinkFilterRemoveRssIn(otInstance *aInstance, const otExtAddress *aExtAddr void otLinkFilterSetDefaultRssIn(otInstance *aInstance, int8_t aRss); /** - * This method clears any previously set default received signal strength (in dBm) on MAC Filter. + * Clears any previously set default received signal strength (in dBm) on MAC Filter. * - * This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -841,9 +848,11 @@ void otLinkFilterSetDefaultRssIn(otInstance *aInstance, int8_t aRss); void otLinkFilterClearDefaultRssIn(otInstance *aInstance); /** - * This method clears all the received signal strength entries (including default RSS-in) on MAC Filter. + * Clears all the received signal strength (`rss`) and link quality + * indicator (`lqi`) entries (including defaults) from the `RssIn` list. + * Performing this action means that all Extended Addresses will use the on-air signal. * - * This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -851,9 +860,9 @@ void otLinkFilterClearDefaultRssIn(otInstance *aInstance); void otLinkFilterClearAllRssIn(otInstance *aInstance); /** - * This method gets an in-use RssIn filter entry. + * Gets an in-use RssIn filter entry. * - * This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in,out] aIterator A pointer to the MAC filter iterator context. MUST NOT be NULL. @@ -869,9 +878,9 @@ void otLinkFilterClearAllRssIn(otInstance *aInstance); otError otLinkFilterGetNextRssIn(otInstance *aInstance, otMacFilterIterator *aIterator, otMacFilterEntry *aEntry); /** - * This function enables/disables IEEE 802.15.4 radio filter mode. + * Enables/disables IEEE 802.15.4 radio filter mode. * - * This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * The radio filter is mainly intended for testing. It can be used to temporarily block all tx/rx on the 802.15.4 radio. * When radio filter is enabled, radio is put to sleep instead of receive (to ensure device does not receive any frame @@ -885,9 +894,9 @@ otError otLinkFilterGetNextRssIn(otInstance *aInstance, otMacFilterIterator *aIt void otLinkSetRadioFilterEnabled(otInstance *aInstance, bool aFilterEnabled); /** - * This function indicates whether the IEEE 802.15.4 radio filter is enabled or not. + * Indicates whether the IEEE 802.15.4 radio filter is enabled or not. * - * This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * @retval TRUE If the radio filter is enabled. * @retval FALSE If the radio filter is disabled. @@ -896,7 +905,7 @@ void otLinkSetRadioFilterEnabled(otInstance *aInstance, bool aFilterEnabled); bool otLinkIsRadioFilterEnabled(otInstance *aInstance); /** - * This method converts received signal strength to link quality. + * Converts received signal strength to link quality. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aRss The received signal strength value to be converted. @@ -907,7 +916,7 @@ bool otLinkIsRadioFilterEnabled(otInstance *aInstance); uint8_t otLinkConvertRssToLinkQuality(otInstance *aInstance, int8_t aRss); /** - * This method converts link quality to typical received signal strength. + * Converts link quality to typical received signal strength. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aLinkQuality LinkQuality value, should be in range [0,3]. @@ -918,9 +927,9 @@ uint8_t otLinkConvertRssToLinkQuality(otInstance *aInstance, int8_t aRss); int8_t otLinkConvertLinkQualityToRss(otInstance *aInstance, uint8_t aLinkQuality); /** - * This method gets histogram of retries for a single direct packet until success. + * Gets histogram of retries for a single direct packet until success. * - * This function is valid when OPENTHREAD_CONFIG_MAC_RETRY_SUCCESS_HISTOGRAM_ENABLE configuration is enabled. + * Is valid when OPENTHREAD_CONFIG_MAC_RETRY_SUCCESS_HISTOGRAM_ENABLE configuration is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[out] aNumberOfEntries A pointer to where the size of returned histogram array is placed. @@ -931,9 +940,9 @@ int8_t otLinkConvertLinkQualityToRss(otInstance *aInstance, uint8_t aLinkQuality const uint32_t *otLinkGetTxDirectRetrySuccessHistogram(otInstance *aInstance, uint8_t *aNumberOfEntries); /** - * This method gets histogram of retries for a single indirect packet until success. + * Gets histogram of retries for a single indirect packet until success. * - * This function is valid when OPENTHREAD_CONFIG_MAC_RETRY_SUCCESS_HISTOGRAM_ENABLE configuration is enabled. + * Is valid when OPENTHREAD_CONFIG_MAC_RETRY_SUCCESS_HISTOGRAM_ENABLE configuration is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[out] aNumberOfEntries A pointer to where the size of returned histogram array is placed. @@ -945,9 +954,9 @@ const uint32_t *otLinkGetTxDirectRetrySuccessHistogram(otInstance *aInstance, ui const uint32_t *otLinkGetTxIndirectRetrySuccessHistogram(otInstance *aInstance, uint8_t *aNumberOfEntries); /** - * This method clears histogram statistics for direct and indirect transmissions. + * Clears histogram statistics for direct and indirect transmissions. * - * This function is valid when OPENTHREAD_CONFIG_MAC_RETRY_SUCCESS_HISTOGRAM_ENABLE configuration is enabled. + * Is valid when OPENTHREAD_CONFIG_MAC_RETRY_SUCCESS_HISTOGRAM_ENABLE configuration is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -973,7 +982,7 @@ const otMacCounters *otLinkGetCounters(otInstance *aInstance); void otLinkResetCounters(otInstance *aInstance); /** - * This function pointer is called when an IEEE 802.15.4 frame is received. + * Pointer is called when an IEEE 802.15.4 frame is received. * * @note This callback is called after FCS processing and @p aFrame may not contain the actual FCS that was received. * @@ -987,7 +996,7 @@ void otLinkResetCounters(otInstance *aInstance); typedef void (*otLinkPcapCallback)(const otRadioFrame *aFrame, bool aIsTx, void *aContext); /** - * This function registers a callback to provide received raw IEEE 802.15.4 frames. + * Registers a callback to provide received raw IEEE 802.15.4 frames. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aPcapCallback A pointer to a function that is called when receiving an IEEE 802.15.4 link frame or @@ -998,18 +1007,18 @@ typedef void (*otLinkPcapCallback)(const otRadioFrame *aFrame, bool aIsTx, void void otLinkSetPcapCallback(otInstance *aInstance, otLinkPcapCallback aPcapCallback, void *aCallbackContext); /** - * This function indicates whether or not promiscuous mode is enabled at the link layer. + * Indicates whether or not promiscuous mode is enabled at the link layer. * * @param[in] aInstance A pointer to an OpenThread instance. * - * @retval true Promiscuous mode is enabled. - * @retval false Promiscuous mode is not enabled. + * @retval TRUE Promiscuous mode is enabled. + * @retval FALSE Promiscuous mode is not enabled. * */ bool otLinkIsPromiscuous(otInstance *aInstance); /** - * This function enables or disables the link layer promiscuous mode. + * Enables or disables the link layer promiscuous mode. * * @note Promiscuous mode may only be enabled when the Thread interface is disabled. * @@ -1024,14 +1033,14 @@ bool otLinkIsPromiscuous(otInstance *aInstance); otError otLinkSetPromiscuous(otInstance *aInstance, bool aPromiscuous); /** - * This function gets the CSL channel. + * Gets the CSL channel. * * @param[in] aInstance A pointer to an OpenThread instance. * * @returns The CSL channel. * */ -uint8_t otLinkCslGetChannel(otInstance *aInstance); +uint8_t otLinkGetCslChannel(otInstance *aInstance); /** * Sets the CSL channel. @@ -1044,39 +1053,50 @@ uint8_t otLinkCslGetChannel(otInstance *aInstance); * @retval OT_ERROR_INVALID_ARGS Invalid @p aChannel. * */ -otError otLinkCslSetChannel(otInstance *aInstance, uint8_t aChannel); +otError otLinkSetCslChannel(otInstance *aInstance, uint8_t aChannel); + +/** + * Represents CSL period ten symbols unit in microseconds. + * + * The CSL period (in micro seconds) MUST be a multiple of this value. + * + */ +#define OT_LINK_CSL_PERIOD_TEN_SYMBOLS_UNIT_IN_USEC (160) /** - * This function gets the CSL period. + * Gets the CSL period in microseconds * * @param[in] aInstance A pointer to an OpenThread instance. * - * @returns The CSL period in units of 10 symbols. + * @returns The CSL period in microseconds. * */ -uint16_t otLinkCslGetPeriod(otInstance *aInstance); +uint32_t otLinkGetCslPeriod(otInstance *aInstance); /** - * Sets the CSL period in units of 10 symbols. Disable CSL by setting this parameter to `0`. + * Sets the CSL period in microseconds. Disable CSL by setting this parameter to `0`. + * + * The CSL period MUST be a multiple of `OT_LINK_CSL_PERIOD_TEN_SYMBOLS_UNIT_IN_USEC`, otherwise `OT_ERROR_INVALID_ARGS` + * is returned. * * @param[in] aInstance A pointer to an OpenThread instance. - * @param[in] aPeriod The CSL period in units of 10 symbols. + * @param[in] aPeriod The CSL period in microseconds. * * @retval OT_ERROR_NONE Successfully set the CSL period. - * @retval OT_ERROR_INVALID_ARGS Invalid CSL period. + * @retval OT_ERROR_INVALID_ARGS Invalid CSL period * */ -otError otLinkCslSetPeriod(otInstance *aInstance, uint16_t aPeriod); +otError otLinkSetCslPeriod(otInstance *aInstance, uint32_t aPeriod); /** - * This function gets the CSL timeout. + * Gets the CSL timeout. * * @param[in] aInstance A pointer to an OpenThread instance. * * @returns The CSL timeout in seconds. * */ -uint32_t otLinkCslGetTimeout(otInstance *aInstance); +uint32_t otLinkGetCslTimeout(otInstance *aInstance); /** * Sets the CSL timeout in seconds. @@ -1088,10 +1108,10 @@ uint32_t otLinkCslGetTimeout(otInstance *aInstance); * @retval OT_ERROR_INVALID_ARGS Invalid CSL timeout. * */ -otError otLinkCslSetTimeout(otInstance *aInstance, uint32_t aTimeout); +otError otLinkSetCslTimeout(otInstance *aInstance, uint32_t aTimeout); /** - * This function returns the current CCA (Clear Channel Assessment) failure rate. + * Returns the current CCA (Clear Channel Assessment) failure rate. * * The rate is maintained over a window of (roughly) last `OPENTHREAD_CONFIG_CCA_FAILURE_RATE_AVERAGING_WINDOW` * frame transmissions. @@ -1102,7 +1122,7 @@ otError otLinkCslSetTimeout(otInstance *aInstance, uint32_t aTimeout); uint16_t otLinkGetCcaFailureRate(otInstance *aInstance); /** - * This function enables or disables the link layer. + * Enables or disables the link layer. * * @note The link layer may only be enabled / disabled when the Thread Interface is disabled. * @@ -1117,20 +1137,40 @@ uint16_t otLinkGetCcaFailureRate(otInstance *aInstance); otError otLinkSetEnabled(otInstance *aInstance, bool aEnable); /** - * This function indicates whether or not the link layer is enabled. + * Indicates whether or not the link layer is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * - * @retval true Link layer is enabled. - * @retval false Link layer is not enabled. + * @retval TRUE Link layer is enabled. + * @retval FALSE Link layer is not enabled. * */ bool otLinkIsEnabled(otInstance *aInstance); /** - * This function instructs the device to send an empty IEEE 802.15.4 data frame. + * Indicates whether or not CSL is enabled. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * + * @retval TRUE Link layer is CSL enabled. + * @retval FALSE Link layer is not CSL enabled. + * + */ +bool otLinkIsCslEnabled(otInstance *aInstance); + +/** + * Indicates whether the device is connected to a parent which supports CSL. + * + * @retval TRUE If parent supports CSL. + * @retval FALSE If parent does not support CSL. + * + */ +bool otLinkIsCslSupported(otInstance *aInstance); + +/** + * Instructs the device to send an empty IEEE 802.15.4 data frame. * - * This function is only supported on an Rx-Off-When-Idle device to send an empty data frame to its parent. + * Is only supported on an Rx-Off-When-Idle device to send an empty data frame to its parent. * Note: available only when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. diff --git a/openthread/include/openthread/link_metrics.h b/openthread/include/openthread/link_metrics.h index fc9a7f0091..3b6a76ac53 100644 --- a/openthread/include/openthread/link_metrics.h +++ b/openthread/include/openthread/link_metrics.h @@ -35,8 +35,6 @@ #ifndef LINK_METRICS_H_ #define LINK_METRICS_H_ -#include "openthread-core-config.h" - #include #include #include @@ -56,7 +54,7 @@ extern "C" { */ /** - * This structure represents the result (value) for a Link Metrics query. + * Represents the result (value) for a Link Metrics query. * */ typedef struct otLinkMetricsValues @@ -70,7 +68,7 @@ typedef struct otLinkMetricsValues } otLinkMetricsValues; /** - * This structure represents which frames are accounted in a Forward Tracking Series. + * Represents which frames are accounted in a Forward Tracking Series. * */ typedef struct otLinkMetricsSeriesFlags @@ -108,7 +106,7 @@ typedef enum otLinkMetricsStatus } otLinkMetricsStatus; /** - * This function pointer is called when a Link Metrics report is received. + * Pointer is called when a Link Metrics report is received. * * @param[in] aSource A pointer to the source address. * @param[in] aMetricsValues A pointer to the Link Metrics values (the query result). @@ -118,20 +116,22 @@ typedef enum otLinkMetricsStatus */ typedef void (*otLinkMetricsReportCallback)(const otIp6Address *aSource, const otLinkMetricsValues *aMetricsValues, - uint8_t aStatus, + otLinkMetricsStatus aStatus, void *aContext); /** - * This function pointer is called when a Link Metrics Management Response is received. + * Pointer is called when a Link Metrics Management Response is received. * * @param[in] aSource A pointer to the source address. * @param[in] aStatus The status code in the response. * @param[in] aContext A pointer to application-specific context. * */ -typedef void (*otLinkMetricsMgmtResponseCallback)(const otIp6Address *aSource, uint8_t aStatus, void *aContext); +typedef void (*otLinkMetricsMgmtResponseCallback)(const otIp6Address *aSource, + otLinkMetricsStatus aStatus, + void *aContext); /** - * This function pointer is called when Enh-ACK Probing IE is received. + * Pointer is called when Enh-ACK Probing IE is received. * * @param[in] aShortAddress The Mac short address of the Probing Subject. * @param[in] aExtAddress A pointer to the Mac extended address of the Probing Subject. @@ -145,7 +145,7 @@ typedef void (*otLinkMetricsEnhAckProbingIeReportCallback)(otShortAddress void *aContext); /** - * This function sends an MLE Data Request to query Link Metrics. + * Sends an MLE Data Request to query Link Metrics. * * It could be either Single Probe or Forward Tracking Series. * @@ -198,7 +198,7 @@ otError otLinkMetricsConfigForwardTrackingSeries(otInstance void *aCallbackContext); /** - * This function sends an MLE Link Metrics Management Request to configure/clear an Enhanced-ACK Based Probing. + * Sends an MLE Link Metrics Management Request to configure/clear an Enhanced-ACK Based Probing. * This functionality requires OT_LINK_METRICS_INITIATOR feature enabled. * * @param[in] aInstance A pointer to an OpenThread instance. @@ -247,6 +247,31 @@ otError otLinkMetricsSendLinkProbe(otInstance *aInstance, uint8_t aSeriesId, uint8_t aLength); +/** + * Enable or disable Link Metrics Manager. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aEnable A boolean indicating to enable or disable. + * + */ +void otLinkMetricsManagerSetEnabled(otInstance *aInstance, bool aEnable); + +/** + * Get Link Metrics data of a neighbor by its extended address. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aExtAddress A pointer to the Mac extended address of the Probing Subject. + * @param[out] aLinkMetricsValues A pointer to the Link Metrics values of the subject. + * + * @retval OT_ERROR_NONE Successfully got the Link Metrics data. + * @retval OT_ERROR_INVALID_ARGS The arguments are invalid. + * @retval OT_ERROR_NOT_FOUND No neighbor with the given extended address is found. + * + */ +otError otLinkMetricsManagerGetMetricsValueByExtAddr(otInstance *aInstance, + const otExtAddress *aExtAddress, + otLinkMetricsValues *aLinkMetricsValues); + /** * @} * diff --git a/openthread/include/openthread/link_raw.h b/openthread/include/openthread/link_raw.h index 461b81d7a2..c5ba5adba9 100644 --- a/openthread/include/openthread/link_raw.h +++ b/openthread/include/openthread/link_raw.h @@ -52,7 +52,7 @@ extern "C" { */ /** - * This function pointer on receipt of a IEEE 802.15.4 frame. + * Pointer on receipt of a IEEE 802.15.4 frame. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aFrame A pointer to the received frame or NULL if the receive operation was aborted. @@ -63,7 +63,7 @@ extern "C" { typedef void (*otLinkRawReceiveDone)(otInstance *aInstance, otRadioFrame *aFrame, otError aError); /** - * This function enables/disables the raw link-layer. + * Enables/disables the raw link-layer. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aCallback A pointer to a function called on receipt of a IEEE 802.15.4 frame. NULL to disable the @@ -77,7 +77,7 @@ typedef void (*otLinkRawReceiveDone)(otInstance *aInstance, otRadioFrame *aFrame otError otLinkRawSetReceiveDone(otInstance *aInstance, otLinkRawReceiveDone aCallback); /** - * This function indicates whether or not the raw link-layer is enabled. + * Indicates whether or not the raw link-layer is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -88,7 +88,7 @@ otError otLinkRawSetReceiveDone(otInstance *aInstance, otLinkRawReceiveDone aCal bool otLinkRawIsEnabled(otInstance *aInstance); /** - * This function gets the status of promiscuous mode. + * Gets the status of promiscuous mode. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -99,7 +99,7 @@ bool otLinkRawIsEnabled(otInstance *aInstance); bool otLinkRawGetPromiscuous(otInstance *aInstance); /** - * This function enables or disables promiscuous mode. + * Enables or disables promiscuous mode. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aEnable A value to enable or disable promiscuous mode. @@ -149,7 +149,7 @@ otError otLinkRawReceive(otInstance *aInstance); /** * The radio transitions from Transmit to Receive. - * This method returns a pointer to the transmit buffer. + * Returns a pointer to the transmit buffer. * * The caller forms the IEEE 802.15.4 frame in this buffer then calls otLinkRawTransmit() * to request transmission. @@ -162,7 +162,7 @@ otError otLinkRawReceive(otInstance *aInstance); otRadioFrame *otLinkRawGetTransmitBuffer(otInstance *aInstance); /** - * This function pointer on receipt of a IEEE 802.15.4 frame. + * Pointer on receipt of a IEEE 802.15.4 frame. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aFrame A pointer to the frame that was transmitted. @@ -180,7 +180,7 @@ typedef void (*otLinkRawTransmitDone)(otInstance *aInstance, otError aError); /** - * This method begins the transmit sequence on the radio. + * Begins the transmit sequence on the radio. * * The caller must form the IEEE 802.15.4 frame in the buffer provided by otLinkRawGetTransmitBuffer() before * requesting transmission. The channel and transmit power are also included in the otRadioFrame structure. @@ -219,7 +219,7 @@ int8_t otLinkRawGetRssi(otInstance *aInstance); otRadioCaps otLinkRawGetCaps(otInstance *aInstance); /** - * This function pointer on receipt of a IEEE 802.15.4 frame. + * Pointer on receipt of a IEEE 802.15.4 frame. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aEnergyScanMaxRssi The maximum RSSI encountered on the scanned channel. @@ -228,7 +228,7 @@ otRadioCaps otLinkRawGetCaps(otInstance *aInstance); typedef void (*otLinkRawEnergyScanDone)(otInstance *aInstance, int8_t aEnergyScanMaxRssi); /** - * This method begins the energy scan sequence on the radio. + * Begins the energy scan sequence on the radio. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aScanChannel The channel to perform the energy scan on. @@ -236,7 +236,7 @@ typedef void (*otLinkRawEnergyScanDone)(otInstance *aInstance, int8_t aEnergySca * @param[in] aCallback A pointer to a function called on completion of a scanned channel. * * @retval OT_ERROR_NONE Successfully started scanning the channel. - * @retval OT_ERROR_BUSY The radio is performing enery scanning. + * @retval OT_ERROR_BUSY The radio is performing energy scanning. * @retval OT_ERROR_NOT_IMPLEMENTED The radio doesn't support energy scanning. * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. * @@ -356,7 +356,7 @@ otError otLinkRawSetMacKey(otInstance *aInstance, /** * Sets the current MAC frame counter value. * - * This function always sets the MAC counter to the new given value @p aMacFrameCounter independent of the current + * Always sets the MAC counter to the new given value @p aMacFrameCounter independent of the current * value. * * @param[in] aInstance A pointer to an OpenThread instance. diff --git a/openthread/include/openthread/logging.h b/openthread/include/openthread/logging.h index b581b27021..143a0d5111 100644 --- a/openthread/include/openthread/logging.h +++ b/openthread/include/openthread/logging.h @@ -53,7 +53,7 @@ extern "C" { */ /** - * This function returns the current log level. + * Returns the current log level. * * If dynamic log level feature `OPENTHREAD_CONFIG_LOG_LEVEL_DYNAMIC_ENABLE` is enabled, this function returns the * currently set dynamic log level. Otherwise, this function returns the build-time configured log level. @@ -64,7 +64,7 @@ extern "C" { otLogLevel otLoggingGetLevel(void); /** - * This function sets the log level. + * Sets the log level. * * @note This function requires `OPENTHREAD_CONFIG_LOG_LEVEL_DYNAMIC_ENABLE=1`. * @@ -77,9 +77,9 @@ otLogLevel otLoggingGetLevel(void); otError otLoggingSetLevel(otLogLevel aLogLevel); /** - * This function emits a log message at critical log level. + * Emits a log message at critical log level. * - * This function is intended for use by platform. If `OPENTHREAD_CONFIG_LOG_PLATFORM` is not set or the current log + * Is intended for use by platform. If `OPENTHREAD_CONFIG_LOG_PLATFORM` is not set or the current log * level is below critical, this function does not emit any log message. * * @param[in] aFormat The format string. @@ -89,9 +89,9 @@ otError otLoggingSetLevel(otLogLevel aLogLevel); void otLogCritPlat(const char *aFormat, ...) OT_TOOL_PRINTF_STYLE_FORMAT_ARG_CHECK(1, 2); /** - * This function emits a log message at warning log level. + * Emits a log message at warning log level. * - * This function is intended for use by platform. If `OPENTHREAD_CONFIG_LOG_PLATFORM` is not set or the current log + * Is intended for use by platform. If `OPENTHREAD_CONFIG_LOG_PLATFORM` is not set or the current log * level is below warning, this function does not emit any log message. * * @param[in] aFormat The format string. @@ -101,9 +101,9 @@ void otLogCritPlat(const char *aFormat, ...) OT_TOOL_PRINTF_STYLE_FORMAT_ARG_CHE void otLogWarnPlat(const char *aFormat, ...) OT_TOOL_PRINTF_STYLE_FORMAT_ARG_CHECK(1, 2); /** - * This function emits a log message at note log level. + * Emits a log message at note log level. * - * This function is intended for use by platform. If `OPENTHREAD_CONFIG_LOG_PLATFORM` is not set or the current log + * Is intended for use by platform. If `OPENTHREAD_CONFIG_LOG_PLATFORM` is not set or the current log * level is below note, this function does not emit any log message. * * @param[in] aFormat The format string. @@ -113,9 +113,9 @@ void otLogWarnPlat(const char *aFormat, ...) OT_TOOL_PRINTF_STYLE_FORMAT_ARG_CHE void otLogNotePlat(const char *aFormat, ...) OT_TOOL_PRINTF_STYLE_FORMAT_ARG_CHECK(1, 2); /** - * This function emits a log message at info log level. + * Emits a log message at info log level. * - * This function is intended for use by platform. If `OPENTHREAD_CONFIG_LOG_PLATFORM` is not set or the current log + * Is intended for use by platform. If `OPENTHREAD_CONFIG_LOG_PLATFORM` is not set or the current log * level is below info, this function does not emit any log message. * * @param[in] aFormat The format string. @@ -125,9 +125,9 @@ void otLogNotePlat(const char *aFormat, ...) OT_TOOL_PRINTF_STYLE_FORMAT_ARG_CHE void otLogInfoPlat(const char *aFormat, ...) OT_TOOL_PRINTF_STYLE_FORMAT_ARG_CHECK(1, 2); /** - * This function emits a log message at debug log level. + * Emits a log message at debug log level. * - * This function is intended for use by platform. If `OPENTHREAD_CONFIG_LOG_PLATFORM` is not set or the current log + * Is intended for use by platform. If `OPENTHREAD_CONFIG_LOG_PLATFORM` is not set or the current log * level is below debug, this function does not emit any log message. * * @param[in] aFormat The format string. @@ -137,7 +137,7 @@ void otLogInfoPlat(const char *aFormat, ...) OT_TOOL_PRINTF_STYLE_FORMAT_ARG_CHE void otLogDebgPlat(const char *aFormat, ...) OT_TOOL_PRINTF_STYLE_FORMAT_ARG_CHECK(1, 2); /** - * This function generates a memory dump at critical log level. + * Generates a memory dump at critical log level. * * If `OPENTHREAD_CONFIG_LOG_PLATFORM` or `OPENTHREAD_CONFIG_LOG_PKT_DUMP` is not set or the current log level is below * critical this function does not emit any log message. @@ -150,7 +150,7 @@ void otLogDebgPlat(const char *aFormat, ...) OT_TOOL_PRINTF_STYLE_FORMAT_ARG_CHE void otDumpCritPlat(const char *aText, const void *aData, uint16_t aDataLength); /** - * This function generates a memory dump at warning log level. + * Generates a memory dump at warning log level. * * If `OPENTHREAD_CONFIG_LOG_PLATFORM` or `OPENTHREAD_CONFIG_LOG_PKT_DUMP` is not set or the current log level is below * warning this function does not emit any log message. @@ -163,7 +163,7 @@ void otDumpCritPlat(const char *aText, const void *aData, uint16_t aDataLength); void otDumpWarnPlat(const char *aText, const void *aData, uint16_t aDataLength); /** - * This function generates a memory dump at note log level. + * Generates a memory dump at note log level. * * If `OPENTHREAD_CONFIG_LOG_PLATFORM` or `OPENTHREAD_CONFIG_LOG_PKT_DUMP` is not set or the current log level is below * note this function does not emit any log message. @@ -176,7 +176,7 @@ void otDumpWarnPlat(const char *aText, const void *aData, uint16_t aDataLength); void otDumpNotePlat(const char *aText, const void *aData, uint16_t aDataLength); /** - * This function generates a memory dump at info log level. + * Generates a memory dump at info log level. * * If `OPENTHREAD_CONFIG_LOG_PLATFORM` or `OPENTHREAD_CONFIG_LOG_PKT_DUMP` is not set or the current log level is below * info this function does not emit any log message. @@ -189,7 +189,7 @@ void otDumpNotePlat(const char *aText, const void *aData, uint16_t aDataLength); void otDumpInfoPlat(const char *aText, const void *aData, uint16_t aDataLength); /** - * This function generates a memory dump at debug log level. + * Generates a memory dump at debug log level. * * If `OPENTHREAD_CONFIG_LOG_PLATFORM` or `OPENTHREAD_CONFIG_LOG_PKT_DUMP` is not set or the current log level is below * debug this function does not emit any log message. @@ -202,9 +202,9 @@ void otDumpInfoPlat(const char *aText, const void *aData, uint16_t aDataLength); void otDumpDebgPlat(const char *aText, const void *aData, uint16_t aDataLength); /** - * This function emits a log message at a given log level. + * Emits a log message at a given log level. * - * This function is intended for use by CLI only. If `OPENTHREAD_CONFIG_LOG_CLI` is not set or the current log + * Is intended for use by CLI only. If `OPENTHREAD_CONFIG_LOG_CLI` is not set or the current log * level is below the given log level, this function does not emit any log message. * * @param[in] aLogLevel The log level. diff --git a/openthread/include/openthread/mesh_diag.h b/openthread/include/openthread/mesh_diag.h new file mode 100644 index 0000000000..e21e47c937 --- /dev/null +++ b/openthread/include/openthread/mesh_diag.h @@ -0,0 +1,416 @@ +/* + * Copyright (c) 2023, The OpenThread Authors. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * 3. Neither the name of the copyright holder nor the + * names of its contributors may be used to endorse or promote products + * derived from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +/** + * @file + * @brief + * This file defines the OpenThread Mesh Diagnostic APIs. + */ + +#ifndef OPENTHREAD_MESH_DIAG_H_ +#define OPENTHREAD_MESH_DIAG_H_ + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @addtogroup api-mesh-diag + * + * @brief + * This module includes definitions and functions for Mesh Diagnostics. + * + * The Mesh Diagnostics APIs require `OPENTHREAD_CONFIG_MESH_DIAG_ENABLE` and `OPENTHREAD_FTD`. + * + * @{ + * + */ + +/** + * Represents the set of configurations used when discovering mesh topology indicating which items to + * discover. + * + */ +typedef struct otMeshDiagDiscoverConfig +{ + bool mDiscoverIp6Addresses : 1; ///< Whether or not to discover IPv6 addresses of every router. + bool mDiscoverChildTable : 1; ///< Whether or not to discover children of every router. +} otMeshDiagDiscoverConfig; + +/** + * An opaque iterator to iterate over list of IPv6 addresses of a router. + * + * Pointers to instance of this type are provided in `otMeshDiagRouterInfo`. + * + */ +typedef struct otMeshDiagIp6AddrIterator otMeshDiagIp6AddrIterator; + +/** + * An opaque iterator to iterate over list of children of a router. + * + * Pointers to instance of this type are provided in `otMeshDiagRouterInfo`. + * + */ +typedef struct otMeshDiagChildIterator otMeshDiagChildIterator; + +/** + * Specifies that Thread Version is unknown. + * + * This is used in `otMeshDiagRouterInfo` for `mVersion` property when device does not provide its version. This + * indicates that device is likely running 1.3.0 (version value 4) or earlier. + * + */ +#define OT_MESH_DIAG_VERSION_UNKNOWN 0xffff + +/** + * Represents information about a router in Thread mesh discovered using `otMeshDiagDiscoverTopology()`. + * + */ +typedef struct otMeshDiagRouterInfo +{ + otExtAddress mExtAddress; ///< Extended MAC address. + uint16_t mRloc16; ///< RLOC16. + uint8_t mRouterId; ///< Router ID. + uint16_t mVersion; ///< Thread Version. `OT_MESH_DIAG_VERSION_UNKNOWN` if unknown. + bool mIsThisDevice : 1; ///< Whether router is this device itself. + bool mIsThisDeviceParent : 1; ///< Whether router is parent of this device (when device is a child). + bool mIsLeader : 1; ///< Whether router is leader. + bool mIsBorderRouter : 1; ///< Whether router acts as a border router providing ext connectivity. + + /** + * Provides the link quality from this router to other routers, also indicating whether a link is established + * between the routers. + * + * The array is indexed based on Router ID. `mLinkQualities[routerId]` indicates the incoming link quality, the + * router sees to the router with `routerId`. Link quality is a value in [0, 3]. Value zero indicates no link. + * Larger value indicate better link quality (as defined by Thread specification). + * + */ + uint8_t mLinkQualities[OT_NETWORK_MAX_ROUTER_ID + 1]; + + /** + * A pointer to an iterator to go through the list of IPv6 addresses of the router. + * + * The pointer is valid only while `otMeshDiagRouterInfo` is valid. It can be used in `otMeshDiagGetNextIp6Address` + * to iterate through the IPv6 addresses. + * + * The pointer can be NULL when there was no request to discover IPv6 addresses (in `otMeshDiagDiscoverConfig`) or + * if the router did not provide the list. + * + */ + otMeshDiagIp6AddrIterator *mIp6AddrIterator; + + /** + * A pointer to an iterator to go through the list of children of the router. + * + * The pointer is valid only while `otMeshDiagRouterInfo` is valid. It can be used in `otMeshDiagGetNextChildInfo` + * to iterate through the children of the router. + * + * The pointer can be NULL when there was no request to discover children (in `otMeshDiagDiscoverConfig`) or + * if the router did not provide the list. + * + */ + otMeshDiagChildIterator *mChildIterator; +} otMeshDiagRouterInfo; + +/** + * Represents information about a discovered child in Thread mesh using `otMeshDiagDiscoverTopology()`. + * + */ +typedef struct otMeshDiagChildInfo +{ + uint16_t mRloc16; ///< RLOC16. + otLinkModeConfig mMode; ///< Device mode. + uint8_t mLinkQuality; ///< Incoming link quality to child from parent. + bool mIsThisDevice : 1; ///< Whether child is this device itself. + bool mIsBorderRouter : 1; ///< Whether child acts as a border router providing ext connectivity. +} otMeshDiagChildInfo; + +/** + * Pointer type represents the callback used by `otMeshDiagDiscoverTopology()` to provide information + * about a discovered router. + * + * When @p aError is `OT_ERROR_PENDING`, it indicates that the discovery is not yet finished and there will be more + * routers to discover and the callback will be invoked again. + * + * @param[in] aError OT_ERROR_PENDING Indicates there are more routers to be discovered. + * OT_ERROR_NONE Indicates this is the last router and mesh discovery is done. + * OT_ERROR_RESPONSE_TIMEOUT Timed out waiting for response from one or more routers. + * @param[in] aRouterInfo The discovered router info (can be null if `aError` is OT_ERROR_RESPONSE_TIMEOUT). + * @param[in] aContext Application-specific context. + * + */ +typedef void (*otMeshDiagDiscoverCallback)(otError aError, otMeshDiagRouterInfo *aRouterInfo, void *aContext); + +/** + * Starts network topology discovery. + * + * @param[in] aInstance The OpenThread instance. + * @param[in] aConfig The configuration to use for discovery (e.g., which items to discover). + * @param[in] aCallback The callback to report the discovered routers. + * @param[in] aContext A context to pass in @p aCallback. + * + * @retval OT_ERROR_NONE The network topology discovery started successfully. + * @retval OT_ERROR_BUSY A previous discovery request is still ongoing. + * @retval OT_ERROR_INVALID_STATE Device is not attached. + * @retval OT_ERROR_NO_BUFS Could not allocate buffer to send discovery messages. + * + */ +otError otMeshDiagDiscoverTopology(otInstance *aInstance, + const otMeshDiagDiscoverConfig *aConfig, + otMeshDiagDiscoverCallback aCallback, + void *aContext); + +/** + * Cancels an ongoing topology discovery if there is one, otherwise no action. + * + * When ongoing discovery is cancelled, the callback from `otMeshDiagDiscoverTopology()` will not be called anymore. + * + */ +void otMeshDiagCancel(otInstance *aInstance); + +/** + * Iterates through the discovered IPv6 addresses of a router or an MTD child. + * + * MUST be used + * - from the callback `otMeshDiagDiscoverCallback()` and use the `mIp6AddrIterator` from the `aRouterInfo` struct that + * is provided as input to the callback, or + * - from the callback `otMeshDiagChildIp6AddrsCallback()` along with provided `aIp6AddrIterator`. + * + * @param[in,out] aIterator The address iterator to use. + * @param[out] aIp6Address A pointer to return the next IPv6 address (if any). + * + * @retval OT_ERROR_NONE Successfully retrieved the next address. @p aIp6Address and @p aIterator are updated. + * @retval OT_ERROR_NOT_FOUND No more address. Reached the end of the list. + * + */ +otError otMeshDiagGetNextIp6Address(otMeshDiagIp6AddrIterator *aIterator, otIp6Address *aIp6Address); + +/** + * Iterates through the discovered children of a router. + * + * This function MUST be used from the callback `otMeshDiagDiscoverCallback()` and use the `mChildIterator` from the + * `aRouterInfo` struct that is provided as input to the callback. + * + * @param[in,out] aIterator The address iterator to use. + * @param[out] aChildInfo A pointer to return the child info (if any). + * + * @retval OT_ERROR_NONE Successfully retrieved the next child. @p aChildInfo and @p aIterator are updated. + * @retval OT_ERROR_NOT_FOUND No more child. Reached the end of the list. + * + */ +otError otMeshDiagGetNextChildInfo(otMeshDiagChildIterator *aIterator, otMeshDiagChildInfo *aChildInfo); + +/** + * Represents information about a child entry from `otMeshDiagQueryChildTable()`. + * + * `mSupportsErrRate` indicates whether or not the error tracking feature is supported and `mFrameErrorRate` and + * `mMessageErrorRate` values are valid. The frame error rate tracks frame tx errors (towards the child) at MAC + * layer, while `mMessageErrorRate` tracks the IPv6 message error rate (above MAC layer and after MAC retries) when + * an IPv6 message is dropped. For example, if the message is large and requires 6LoWPAN fragmentation, message tx is + * considered as failed if one of its fragment frame tx fails (for example, never acked). + * + */ +typedef struct otMeshDiagChildEntry +{ + bool mRxOnWhenIdle : 1; ///< Is rx-on when idle (vs sleepy). + bool mDeviceTypeFtd : 1; ///< Is device FTD (vs MTD). + bool mFullNetData : 1; ///< Whether device gets full Network Data (vs stable sub-set). + bool mCslSynchronized : 1; ///< Is CSL capable and CSL synchronized. + bool mSupportsErrRate : 1; ///< `mFrameErrorRate` and `mMessageErrorRate` values are valid. + uint16_t mRloc16; ///< RLOC16. + otExtAddress mExtAddress; ///< Extended Address. + uint16_t mVersion; ///< Version. + uint32_t mTimeout; ///< Timeout in seconds. + uint32_t mAge; ///< Seconds since last heard from the child. + uint32_t mConnectionTime; ///< Seconds since child attach. + uint16_t mSupervisionInterval; ///< Supervision interval in seconds. Zero to indicate not used. + uint8_t mLinkMargin; ///< Link Margin in dB. + int8_t mAverageRssi; ///< Average RSSI. + int8_t mLastRssi; ///< RSSI of last received frame. + uint16_t mFrameErrorRate; ///< Frame error rate (0x0000->0%, 0xffff->100%). + uint16_t mMessageErrorRate; ///< (IPv6) msg error rate (0x0000->0%, 0xffff->100%). + uint16_t mQueuedMessageCount; ///< Number of queued messages for indirect tx to child. + uint16_t mCslPeriod; ///< CSL Period in unit of 10-symbols-time. Zero indicates CSL is disabled. + uint32_t mCslTimeout; ///< CSL Timeout in seconds. + uint8_t mCslChannel; ///< CSL channel. +} otMeshDiagChildEntry; + +/** + * Represents the callback used by `otMeshDiagQueryChildTable()` to provide information about child table entries. + * + * When @p aError is `OT_ERROR_PENDING`, it indicates that the table still has more entries and the callback will be + * invoked again. + * + * @param[in] aError OT_ERROR_PENDING Indicates there are more entries in the table. + * OT_ERROR_NONE Indicates the table is finished. + * OT_ERROR_RESPONSE_TIMEOUT Timed out waiting for response. + * @param[in] aChildEntry The child entry (can be null if `aError` is OT_ERROR_RESPONSE_TIMEOUT or OT_ERROR_NONE). + * @param[in] aContext Application-specific context. + * + */ +typedef void (*otMeshDiagQueryChildTableCallback)(otError aError, + const otMeshDiagChildEntry *aChildEntry, + void *aContext); + +/** + * Starts query for child table for a given router. + * + * @param[in] aInstance The OpenThread instance. + * @param[in] aRloc16 The RLOC16 of router to query. + * @param[in] aCallback The callback to report the queried child table. + * @param[in] aContext A context to pass in @p aCallback. + * + * @retval OT_ERROR_NONE The query started successfully. + * @retval OT_ERROR_BUSY A previous discovery or query request is still ongoing. + * @retval OT_ERROR_INVALID_ARGS The @p aRloc16 is not a valid router RLOC16. + * @retval OT_ERROR_INVALID_STATE Device is not attached. + * @retval OT_ERROR_NO_BUFS Could not allocate buffer to send query messages. + * + */ +otError otMeshDiagQueryChildTable(otInstance *aInstance, + uint16_t aRloc16, + otMeshDiagQueryChildTableCallback aCallback, + void *aContext); + +/** + * Represents the callback used by `otMeshDiagQueryChildrenIp6Addrs()` to provide information about an MTD child and + * its list of IPv6 addresses. + * + * When @p aError is `OT_ERROR_PENDING`, it indicates that there are more children and the callback will be invoked + * again. + * + * @param[in] aError OT_ERROR_PENDING Indicates there are more children in the table. + * OT_ERROR_NONE Indicates the table is finished. + * OT_ERROR_RESPONSE_TIMEOUT Timed out waiting for response. + * @param[in] aChildRloc16 The RLOC16 of the child. `0xfffe` is used on `OT_ERROR_RESPONSE_TIMEOUT`. + * @param[in] aIp6AddrIterator An iterator to go through the IPv6 addresses of the child with @p aRloc using + * `otMeshDiagGetNextIp6Address()`. Set to NULL on `OT_ERROR_RESPONSE_TIMEOUT`. + * @param[in] aContext Application-specific context. + * + */ +typedef void (*otMeshDiagChildIp6AddrsCallback)(otError aError, + uint16_t aChildRloc16, + otMeshDiagIp6AddrIterator *aIp6AddrIterator, + void *aContext); + +/** + * Sends a query to a parent to retrieve the IPv6 addresses of all its MTD children. + * + * @param[in] aInstance The OpenThread instance. + * @param[in] aRloc16 The RLOC16 of parent to query. + * @param[in] aCallback The callback to report the queried child IPv6 address list. + * @param[in] aContext A context to pass in @p aCallback. + * + * @retval OT_ERROR_NONE The query started successfully. + * @retval OT_ERROR_BUSY A previous discovery or query request is still ongoing. + * @retval OT_ERROR_INVALID_ARGS The @p aRloc16 is not a valid RLOC16. + * @retval OT_ERROR_INVALID_STATE Device is not attached. + * @retval OT_ERROR_NO_BUFS Could not allocate buffer to send query messages. + * + */ +otError otMeshDiagQueryChildrenIp6Addrs(otInstance *aInstance, + uint16_t aRloc16, + otMeshDiagChildIp6AddrsCallback aCallback, + void *aContext); + +/** + * Represents information about a router neighbor entry from `otMeshDiagQueryRouterNeighborTable()`. + * + * `mSupportsErrRate` indicates whether or not the error tracking feature is supported and `mFrameErrorRate` and + * `mMessageErrorRate` values are valid. The frame error rate tracks frame tx errors (towards the child) at MAC + * layer, while `mMessageErrorRate` tracks the IPv6 message error rate (above MAC layer and after MAC retries) when + * an IPv6 message is dropped. For example, if the message is large and requires 6LoWPAN fragmentation, message tx is + * considered as failed if one of its fragment frame tx fails (for example, never acked). + * + */ +typedef struct otMeshDiagRouterNeighborEntry +{ + bool mSupportsErrRate : 1; ///< `mFrameErrorRate` and `mMessageErrorRate` values are valid. + uint16_t mRloc16; ///< RLOC16. + otExtAddress mExtAddress; ///< Extended Address. + uint16_t mVersion; ///< Version. + uint32_t mConnectionTime; ///< Seconds since link establishment. + uint8_t mLinkMargin; ///< Link Margin in dB. + int8_t mAverageRssi; ///< Average RSSI. + int8_t mLastRssi; ///< RSSI of last received frame. + uint16_t mFrameErrorRate; ///< Frame error rate (0x0000->0%, 0xffff->100%). + uint16_t mMessageErrorRate; ///< (IPv6) msg error rate (0x0000->0%, 0xffff->100%). +} otMeshDiagRouterNeighborEntry; + +/** + * Represents the callback used by `otMeshDiagQueryRouterNeighborTable()` to provide information about neighbor router + * table entries. + * + * When @p aError is `OT_ERROR_PENDING`, it indicates that the table still has more entries and the callback will be + * invoked again. + * + * @param[in] aError OT_ERROR_PENDING Indicates there are more entries in the table. + * OT_ERROR_NONE Indicates the table is finished. + * OT_ERROR_RESPONSE_TIMEOUT Timed out waiting for response. + * @param[in] aNeighborEntry The neighbor entry (can be null if `aError` is RESPONSE_TIMEOUT or NONE). + * @param[in] aContext Application-specific context. + * + */ +typedef void (*otMeshDiagQueryRouterNeighborTableCallback)(otError aError, + const otMeshDiagRouterNeighborEntry *aNeighborEntry, + void *aContext); + +/** + * Starts query for router neighbor table for a given router. + * + * @param[in] aInstance The OpenThread instance. + * @param[in] aRloc16 The RLOC16 of router to query. + * @param[in] aCallback The callback to report the queried table. + * @param[in] aContext A context to pass in @p aCallback. + * + * @retval OT_ERROR_NONE The query started successfully. + * @retval OT_ERROR_BUSY A previous discovery or query request is still ongoing. + * @retval OT_ERROR_INVALID_ARGS The @p aRloc16 is not a valid router RLOC16. + * @retval OT_ERROR_INVALID_STATE Device is not attached. + * @retval OT_ERROR_NO_BUFS Could not allocate buffer to send query messages. + * + */ +otError otMeshDiagQueryRouterNeighborTable(otInstance *aInstance, + uint16_t aRloc16, + otMeshDiagQueryRouterNeighborTableCallback aCallback, + void *aContext); + +/** + * @} + * + */ + +#ifdef __cplusplus +} // extern "C" +#endif + +#endif // OPENTHREAD_MESH_DIAG_H_ diff --git a/openthread/include/openthread/message.h b/openthread/include/openthread/message.h index d94c176e4a..99dc49cf18 100644 --- a/openthread/include/openthread/message.h +++ b/openthread/include/openthread/message.h @@ -53,13 +53,13 @@ extern "C" { */ /** - * This type is an opaque representation of an OpenThread message buffer. + * An opaque representation of an OpenThread message buffer. * */ typedef struct otMessage otMessage; /** - * This enumeration defines the OpenThread message priority levels. + * Defines the OpenThread message priority levels. * */ typedef enum otMessagePriority @@ -70,7 +70,18 @@ typedef enum otMessagePriority } otMessagePriority; /** - * This structure represents a message settings. + * Defines the OpenThread message origins. + * + */ +typedef enum otMessageOrigin +{ + OT_MESSAGE_ORIGIN_THREAD_NETIF = 0, ///< Message from Thread Netif. + OT_MESSAGE_ORIGIN_HOST_TRUSTED = 1, ///< Message from a trusted source on host. + OT_MESSAGE_ORIGIN_HOST_UNTRUSTED = 2, ///< Message from an untrusted source on host. +} otMessageOrigin; + +/** + * Represents a message settings. * */ typedef struct otMessageSettings @@ -170,7 +181,7 @@ uint16_t otMessageGetOffset(const otMessage *aMessage); void otMessageSetOffset(otMessage *aMessage, uint16_t aOffset); /** - * This function indicates whether or not link security is enabled for the message. + * Indicates whether or not link security is enabled for the message. * * @param[in] aMessage A pointer to a message buffer. * @@ -181,7 +192,46 @@ void otMessageSetOffset(otMessage *aMessage, uint16_t aOffset); bool otMessageIsLinkSecurityEnabled(const otMessage *aMessage); /** - * This function sets/forces the message to be forwarded using direct transmission. + * Indicates whether or not the message is allowed to be looped back to host. + * + * @param[in] aMessage A pointer to a message buffer. + * + * @retval TRUE If the message is allowed to be looped back to host. + * @retval FALSE If the message is not allowed to be looped back to host. + * + */ +bool otMessageIsLoopbackToHostAllowed(const otMessage *aMessage); + +/** + * Sets whether or not the message is allowed to be looped back to host. + * + * @param[in] aMessage A pointer to a message buffer. + * @param[in] aAllowLoopbackToHost Whether to allow the message to be looped back to host. + * + */ +void otMessageSetLoopbackToHostAllowed(otMessage *aMessage, bool aAllowLoopbackToHost); + +/** + * Gets the message origin. + * + * @param[in] aMessage A pointer to a message buffer. + * + * @returns The message origin. + * + */ +otMessageOrigin otMessageGetOrigin(const otMessage *aMessage); + +/** + * Sets the message origin. + * + * @param[in] aMessage A pointer to a message buffer. + * @param[in] aOrigin The message origin. + * + */ +void otMessageSetOrigin(otMessage *aMessage, otMessageOrigin aOrigin); + +/** + * Sets/forces the message to be forwarded using direct transmission. * Default setting for a new message is `false`. * * @param[in] aMessage A pointer to a message buffer. @@ -192,7 +242,7 @@ bool otMessageIsLinkSecurityEnabled(const otMessage *aMessage); void otMessageSetDirectTransmission(otMessage *aMessage, bool aEnabled); /** - * This function returns the average RSS (received signal strength) associated with the message. + * Returns the average RSS (received signal strength) associated with the message. * * @returns The average RSS value (in dBm) or OT_RADIO_RSSI_INVALID if no average RSS is available. * @@ -263,7 +313,7 @@ uint16_t otMessageRead(const otMessage *aMessage, uint16_t aOffset, void *aBuf, int otMessageWrite(otMessage *aMessage, uint16_t aOffset, const void *aBuf, uint16_t aLength); /** - * This structure represents an OpenThread message queue. + * Represents an OpenThread message queue. */ typedef struct { @@ -271,7 +321,7 @@ typedef struct } otMessageQueue; /** - * This structure represents information about a message queue. + * Represents information about a message queue. * */ typedef struct otMessageQueueInfo @@ -282,13 +332,21 @@ typedef struct otMessageQueueInfo } otMessageQueueInfo; /** - * This structure represents the message buffer information for different queues used by OpenThread stack. + * Represents the message buffer information for different queues used by OpenThread stack. * */ typedef struct otBufferInfo { - uint16_t mTotalBuffers; ///< The total number of buffers in the messages pool (0xffff if unknown). - uint16_t mFreeBuffers; ///< The number of free buffers (0xffff if unknown). + uint16_t mTotalBuffers; ///< The total number of buffers in the messages pool (0xffff if unknown). + uint16_t mFreeBuffers; ///< The number of free buffers (0xffff if unknown). + + /** + * The maximum number of used buffers at the same time since OT stack initialization or last call to + * `otMessageResetBufferInfo()`. + * + */ + uint16_t mMaxUsedBuffers; + otMessageQueueInfo m6loSendQueue; ///< Info about 6LoWPAN send queue. otMessageQueueInfo m6loReassemblyQueue; ///< Info about 6LoWPAN reassembly queue. otMessageQueueInfo mIp6Queue; ///< Info about IPv6 send queue. @@ -302,7 +360,7 @@ typedef struct otBufferInfo /** * Initialize the message queue. * - * This function MUST be called once and only once for a `otMessageQueue` instance before any other `otMessageQueue` + * MUST be called once and only once for a `otMessageQueue` instance before any other `otMessageQueue` * functions. The behavior is undefined if other queue APIs are used with an `otMessageQueue` before it being * initialized or if it is initialized more than once. * @@ -312,7 +370,7 @@ typedef struct otBufferInfo void otMessageQueueInit(otMessageQueue *aQueue); /** - * This function adds a message to the end of the given message queue. + * Adds a message to the end of the given message queue. * * @param[in] aQueue A pointer to the message queue. * @param[in] aMessage The message to add. @@ -321,7 +379,7 @@ void otMessageQueueInit(otMessageQueue *aQueue); void otMessageQueueEnqueue(otMessageQueue *aQueue, otMessage *aMessage); /** - * This function adds a message at the head/front of the given message queue. + * Adds a message at the head/front of the given message queue. * * @param[in] aQueue A pointer to the message queue. * @param[in] aMessage The message to add. @@ -330,7 +388,7 @@ void otMessageQueueEnqueue(otMessageQueue *aQueue, otMessage *aMessage); void otMessageQueueEnqueueAtHead(otMessageQueue *aQueue, otMessage *aMessage); /** - * This function removes a message from the given message queue. + * Removes a message from the given message queue. * * @param[in] aQueue A pointer to the message queue. * @param[in] aMessage The message to remove. @@ -339,7 +397,7 @@ void otMessageQueueEnqueueAtHead(otMessageQueue *aQueue, otMessage *aMessage); void otMessageQueueDequeue(otMessageQueue *aQueue, otMessage *aMessage); /** - * This function returns a pointer to the message at the head of the queue. + * Returns a pointer to the message at the head of the queue. * * @param[in] aQueue A pointer to a message queue. * @@ -349,7 +407,7 @@ void otMessageQueueDequeue(otMessageQueue *aQueue, otMessage *aMessage); otMessage *otMessageQueueGetHead(otMessageQueue *aQueue); /** - * This function returns a pointer to the next message in the queue by iterating forward (from head to tail). + * Returns a pointer to the next message in the queue by iterating forward (from head to tail). * * @param[in] aQueue A pointer to a message queue. * @param[in] aMessage A pointer to current message buffer. @@ -369,6 +427,16 @@ otMessage *otMessageQueueGetNext(otMessageQueue *aQueue, const otMessage *aMessa */ void otMessageGetBufferInfo(otInstance *aInstance, otBufferInfo *aBufferInfo); +/** + * Reset the Message Buffer information counter tracking the maximum number buffers in use at the same time. + * + * This resets `mMaxUsedBuffers` in `otBufferInfo`. + * + * @param[in] aInstance A pointer to the OpenThread instance. + * + */ +void otMessageResetBufferInfo(otInstance *aInstance); + /** * @} * diff --git a/openthread/include/openthread/multi_radio.h b/openthread/include/openthread/multi_radio.h index 13930f58c5..9ad35723bb 100644 --- a/openthread/include/openthread/multi_radio.h +++ b/openthread/include/openthread/multi_radio.h @@ -52,7 +52,7 @@ extern "C" { */ /** - * This type represents information associated with a radio link. + * Represents information associated with a radio link. * */ typedef struct otRadioLinkInfo @@ -61,7 +61,7 @@ typedef struct otRadioLinkInfo } otRadioLinkInfo; /** - * This type represents multi radio link information associated with a neighbor. + * Represents multi radio link information associated with a neighbor. * */ typedef struct otMultiRadioNeighborInfo @@ -73,9 +73,9 @@ typedef struct otMultiRadioNeighborInfo } otMultiRadioNeighborInfo; /** - * This function gets the multi radio link information associated with a neighbor with a given Extended Address. + * Gets the multi radio link information associated with a neighbor with a given Extended Address. * - * This function requires the multi radio link feature to be enabled (please see `config/radio_link.h`). + * `OPENTHREAD_CONFIG_MULTI_RADIO` must be enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aExtAddress The Extended Address of neighbor. diff --git a/openthread/include/openthread/nat64.h b/openthread/include/openthread/nat64.h index 4589d3620c..930c4c3423 100644 --- a/openthread/include/openthread/nat64.h +++ b/openthread/include/openthread/nat64.h @@ -57,7 +57,7 @@ extern "C" { /** * @struct otIp4Address * - * This structure represents an IPv4 address. + * Represents an IPv4 address. * */ OT_TOOL_PACKED_BEGIN @@ -71,7 +71,7 @@ struct otIp4Address } OT_TOOL_PACKED_END; /** - * This structure represents an IPv4 address. + * Represents an IPv4 address. * */ typedef struct otIp4Address otIp4Address; @@ -79,7 +79,7 @@ typedef struct otIp4Address otIp4Address; /** * @struct otIp4Cidr * - * This structure represents an IPv4 CIDR block. + * Represents an IPv4 CIDR block. * */ typedef struct otIp4Cidr @@ -291,7 +291,7 @@ otNat64State otNat64GetPrefixManagerState(otInstance *aInstance); * @sa otNat64GetPrefixManagerState * */ -void otNat64SetEnabled(otInstance *aInstance, bool aEnable); +void otNat64SetEnabled(otInstance *aInstance, bool aEnabled); /** * Allocate a new message buffer for sending an IPv4 message to the NAT64 translator. @@ -317,7 +317,7 @@ otMessage *otIp4NewMessage(otInstance *aInstance, const otMessageSettings *aSett /** * 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. + * 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. @@ -358,7 +358,7 @@ otError otNat64SetIp4Cidr(otInstance *aInstance, const otIp4Cidr *aCidr); otError otNat64Send(otInstance *aInstance, otMessage *aMessage); /** - * This function pointer is called when an IPv4 datagram (translated by NAT64 translator) is received. + * 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 @@ -374,7 +374,7 @@ typedef void (*otNat64ReceiveIp4Callback)(otMessage *aMessage, void *aContext); * @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. + * @param[in] aContext A pointer to application-specific context. * */ void otNat64SetReceiveIp4Callback(otInstance *aInstance, otNat64ReceiveIp4Callback aCallback, void *aContext); @@ -435,6 +435,18 @@ void otIp4AddressToString(const otIp4Address *aAddress, char *aBuffer, uint16_t #define OT_IP4_CIDR_STRING_SIZE 20 ///< Length of 000.000.000.000/00 plus a suffix NUL +/** + * Converts a human-readable IPv4 CIDR string into a binary representation. + * + * @param[in] aString A pointer to a NULL-terminated string. + * @param[out] aCidr A pointer to an IPv4 CIDR. + * + * @retval OT_ERROR_NONE Successfully parsed the string. + * @retval OT_ERROR_INVALID_ARGS Failed to parse the string. + * + */ +otError otIp4CidrFromString(const char *aString, otIp4Cidr *aCidr); + /** * Converts the IPv4 CIDR to a string. * diff --git a/openthread/include/openthread/ncp.h b/openthread/include/openthread/ncp.h index fb766ef9d1..7e07fa2901 100644 --- a/openthread/include/openthread/ncp.h +++ b/openthread/include/openthread/ncp.h @@ -55,7 +55,7 @@ extern "C" { */ /** - * This function pointer is called to send HDLC encoded NCP data. + * Pointer is called to send HDLC encoded NCP data. * * @param[in] aBuf A pointer to a buffer with an output. * @param[in] aBufLength A length of the output data stored in the buffer. @@ -66,13 +66,13 @@ extern "C" { typedef int (*otNcpHdlcSendCallback)(const uint8_t *aBuf, uint16_t aBufLength); /** - * This function is called after NCP send finished. + * Is called after NCP send finished. * */ void otNcpHdlcSendDone(void); /** - * This function is called after HDLC encoded NCP data received. + * Is called after HDLC encoded NCP data received. * * @param[in] aBuf A pointer to a buffer. * @param[in] aBufLength The length of the data stored in the buffer. @@ -100,7 +100,7 @@ void otNcpSpiInit(otInstance *aInstance); /** * @brief Send data to the host via a specific stream. * - * This function attempts to send the given data to the host + * Attempts to send the given data to the host * using the given aStreamId. This is useful for reporting * error messages, implementing debug/diagnostic consoles, * and potentially other types of datastreams. @@ -149,7 +149,7 @@ void otNcpPlatLogv(otLogLevel aLogLevel, otLogRegion aLogRegion, const char *aFo typedef bool (*otNcpDelegateAllowPeekPoke)(uint32_t aAddress, uint16_t aCount); /** - * This method registers peek/poke delegate functions with NCP module. + * Registers peek/poke delegate functions with NCP module. * * The delegate functions are called by NCP module to decide whether to allow peek or poke of a specific memory region. * If the delegate pointer is set to NULL, it allows peek/poke operation for any address. @@ -158,7 +158,7 @@ typedef bool (*otNcpDelegateAllowPeekPoke)(uint32_t aAddress, uint16_t aCount); * @param[in] aAllowPokeDelegate Delegate function pointer for poke operation. * */ -void otNcpRegisterPeekPokeDelagates(otNcpDelegateAllowPeekPoke aAllowPeekDelegate, +void otNcpRegisterPeekPokeDelegates(otNcpDelegateAllowPeekPoke aAllowPeekDelegate, otNcpDelegateAllowPeekPoke aAllowPokeDelegate); /** diff --git a/openthread/include/openthread/netdata.h b/openthread/include/openthread/netdata.h index 12c48e8175..aae61148af 100644 --- a/openthread/include/openthread/netdata.h +++ b/openthread/include/openthread/netdata.h @@ -53,7 +53,7 @@ extern "C" { typedef uint32_t otNetworkDataIterator; ///< Used to iterate through Network Data information. /** - * This structure represents a Border Router configuration. + * Represents a Border Router configuration. */ typedef struct otBorderRouterConfig { @@ -72,7 +72,18 @@ typedef struct otBorderRouterConfig } otBorderRouterConfig; /** - * This structure represents an External Route configuration. + * Represents 6LoWPAN Context ID information associated with a prefix in Network Data. + * + */ +typedef struct otLowpanContextInfo +{ + uint8_t mContextId; ///< The 6LoWPAN Context ID. + bool mCompressFlag; ///< The compress flag. + otIp6Prefix mPrefix; ///< The associated IPv6 prefix. +} otLowpanContextInfo; + +/** + * Represents an External Route configuration. * */ typedef struct otExternalRouteConfig @@ -83,6 +94,7 @@ typedef struct otExternalRouteConfig bool mNat64 : 1; ///< Whether this is a NAT64 prefix. bool mStable : 1; ///< Whether this configuration is considered Stable Network Data. bool mNextHopIsThisDevice : 1; ///< Whether the next hop is this device (value ignored on config add). + bool mAdvPio : 1; ///< Whether or not BR is advertising a ULA prefix in PIO (AP flag). } otExternalRouteConfig; /** @@ -100,7 +112,7 @@ typedef enum otRoutePreference #define OT_SERVER_DATA_MAX_SIZE 248 ///< Max size of Server Data in bytes. Theoretical limit, practically much lower. /** - * This structure represents a Server configuration. + * Represents a Server configuration. * */ typedef struct otServerConfig @@ -112,7 +124,7 @@ typedef struct otServerConfig } otServerConfig; /** - * This structure represents a Service configuration. + * Represents a Service configuration. * */ typedef struct otServiceConfig @@ -125,7 +137,7 @@ typedef struct otServiceConfig } otServiceConfig; /** - * This method provides a full or stable copy of the Partition's Thread Network Data. + * Provide full or stable copy of the Partition's Thread Network Data. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aStable TRUE when copying the stable version, FALSE when copying the full version. @@ -133,11 +145,45 @@ typedef struct otServiceConfig * @param[in,out] aDataLength On entry, size of the data buffer pointed to by @p aData. * On exit, number of copied bytes. * + * @retval OT_ERROR_NONE Successfully copied the Thread Network Data into @p aData and updated @p aDataLength. + * @retval OT_ERROR_NO_BUFS Not enough space in @p aData to fully copy the Thread Network Data. + * */ otError otNetDataGet(otInstance *aInstance, bool aStable, uint8_t *aData, uint8_t *aDataLength); /** - * This function gets the next On Mesh Prefix in the partition's Network Data. + * Get the current length (number of bytes) of Partition's Thread Network Data. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * + * @return The length of the Network Data. + * + */ +uint8_t otNetDataGetLength(otInstance *aInstance); + +/** + * Get the maximum observed length of the Thread Network Data since OT stack initialization or since the last call to + * `otNetDataResetMaxLength()`. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * + * @return The maximum length of the Network Data (high water mark for Network Data length). + * + */ +uint8_t otNetDataGetMaxLength(otInstance *aInstance); + +/** + * Reset the tracked maximum length of the Thread Network Data. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * + * @sa otNetDataGetMaxLength + * + */ +void otNetDataResetMaxLength(otInstance *aInstance); + +/** + * Get the next On Mesh Prefix in the partition's Network Data. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in,out] aIterator A pointer to the Network Data iterator context. To get the first on-mesh entry @@ -153,7 +199,7 @@ otError otNetDataGetNextOnMeshPrefix(otInstance *aInstance, otBorderRouterConfig *aConfig); /** - * This function gets the next external route in the partition's Network Data. + * Get the next external route in the partition's Network Data. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in,out] aIterator A pointer to the Network Data iterator context. To get the first external route entry @@ -167,7 +213,7 @@ otError otNetDataGetNextOnMeshPrefix(otInstance *aInstance, otError otNetDataGetNextRoute(otInstance *aInstance, otNetworkDataIterator *aIterator, otExternalRouteConfig *aConfig); /** - * This function gets the next service in the partition's Network Data. + * Get the next service in the partition's Network Data. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in,out] aIterator A pointer to the Network Data iterator context. To get the first service entry @@ -180,6 +226,22 @@ otError otNetDataGetNextRoute(otInstance *aInstance, otNetworkDataIterator *aIte */ otError otNetDataGetNextService(otInstance *aInstance, otNetworkDataIterator *aIterator, otServiceConfig *aConfig); +/** + * Get the next 6LoWPAN Context ID info in the partition's Network Data. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in,out] aIterator A pointer to the Network Data iterator. To get the first service entry + it should be set to OT_NETWORK_DATA_ITERATOR_INIT. + * @param[out] aContextInfo A pointer to where the retrieved 6LoWPAN Context ID information will be placed. + * + * @retval OT_ERROR_NONE Successfully found the next 6LoWPAN Context ID info. + * @retval OT_ERROR_NOT_FOUND No subsequent 6LoWPAN Context info exists in the partition's Network Data. + * + */ +otError otNetDataGetNextLowpanContextInfo(otInstance *aInstance, + otNetworkDataIterator *aIterator, + otLowpanContextInfo *aContextInfo); + /** * Get the Network Data Version. * @@ -231,8 +293,7 @@ otError otNetDataSteeringDataCheckJoinerWithDiscerner(otInstance const struct otJoinerDiscerner *aDiscerner); /** - * This function checks whether a given Prefix can act as a valid OMR prefix and also the Leader's Network Data contains - * this prefix. + * Check whether a given Prefix can act as a valid OMR prefix and also the Leader's Network Data contains this prefix. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aPrefix A pointer to the IPv6 prefix. diff --git a/openthread/include/openthread/netdata_publisher.h b/openthread/include/openthread/netdata_publisher.h index 0e68b0ec40..21a934523a 100644 --- a/openthread/include/openthread/netdata_publisher.h +++ b/openthread/include/openthread/netdata_publisher.h @@ -55,7 +55,7 @@ extern "C" { */ /** - * This enumeration represents the events reported from the Publisher callbacks. + * Represents the events reported from the Publisher callbacks. * */ typedef enum otNetDataPublisherEvent @@ -65,7 +65,7 @@ typedef enum otNetDataPublisherEvent } otNetDataPublisherEvent; /** - * This function pointer type defines the callback used to notify when a "DNS/SRP Service" entry is added to or removed + * Pointer type defines the callback used to notify when a "DNS/SRP Service" entry is added to or removed * from the Thread Network Data. * * On remove the callback is invoked independent of whether the entry is removed by `Publisher` (e.g., when there are @@ -79,7 +79,7 @@ typedef enum otNetDataPublisherEvent typedef void (*otNetDataDnsSrpServicePublisherCallback)(otNetDataPublisherEvent aEvent, void *aContext); /** - * This function pointer type defines the callback used to notify when a prefix (on-mesh or external route) entry is + * Pointer type defines the callback used to notify when a prefix (on-mesh or external route) entry is * added to or removed from the Thread Network Data. * * On remove the callback is invoked independent of whether the entry is removed by `Publisher` (e.g., when there are @@ -95,9 +95,9 @@ typedef void (*otNetDataPrefixPublisherCallback)(otNetDataPublisherEvent aEvent, void *aContext); /** - * This function requests "DNS/SRP Service Anycast Address" to be published in the Thread Network Data. + * Requests "DNS/SRP Service Anycast Address" to be published in the Thread Network Data. * - * This function requires the feature `OPENTHREAD_CONFIG_TMF_NETDATA_SERVICE_ENABLE` to be enabled. + * Requires the feature `OPENTHREAD_CONFIG_TMF_NETDATA_SERVICE_ENABLE` to be enabled. * * A call to this function will remove and replace any previous "DNS/SRP Service" entry that was being published (from * earlier call to any of `otNetDataPublishDnsSrpService{Type}()` functions). @@ -109,14 +109,14 @@ typedef void (*otNetDataPrefixPublisherCallback)(otNetDataPublisherEvent aEvent, void otNetDataPublishDnsSrpServiceAnycast(otInstance *aInstance, uint8_t aSequenceNUmber); /** - * This function requests "DNS/SRP Service Unicast Address" to be published in the Thread Network Data. + * Requests "DNS/SRP Service Unicast Address" to be published in the Thread Network Data. * - * This function requires the feature `OPENTHREAD_CONFIG_TMF_NETDATA_SERVICE_ENABLE` to be enabled. + * Requires the feature `OPENTHREAD_CONFIG_TMF_NETDATA_SERVICE_ENABLE` to be enabled. * * A call to this function will remove and replace any previous "DNS/SRP Service" entry that was being published (from * earlier call to any of `otNetDataPublishDnsSrpService{Type}()` functions). * - * This function publishes the "DNS/SRP Service Unicast Address" by including the address and port info in the Service + * Publishes the "DNS/SRP Service Unicast Address" by including the address and port info in the Service * TLV data. * * @param[in] aInstance A pointer to an OpenThread instance. @@ -127,9 +127,9 @@ void otNetDataPublishDnsSrpServiceAnycast(otInstance *aInstance, uint8_t aSequen void otNetDataPublishDnsSrpServiceUnicast(otInstance *aInstance, const otIp6Address *aAddress, uint16_t aPort); /** - * This function requests "DNS/SRP Service Unicast Address" to be published in the Thread Network Data. + * Requests "DNS/SRP Service Unicast Address" to be published in the Thread Network Data. * - * This function requires the feature `OPENTHREAD_CONFIG_TMF_NETDATA_SERVICE_ENABLE` to be enabled. + * Requires the feature `OPENTHREAD_CONFIG_TMF_NETDATA_SERVICE_ENABLE` to be enabled. * * A call to this function will remove and replace any previous "DNS/SRP Service" entry that was being published (from * earlier call to any of `otNetDataPublishDnsSrpService{Type}()` functions). @@ -145,9 +145,9 @@ void otNetDataPublishDnsSrpServiceUnicast(otInstance *aInstance, const otIp6Addr void otNetDataPublishDnsSrpServiceUnicastMeshLocalEid(otInstance *aInstance, uint16_t aPort); /** - * This function indicates whether or not currently the "DNS/SRP Service" entry is added to the Thread Network Data. + * Indicates whether or not currently the "DNS/SRP Service" entry is added to the Thread Network Data. * - * This function requires the feature `OPENTHREAD_CONFIG_TMF_NETDATA_SERVICE_ENABLE` to be enabled. + * Requires the feature `OPENTHREAD_CONFIG_TMF_NETDATA_SERVICE_ENABLE` to be enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -158,12 +158,12 @@ void otNetDataPublishDnsSrpServiceUnicastMeshLocalEid(otInstance *aInstance, uin bool otNetDataIsDnsSrpServiceAdded(otInstance *aInstance); /** - * This function sets a callback for notifying when a published "DNS/SRP Service" is actually added to or removed from + * Sets a callback for notifying when a published "DNS/SRP Service" is actually added to or removed from * the Thread Network Data. * * A subsequent call to this function replaces any previously set callback function. * - * This function requires the feature `OPENTHREAD_CONFIG_TMF_NETDATA_SERVICE_ENABLE` to be enabled. + * Requires the feature `OPENTHREAD_CONFIG_TMF_NETDATA_SERVICE_ENABLE` to be enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aCallback The callback function pointer (can be NULL if not needed). @@ -186,9 +186,9 @@ void otNetDataSetDnsSrpServicePublisherCallback(otInstance void otNetDataUnpublishDnsSrpService(otInstance *aInstance); /** - * This function requests an on-mesh prefix to be published in the Thread Network Data. + * Requests an on-mesh prefix to be published in the Thread Network Data. * - * This function requires the feature `OPENTHREAD_CONFIG_BORDER_ROUTER_ENABLE` to be enabled. + * Requires the feature `OPENTHREAD_CONFIG_BORDER_ROUTER_ENABLE` to be enabled. * * Only stable entries can be published (i.e.,`aConfig.mStable` MUST be TRUE). * @@ -213,9 +213,9 @@ void otNetDataUnpublishDnsSrpService(otInstance *aInstance); otError otNetDataPublishOnMeshPrefix(otInstance *aInstance, const otBorderRouterConfig *aConfig); /** - * This function requests an external route prefix to be published in the Thread Network Data. + * Requests an external route prefix to be published in the Thread Network Data. * - * This function requires the feature `OPENTHREAD_CONFIG_BORDER_ROUTER_ENABLE` to be enabled. + * Requires the feature `OPENTHREAD_CONFIG_BORDER_ROUTER_ENABLE` to be enabled. * * Only stable entries can be published (i.e.,`aConfig.mStable` MUST be TRUE). * @@ -238,10 +238,46 @@ otError otNetDataPublishOnMeshPrefix(otInstance *aInstance, const otBorderRouter otError otNetDataPublishExternalRoute(otInstance *aInstance, const otExternalRouteConfig *aConfig); /** - * This function indicates whether or not currently a published prefix entry (on-mesh or external route) is added to + * Replaces a previously published external route in the Thread Network Data. + * + * Requires the feature `OPENTHREAD_CONFIG_BORDER_ROUTER_ENABLE` to be enabled. + * + * If there is no previously published external route matching @p aPrefix, this function behaves similarly to + * `otNetDataPublishExternalRoute()`, i.e., it will start the process of publishing @a aConfig as an external route in + * the Thread Network Data. + * + * If there is a previously published route entry matching @p aPrefix, it will be replaced with the new prefix from + * @p aConfig. + * + * - If the @p aPrefix was already added in the Network Data, the change to the new prefix in @p aConfig is immediately + * reflected in the Network Data. This ensures that route entries in the Network Data are not abruptly removed and + * the transition from aPrefix to the new prefix is smooth. + * + * - If the old published @p aPrefix was not added in the Network Data, it will be replaced with the new @p aConfig + * prefix but it will not be immediately added. Instead, it will start the process of publishing it in the Network + * Data (monitoring the Network Data to determine when/if to add the prefix, depending on the number of similar + * prefixes present in the Network Data). + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aPrefix The previously published external route prefix to replace. + * @param[in] aConfig The external route config to publish. + * + * @retval OT_ERROR_NONE The external route is published successfully. + * @retval OT_ERROR_INVALID_ARGS The @p aConfig is not valid (bad prefix, invalid flag combinations, or not stable). + * @retval OT_ERROR_NO_BUFS Could not allocate an entry for the new request. Publisher supports a limited number + * of entries (shared between on-mesh prefix and external route) determined by config + * `OPENTHREAD_CONFIG_NETDATA_PUBLISHER_MAX_PREFIX_ENTRIES`. + * + */ +otError otNetDataReplacePublishedExternalRoute(otInstance *aInstance, + const otIp6Prefix *aPrefix, + const otExternalRouteConfig *aConfig); + +/** + * Indicates whether or not currently a published prefix entry (on-mesh or external route) is added to * the Thread Network Data. * - * This function requires the feature `OPENTHREAD_CONFIG_BORDER_ROUTER_ENABLE` to be enabled. + * Requires the feature `OPENTHREAD_CONFIG_BORDER_ROUTER_ENABLE` to be enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aPrefix A pointer to the prefix (MUST NOT be NULL). @@ -253,12 +289,12 @@ otError otNetDataPublishExternalRoute(otInstance *aInstance, const otExternalRou bool otNetDataIsPrefixAdded(otInstance *aInstance, const otIp6Prefix *aPrefix); /** - * This function sets a callback for notifying when a published prefix entry is actually added to or removed from + * Sets a callback for notifying when a published prefix entry is actually added to or removed from * the Thread Network Data. * * A subsequent call to this function replaces any previously set callback function. * - * This function requires the feature `OPENTHREAD_CONFIG_BORDER_ROUTER_ENABLE` to be enabled. + * Requires the feature `OPENTHREAD_CONFIG_BORDER_ROUTER_ENABLE` to be enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aCallback The callback function pointer (can be NULL if not needed). diff --git a/openthread/include/openthread/netdiag.h b/openthread/include/openthread/netdiag.h index eb3e7b6977..040ad75d1e 100644 --- a/openthread/include/openthread/netdiag.h +++ b/openthread/include/openthread/netdiag.h @@ -66,28 +66,45 @@ extern "C" { enum { - OT_NETWORK_DIAGNOSTIC_TLV_EXT_ADDRESS = 0, ///< MAC Extended Address TLV - OT_NETWORK_DIAGNOSTIC_TLV_SHORT_ADDRESS = 1, ///< Address16 TLV - OT_NETWORK_DIAGNOSTIC_TLV_MODE = 2, ///< Mode TLV - OT_NETWORK_DIAGNOSTIC_TLV_TIMEOUT = 3, ///< Timeout TLV (the maximum polling time period for SEDs) - OT_NETWORK_DIAGNOSTIC_TLV_CONNECTIVITY = 4, ///< Connectivity TLV - OT_NETWORK_DIAGNOSTIC_TLV_ROUTE = 5, ///< Route64 TLV - OT_NETWORK_DIAGNOSTIC_TLV_LEADER_DATA = 6, ///< Leader Data TLV - OT_NETWORK_DIAGNOSTIC_TLV_NETWORK_DATA = 7, ///< Network Data TLV - OT_NETWORK_DIAGNOSTIC_TLV_IP6_ADDR_LIST = 8, ///< IPv6 Address List TLV - OT_NETWORK_DIAGNOSTIC_TLV_MAC_COUNTERS = 9, ///< MAC Counters TLV - OT_NETWORK_DIAGNOSTIC_TLV_BATTERY_LEVEL = 14, ///< Battery Level TLV - OT_NETWORK_DIAGNOSTIC_TLV_SUPPLY_VOLTAGE = 15, ///< Supply Voltage TLV - OT_NETWORK_DIAGNOSTIC_TLV_CHILD_TABLE = 16, ///< Child Table TLV - OT_NETWORK_DIAGNOSTIC_TLV_CHANNEL_PAGES = 17, ///< Channel Pages TLV - OT_NETWORK_DIAGNOSTIC_TLV_TYPE_LIST = 18, ///< Type List TLV - OT_NETWORK_DIAGNOSTIC_TLV_MAX_CHILD_TIMEOUT = 19, ///< Max Child Timeout TLV + OT_NETWORK_DIAGNOSTIC_TLV_EXT_ADDRESS = 0, ///< MAC Extended Address TLV + OT_NETWORK_DIAGNOSTIC_TLV_SHORT_ADDRESS = 1, ///< Address16 TLV + OT_NETWORK_DIAGNOSTIC_TLV_MODE = 2, ///< Mode TLV + OT_NETWORK_DIAGNOSTIC_TLV_TIMEOUT = 3, ///< Timeout TLV (the maximum polling time period for SEDs) + OT_NETWORK_DIAGNOSTIC_TLV_CONNECTIVITY = 4, ///< Connectivity TLV + OT_NETWORK_DIAGNOSTIC_TLV_ROUTE = 5, ///< Route64 TLV + OT_NETWORK_DIAGNOSTIC_TLV_LEADER_DATA = 6, ///< Leader Data TLV + OT_NETWORK_DIAGNOSTIC_TLV_NETWORK_DATA = 7, ///< Network Data TLV + OT_NETWORK_DIAGNOSTIC_TLV_IP6_ADDR_LIST = 8, ///< IPv6 Address List TLV + OT_NETWORK_DIAGNOSTIC_TLV_MAC_COUNTERS = 9, ///< MAC Counters TLV + OT_NETWORK_DIAGNOSTIC_TLV_BATTERY_LEVEL = 14, ///< Battery Level TLV + OT_NETWORK_DIAGNOSTIC_TLV_SUPPLY_VOLTAGE = 15, ///< Supply Voltage TLV + OT_NETWORK_DIAGNOSTIC_TLV_CHILD_TABLE = 16, ///< Child Table TLV + OT_NETWORK_DIAGNOSTIC_TLV_CHANNEL_PAGES = 17, ///< Channel Pages TLV + OT_NETWORK_DIAGNOSTIC_TLV_TYPE_LIST = 18, ///< Type List TLV + OT_NETWORK_DIAGNOSTIC_TLV_MAX_CHILD_TIMEOUT = 19, ///< Max Child Timeout TLV + OT_NETWORK_DIAGNOSTIC_TLV_VERSION = 24, ///< Version TLV + OT_NETWORK_DIAGNOSTIC_TLV_VENDOR_NAME = 25, ///< Vendor Name TLV + OT_NETWORK_DIAGNOSTIC_TLV_VENDOR_MODEL = 26, ///< Vendor Model TLV + OT_NETWORK_DIAGNOSTIC_TLV_VENDOR_SW_VERSION = 27, ///< Vendor SW Version TLV + OT_NETWORK_DIAGNOSTIC_TLV_THREAD_STACK_VERSION = 28, ///< Thread Stack Version TLV + OT_NETWORK_DIAGNOSTIC_TLV_CHILD = 29, ///< Child TLV + OT_NETWORK_DIAGNOSTIC_TLV_CHILD_IP6_ADDR_LIST = 30, ///< Child IPv6 Address List TLV + OT_NETWORK_DIAGNOSTIC_TLV_ROUTER_NEIGHBOR = 31, ///< Router Neighbor TLV + OT_NETWORK_DIAGNOSTIC_TLV_ANSWER = 32, ///< Answer TLV + OT_NETWORK_DIAGNOSTIC_TLV_QUERY_ID = 33, ///< Query ID TLV + OT_NETWORK_DIAGNOSTIC_TLV_MLE_COUNTERS = 34, ///< MLE Counters TLV + }; +#define OT_NETWORK_DIAGNOSTIC_MAX_VENDOR_NAME_TLV_LENGTH 32 ///< Max length of Vendor Name TLV. +#define OT_NETWORK_DIAGNOSTIC_MAX_VENDOR_MODEL_TLV_LENGTH 32 ///< Max length of Vendor Model TLV. +#define OT_NETWORK_DIAGNOSTIC_MAX_VENDOR_SW_VERSION_TLV_LENGTH 16 ///< Max length of Vendor SW Version TLV. +#define OT_NETWORK_DIAGNOSTIC_MAX_THREAD_STACK_VERSION_TLV_LENGTH 64 ///< Max length of Thread Stack Version TLV. + typedef uint16_t otNetworkDiagIterator; ///< Used to iterate through Network Diagnostic TLV. /** - * This structure represents a Network Diagnostic Connectivity value. + * Represents a Network Diagnostic Connectivity value. * */ typedef struct otNetworkDiagConnectivity @@ -139,7 +156,7 @@ typedef struct otNetworkDiagConnectivity } otNetworkDiagConnectivity; /** - * This structure represents a Network Diagnostic Route data. + * Represents a Network Diagnostic Route data. * */ typedef struct otNetworkDiagRouteData @@ -151,7 +168,7 @@ typedef struct otNetworkDiagRouteData } otNetworkDiagRouteData; /** - * This structure represents a Network Diagnostic Route TLV value. + * Represents a Network Diagnostic Route TLV value. * */ typedef struct otNetworkDiagRoute @@ -173,7 +190,7 @@ typedef struct otNetworkDiagRoute } otNetworkDiagRoute; /** - * This structure represents a Network Diagnostic Mac Counters value. + * Represents a Network Diagnostic Mac Counters value. * * See RFC 2863 for definitions of member fields. * @@ -192,7 +209,30 @@ typedef struct otNetworkDiagMacCounters } otNetworkDiagMacCounters; /** - * This structure represents a Network Diagnostic Child Table Entry. + * Represents a Network Diagnostics MLE Counters value. + * + */ +typedef struct otNetworkDiagMleCounters +{ + uint16_t mDisabledRole; ///< Number of times device entered disabled role. + uint16_t mDetachedRole; ///< Number of times device entered detached role. + uint16_t mChildRole; ///< Number of times device entered child role. + uint16_t mRouterRole; ///< Number of times device entered router role. + uint16_t mLeaderRole; ///< Number of times device entered leader role. + uint16_t mAttachAttempts; ///< Number of attach attempts while device was detached. + uint16_t mPartitionIdChanges; ///< Number of changes to partition ID. + uint16_t mBetterPartitionAttachAttempts; ///< Number of attempts to attach to a better partition. + uint16_t mParentChanges; ///< Number of time device changed its parent. + uint64_t mTrackedTime; ///< Milliseconds tracked by next counters (zero if not supported). + uint64_t mDisabledTime; ///< Milliseconds device has been in disabled role. + uint64_t mDetachedTime; ///< Milliseconds device has been in detached role. + uint64_t mChildTime; ///< Milliseconds device has been in child role. + uint64_t mRouterTime; ///< Milliseconds device has been in router role. + uint64_t mLeaderTime; ///< Milliseconds device has been in leader role. +} otNetworkDiagMleCounters; + +/** + * Represents a Network Diagnostic Child Table Entry. * */ typedef struct otNetworkDiagChildEntry @@ -222,7 +262,7 @@ typedef struct otNetworkDiagChildEntry } otNetworkDiagChildEntry; /** - * This structure represents a Network Diagnostic TLV. + * Represents a Network Diagnostic TLV. * */ typedef struct otNetworkDiagTlv @@ -242,9 +282,15 @@ typedef struct otNetworkDiagTlv otNetworkDiagRoute mRoute; otLeaderData mLeaderData; otNetworkDiagMacCounters mMacCounters; + otNetworkDiagMleCounters mMleCounters; uint8_t mBatteryLevel; uint16_t mSupplyVoltage; uint32_t mMaxChildTimeout; + uint16_t mVersion; + char mVendorName[OT_NETWORK_DIAGNOSTIC_MAX_VENDOR_NAME_TLV_LENGTH + 1]; + char mVendorModel[OT_NETWORK_DIAGNOSTIC_MAX_VENDOR_MODEL_TLV_LENGTH + 1]; + char mVendorSwVersion[OT_NETWORK_DIAGNOSTIC_MAX_VENDOR_SW_VERSION_TLV_LENGTH + 1]; + char mThreadStackVersion[OT_NETWORK_DIAGNOSTIC_MAX_THREAD_STACK_VERSION_TLV_LENGTH + 1]; struct { uint8_t mCount; @@ -270,7 +316,9 @@ typedef struct otNetworkDiagTlv } otNetworkDiagTlv; /** - * This function gets the next Network Diagnostic TLV in the message. + * Gets the next Network Diagnostic TLV in the message. + * + * Requires `OPENTHREAD_CONFIG_TMF_NETDIAG_CLIENT_ENABLE`. * * @param[in] aMessage A pointer to a message. * @param[in,out] aIterator A pointer to the Network Diagnostic iterator context. To get the first @@ -289,7 +337,7 @@ otError otThreadGetNextDiagnosticTlv(const otMessage *aMessage, otNetworkDiagTlv *aNetworkDiagTlv); /** - * This function pointer is called when Network Diagnostic Get response is received. + * Pointer is called when Network Diagnostic Get response is received. * * @param[in] aError The error when failed to get the response. * @param[in] aMessage A pointer to the message buffer containing the received Network Diagnostic @@ -307,6 +355,8 @@ typedef void (*otReceiveDiagnosticGetCallback)(otError aError, /** * Send a Network Diagnostic Get request. * + * Requires `OPENTHREAD_CONFIG_TMF_NETDIAG_CLIENT_ENABLE`. + * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aDestination A pointer to destination address. * @param[in] aTlvTypes An array of Network Diagnostic TLV types. @@ -329,6 +379,8 @@ otError otThreadSendDiagnosticGet(otInstance *aInstance, /** * Send a Network Diagnostic Reset request. * + * Requires `OPENTHREAD_CONFIG_TMF_NETDIAG_CLIENT_ENABLE`. + * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aDestination A pointer to destination address. * @param[in] aTlvTypes An array of Network Diagnostic TLV types. Currently only Type 9 is allowed. @@ -343,6 +395,87 @@ otError otThreadSendDiagnosticReset(otInstance *aInstance, const uint8_t aTlvTypes[], uint8_t aCount); +/** + * Get the vendor name string. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * + * @returns The vendor name string. + * + */ +const char *otThreadGetVendorName(otInstance *aInstance); + +/** + * Get the vendor model string. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * + * @returns The vendor model string. + * + */ +const char *otThreadGetVendorModel(otInstance *aInstance); + +/** + * Get the vendor sw version string. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * + * @returns The vendor sw version string. + * + */ +const char *otThreadGetVendorSwVersion(otInstance *aInstance); + +/** + * Set the vendor name string. + * + * Requires `OPENTHREAD_CONFIG_NET_DIAG_VENDOR_INFO_SET_API_ENABLE`. + * + * @p aVendorName should be UTF8 with max length of 32 chars (`MAX_VENDOR_NAME_TLV_LENGTH`). Maximum length does not + * include the null `\0` character. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aVendorName The vendor name string. + * + * @retval OT_ERROR_NONE Successfully set the vendor name. + * @retval OT_ERROR_INVALID_ARGS @p aVendorName is not valid (too long or not UTF8). + * + */ +otError otThreadSetVendorName(otInstance *aInstance, const char *aVendorName); + +/** + * Set the vendor model string. + * + * Requires `OPENTHREAD_CONFIG_NET_DIAG_VENDOR_INFO_SET_API_ENABLE`. + * + * @p aVendorModel should be UTF8 with max length of 32 chars (`MAX_VENDOR_MODEL_TLV_LENGTH`). Maximum length does not + * include the null `\0` character. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aVendorModel The vendor model string. + * + * @retval OT_ERROR_NONE Successfully set the vendor model. + * @retval OT_ERROR_INVALID_ARGS @p aVendorModel is not valid (too long or not UTF8). + * + */ +otError otThreadSetVendorModel(otInstance *aInstance, const char *aVendorModel); + +/** + * Set the vendor software version string. + * + * Requires `OPENTHREAD_CONFIG_NET_DIAG_VENDOR_INFO_SET_API_ENABLE`. + * + * @p aVendorSwVersion should be UTF8 with max length of 16 chars(`MAX_VENDOR_SW_VERSION_TLV_LENGTH`). Maximum length + * does not include the null `\0` character. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aVendorSwVersion The vendor software version string. + * + * @retval OT_ERROR_NONE Successfully set the vendor software version. + * @retval OT_ERROR_INVALID_ARGS @p aVendorSwVersion is not valid (too long or not UTF8). + * + */ +otError otThreadSetVendorSwVersion(otInstance *aInstance, const char *aVendorSwVersion); + /** * @} * diff --git a/openthread/include/openthread/network_time.h b/openthread/include/openthread/network_time.h index e20a9d5a34..7d5d153c5c 100644 --- a/openthread/include/openthread/network_time.h +++ b/openthread/include/openthread/network_time.h @@ -53,7 +53,7 @@ extern "C" { */ /** - * This enumeration represents OpenThread time synchronization status. + * Represents OpenThread time synchronization status. * */ typedef enum otNetworkTimeStatus @@ -64,7 +64,7 @@ typedef enum otNetworkTimeStatus } otNetworkTimeStatus; /** - * This function pointer is called when a network time sync or status change occurs. + * Pointer is called when a network time sync or status change occurs. * */ typedef void (*otNetworkTimeSyncCallbackFn)(void *aCallbackContext); @@ -89,7 +89,7 @@ otNetworkTimeStatus otNetworkTimeGet(otInstance *aInstance, uint64_t *aNetworkTi /** * Set the time synchronization period. * - * This function can only be called while Thread protocols are disabled. + * Can only be called while Thread protocols are disabled. * * @param[in] aInstance The OpenThread instance structure. * @param[in] aTimeSyncPeriod The time synchronization period, in seconds. @@ -113,7 +113,7 @@ uint16_t otNetworkTimeGetSyncPeriod(otInstance *aInstance); /** * Set the time synchronization XTAL accuracy threshold for Router-Capable device. * - * This function can only be called while Thread protocols are disabled. + * Can only be called while Thread protocols are disabled. * * @param[in] aInstance The OpenThread instance structure. * @param[in] aXTALThreshold The XTAL accuracy threshold for Router, in PPM. diff --git a/openthread/include/openthread/ping_sender.h b/openthread/include/openthread/ping_sender.h index a0e30ca9ae..174cccc25c 100644 --- a/openthread/include/openthread/ping_sender.h +++ b/openthread/include/openthread/ping_sender.h @@ -56,7 +56,7 @@ extern "C" { */ /** - * This structure represents a ping reply. + * Represents a ping reply. * */ typedef struct otPingSenderReply @@ -69,7 +69,7 @@ typedef struct otPingSenderReply } otPingSenderReply; /** - * This structure represents statistics of a ping request. + * Represents statistics of a ping request. * */ typedef struct otPingSenderStatistics @@ -83,7 +83,7 @@ typedef struct otPingSenderStatistics } otPingSenderStatistics; /** - * This function pointer type specifies the callback to notify receipt of a ping reply. + * Pointer type specifies the callback to notify receipt of a ping reply. * * @param[in] aReply A pointer to a `otPingSenderReply` containing info about the received ping reply. * @param[in] aContext A pointer to application-specific context. @@ -92,7 +92,7 @@ typedef struct otPingSenderStatistics typedef void (*otPingSenderReplyCallback)(const otPingSenderReply *aReply, void *aContext); /** - * This function pointer type specifies the callback to report the ping statistics. + * Pointer type specifies the callback to report the ping statistics. * * @param[in] aStatistics A pointer to a `otPingSenderStatistics` containing info about the received ping * statistics. @@ -102,7 +102,7 @@ typedef void (*otPingSenderReplyCallback)(const otPingSenderReply *aReply, void typedef void (*otPingSenderStatisticsCallback)(const otPingSenderStatistics *aStatistics, void *aContext); /** - * This structure represents a ping request configuration. + * Represents a ping request configuration. * */ typedef struct otPingSenderConfig @@ -123,7 +123,7 @@ typedef struct otPingSenderConfig } otPingSenderConfig; /** - * This function starts a ping. + * Starts a ping. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aConfig The ping config to use. @@ -137,7 +137,7 @@ typedef struct otPingSenderConfig otError otPingSenderPing(otInstance *aInstance, const otPingSenderConfig *aConfig); /** - * This function stops an ongoing ping. + * Stops an ongoing ping. * * @param[in] aInstance A pointer to an OpenThread instance. * diff --git a/openthread/include/openthread/platform/alarm-micro.h b/openthread/include/openthread/platform/alarm-micro.h index e61640740c..9bbe05d19a 100644 --- a/openthread/include/openthread/platform/alarm-micro.h +++ b/openthread/include/openthread/platform/alarm-micro.h @@ -53,6 +53,9 @@ extern "C" { /** * Set the alarm to fire at @p aDt microseconds after @p aT0. * + * For @p aT0, the platform MUST support all values in [0, 2^32-1]. + * For @p aDt, the platform MUST support all values in [0, 2^31-1]. + * * @param[in] aInstance The OpenThread instance structure. * @param[in] aT0 The reference time. * @param[in] aDt The time delay in microseconds from @p aT0. @@ -71,6 +74,9 @@ void otPlatAlarmMicroStop(otInstance *aInstance); /** * Get the current time. * + * The current time MUST represent a free-running timer. When maintaining current time, the time value MUST utilize the + * entire range [0, 2^32-1] and MUST NOT wrap before 2^32. + * * @returns The current time in microseconds. * */ diff --git a/openthread/include/openthread/platform/alarm-milli.h b/openthread/include/openthread/platform/alarm-milli.h index dd72201633..48fb08cf26 100644 --- a/openthread/include/openthread/platform/alarm-milli.h +++ b/openthread/include/openthread/platform/alarm-milli.h @@ -56,6 +56,9 @@ extern "C" { /** * Set the alarm to fire at @p aDt milliseconds after @p aT0. * + * For @p aT0 the platform MUST support all values in [0, 2^32-1]. + * For @p aDt, the platform MUST support all values in [0, 2^31-1]. + * * @param[in] aInstance The OpenThread instance structure. * @param[in] aT0 The reference time. * @param[in] aDt The time delay in milliseconds from @p aT0. @@ -72,6 +75,9 @@ void otPlatAlarmMilliStop(otInstance *aInstance); /** * Get the current time. * + * The current time MUST represent a free-running timer. When maintaining current time, the time value MUST utilize the + * entire range [0, 2^32-1] and MUST NOT wrap before 2^32. + * * @returns The current time in milliseconds. */ uint32_t otPlatAlarmMilliGetNow(void); diff --git a/openthread/include/openthread/platform/border_routing.h b/openthread/include/openthread/platform/border_routing.h new file mode 100644 index 0000000000..eeb825c0d8 --- /dev/null +++ b/openthread/include/openthread/platform/border_routing.h @@ -0,0 +1,72 @@ +/* + * Copyright (c) 2023, The OpenThread Authors. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * 3. Neither the name of the copyright holder nor the + * names of its contributors may be used to endorse or promote products + * derived from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +/** + * @file + * @brief + * This file includes the platform abstraction for border routing manager. + */ + +#ifndef OPENTHREAD_PLATFORM_BORDER_ROUTER_H_ +#define OPENTHREAD_PLATFORM_BORDER_ROUTER_H_ + +#include + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * Handles ICMP6 RA messages received on the Thread interface on the platform. + * + * The `aMessage` should point to a buffer of a valid ICMPv6 message (without IP headers) with router advertisement as + * the value of type field of the message. + * + * When DHCPv6 PD is disabled, the message will be dropped silently. + * + * Note: RA messages will not be forwarded into Thread networks, while for many platforms, RA messages is the way of + * distributing a prefix and other infomations to the downstream network. The typical usecase of this function is to + * handle the router advertisement messages sent by the platform as a result of DHCPv6 Prefix Delegation. + * + * Requires `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE`. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aMessage A pointer to an ICMPv6 RouterAdvertisement message. + * @param[in] aLength The length of ICMPv6 RouterAdvertisement message. + * + */ +extern void otPlatBorderRoutingProcessIcmp6Ra(otInstance *aInstance, const uint8_t *aMessage, uint16_t aLength); + +#ifdef __cplusplus +} +#endif + +#endif // OPENTHREAD_PLATFORM_BORDER_ROUTER_H_ diff --git a/openthread/include/openthread/platform/crypto.h b/openthread/include/openthread/platform/crypto.h index 69253bb0dd..8762fc2ce6 100644 --- a/openthread/include/openthread/platform/crypto.h +++ b/openthread/include/openthread/platform/crypto.h @@ -55,18 +55,19 @@ extern "C" { */ /** - * This enumeration defines the key types. + * Defines the key types. * */ typedef enum { - OT_CRYPTO_KEY_TYPE_RAW, ///< Key Type: Raw Data. - OT_CRYPTO_KEY_TYPE_AES, ///< Key Type: AES. - OT_CRYPTO_KEY_TYPE_HMAC, ///< Key Type: HMAC. + OT_CRYPTO_KEY_TYPE_RAW, ///< Key Type: Raw Data. + OT_CRYPTO_KEY_TYPE_AES, ///< Key Type: AES. + OT_CRYPTO_KEY_TYPE_HMAC, ///< Key Type: HMAC. + OT_CRYPTO_KEY_TYPE_ECDSA, ///< Key Type: ECDSA. } otCryptoKeyType; /** - * This enumeration defines the key algorithms. + * Defines the key algorithms. * */ typedef enum @@ -74,23 +75,25 @@ typedef enum OT_CRYPTO_KEY_ALG_VENDOR, ///< Key Algorithm: Vendor Defined. OT_CRYPTO_KEY_ALG_AES_ECB, ///< Key Algorithm: AES ECB. OT_CRYPTO_KEY_ALG_HMAC_SHA_256, ///< Key Algorithm: HMAC SHA-256. + OT_CRYPTO_KEY_ALG_ECDSA, ///< Key Algorithm: ECDSA. } otCryptoKeyAlgorithm; /** - * This enumeration defines the key usage flags. + * Defines the key usage flags. * */ enum { - OT_CRYPTO_KEY_USAGE_NONE = 0, ///< Key Usage: Key Usage is empty. - OT_CRYPTO_KEY_USAGE_EXPORT = 1 << 0, ///< Key Usage: Key can be exported. - OT_CRYPTO_KEY_USAGE_ENCRYPT = 1 << 1, ///< Key Usage: Encryption (vendor defined). - OT_CRYPTO_KEY_USAGE_DECRYPT = 1 << 2, ///< Key Usage: AES ECB. - OT_CRYPTO_KEY_USAGE_SIGN_HASH = 1 << 3, ///< Key Usage: HMAC SHA-256. + OT_CRYPTO_KEY_USAGE_NONE = 0, ///< Key Usage: Key Usage is empty. + OT_CRYPTO_KEY_USAGE_EXPORT = 1 << 0, ///< Key Usage: Key can be exported. + OT_CRYPTO_KEY_USAGE_ENCRYPT = 1 << 1, ///< Key Usage: Encryption (vendor defined). + OT_CRYPTO_KEY_USAGE_DECRYPT = 1 << 2, ///< Key Usage: AES ECB. + OT_CRYPTO_KEY_USAGE_SIGN_HASH = 1 << 3, ///< Key Usage: Sign Hash. + OT_CRYPTO_KEY_USAGE_VERIFY_HASH = 1 << 4, ///< Key Usage: Verify Hash. }; /** - * This enumeration defines the key storage types. + * Defines the key storage types. * */ typedef enum @@ -108,7 +111,7 @@ typedef uint32_t otCryptoKeyRef; /** * @struct otCryptoKey * - * This structure represents the Key Material required for Crypto operations. + * Represents the Key Material required for Crypto operations. * */ typedef struct otCryptoKey @@ -121,7 +124,7 @@ typedef struct otCryptoKey /** * @struct otCryptoContext * - * This structure stores the context object for platform APIs. + * Stores the context object for platform APIs. * */ typedef struct otCryptoContext @@ -139,7 +142,7 @@ typedef struct otCryptoContext /** * @struct otPlatCryptoSha256Hash * - * This structure represents a SHA-256 hash. + * Represents a SHA-256 hash. * */ OT_TOOL_PACKED_BEGIN @@ -149,7 +152,7 @@ struct otPlatCryptoSha256Hash } OT_TOOL_PACKED_END; /** - * This structure represents a SHA-256 hash. + * Represents a SHA-256 hash. * */ typedef struct otPlatCryptoSha256Hash otPlatCryptoSha256Hash; @@ -163,7 +166,7 @@ typedef struct otPlatCryptoSha256Hash otPlatCryptoSha256Hash; /** * @struct otPlatCryptoEcdsaKeyPair * - * This structure represents an ECDSA key pair (public and private keys). + * Represents an ECDSA key pair (public and private keys). * * The key pair is stored using Distinguished Encoding Rules (DER) format (per RFC 5915). * @@ -183,7 +186,7 @@ typedef struct otPlatCryptoEcdsaKeyPair /** * @struct otPlatCryptoEcdsaPublicKey * - * This struct represents a ECDSA public key. + * Represents a ECDSA public key. * * The public key is stored as a byte sequence representation of an uncompressed curve point (RFC 6605 - sec 4). * @@ -205,7 +208,7 @@ typedef struct otPlatCryptoEcdsaPublicKey otPlatCryptoEcdsaPublicKey; /** * @struct otPlatCryptoEcdsaSignature * - * This struct represents an ECDSA signature. + * Represents an ECDSA signature. * * The signature is encoded as the concatenated binary representation of two MPIs `r` and `s` which are calculated * during signing (RFC 6605 - section 4). @@ -613,7 +616,7 @@ otError otPlatCryptoEcdsaGetPublicKey(const otPlatCryptoEcdsaKeyPair *aKeyPair, /** * Calculate the ECDSA signature for a hashed message using the private key from the input context. * - * This method uses the deterministic digital signature generation procedure from RFC 6979. + * Uses the deterministic digital signature generation procedure from RFC 6979. * * @param[in] aKeyPair A pointer to an ECDSA key-pair structure where the key-pair is stored. * @param[in] aHash A pointer to a SHA-256 hash structure where the hash value for signature calculation @@ -650,6 +653,85 @@ otError otPlatCryptoEcdsaVerify(const otPlatCryptoEcdsaPublicKey *aPublicKey, const otPlatCryptoSha256Hash *aHash, const otPlatCryptoEcdsaSignature *aSignature); +/** + * Calculate the ECDSA signature for a hashed message using the Key reference passed. + * + * Uses the deterministic digital signature generation procedure from RFC 6979. + * + * @param[in] aKeyRef Key Reference to the slot where the key-pair is stored. + * @param[in] aHash A pointer to a SHA-256 hash structure where the hash value for signature calculation + * is stored. + * @param[out] aSignature A pointer to an ECDSA signature structure to output the calculated signature. + * + * @retval OT_ERROR_NONE The signature was calculated successfully, @p aSignature was updated. + * @retval OT_ERROR_PARSE The key-pair DER format could not be parsed (invalid format). + * @retval OT_ERROR_NO_BUFS Failed to allocate buffer for signature calculation. + * @retval OT_ERROR_INVALID_ARGS The @p aContext is NULL. + * + * @note This API is only used by OT core when `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` is enabled. + * + */ +otError otPlatCryptoEcdsaSignUsingKeyRef(otCryptoKeyRef aKeyRef, + const otPlatCryptoSha256Hash *aHash, + otPlatCryptoEcdsaSignature *aSignature); + +/** + * Get the associated public key from the key reference passed. + * + * The public key is stored differently depending on the crypto backend library being used + * (OPENTHREAD_CONFIG_CRYPTO_LIB). + * + * This API must make sure to return the public key as a byte sequence representation of an + * uncompressed curve point (RFC 6605 - sec 4) + * + * @param[in] aKeyRef Key Reference to the slot where the key-pair is stored. + * @param[out] aPublicKey A pointer to an ECDSA public key structure to store the public key. + * + * @retval OT_ERROR_NONE Public key was retrieved successfully, and @p aBuffer is updated. + * @retval OT_ERROR_PARSE The key-pair DER format could not be parsed (invalid format). + * @retval OT_ERROR_INVALID_ARGS The @p aContext is NULL. + * + * @note This API is only used by OT core when `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` is enabled. + * + */ +otError otPlatCryptoEcdsaExportPublicKey(otCryptoKeyRef aKeyRef, otPlatCryptoEcdsaPublicKey *aPublicKey); + +/** + * Generate and import a new ECDSA key-pair at reference passed. + * + * @param[in] aKeyRef Key Reference to the slot where the key-pair is stored. + * + * @retval OT_ERROR_NONE A new key-pair was generated successfully. + * @retval OT_ERROR_NO_BUFS Failed to allocate buffer for key generation. + * @retval OT_ERROR_NOT_CAPABLE Feature not supported. + * @retval OT_ERROR_FAILED Failed to generate key-pair. + * + * @note This API is only used by OT core when `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` is enabled. + * + */ +otError otPlatCryptoEcdsaGenerateAndImportKey(otCryptoKeyRef aKeyRef); + +/** + * Use the keyref to verify the ECDSA signature of a hashed message. + * + * @param[in] aKeyRef Key Reference to the slot where the key-pair is stored. + * @param[in] aHash A pointer to a SHA-256 hash structure where the hash value for signature verification + * is stored. + * @param[in] aSignature A pointer to an ECDSA signature structure where the signature value to be verified is + * stored. + * + * @retval OT_ERROR_NONE The signature was verified successfully. + * @retval OT_ERROR_SECURITY The signature is invalid. + * @retval OT_ERROR_INVALID_ARGS The key or hash is invalid. + * @retval OT_ERROR_NO_BUFS Failed to allocate buffer for signature verification. + * + * @note This API is only used by OT core when `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` is enabled. + * + */ +otError otPlatCryptoEcdsaVerifyUsingKeyRef(otCryptoKeyRef aKeyRef, + const otPlatCryptoSha256Hash *aHash, + const otPlatCryptoEcdsaSignature *aSignature); + /** * Perform PKCS#5 PBKDF2 using CMAC (AES-CMAC-PRF-128). * diff --git a/openthread/include/openthread/platform/debug_uart.h b/openthread/include/openthread/platform/debug_uart.h index b0410aff54..a2643d68e3 100644 --- a/openthread/include/openthread/platform/debug_uart.h +++ b/openthread/include/openthread/platform/debug_uart.h @@ -104,7 +104,7 @@ void otPlatDebugUart_vprintf(const char *fmt, va_list ap); * Platform specific write single byte to Debug Uart * This should not perform CR/LF mapping. * - * This function MUST be implemented by the platform + * MUST be implemented by the platform * * @param[in] c what to transmit */ @@ -114,7 +114,7 @@ void otPlatDebugUart_putchar_raw(int c); * Poll/test debug uart if a key has been pressed. * It would be common to a stub function that returns 0. * - * This function MUST be implemented by the platform + * MUST be implemented by the platform * * @retval zero - nothing ready * @retval nonzero - otPlatDebugUart_getc() will succeed. @@ -124,7 +124,7 @@ int otPlatDebugUart_kbhit(void); /** * Poll/Read a byte from the debug uart * - * This function MUST be implemented by the platform + * MUST be implemented by the platform * * @retval (negative) no data available, see otPlatDebugUart_kbhit() * @retval (0x00..0x0ff) data byte value diff --git a/openthread/include/openthread/platform/diag.h b/openthread/include/openthread/platform/diag.h index df889d2774..7bc2299464 100644 --- a/openthread/include/openthread/platform/diag.h +++ b/openthread/include/openthread/platform/diag.h @@ -57,7 +57,7 @@ extern "C" { */ /** - * This enumeration defines the gpio modes. + * Defines the gpio modes. * */ typedef enum @@ -67,7 +67,7 @@ typedef enum } otGpioMode; /** - * This function processes a factory diagnostics command line. + * Processes a factory diagnostics command line. * * The output of this function (the content written to @p aOutput) MUST terminate with `\0` and the `\0` is within the * output buffer. @@ -90,7 +90,7 @@ otError otPlatDiagProcess(otInstance *aInstance, size_t aOutputMaxLen); /** - * This function enables/disables the factory diagnostics mode. + * Enables/disables the factory diagnostics mode. * * @param[in] aMode TRUE to enable diagnostics mode, FALSE otherwise. * @@ -98,7 +98,7 @@ otError otPlatDiagProcess(otInstance *aInstance, void otPlatDiagModeSet(bool aMode); /** - * This function indicates whether or not factory diagnostics mode is enabled. + * Indicates whether or not factory diagnostics mode is enabled. * * @returns TRUE if factory diagnostics mode is enabled, FALSE otherwise. * @@ -106,7 +106,7 @@ void otPlatDiagModeSet(bool aMode); bool otPlatDiagModeGet(void); /** - * This function sets the channel to use for factory diagnostics. + * Sets the channel to use for factory diagnostics. * * @param[in] aChannel The channel value. * @@ -114,7 +114,7 @@ bool otPlatDiagModeGet(void); void otPlatDiagChannelSet(uint8_t aChannel); /** - * This function sets the transmit power to use for factory diagnostics. + * Sets the transmit power to use for factory diagnostics. * * @param[in] aTxPower The transmit power value. * @@ -122,7 +122,7 @@ void otPlatDiagChannelSet(uint8_t aChannel); void otPlatDiagTxPowerSet(int8_t aTxPower); /** - * This function processes the received radio frame. + * Processes the received radio frame. * * @param[in] aInstance The OpenThread instance for current request. * @param[in] aFrame The received radio frame. @@ -132,7 +132,7 @@ void otPlatDiagTxPowerSet(int8_t aTxPower); void otPlatDiagRadioReceived(otInstance *aInstance, otRadioFrame *aFrame, otError aError); /** - * This function processes the alarm event. + * Processes the alarm event. * * @param[in] aInstance The OpenThread instance for current request. * @@ -140,7 +140,7 @@ void otPlatDiagRadioReceived(otInstance *aInstance, otRadioFrame *aFrame, otErro void otPlatDiagAlarmCallback(otInstance *aInstance); /** - * This function sets the gpio value. + * Sets the gpio value. * * @param[in] aGpio The gpio number. * @param[in] aValue true to set the gpio to high level, or false otherwise. @@ -155,7 +155,7 @@ void otPlatDiagAlarmCallback(otInstance *aInstance); otError otPlatDiagGpioSet(uint32_t aGpio, bool aValue); /** - * This function gets the gpio value. + * Gets the gpio value. * * @param[in] aGpio The gpio number. * @param[out] aValue A pointer where to put gpio value. @@ -170,7 +170,7 @@ otError otPlatDiagGpioSet(uint32_t aGpio, bool aValue); otError otPlatDiagGpioGet(uint32_t aGpio, bool *aValue); /** - * This function sets the gpio mode. + * Sets the gpio mode. * * @param[in] aGpio The gpio number. * @param[out] aMode The gpio mode. @@ -185,7 +185,7 @@ otError otPlatDiagGpioGet(uint32_t aGpio, bool *aValue); otError otPlatDiagGpioSetMode(uint32_t aGpio, otGpioMode aMode); /** - * This function gets the gpio mode. + * Gets the gpio mode. * * @param[in] aGpio The gpio number. * @param[out] aMode A pointer where to put gpio mode. @@ -260,6 +260,19 @@ otError otPlatDiagRadioRawPowerSettingEnable(otInstance *aInstance, bool aEnable */ otError otPlatDiagRadioTransmitCarrier(otInstance *aInstance, bool aEnable); +/** + * Start/stop the platform layer to transmit stream of characters. + * + * @param[in] aInstance The OpenThread instance structure. + * @param[in] aEnable TRUE to enable or FALSE to disable the platform layer to transmit stream. + * + * @retval OT_ERROR_NONE Successfully enabled/disabled. + * @retval OT_ERROR_INVALID_STATE The radio was not in the Receive state. + * @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented. + * + */ +otError otPlatDiagRadioTransmitStream(otInstance *aInstance, bool aEnable); + /** * Get the power settings for the given channel. * diff --git a/openthread/include/openthread/platform/dns.h b/openthread/include/openthread/platform/dns.h new file mode 100644 index 0000000000..9e84fbe43f --- /dev/null +++ b/openthread/include/openthread/platform/dns.h @@ -0,0 +1,114 @@ +/* + * Copyright (c) 2023, The OpenThread Authors. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * 3. Neither the name of the copyright holder nor the + * names of its contributors may be used to endorse or promote products + * derived from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +/** + * @file + * @brief + * This file defines the platform DNS interface. + * + */ + +#ifndef OPENTHREAD_PLATFORM_DNS_H_ +#define OPENTHREAD_PLATFORM_DNS_H_ + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @addtogroup plat-dns + * + * @brief + * This module includes the platform abstraction for sending recursive DNS query to upstream DNS servers. + * + * @{ + * + */ + +/** + * This opaque type represents an upstream DNS query transaction. + * + */ +typedef struct otPlatDnsUpstreamQuery otPlatDnsUpstreamQuery; + +/** + * Starts an upstream query transaction. + * + * - In success case (and errors represented by DNS protocol messages), the platform is expected to call + * `otPlatDnsUpstreamQueryDone`. + * - The OpenThread core may cancel a (possibly timeout) query transaction by calling + * `otPlatDnsCancelUpstreamQuery`, the platform must not call `otPlatDnsUpstreamQueryDone` on a + * cancelled transaction. + * + * @param[in] aInstance The OpenThread instance structure. + * @param[in] aTxn A pointer to the opaque DNS query transaction object. + * @param[in] aQuery A message buffer of the DNS payload that should be sent to upstream DNS server. + * + */ +void otPlatDnsStartUpstreamQuery(otInstance *aInstance, otPlatDnsUpstreamQuery *aTxn, const otMessage *aQuery); + +/** + * Cancels a transaction of upstream query. + * + * The platform must call `otPlatDnsUpstreamQueryDone` to release the resources. + * + * @param[in] aInstance The OpenThread instance structure. + * @param[in] aTxn A pointer to the opaque DNS query transaction object. + * + */ +void otPlatDnsCancelUpstreamQuery(otInstance *aInstance, otPlatDnsUpstreamQuery *aTxn); + +/** + * The platform calls this function to finish DNS query. + * + * The transaction will be released, so the platform must not call on the same transaction twice. This function passes + * the ownership of `aResponse` to OpenThread stack. + * + * Platform can pass a nullptr to close a transaction without a response. + * + * @param[in] aInstance The OpenThread instance structure. + * @param[in] aTxn A pointer to the opaque DNS query transaction object. + * @param[in] aResponse A message buffer of the DNS response payload or `nullptr` to close a transaction without a + * response. + * + */ +extern void otPlatDnsUpstreamQueryDone(otInstance *aInstance, otPlatDnsUpstreamQuery *aTxn, otMessage *aResponse); + +/** + * @} + * + */ + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/openthread/include/openthread/platform/dso_transport.h b/openthread/include/openthread/platform/dso_transport.h index 348ee828a9..4e005895c5 100644 --- a/openthread/include/openthread/platform/dso_transport.h +++ b/openthread/include/openthread/platform/dso_transport.h @@ -47,7 +47,7 @@ extern "C" { #endif /** - * This structure represents a DSO connection. + * Represents a DSO connection. * * It is an opaque struct (the platform implementation only deals with pointers to this struct). * @@ -55,7 +55,7 @@ extern "C" { typedef struct otPlatDsoConnection otPlatDsoConnection; /** - * This function can be used by DSO platform implementation to get the the OpenThread instance associated with a + * Can be used by DSO platform implementation to get the the OpenThread instance associated with a * connection instance. * * @param[in] aConnection A pointer to the DSO connection. @@ -66,7 +66,7 @@ typedef struct otPlatDsoConnection otPlatDsoConnection; extern otInstance *otPlatDsoGetInstance(otPlatDsoConnection *aConnection); /** - * This function starts or stops listening for incoming connection requests on transport layer. + * Starts or stops listening for incoming connection requests on transport layer. * * For DNS-over-TLS, the transport layer MUST listen on port 853 and follow RFC 7858. * @@ -79,10 +79,10 @@ extern otInstance *otPlatDsoGetInstance(otPlatDsoConnection *aConnection); void otPlatDsoEnableListening(otInstance *aInstance, bool aEnable); /** - * This function is a callback from the DSO platform to indicate an incoming connection request when listening is + * Is a callback from the DSO platform to indicate an incoming connection request when listening is * enabled. * - * This function determines whether or not to accept the connection request. It returns a non-null `otPlatDsoConnection` + * Determines whether or not to accept the connection request. It returns a non-null `otPlatDsoConnection` * pointer if the request is to be accepted, or `NULL` if the request is to be rejected. * * If a non-null connection pointer is returned, the platform layer MUST continue establishing the connection with the @@ -98,7 +98,7 @@ void otPlatDsoEnableListening(otInstance *aInstance, bool aEnable); extern otPlatDsoConnection *otPlatDsoAccept(otInstance *aInstance, const otSockAddr *aPeerSockAddr); /** - * This function requests the platform layer to initiate establishing a connection with a peer. + * Requests the platform layer to initiate establishing a connection with a peer. * * The platform reports the outcome by invoking `otPlatDsoHandleConnected()` callback on success or * `otPlatDsoHandleDisconnected()` callback (on failure). @@ -110,7 +110,7 @@ extern otPlatDsoConnection *otPlatDsoAccept(otInstance *aInstance, const otSockA void otPlatDsoConnect(otPlatDsoConnection *aConnection, const otSockAddr *aPeerSockAddr); /** - * This function is a callback from the platform layer to indicate that a connection is successfully established. + * Is a callback from the platform layer to indicate that a connection is successfully established. * * It MUST be called either after accepting an incoming connection (`otPlatDsoAccept`) or after a `otPlatDsoConnect()` * call. @@ -123,12 +123,12 @@ void otPlatDsoConnect(otPlatDsoConnection *aConnection, const otSockAddr *aPeerS extern void otPlatDsoHandleConnected(otPlatDsoConnection *aConnection); /** - * This function sends a DSO message to the peer on a connection. + * Sends a DSO message to the peer on a connection. * - * This function is used only after the connection is successfully established (after `otPlatDsoHandleConnected()` + * Is used only after the connection is successfully established (after `otPlatDsoHandleConnected()` * callback). * - * This function passes the ownership of the @p aMessage to the DSO platform layer, and the platform implementation is + * Passes the ownership of the @p aMessage to the DSO platform layer, and the platform implementation is * expected to free the message once it is no longer needed. * * The @p aMessage contains the DNS message (starting with DNS header). Note that it does not contain the the length @@ -142,12 +142,12 @@ extern void otPlatDsoHandleConnected(otPlatDsoConnection *aConnection); void otPlatDsoSend(otPlatDsoConnection *aConnection, otMessage *aMessage); /** - * This function is a callback from the platform layer to indicate that a DNS message was received over a connection. + * Is a callback from the platform layer to indicate that a DNS message was received over a connection. * * The platform MUST call this function only after the connection is successfully established (after callback * `otPlatDsoHandleConnected()` is invoked). * - * This function passes the ownership of the @p aMessage from the DSO platform layer to OpenThread. OpenThread will + * Passes the ownership of the @p aMessage from the DSO platform layer to OpenThread. OpenThread will * free the message when no longer needed. * * The @p aMessage MUST contain the DNS message (starting with DNS header) and not include the length field that may @@ -160,7 +160,7 @@ void otPlatDsoSend(otPlatDsoConnection *aConnection, otMessage *aMessage); extern void otPlatDsoHandleReceive(otPlatDsoConnection *aConnection, otMessage *aMessage); /** - * This enumeration defines disconnect modes. + * Defines disconnect modes. * */ typedef enum @@ -170,7 +170,7 @@ typedef enum } otPlatDsoDisconnectMode; /** - * This function requests a connection to be disconnected. + * Requests a connection to be disconnected. * * After calling this function, the DSO platform implementation MUST NOT maintain `aConnection` pointer (platform * MUST NOT call any callbacks using this `Connection` pointer anymore). In particular, calling `otPlatDsoDisconnect()` @@ -183,7 +183,7 @@ typedef enum void otPlatDsoDisconnect(otPlatDsoConnection *aConnection, otPlatDsoDisconnectMode aMode); /** - * This function is a callback from the platform layer to indicate that peer closed/aborted the connection or the + * Is a callback from the platform layer to indicate that peer closed/aborted the connection or the * connection establishment failed (e.g., peer rejected a connection request). * * After calling this function, the DSO platform implementation MUST NOT maintain `aConnection` pointer (platform diff --git a/openthread/include/openthread/platform/entropy.h b/openthread/include/openthread/platform/entropy.h index 0271d1baca..f86ced7b38 100644 --- a/openthread/include/openthread/platform/entropy.h +++ b/openthread/include/openthread/platform/entropy.h @@ -56,7 +56,7 @@ extern "C" { /** * Fill buffer with entropy. * - * This function MUST be implemented using a true random number generator (TRNG). + * MUST be implemented using a true random number generator (TRNG). * * @param[out] aOutput A pointer to where the true random values are placed. Must not be NULL. * @param[in] aOutputLength Size of @p aBuffer. diff --git a/openthread/include/openthread/platform/flash.h b/openthread/include/openthread/platform/flash.h index bbb7f3e70e..64fc86093d 100644 --- a/openthread/include/openthread/platform/flash.h +++ b/openthread/include/openthread/platform/flash.h @@ -38,7 +38,7 @@ extern "C" { #endif /** - * This function initializes the flash driver. + * Initializes the flash driver. * * @param[in] aInstance The OpenThread instance structure. * @@ -46,7 +46,7 @@ extern "C" { void otPlatFlashInit(otInstance *aInstance); /** - * This function gets the size of the swap space. + * Gets the size of the swap space. * * @param[in] aInstance The OpenThread instance structure. * @@ -56,7 +56,7 @@ void otPlatFlashInit(otInstance *aInstance); uint32_t otPlatFlashGetSwapSize(otInstance *aInstance); /** - * This function erases the swap space indicated by @p aSwapIndex. + * Erases the swap space indicated by @p aSwapIndex. * * @param[in] aInstance The OpenThread instance structure. * @param[in] aSwapIndex A value in [0, 1] that indicates the swap space. @@ -65,7 +65,7 @@ uint32_t otPlatFlashGetSwapSize(otInstance *aInstance); void otPlatFlashErase(otInstance *aInstance, uint8_t aSwapIndex); /** - * This function reads @p aSize bytes into @p aData. + * Reads @p aSize bytes into @p aData. * * @param[in] aInstance The OpenThread instance structure. * @param[in] aSwapIndex A value in [0, 1] that indicates the swap space. @@ -77,7 +77,7 @@ void otPlatFlashErase(otInstance *aInstance, uint8_t aSwapIndex); void otPlatFlashRead(otInstance *aInstance, uint8_t aSwapIndex, uint32_t aOffset, void *aData, uint32_t aSize); /** - * This function writes @p aSize bytes from @p aData. + * Writes @p aSize bytes from @p aData. * * @param[in] aInstance The OpenThread instance structure. * @param[in] aSwapIndex A value in [0, 1] that indicates the swap space. diff --git a/openthread/include/openthread/platform/infra_if.h b/openthread/include/openthread/platform/infra_if.h index 5d2c50f150..4241efd069 100644 --- a/openthread/include/openthread/platform/infra_if.h +++ b/openthread/include/openthread/platform/infra_if.h @@ -57,7 +57,7 @@ extern "C" { */ /** - * This method tells whether an infra interface has the given IPv6 address assigned. + * Tells whether an infra interface has the given IPv6 address assigned. * * @param[in] aInfraIfIndex The index of the infra interface. * @param[in] aAddress The IPv6 address. @@ -68,7 +68,7 @@ extern "C" { bool otPlatInfraIfHasAddress(uint32_t aInfraIfIndex, const otIp6Address *aAddress); /** - * This method sends an ICMPv6 Neighbor Discovery message on given infrastructure interface. + * Sends an ICMPv6 Neighbor Discovery message on given infrastructure interface. * * See RFC 4861: https://tools.ietf.org/html/rfc4861. * @@ -150,7 +150,7 @@ otError otPlatInfraIfDiscoverNat64Prefix(uint32_t aInfraIfIndex); * The infra interface driver calls this method to notify OpenThread that * the discovery of NAT64 prefix is done. * - * This method is expected to be invoked after calling otPlatInfraIfDiscoverNat64Prefix. + * Is expected to be invoked after calling otPlatInfraIfDiscoverNat64Prefix. * If no NAT64 prefix is discovered, @p aIp6Prefix shall point to an empty prefix with zero length. * * @param[in] aInstance The OpenThread instance structure. diff --git a/openthread/include/openthread/platform/logging.h b/openthread/include/openthread/platform/logging.h index adf123f444..20235dfe26 100644 --- a/openthread/include/openthread/platform/logging.h +++ b/openthread/include/openthread/platform/logging.h @@ -107,13 +107,13 @@ extern "C" { #define OT_LOG_LEVEL_DEBG 5 /** - * This type represents the log level. + * Represents the log level. * */ typedef int otLogLevel; /** - * This enumeration represents log regions. + * Represents log regions. * * The support for log region is removed and instead each core module can define its own name to appended to the logs. * However, the `otLogRegion` enumeration is still defined as before to help with platforms which we may be using it @@ -148,7 +148,7 @@ typedef enum otLogRegion } otLogRegion; /** - * This function outputs logs. + * Outputs logs. * * Note that the support for log region is removed. The OT core will always emit all logs with `OT_LOG_REGION_CORE` * as @p aLogRegion. @@ -162,7 +162,7 @@ typedef enum otLogRegion void otPlatLog(otLogLevel aLogLevel, otLogRegion aLogRegion, const char *aFormat, ...); /** - * This function handles OpenThread log level changes. + * Handles OpenThread log level changes. * * This platform function is called whenever the OpenThread log level changes. * This platform function is optional since an empty weak implementation has been provided. diff --git a/openthread/include/openthread/platform/memory.h b/openthread/include/openthread/platform/memory.h index 39b9e87e5f..1f0e4227af 100644 --- a/openthread/include/openthread/platform/memory.h +++ b/openthread/include/openthread/platform/memory.h @@ -63,7 +63,7 @@ extern "C" { * memory each and returns a pointer to the allocated memory. The allocated memory is filled with bytes * of value zero." * - * This function is required for OPENTHREAD_CONFIG_HEAP_EXTERNAL_ENABLE. + * Is required for OPENTHREAD_CONFIG_HEAP_EXTERNAL_ENABLE. * * @param[in] aNum The number of blocks to allocate * @param[in] aSize The size of each block to allocate @@ -76,7 +76,7 @@ void *otPlatCAlloc(size_t aNum, size_t aSize); /** * Frees memory that was dynamically allocated. * - * This function is required for OPENTHREAD_CONFIG_HEAP_EXTERNAL_ENABLE. + * Is required for OPENTHREAD_CONFIG_HEAP_EXTERNAL_ENABLE. * * @param[in] aPtr A pointer the memory blocks to free. The pointer may be NULL. */ diff --git a/openthread/include/openthread/platform/messagepool.h b/openthread/include/openthread/platform/messagepool.h index 6f369c721b..5058871df0 100644 --- a/openthread/include/openthread/platform/messagepool.h +++ b/openthread/include/openthread/platform/messagepool.h @@ -54,7 +54,7 @@ extern "C" { #endif /** - * This struct represents an OpenThread message buffer. + * Represents an OpenThread message buffer. * */ typedef struct otMessageBuffer @@ -65,7 +65,7 @@ typedef struct otMessageBuffer /** * Initialize the platform implemented message pool. * - * This function is used when `OPENTHREAD_CONFIG_PLATFORM_MESSAGE_MANAGEMENT` is enabled. + * 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. @@ -77,7 +77,7 @@ 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. + * Is used when `OPENTHREAD_CONFIG_PLATFORM_MESSAGE_MANAGEMENT` is enabled. * * The returned buffer instance MUST have at least `aBufferSize` bytes (as specified in `otPlatMessagePoolInit()`). * @@ -89,9 +89,9 @@ void otPlatMessagePoolInit(otInstance *aInstance, uint16_t aMinNumFreeBuffers, s otMessageBuffer *otPlatMessagePoolNew(otInstance *aInstance); /** - * This function is used to free a buffer back to the platform managed buffer pool. + * 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. + * 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. @@ -102,7 +102,7 @@ void otPlatMessagePoolFree(otInstance *aInstance, otMessageBuffer *aBuffer); /** * Get the number of free buffers. * - * This function is used when `OPENTHREAD_CONFIG_PLATFORM_MESSAGE_MANAGEMENT` is enabled. + * Is used when `OPENTHREAD_CONFIG_PLATFORM_MESSAGE_MANAGEMENT` is enabled. * * @param[in] aInstance A pointer to the OpenThread instance. * diff --git a/openthread/include/openthread/platform/misc.h b/openthread/include/openthread/platform/misc.h index 99c3ed3f53..7fbee54b1f 100644 --- a/openthread/include/openthread/platform/misc.h +++ b/openthread/include/openthread/platform/misc.h @@ -54,7 +54,7 @@ extern "C" { */ /** - * This function performs a software reset on the platform, if supported. + * Performs a software reset on the platform, if supported. * * @param[in] aInstance The OpenThread instance structure. * @@ -83,7 +83,7 @@ typedef enum } otPlatResetReason; /** - * This function returns the reason for the last platform reset. + * Returns the reason for the last platform reset. * * @param[in] aInstance The OpenThread instance structure. * @@ -91,7 +91,7 @@ typedef enum otPlatResetReason otPlatGetResetReason(otInstance *aInstance); /** - * This function provides a platform specific implementation for assert. + * Provides a platform specific implementation for assert. * * @param[in] aFilename The name of the file where the assert occurred. * @param[in] aLineNumber The line number in the file where the assert occurred. @@ -100,7 +100,7 @@ otPlatResetReason otPlatGetResetReason(otInstance *aInstance); void otPlatAssertFail(const char *aFilename, int aLineNumber); /** - * This function performs a platform specific operation to wake the host MCU. + * Performs a platform specific operation to wake the host MCU. * This is used only for NCP configurations. * */ @@ -163,7 +163,7 @@ typedef enum } otPlatMcuPowerState; /** - * This function sets the desired MCU power state. + * Sets the desired MCU power state. * * This is only applicable and used for NCP configuration when `OPENTHREAD_CONFIG_NCP_ENABLE_MCU_POWER_STATE_CONTROL` * is enabled. @@ -178,7 +178,7 @@ typedef enum otError otPlatSetMcuPowerState(otInstance *aInstance, otPlatMcuPowerState aState); /** - * This function gets the current desired MCU power state. + * Gets the current desired MCU power state. * * This is only applicable and used for NCP configuration when `OPENTHREAD_CONFIG_NCP_ENABLE_MCU_POWER_STATE_CONTROL` * is enabled. diff --git a/openthread/include/openthread/platform/otns.h b/openthread/include/openthread/platform/otns.h index 6d862e24cc..19b206b2ea 100644 --- a/openthread/include/openthread/platform/otns.h +++ b/openthread/include/openthread/platform/otns.h @@ -54,7 +54,7 @@ extern "C" { */ /** - * This function exports status information to OTNS. + * Exports status information to OTNS. * * The status information is represented by a null-terminated string with format recognizable by OTNS. * Each call to `otPlatOtnsStatus` can send multiple statuses, separated by ';', e.x. "parid=577fbc37;lrid=5". diff --git a/openthread/include/openthread/platform/radio.h b/openthread/include/openthread/platform/radio.h index 5d90e501a8..d11549e078 100644 --- a/openthread/include/openthread/platform/radio.h +++ b/openthread/include/openthread/platform/radio.h @@ -88,7 +88,7 @@ enum }; /** - * This enumeration defines the channel page. + * Defines the channel page. * */ enum @@ -100,7 +100,7 @@ enum }; /** - * This enumeration defines the frequency band channel range. + * Defines the frequency band channel range. * */ enum @@ -114,7 +114,7 @@ enum }; /** - * This type represents radio capabilities. + * Represents radio capabilities. * * The value is a bit-field indicating the capabilities supported by the radio. See `OT_RADIO_CAPS_*` definitions. * @@ -122,7 +122,7 @@ enum typedef uint8_t otRadioCaps; /** - * This enumeration defines constants that are used to indicate different radio capabilities. See `otRadioCaps`. + * Defines constants that are used to indicate different radio capabilities. See `otRadioCaps`. * */ enum @@ -141,13 +141,13 @@ enum #define OT_PANID_BROADCAST 0xffff ///< IEEE 802.15.4 Broadcast PAN ID /** - * This type represents the IEEE 802.15.4 PAN ID. + * Represents the IEEE 802.15.4 PAN ID. * */ typedef uint16_t otPanId; /** - * This type represents the IEEE 802.15.4 Short Address. + * Represents the IEEE 802.15.4 Short Address. * */ typedef uint16_t otShortAddress; @@ -155,7 +155,7 @@ typedef uint16_t otShortAddress; #define OT_EXT_ADDRESS_SIZE 8 ///< Size of an IEEE 802.15.4 Extended Address (bytes) /** - * This enumeration defines constants about size of header IE in ACK. + * Defines constants about size of header IE in ACK. * */ enum @@ -172,7 +172,7 @@ enum /** * @struct otExtAddress * - * This structure represents the IEEE 802.15.4 Extended Address. + * Represents the IEEE 802.15.4 Extended Address. * */ OT_TOOL_PACKED_BEGIN @@ -182,7 +182,7 @@ struct otExtAddress } OT_TOOL_PACKED_END; /** - * This structure represents the IEEE 802.15.4 Extended Address. + * Represents the IEEE 802.15.4 Extended Address. * */ typedef struct otExtAddress otExtAddress; @@ -192,7 +192,7 @@ typedef struct otExtAddress otExtAddress; /** * @struct otMacKey * - * This structure represents a MAC Key. + * Represents a MAC Key. * */ OT_TOOL_PACKED_BEGIN @@ -202,13 +202,13 @@ struct otMacKey } OT_TOOL_PACKED_END; /** - * This structure represents a MAC Key. + * Represents a MAC Key. * */ typedef struct otMacKey otMacKey; /** - * This type represents a MAC Key Ref used by PSA. + * Represents a MAC Key Ref used by PSA. * */ typedef otCryptoKeyRef otMacKeyRef; @@ -216,7 +216,7 @@ typedef otCryptoKeyRef otMacKeyRef; /** * @struct otMacKeyMaterial * - * This structure represents a MAC Key. + * Represents a MAC Key. * */ typedef struct otMacKeyMaterial @@ -229,7 +229,7 @@ typedef struct otMacKeyMaterial } otMacKeyMaterial; /** - * This enumeration defines constants about key types. + * Defines constants about key types. * */ typedef enum @@ -239,7 +239,7 @@ typedef enum } otRadioKeyType; /** - * This structure represents the IEEE 802.15.4 Header IE (Information Element) related information of a radio frame. + * Represents the IEEE 802.15.4 Header IE (Information Element) related information of a radio frame. */ typedef struct otRadioIeInfo { @@ -249,7 +249,7 @@ typedef struct otRadioIeInfo } otRadioIeInfo; /** - * This structure represents an IEEE 802.15.4 radio frame. + * Represents an IEEE 802.15.4 radio frame. */ typedef struct otRadioFrame { @@ -270,13 +270,50 @@ typedef struct otRadioFrame */ struct { - const otMacKeyMaterial *mAesKey; ///< The key material used for AES-CCM frame security. - otRadioIeInfo *mIeInfo; ///< The pointer to the Header IE(s) related information. - uint32_t mTxDelay; ///< The delay time for this transmission (based on `mTxDelayBaseTime`). - uint32_t mTxDelayBaseTime; ///< The base time for the transmission delay. + const otMacKeyMaterial *mAesKey; ///< The key material used for AES-CCM frame security. + otRadioIeInfo *mIeInfo; ///< The pointer to the Header IE(s) related information. + + /** + * The base time in microseconds for scheduled transmissions + * relative to the local radio clock, see `otPlatRadioGetNow` and + * `mTxDelay`. + */ + uint32_t mTxDelayBaseTime; + + /** + * The delay time in microseconds for this transmission referenced + * to `mTxDelayBaseTime`. + * + * Note: `mTxDelayBaseTime` + `mTxDelay` SHALL point to the point in + * time when the end of the SFD will be present at the local + * antenna, relative to the local radio clock. + */ + uint32_t mTxDelay; + uint8_t mMaxCsmaBackoffs; ///< Maximum number of backoffs attempts before declaring CCA failure. uint8_t mMaxFrameRetries; ///< Maximum number of retries allowed after a transmission failure. + /** + * The RX channel after frame TX is done (after all frame retries - ack received, or timeout, or abort). + * + * Radio platforms can choose to fully ignore this. OT stack will make sure to call `otPlatRadioReceive()` + * with the desired RX channel after a frame TX is done and signaled in `otPlatRadioTxDone()` callback. + * Radio platforms that don't provide `OT_RADIO_CAPS_TRANSMIT_RETRIES` must always ignore this. + * + * This is intended for situations where there may be delay in interactions between OT stack and radio, as + * an example this is used in RCP/host architecture to make sure RCP switches to PAN channel more quickly. + * In particular, this can help with CSL tx to a sleepy child, where the child may use a different channel + * for CSL than the PAN channel. After frame tx, we want the radio/RCP to go back to the PAN channel + * quickly to ensure that parent does not miss tx from child afterwards, e.g., child responding to the + * earlier CSL transmitted frame from parent using PAN channel while radio still staying on CSL channel. + * + * The switch to the RX channel MUST happen after the frame TX is fully done, i.e., after all retries and + * when ack is received (when "Ack Request" flag is set on the TX frame) or ack timeout. Note that ack is + * expected on the same channel that frame is sent on. + * + */ + uint8_t mRxChannelAfterTxDone; + /** * Indicates whether frame counter and CSL IEs are properly updated in the header. * @@ -311,11 +348,8 @@ typedef struct otRadioFrame struct { /** - * The timestamp when the frame was received in microseconds. - * - * The value SHALL be the time when the SFD was received when TIME_SYNC or CSL is enabled. - * Otherwise, the time when the MAC frame was fully received is also acceptable. - * + * The time of the local radio clock in microseconds when the end of + * the SFD was present at the local antenna. */ uint64_t mTimestamp; @@ -332,7 +366,7 @@ typedef struct otRadioFrame } otRadioFrame; /** - * This structure represents the state of a radio. + * Represents the state of a radio. * Initially, a radio is in the Disabled state. */ typedef enum otRadioState @@ -362,7 +396,7 @@ typedef enum otRadioState */ /** - * This structure represents radio coexistence metrics. + * Represents radio coexistence metrics. */ typedef struct otRadioCoexMetrics { @@ -388,7 +422,7 @@ typedef struct otRadioCoexMetrics } otRadioCoexMetrics; /** - * This structure represents what metrics are specified to query. + * Represents what metrics are specified to query. * */ typedef struct otLinkMetrics @@ -590,7 +624,7 @@ void otPlatRadioSetPromiscuous(otInstance *aInstance, bool aEnable); /** * Update MAC keys and key index * - * This function is used when radio provides OT_RADIO_CAPS_TRANSMIT_SEC capability. + * Is used when radio provides OT_RADIO_CAPS_TRANSMIT_SEC capability. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aKeyIdMode The key ID mode. @@ -610,9 +644,9 @@ void otPlatRadioSetMacKey(otInstance *aInstance, otRadioKeyType aKeyType); /** - * This method sets the current MAC frame counter value. + * Sets the current MAC frame counter value. * - * This function is used when radio provides `OT_RADIO_CAPS_TRANSMIT_SEC` capability. + * Is used when radio provides `OT_RADIO_CAPS_TRANSMIT_SEC` capability. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aMacFrameCounter The MAC frame counter value. @@ -621,9 +655,9 @@ void otPlatRadioSetMacKey(otInstance *aInstance, void otPlatRadioSetMacFrameCounter(otInstance *aInstance, uint32_t aMacFrameCounter); /** - * This method sets the current MAC frame counter value only if the new given value is larger than the current value. + * Sets the current MAC frame counter value only if the new given value is larger than the current value. * - * This function is used when radio provides `OT_RADIO_CAPS_TRANSMIT_SEC` capability. + * Is used when radio provides `OT_RADIO_CAPS_TRANSMIT_SEC` capability. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aMacFrameCounter The MAC frame counter value. @@ -632,14 +666,25 @@ void otPlatRadioSetMacFrameCounter(otInstance *aInstance, uint32_t aMacFrameCoun void otPlatRadioSetMacFrameCounterIfLarger(otInstance *aInstance, uint32_t aMacFrameCounter); /** - * Get the current estimated time (in microseconds) of the radio chip. + * Get the current time in microseconds referenced to a continuous monotonic + * local radio clock (64 bits width). + * + * The radio clock SHALL NOT wrap during the device's uptime. Implementations + * SHALL therefore identify and compensate for internal counter overflows. The + * clock does not have a defined epoch and it SHALL NOT introduce any continuous + * or discontinuous adjustments (e.g. leap seconds). Implementations SHALL + * compensate for any sleep times of the device. * - * This microsecond timer must be a free-running timer. The timer must continue to advance with microsecond precision - * even when the radio is in the sleep state. + * Implementations MAY choose to discipline the radio clock and compensate for + * sleep times by any means (e.g. by combining a high precision/low power RTC + * with a high resolution counter) as long as the exposed combined clock + * provides continuous monotonic microsecond resolution ticks within the + * accuracy limits announced by @ref otPlatRadioGetCslAccuracy. * * @param[in] aInstance A pointer to an OpenThread instance. * - * @returns The current time in microseconds. UINT64_MAX when platform does not support or radio time is not ready. + * @returns The current time in microseconds. UINT64_MAX when platform does not + * support or radio time is not ready. * */ uint64_t otPlatRadioGetNow(otInstance *aInstance); @@ -673,7 +718,7 @@ uint32_t otPlatRadioGetBusSpeed(otInstance *aInstance); /** * Get current state of the radio. * - * This function is not required by OpenThread. It may be used for debugging and/or application-specific purposes. + * Is not required by OpenThread. It may be used for debugging and/or application-specific purposes. * * @note This function may be not implemented. It does not affect OpenThread. * @@ -744,8 +789,17 @@ otError otPlatRadioReceive(otInstance *aInstance, uint8_t aChannel); * Schedule a radio reception window at a specific time and duration. * * @param[in] aChannel The radio channel on which to receive. - * @param[in] aStart The receive window start time, in microseconds. - * @param[in] aDuration The receive window duration, in microseconds + * @param[in] aStart The receive window start time relative to the local + * radio clock, see `otPlatRadioGetNow`. The radio + * receiver SHALL be on and ready to receive the first + * symbol of a frame's SHR at the window start time. + * @param[in] aDuration The receive window duration, in microseconds, as + * measured by the local radio clock. The radio SHOULD be + * turned off (or switched to TX mode if an ACK frame + * needs to be sent) after that duration unless it is + * still actively receiving a frame. In the latter case + * the radio SHALL be kept in reception mode until frame + * reception has either succeeded or failed. * * @retval OT_ERROR_NONE Successfully scheduled receive window. * @retval OT_ERROR_FAILED The receive window could not be scheduled. @@ -767,7 +821,7 @@ extern void otPlatRadioReceiveDone(otInstance *aInstance, otRadioFrame *aFrame, /** * The radio driver calls this method to notify OpenThread diagnostics module of a received frame. * - * This function is used when diagnostics is enabled. + * Is used when diagnostics is enabled. * * @param[in] aInstance The OpenThread instance structure. * @param[in] aFrame A pointer to the received frame or NULL if the receive operation failed. @@ -844,7 +898,7 @@ extern void otPlatRadioTxDone(otInstance *aInstance, otRadioFrame *aFrame, otRad /** * The radio driver calls this method to notify OpenThread diagnostics module that the transmission has completed. * - * This function is used when diagnostics is enabled. + * Is used when diagnostics is enabled. * * @param[in] aInstance The OpenThread instance structure. * @param[in] aFrame A pointer to the frame that was transmitted. @@ -868,14 +922,14 @@ int8_t otPlatRadioGetRssi(otInstance *aInstance); /** * Begin the energy scan sequence on the radio. * - * This function is used when radio provides OT_RADIO_CAPS_ENERGY_SCAN capability. + * Is used when radio provides OT_RADIO_CAPS_ENERGY_SCAN capability. * * @param[in] aInstance The OpenThread instance structure. * @param[in] aScanChannel The channel to perform the energy scan on. * @param[in] aScanDuration The duration, in milliseconds, for the channel to be scanned. * * @retval OT_ERROR_NONE Successfully started scanning the channel. - * @retval OT_ERROR_BUSY The radio is performing enery scanning. + * @retval OT_ERROR_BUSY The radio is performing energy scanning. * @retval OT_ERROR_NOT_IMPLEMENTED The radio doesn't support energy scanning. * */ @@ -884,7 +938,7 @@ otError otPlatRadioEnergyScan(otInstance *aInstance, uint8_t aScanChannel, uint1 /** * The radio driver calls this method to notify OpenThread that the energy scan is complete. * - * This function is used when radio provides OT_RADIO_CAPS_ENERGY_SCAN capability. + * Is used when radio provides OT_RADIO_CAPS_ENERGY_SCAN capability. * * @param[in] aInstance The OpenThread instance structure. * @param[in] aEnergyScanMaxRssi The maximum RSSI encountered on the scanned channel. @@ -999,7 +1053,7 @@ uint32_t otPlatRadioGetPreferredChannelMask(otInstance *aInstance); /** * Enable the radio coex. * - * This function is used when feature OPENTHREAD_CONFIG_PLATFORM_RADIO_COEX_ENABLE is enabled. + * Is used when feature OPENTHREAD_CONFIG_PLATFORM_RADIO_COEX_ENABLE is enabled. * * @param[in] aInstance The OpenThread instance structure. * @param[in] aEnabled TRUE to enable the radio coex, FALSE otherwise. @@ -1013,7 +1067,7 @@ otError otPlatRadioSetCoexEnabled(otInstance *aInstance, bool aEnabled); /** * Check whether radio coex is enabled or not. * - * This function is used when feature OPENTHREAD_CONFIG_PLATFORM_RADIO_COEX_ENABLE is enabled. + * Is used when feature OPENTHREAD_CONFIG_PLATFORM_RADIO_COEX_ENABLE is enabled. * * @param[in] aInstance The OpenThread instance structure. * @@ -1025,7 +1079,7 @@ bool otPlatRadioIsCoexEnabled(otInstance *aInstance); /** * Get the radio coexistence metrics. * - * This function is used when feature OPENTHREAD_CONFIG_PLATFORM_RADIO_COEX_ENABLE is enabled. + * Is used when feature OPENTHREAD_CONFIG_PLATFORM_RADIO_COEX_ENABLE is enabled. * * @param[in] aInstance The OpenThread instance structure. * @param[out] aCoexMetrics A pointer to the coexistence metrics structure. @@ -1039,7 +1093,7 @@ otError otPlatRadioGetCoexMetrics(otInstance *aInstance, otRadioCoexMetrics *aCo * Enable or disable CSL receiver. * * @param[in] aInstance The OpenThread instance structure. - * @param[in] aCslPeriod CSL period, 0 for disabling CSL. + * @param[in] aCslPeriod CSL period, 0 for disabling CSL. CSL period is in unit of 10 symbols. * @param[in] aShortAddr The short source address of CSL receiver's peer. * @param[in] aExtAddr The extended source address of CSL receiver's peer. * @@ -1058,28 +1112,50 @@ otError otPlatRadioEnableCsl(otInstance *aInstance, /** * Update CSL sample time in radio driver. * - * Sample time is stored in radio driver as a copy to calculate phase when sending ACK with CSL IE. + * Sample time is stored in radio driver as a copy to calculate phase when + * sending ACK with CSL IE. The CSL sample (window) of the CSL receiver extends + * before and after the sample time. The CSL sample time marks a timestamp in + * the CSL sample window when a frame should be received in "ideal conditions" + * if there would be no inaccuracy/clock-drift. * * @param[in] aInstance The OpenThread instance structure. - * @param[in] aCslSampleTime The latest sample time. - * + * @param[in] aCslSampleTime The next sample time, in microseconds. It is + * the time when the first symbol of the MHR of + * the frame is expected. */ void otPlatRadioUpdateCslSampleTime(otInstance *aInstance, uint32_t aCslSampleTime); /** - * Get the current accuracy, in units of ± ppm, of the clock used for scheduling CSL operations. + * Get the current estimated worst case accuracy (maximum ± deviation from the + * nominal frequency) of the local radio clock in units of PPM. This is the + * clock used to schedule CSL operations. * - * @note Platforms may optimize this value based on operational conditions (i.e.: temperature). + * @note Implementations MAY estimate this value based on current operating + * conditions (e.g. temperature). + * + * In case the implementation does not estimate the current value but returns a + * fixed value, this value MUST be the worst-case accuracy over all possible + * foreseen operating conditions (temperature, pressure, etc) of the + * implementation. * * @param[in] aInstance A pointer to an OpenThread instance. * - * @returns The current CSL rx/tx scheduling drift, in units of ± ppm. + * @returns The current CSL rx/tx scheduling drift, in PPM. * */ uint8_t otPlatRadioGetCslAccuracy(otInstance *aInstance); /** - * The fixed uncertainty of the Device for scheduling CSL Transmissions in units of 10 microseconds. + * The fixed uncertainty (i.e. random jitter) of the arrival time of CSL + * transmissions received by this device in units of 10 microseconds. + * + * This designates the worst case constant positive or negative deviation of + * the actual arrival time of a transmission from the transmission time + * calculated relative to the local radio clock independent of elapsed time. In + * addition to uncertainty accumulated over elapsed time, the CSL channel sample + * ("RX window") must be extended by twice this deviation such that an actual + * transmission is guaranteed to be detected by the local receiver in the + * presence of random arrival time jitter. * * @param[in] aInstance A pointer to an OpenThread instance. * diff --git a/openthread/include/openthread/platform/settings.h b/openthread/include/openthread/platform/settings.h index 0b2f035760..5a1783c546 100644 --- a/openthread/include/openthread/platform/settings.h +++ b/openthread/include/openthread/platform/settings.h @@ -52,7 +52,7 @@ extern "C" { */ /** - * This enumeration defines the keys of settings. + * Defines the keys of settings. * * Note: When adding a new settings key, if the settings corresponding to the key contains security sensitive * information, the developer MUST add the key to the array `aSensitiveKeys` which is passed in @@ -73,6 +73,7 @@ enum OT_SETTINGS_KEY_SRP_SERVER_INFO = 0x000d, ///< The SRP server info (UDP port). OT_SETTINGS_KEY_BR_ULA_PREFIX = 0x000f, ///< BR ULA prefix. OT_SETTINGS_KEY_BR_ON_LINK_PREFIXES = 0x0010, ///< BR local on-link prefixes. + OT_SETTINGS_KEY_BORDER_AGENT_ID = 0x0011, ///< Unique Border Agent/Router ID. // Deprecated and reserved key values: // @@ -89,7 +90,7 @@ enum /** * Performs any initialization for the settings subsystem, if necessary. * - * This function also sets the sensitive keys that should be stored in the secure area. + * Also sets the sensitive keys that should be stored in the secure area. * * Note that the memory pointed by @p aSensitiveKeys MUST not be released before @p aInstance is destroyed. * @@ -112,13 +113,13 @@ void otPlatSettingsDeinit(otInstance *aInstance); /** * Fetches the value of a setting. * - * This function fetches the value of the setting identified + * Fetches the value of the setting identified * by @p aKey and write it to the memory pointed to by aValue. * It then writes the length to the integer pointed to by * @p aValueLength. The initial value of @p aValueLength is the * maximum number of bytes to be written to @p aValue. * - * This function can be used to check for the existence of + * Can be used to check for the existence of * a key without fetching the value by setting @p aValue and * @p aValueLength to NULL. You can also check the length of * the setting without fetching it by setting only aValue @@ -148,7 +149,7 @@ otError otPlatSettingsGet(otInstance *aInstance, uint16_t aKey, int aIndex, uint /** * Sets or replaces the value of a setting. * - * This function sets or replaces the value of a setting + * Sets or replaces the value of a setting * identified by @p aKey. * * Calling this function successfully may cause unrelated @@ -177,7 +178,7 @@ otError otPlatSettingsSet(otInstance *aInstance, uint16_t aKey, const uint8_t *a /** * Adds a value to a setting. * - * This function adds the value to a setting + * Adds the value to a setting * identified by @p aKey, without replacing any existing * values. * @@ -213,7 +214,7 @@ otError otPlatSettingsAdd(otInstance *aInstance, uint16_t aKey, const uint8_t *a /** * Removes a setting from the setting store. * - * This function deletes a specific value from the + * Deletes a specific value from the * setting identified by aKey from the settings store. * * Note that the underlying implementation is not required @@ -234,7 +235,7 @@ otError otPlatSettingsDelete(otInstance *aInstance, uint16_t aKey, int aIndex); /** * Removes all settings from the setting store. * - * This function deletes all settings from the settings + * Deletes all settings from the settings * store, resetting it to its initial factory state. * * @param[in] aInstance The OpenThread instance structure. diff --git a/openthread/include/openthread/platform/spi-slave.h b/openthread/include/openthread/platform/spi-slave.h index 551d701635..c3e4cb8fc8 100644 --- a/openthread/include/openthread/platform/spi-slave.h +++ b/openthread/include/openthread/platform/spi-slave.h @@ -126,7 +126,7 @@ void otPlatSpiSlaveDisable(void); * Prepare data for the next SPI transaction. Data pointers MUST remain valid until the transaction complete callback * is called by the SPI slave driver, or until after the next call to `otPlatSpiSlavePrepareTransaction()`. * - * This function may be called more than once before the SPI master initiates the transaction. Each *successful* call + * May be called more than once before the SPI master initiates the transaction. Each *successful* call * to this function will cause the previous values from earlier calls to be discarded. * * Not calling this function after a completed transaction is the same as if this function was previously called with diff --git a/openthread/include/openthread/platform/time.h b/openthread/include/openthread/platform/time.h index eecb34b842..1766cc5593 100644 --- a/openthread/include/openthread/platform/time.h +++ b/openthread/include/openthread/platform/time.h @@ -52,7 +52,20 @@ extern "C" { */ /** - * Get the current time (64bits width). + * Get the current platform time in microseconds referenced to a continuous + * monotonic local clock (64 bits width). + * + * The clock SHALL NOT wrap during the device's uptime. Implementations SHALL + * therefore identify and compensate for internal counter overflows. The clock + * does not have a defined epoch and it SHALL NOT introduce any continuous or + * discontinuous adjustments (e.g. leap seconds). Implementations SHALL + * compensate for any sleep times of the device. + * + * Implementations MAY choose to discipline the platform clock and compensate + * for sleep times by any means (e.g. by combining a high precision/low power + * RTC with a high resolution counter) as long as the exposed combined clock + * provides continuous monotonic microsecond resolution ticks within the + * accuracy limits announced by @ref otPlatTimeGetXtalAccuracy. * * @returns The current time in microseconds. * @@ -60,9 +73,18 @@ extern "C" { uint64_t otPlatTimeGet(void); /** - * Get the device's XTAL accuracy. + * Get the current estimated worst case accuracy (maximum ± deviation from the + * nominal frequency) of the local platform clock in units of PPM. + * + * @note Implementations MAY estimate this value based on current operating + * conditions (e.g. temperature). + * + * In case the implementation does not estimate the current value but returns a + * fixed value, this value MUST be the worst-case accuracy over all possible + * foreseen operating conditions (temperature, pressure, etc) of the + * implementation. * - * @returns The device's XTAL accuracy, in ppm. + * @returns The current platform clock accuracy, in PPM. * */ uint16_t otPlatTimeGetXtalAccuracy(void); diff --git a/openthread/include/openthread/platform/toolchain.h b/openthread/include/openthread/platform/toolchain.h index d8b0308ef8..383aefbb32 100644 --- a/openthread/include/openthread/platform/toolchain.h +++ b/openthread/include/openthread/platform/toolchain.h @@ -113,10 +113,10 @@ extern "C" { /** * @def OT_TOOL_PRINTF_STYLE_FORMAT_ARG_CHECK * - * This macro specifies that a function or method takes `printf` style arguments and should be type-checked against + * Specifies that a function or method takes `printf` style arguments and should be type-checked against * a format string. * - * This macro must be added after the function/method declaration. For example: + * Must be added after the function/method declaration. For example: * * `void MyPrintf(void *aObject, const char *aFormat, ...) OT_TOOL_PRINTF_STYLE_FORMAT_ARG_CHECK(2, 3);` * diff --git a/openthread/include/openthread/platform/trel.h b/openthread/include/openthread/platform/trel.h index 6515b98d59..b372fded54 100644 --- a/openthread/include/openthread/platform/trel.h +++ b/openthread/include/openthread/platform/trel.h @@ -58,7 +58,7 @@ extern "C" { */ /** - * This function initializes and enables TREL platform layer. + * Initializes and enables TREL platform layer. * * Upon this call, the platform layer MUST perform the following: * @@ -87,7 +87,7 @@ extern "C" { void otPlatTrelEnable(otInstance *aInstance, uint16_t *aUdpPort); /** - * This function disables TREL platform layer. + * Disables TREL platform layer. * * After this call, the platform layer MUST stop DNS-SD browse on the service name "_trel._udp", stop advertising the * TREL DNS-SD service (from `otPlatTrelRegisterService()`) and MUST close the UDP socket used to receive TREL messages. @@ -98,7 +98,7 @@ void otPlatTrelEnable(otInstance *aInstance, uint16_t *aUdpPort); void otPlatTrelDisable(otInstance *aInstance); /** - * This structure represents a TREL peer info discovered using DNS-SD browse on the service name "_trel._udp". + * Represents a TREL peer info discovered using DNS-SD browse on the service name "_trel._udp". * */ typedef struct otPlatTrelPeerInfo @@ -145,7 +145,7 @@ typedef struct otPlatTrelPeerInfo extern void otPlatTrelHandleDiscoveredPeerInfo(otInstance *aInstance, const otPlatTrelPeerInfo *aInfo); /** - * This function registers a new service to be advertised using DNS-SD [RFC6763]. + * Registers a new service to be advertised using DNS-SD [RFC6763]. * * The service name is "_trel._udp". The platform should use its own hostname, which when combined with the service * name and the local DNS-SD domain name will produce the full service instance name, for example @@ -170,7 +170,7 @@ extern void otPlatTrelHandleDiscoveredPeerInfo(otInstance *aInstance, const otPl void otPlatTrelRegisterService(otInstance *aInstance, uint16_t aPort, const uint8_t *aTxtData, uint8_t aTxtLength); /** - * This function requests a TREL UDP packet to be sent to a given destination. + * Requests a TREL UDP packet to be sent to a given destination. * * @param[in] aInstance The OpenThread instance structure. * @param[in] aUdpPayload A pointer to UDP payload. @@ -184,7 +184,7 @@ void otPlatTrelSend(otInstance *aInstance, const otSockAddr *aDestSockAddr); /** - * This function is a callback from platform to notify of a received TREL UDP packet. + * Is a callback from platform to notify of a received TREL UDP packet. * * @note The buffer content (up to its specified length) may get changed during processing by OpenThread core (e.g., * decrypted in place), so the platform implementation should expect that after returning from this function the diff --git a/openthread/include/openthread/platform/udp.h b/openthread/include/openthread/platform/udp.h index 5b4a21c6c3..59d1fc7e46 100644 --- a/openthread/include/openthread/platform/udp.h +++ b/openthread/include/openthread/platform/udp.h @@ -42,7 +42,7 @@ extern "C" { #endif /** - * This function initializes the UDP socket by platform. + * Initializes the UDP socket by platform. * * @param[in] aUdpSocket A pointer to the UDP socket. * @@ -53,7 +53,7 @@ extern "C" { otError otPlatUdpSocket(otUdpSocket *aUdpSocket); /** - * This function closes the UDP socket by platform. + * Closes the UDP socket by platform. * * @param[in] aUdpSocket A pointer to the UDP socket. * @@ -64,18 +64,18 @@ otError otPlatUdpSocket(otUdpSocket *aUdpSocket); otError otPlatUdpClose(otUdpSocket *aUdpSocket); /** - * This function binds the UDP socket by platform. + * Binds the UDP socket by platform. * * @param[in] aUdpSocket A pointer to the UDP socket. * - * @retval OT_ERROR_NONE Successfully binded UDP socket by platform. + * @retval OT_ERROR_NONE Successfully bound UDP socket by platform. * @retval OT_ERROR_FAILED Failed to bind UDP socket. * */ otError otPlatUdpBind(otUdpSocket *aUdpSocket); /** - * This function binds the UDP socket to a platform network interface. + * Binds the UDP socket to a platform network interface. * * Note: only available when `OPENTHREAD_CONFIG_PLATFORM_UDP_ENABLE` is used. * @@ -89,7 +89,7 @@ otError otPlatUdpBind(otUdpSocket *aUdpSocket); otError otPlatUdpBindToNetif(otUdpSocket *aUdpSocket, otNetifIdentifier aNetifIdentifier); /** - * This function connects UDP socket by platform. + * Connects UDP socket by platform. * * @param[in] aUdpSocket A pointer to the UDP socket. * @@ -100,20 +100,20 @@ otError otPlatUdpBindToNetif(otUdpSocket *aUdpSocket, otNetifIdentifier aNetifId otError otPlatUdpConnect(otUdpSocket *aUdpSocket); /** - * This function sends UDP payload by platform. + * Sends UDP payload by platform. * * @param[in] aUdpSocket A pointer to the UDP socket. * @param[in] aMessage A pointer to the message to send. * @param[in] aMessageInfo A pointer to the message info associated with @p aMessage. * * @retval OT_ERROR_NONE Successfully sent by platform, and @p aMessage is freed. - * @retval OT_ERROR_FAILED Failed to binded UDP socket. + * @retval OT_ERROR_FAILED Failed to bind UDP socket. * */ otError otPlatUdpSend(otUdpSocket *aUdpSocket, otMessage *aMessage, const otMessageInfo *aMessageInfo); /** - * This function configures the UDP socket to join a UDP multicast group. + * Configures the UDP socket to join a UDP multicast group. * * Note: only available when `OPENTHREAD_CONFIG_PLATFORM_UDP_ENABLE` is used. * @@ -130,7 +130,7 @@ otError otPlatUdpJoinMulticastGroup(otUdpSocket *aUdpSocket, const otIp6Address *aAddress); /** - * This function configures the UDP socket to leave a UDP multicast group. + * Configures the UDP socket to leave a UDP multicast group. * * Note: only available when `OPENTHREAD_CONFIG_PLATFORM_UDP_ENABLE` is used. * diff --git a/openthread/include/openthread/radio_stats.h b/openthread/include/openthread/radio_stats.h new file mode 100644 index 0000000000..2db394d726 --- /dev/null +++ b/openthread/include/openthread/radio_stats.h @@ -0,0 +1,102 @@ +/* + * Copyright (c) 2023, The OpenThread Authors. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * 3. Neither the name of the copyright holder nor the + * names of its contributors may be used to endorse or promote products + * derived from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +/** + * @file + * @brief + * This file includes the OpenThread API for radio stats module. + */ + +#ifndef OPENTHREAD_RADIO_STATS_H_ +#define OPENTHREAD_RADIO_STATS_H_ + +#include + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @addtogroup api-radio + * + * @brief + * This module includes functions for radio statistics. + * + * @{ + * + */ + +/** + * Contains the statistics of radio. + * + */ +typedef struct otRadioTimeStats +{ + uint64_t mDisabledTime; ///< The total time that radio is in disabled state, in unit of microseconds. + uint64_t mSleepTime; ///< The total time that radio is in sleep state, in unit of microseconds. + uint64_t mTxTime; ///> The total time that radio is doing transmission, in unit of microseconds. + uint64_t mRxTime; ///> The total time that radio is in receive state, in unit of microseconds. +} otRadioTimeStats; + +/** + * Gets the radio statistics. + * + * The radio statistics include the time when the radio is in TX/RX/Sleep state. These times are in units of + * microseconds. All times are calculated from the last reset of radio statistics. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * + * @returns A const pointer to the otRadioTimeStats struct that contains the data. + * + */ +const otRadioTimeStats *otRadioTimeStatsGet(otInstance *aInstance); + +/** + * Resets the radio statistics. + * + * All times are reset to 0. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * + * + */ +void otRadioTimeStatsReset(otInstance *aInstance); + +/** + * @} + * + */ + +#ifdef __cplusplus +} // extern "C" +#endif + +#endif // OPENTHREAD_RADIO_STATS_H_ diff --git a/openthread/include/openthread/random_crypto.h b/openthread/include/openthread/random_crypto.h index 937136a782..94d3e61730 100644 --- a/openthread/include/openthread/random_crypto.h +++ b/openthread/include/openthread/random_crypto.h @@ -37,7 +37,6 @@ #include -#include #include #ifdef __cplusplus @@ -55,7 +54,7 @@ extern "C" { */ /** - * This function fills a given buffer with cryptographically secure random bytes. + * Fills a given buffer with cryptographically secure random bytes. * * @param[out] aBuffer A pointer to a buffer to fill with the random bytes. * @param[in] aSize Size of buffer (number of bytes to fill). diff --git a/openthread/include/openthread/random_noncrypto.h b/openthread/include/openthread/random_noncrypto.h index 40bb2600e5..0b353ca78d 100644 --- a/openthread/include/openthread/random_noncrypto.h +++ b/openthread/include/openthread/random_noncrypto.h @@ -52,7 +52,7 @@ extern "C" { */ /** - * This function generates and returns a random `uint32_t` value. + * Generates and returns a random `uint32_t` value. * * @returns A random `uint32_t` value. * @@ -60,7 +60,7 @@ extern "C" { uint32_t otRandomNonCryptoGetUint32(void); /** - * This function generates and returns a random byte. + * Generates and returns a random byte. * * @returns A random `uint8_t` value. * @@ -68,7 +68,7 @@ uint32_t otRandomNonCryptoGetUint32(void); uint8_t otRandomNonCryptoGetUint8(void); /** - * This function generates and returns a random `uint16_t` value. + * Generates and returns a random `uint16_t` value. * * @returns A random `uint16_t` value. * @@ -76,7 +76,7 @@ uint8_t otRandomNonCryptoGetUint8(void); uint16_t otRandomNonCryptoGetUint16(void); /** - * This function generates and returns a random `uint8_t` value within a given range `[aMin, aMax)`. + * Generates and returns a random `uint8_t` value within a given range `[aMin, aMax)`. * * @param[in] aMin A minimum value (this value can be included in returned random result). * @param[in] aMax A maximum value (this value is excluded from returned random result). @@ -86,7 +86,7 @@ uint16_t otRandomNonCryptoGetUint16(void); uint8_t otRandomNonCryptoGetUint8InRange(uint8_t aMin, uint8_t aMax); /** - * This function generates and returns a random `uint16_t` value within a given range `[aMin, aMax)`. + * Generates and returns a random `uint16_t` value within a given range `[aMin, aMax)`. * * @note The returned random value can include the @p aMin value but excludes the @p aMax. * @@ -98,7 +98,7 @@ uint8_t otRandomNonCryptoGetUint8InRange(uint8_t aMin, uint8_t aMax); uint16_t otRandomNonCryptoGetUint16InRange(uint16_t aMin, uint16_t aMax); /** - * This function generates and returns a random `uint32_t` value within a given range `[aMin, aMax)`. + * Generates and returns a random `uint32_t` value within a given range `[aMin, aMax)`. * * @note The returned random value can include the @p aMin value but excludes the @p aMax. * @@ -111,7 +111,7 @@ uint16_t otRandomNonCryptoGetUint16InRange(uint16_t aMin, uint16_t aMax); uint32_t otRandomNonCryptoGetUint32InRange(uint32_t aMin, uint32_t aMax); /** - * This function fills a given buffer with random bytes. + * Fills a given buffer with random bytes. * * @param[out] aBuffer A pointer to a buffer to fill with the random bytes. * @param[in] aSize Size of buffer (number of bytes to fill). @@ -120,7 +120,7 @@ uint32_t otRandomNonCryptoGetUint32InRange(uint32_t aMin, uint32_t aMax); void otRandomNonCryptoFillBuffer(uint8_t *aBuffer, uint16_t aSize); /** - * This function adds a random jitter within a given range to a given value. + * Adds a random jitter within a given range to a given value. * * @param[in] aValue A value to which the random jitter is added. * @param[in] aJitter Maximum jitter. Random jitter is selected from the range `[-aJitter, aJitter]`. diff --git a/openthread/include/openthread/server.h b/openthread/include/openthread/server.h index 3ce1117052..28cb56325f 100644 --- a/openthread/include/openthread/server.h +++ b/openthread/include/openthread/server.h @@ -52,7 +52,7 @@ extern "C" { */ /** - * This method provides a full or stable copy of the local Thread Network Data. + * Provides a full or stable copy of the local Thread Network Data. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aStable TRUE when copying the stable version, FALSE when copying the full version. @@ -100,7 +100,7 @@ otError otServerRemoveService(otInstance *aInstance, uint8_t aServiceDataLength); /** - * This function gets the next service in the local Network Data. + * Gets the next service in the local Network Data. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in,out] aIterator A pointer to the Network Data iterator context. To get the first service entry diff --git a/openthread/include/openthread/sntp.h b/openthread/include/openthread/sntp.h index 34b26c28c6..98f9e86a5c 100644 --- a/openthread/include/openthread/sntp.h +++ b/openthread/include/openthread/sntp.h @@ -57,7 +57,7 @@ extern "C" { #define OT_SNTP_DEFAULT_SERVER_PORT 123 ///< Defines default SNTP Server port. /** - * This structure implements SNTP Query parameters. + * Implements SNTP Query parameters. * */ typedef struct otSntpQuery @@ -66,7 +66,7 @@ typedef struct otSntpQuery } otSntpQuery; /** - * This function pointer is called when a SNTP response is received. + * Pointer is called when a SNTP response is received. * * @param[in] aContext A pointer to application-specific context. * @param[in] aTime Specifies the time at the server when the response left for the client, in UNIX time. @@ -83,9 +83,9 @@ typedef struct otSntpQuery typedef void (*otSntpResponseHandler)(void *aContext, uint64_t aTime, otError aResult); /** - * This function sends a SNTP query. + * Sends a SNTP query. * - * This function is available only if feature `OPENTHREAD_CONFIG_SNTP_CLIENT_ENABLE` is enabled. + * Is available only if feature `OPENTHREAD_CONFIG_SNTP_CLIENT_ENABLE` is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aQuery A pointer to specify SNTP query parameters. @@ -99,7 +99,7 @@ otError otSntpClientQuery(otInstance *aInstance, void *aContext); /** - * This function sets the unix era number. + * Sets the unix era number. * * The default value of unix era is set to 0. The subsequent eras start after year 2106. * diff --git a/openthread/include/openthread/srp_client.h b/openthread/include/openthread/srp_client.h index beaa062250..6eac2b1a85 100644 --- a/openthread/include/openthread/srp_client.h +++ b/openthread/include/openthread/srp_client.h @@ -53,7 +53,7 @@ extern "C" { */ /** - * This enumeration specifies an SRP client item (service or host info) state. + * Specifies an SRP client item (service or host info) state. * */ typedef enum @@ -69,7 +69,7 @@ typedef enum } otSrpClientItemState; /** - * This structure represents an SRP client host info. + * Represents an SRP client host info. * */ typedef struct otSrpClientHostInfo @@ -82,7 +82,7 @@ typedef struct otSrpClientHostInfo } otSrpClientHostInfo; /** - * This structure represents an SRP client service. + * Represents an SRP client service. * * The values in this structure, including the string buffers for the names and the TXT record entries, MUST persist * and stay constant after an instance of this structure is passed to OpenThread from `otSrpClientAddService()` or @@ -119,7 +119,7 @@ typedef struct otSrpClientService } otSrpClientService; /** - * This function pointer type defines the callback used by SRP client to notify user of changes/events/errors. + * Pointer type defines the callback used by SRP client to notify user of changes/events/errors. * * This callback is invoked on a successful registration of an update (i.e., add/remove of host-info and/or some * service(s)) with the SRP server, or if there is a failure or error (e.g., server rejects a update request or client @@ -180,7 +180,7 @@ typedef void (*otSrpClientCallback)(otError aError, void *aContext); /** - * This function pointer type defines the callback used by SRP client to notify user when it is auto-started or stopped. + * Pointer type defines the callback used by SRP client to notify user when it is auto-started or stopped. * * This is only used when auto-start feature `OPENTHREAD_CONFIG_SRP_CLIENT_AUTO_START_API_ENABLE` is enabled. * @@ -195,7 +195,7 @@ typedef void (*otSrpClientCallback)(otError aError, typedef void (*otSrpClientAutoStartCallback)(const otSockAddr *aServerSockAddr, void *aContext); /** - * This function starts the SRP client operation. + * Starts the SRP client operation. * * SRP client will prepare and send "SRP Update" message to the SRP server once all the following conditions are met: * @@ -222,9 +222,9 @@ typedef void (*otSrpClientAutoStartCallback)(const otSockAddr *aServerSockAddr, otError otSrpClientStart(otInstance *aInstance, const otSockAddr *aServerSockAddr); /** - * This function stops the SRP client operation. + * Stops the SRP client operation. * - * This function stops any further interactions with the SRP server. Note that it does not remove or clear host info + * Stops any further interactions with the SRP server. Note that it does not remove or clear host info * and/or list of services. It marks all services to be added/removed again once the client is (re)started. * * @param[in] aInstance A pointer to the OpenThread instance. @@ -233,7 +233,7 @@ otError otSrpClientStart(otInstance *aInstance, const otSockAddr *aServerSockAdd void otSrpClientStop(otInstance *aInstance); /** - * This function indicates whether the SRP client is running or not. + * Indicates whether the SRP client is running or not. * * @param[in] aInstance A pointer to the OpenThread instance. * @@ -243,7 +243,7 @@ void otSrpClientStop(otInstance *aInstance); bool otSrpClientIsRunning(otInstance *aInstance); /** - * This function gets the socket address (IPv6 address and port number) of the SRP server which is being used by SRP + * Gets the socket address (IPv6 address and port number) of the SRP server which is being used by SRP * client. * * If the client is not running, the address is unspecified (all zero) with zero port number. @@ -256,7 +256,7 @@ bool otSrpClientIsRunning(otInstance *aInstance); const otSockAddr *otSrpClientGetServerAddress(otInstance *aInstance); /** - * This function sets the callback to notify caller of events/changes from SRP client. + * Sets the callback to notify caller of events/changes from SRP client. * * The SRP client allows a single callback to be registered. So consecutive calls to this function will overwrite any * previously set callback functions. @@ -269,7 +269,7 @@ const otSockAddr *otSrpClientGetServerAddress(otInstance *aInstance); void otSrpClientSetCallback(otInstance *aInstance, otSrpClientCallback aCallback, void *aContext); /** - * This function enables the auto-start mode. + * Enables the auto-start mode. * * This is only available when auto-start feature `OPENTHREAD_CONFIG_SRP_CLIENT_AUTO_START_API_ENABLE` is enabled. * @@ -310,7 +310,7 @@ void otSrpClientSetCallback(otInstance *aInstance, otSrpClientCallback aCallback void otSrpClientEnableAutoStartMode(otInstance *aInstance, otSrpClientAutoStartCallback aCallback, void *aContext); /** - * This function disables the auto-start mode. + * Disables the auto-start mode. * * This is only available when auto-start feature `OPENTHREAD_CONFIG_SRP_CLIENT_AUTO_START_API_ENABLE` is enabled. * @@ -325,7 +325,7 @@ void otSrpClientEnableAutoStartMode(otInstance *aInstance, otSrpClientAutoStartC void otSrpClientDisableAutoStartMode(otInstance *aInstance); /** - * This function indicates the current state of auto-start mode (enabled or disabled). + * Indicates the current state of auto-start mode (enabled or disabled). * * This is only available when auto-start feature `OPENTHREAD_CONFIG_SRP_CLIENT_AUTO_START_API_ENABLE` is enabled. * @@ -337,7 +337,7 @@ void otSrpClientDisableAutoStartMode(otInstance *aInstance); bool otSrpClientIsAutoStartModeEnabled(otInstance *aInstance); /** - * This function gets the TTL value in every record included in SRP update requests. + * Gets the TTL value in every record included in SRP update requests. * * Note that this is the TTL requested by the SRP client. The server may choose to accept a different TTL. * @@ -352,7 +352,7 @@ bool otSrpClientIsAutoStartModeEnabled(otInstance *aInstance); uint32_t otSrpClientGetTtl(otInstance *aInstance); /** - * This function sets the TTL value in every record included in SRP update requests. + * Sets the TTL value in every record included in SRP update requests. * * Changing the TTL does not impact the TTL of already registered services/host-info. * It only affects future SRP update messages (i.e., adding new services and/or refreshes of the existing services). @@ -365,7 +365,7 @@ uint32_t otSrpClientGetTtl(otInstance *aInstance); void otSrpClientSetTtl(otInstance *aInstance, uint32_t aTtl); /** - * This function gets the default lease interval used in SRP update requests. + * Gets the default lease interval used in SRP update requests. * * The default interval is used only for `otSrpClientService` instances with `mLease` set to zero. * @@ -380,7 +380,7 @@ void otSrpClientSetTtl(otInstance *aInstance, uint32_t aTtl); uint32_t otSrpClientGetLeaseInterval(otInstance *aInstance); /** - * This function sets the default lease interval used in SRP update requests. + * Sets the default lease interval used in SRP update requests. * * The default interval is used only for `otSrpClientService` instances with `mLease` set to zero. * @@ -395,7 +395,7 @@ uint32_t otSrpClientGetLeaseInterval(otInstance *aInstance); void otSrpClientSetLeaseInterval(otInstance *aInstance, uint32_t aInterval); /** - * This function gets the default key lease interval used in SRP update requests. + * Gets the default key lease interval used in SRP update requests. * * The default interval is used only for `otSrpClientService` instances with `mKeyLease` set to zero. * @@ -410,7 +410,7 @@ void otSrpClientSetLeaseInterval(otInstance *aInstance, uint32_t aInterval); uint32_t otSrpClientGetKeyLeaseInterval(otInstance *aInstance); /** - * This function sets the default key lease interval used in SRP update requests. + * Sets the default key lease interval used in SRP update requests. * * The default interval is used only for `otSrpClientService` instances with `mKeyLease` set to zero. * @@ -425,7 +425,7 @@ uint32_t otSrpClientGetKeyLeaseInterval(otInstance *aInstance); void otSrpClientSetKeyLeaseInterval(otInstance *aInstance, uint32_t aInterval); /** - * This function gets the host info. + * Gets the host info. * * @param[in] aInstance A pointer to the OpenThread instance. * @@ -435,7 +435,7 @@ void otSrpClientSetKeyLeaseInterval(otInstance *aInstance, uint32_t aInterval); const otSrpClientHostInfo *otSrpClientGetHostInfo(otInstance *aInstance); /** - * This function sets the host name label. + * Sets the host name label. * * After a successful call to this function, `otSrpClientCallback` will be called to report the status of host info * registration with SRP server. @@ -458,7 +458,7 @@ const otSrpClientHostInfo *otSrpClientGetHostInfo(otInstance *aInstance); otError otSrpClientSetHostName(otInstance *aInstance, const char *aName); /** - * This function enables auto host address mode. + * Enables auto host address mode. * * When enabled host IPv6 addresses are automatically set by SRP client using all the unicast addresses on Thread netif * excluding all link-local and mesh-local addresses. If there is no valid address, then Mesh Local EID address is @@ -479,7 +479,7 @@ otError otSrpClientSetHostName(otInstance *aInstance, const char *aName); otError otSrpClientEnableAutoHostAddress(otInstance *aInstance); /** - * This function sets/updates the list of host IPv6 address. + * Sets/updates the list of host IPv6 address. * * Host IPv6 addresses can be set/changed before start or during operation of SRP client (e.g. to add/remove or change * a previously registered host address), except when the host info is being removed (client is busy handling a remove @@ -508,7 +508,7 @@ otError otSrpClientEnableAutoHostAddress(otInstance *aInstance); otError otSrpClientSetHostAddresses(otInstance *aInstance, const otIp6Address *aIp6Addresses, uint8_t aNumAddresses); /** - * This function adds a service to be registered with server. + * Adds a service to be registered with server. * * After a successful call to this function, `otSrpClientCallback` will be called to report the status of the service * addition/registration with SRP server. @@ -535,7 +535,7 @@ otError otSrpClientSetHostAddresses(otInstance *aInstance, const otIp6Address *a otError otSrpClientAddService(otInstance *aInstance, otSrpClientService *aService); /** - * This function requests a service to be unregistered with server. + * Requests a service to be unregistered with server. * * After a successful call to this function, `otSrpClientCallback` will be called to report the status of remove * request with SRP server. @@ -556,14 +556,14 @@ otError otSrpClientAddService(otInstance *aInstance, otSrpClientService *aServic otError otSrpClientRemoveService(otInstance *aInstance, otSrpClientService *aService); /** - * This function clears a service, immediately removing it from the client service list. + * Clears a service, immediately removing it from the client service list. * * Unlike `otSrpClientRemoveService()` which sends an update message to the server to remove the service, this function * clears the service from the client's service list without any interaction with the server. On a successful call to * this function, the `otSrpClientCallback` will NOT be called and the @p aService entry can be reclaimed and re-used * by the caller immediately. * - * This function can be used along with a subsequent call to `otSrpClientAddService()` (potentially reusing the same @p + * Can be used along with a subsequent call to `otSrpClientAddService()` (potentially reusing the same @p * aService entry with the same service and instance names) to update some of the parameters in an existing service. * * @param[in] aInstance A pointer to the OpenThread instance. @@ -576,7 +576,7 @@ otError otSrpClientRemoveService(otInstance *aInstance, otSrpClientService *aSer otError otSrpClientClearService(otInstance *aInstance, otSrpClientService *aService); /** - * This function gets the list of services being managed by client. + * Gets the list of services being managed by client. * * @param[in] aInstance A pointer to the OpenThread instance. * @@ -586,7 +586,7 @@ otError otSrpClientClearService(otInstance *aInstance, otSrpClientService *aServ const otSrpClientService *otSrpClientGetServices(otInstance *aInstance); /** - * This function starts the remove process of the host info and all services. + * Starts the remove process of the host info and all services. * * After returning from this function, `otSrpClientCallback` will be called to report the status of remove request with * SRP server. @@ -619,7 +619,7 @@ const otSrpClientService *otSrpClientGetServices(otInstance *aInstance); otError otSrpClientRemoveHostAndServices(otInstance *aInstance, bool aRemoveKeyLease, bool aSendUnregToServer); /** - * This function clears all host info and all the services. + * Clears all host info and all the services. * * Unlike `otSrpClientRemoveHostAndServices()` which sends an update message to the server to remove all the info, this * function clears all the info immediately without any interaction with the server. @@ -630,9 +630,9 @@ otError otSrpClientRemoveHostAndServices(otInstance *aInstance, bool aRemoveKeyL void otSrpClientClearHostAndServices(otInstance *aInstance); /** - * This function gets the domain name being used by SRP client. + * Gets the domain name being used by SRP client. * - * This function requires `OPENTHREAD_CONFIG_SRP_CLIENT_DOMAIN_NAME_API_ENABLE` to be enabled. + * Requires `OPENTHREAD_CONFIG_SRP_CLIENT_DOMAIN_NAME_API_ENABLE` to be enabled. * * If domain name is not set, "default.service.arpa" will be used. * @@ -644,9 +644,9 @@ void otSrpClientClearHostAndServices(otInstance *aInstance); const char *otSrpClientGetDomainName(otInstance *aInstance); /** - * This function sets the domain name to be used by SRP client. + * Sets the domain name to be used by SRP client. * - * This function requires `OPENTHREAD_CONFIG_SRP_CLIENT_DOMAIN_NAME_API_ENABLE` to be enabled. + * Requires `OPENTHREAD_CONFIG_SRP_CLIENT_DOMAIN_NAME_API_ENABLE` to be enabled. * * If not set "default.service.arpa" will be used. * @@ -666,7 +666,7 @@ const char *otSrpClientGetDomainName(otInstance *aInstance); otError otSrpClientSetDomainName(otInstance *aInstance, const char *aName); /** - * This function converts a `otSrpClientItemState` to a string. + * Converts a `otSrpClientItemState` to a string. * * @param[in] aItemState An item state. * @@ -676,12 +676,12 @@ otError otSrpClientSetDomainName(otInstance *aInstance, const char *aName); const char *otSrpClientItemStateToString(otSrpClientItemState aItemState); /** - * This function enables/disables "service key record inclusion" mode. + * Enables/disables "service key record inclusion" mode. * * When enabled, SRP client will include KEY record in Service Description Instructions in the SRP update messages * that it sends. * - * This function is available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` configuration is enabled. * * @note KEY record is optional in Service Description Instruction (it is required and always included in the Host * Description Instruction). The default behavior of SRP client is to not include it. This function is intended to @@ -694,9 +694,9 @@ const char *otSrpClientItemStateToString(otSrpClientItemState aItemState); void otSrpClientSetServiceKeyRecordEnabled(otInstance *aInstance, bool aEnabled); /** - * This method indicates whether the "service key record inclusion" mode is enabled or disabled. + * Indicates whether the "service key record inclusion" mode is enabled or disabled. * - * This function is available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` configuration is enabled. * * @param[in] aInstance A pointer to the OpenThread instance. * diff --git a/openthread/include/openthread/srp_client_buffers.h b/openthread/include/openthread/srp_client_buffers.h index 1f8c457c87..974da0d565 100644 --- a/openthread/include/openthread/srp_client_buffers.h +++ b/openthread/include/openthread/srp_client_buffers.h @@ -55,7 +55,7 @@ extern "C" { */ /** - * This struct represents a SRP client service pool entry. + * Represents a SRP client service pool entry. * */ typedef struct otSrpClientBuffersServiceEntry @@ -65,7 +65,7 @@ typedef struct otSrpClientBuffersServiceEntry } otSrpClientBuffersServiceEntry; /** - * This function gets the string buffer to use for SRP client host name. + * Gets the string buffer to use for SRP client host name. * * @param[in] aInstance A pointer to the OpenThread instance. * @param[out] aSize Pointer to a variable to return the size (number of bytes) of the string buffer (MUST NOT be @@ -77,7 +77,7 @@ typedef struct otSrpClientBuffersServiceEntry char *otSrpClientBuffersGetHostNameString(otInstance *aInstance, uint16_t *aSize); /** - * This function gets the array of IPv6 address entries to use as SRP client host address list. + * Gets the array of IPv6 address entries to use as SRP client host address list. * * @param[in] aInstance A pointer to the OpenThread instance. * @param[out] aArrayLength Pointer to a variable to return the array length i.e., number of IPv6 address entries in @@ -89,7 +89,7 @@ char *otSrpClientBuffersGetHostNameString(otInstance *aInstance, uint16_t *aSize otIp6Address *otSrpClientBuffersGetHostAddressesArray(otInstance *aInstance, uint8_t *aArrayLength); /** - * This function allocates a new service entry from the pool. + * Allocates a new service entry from the pool. * * The returned service entry instance will be initialized as follows: * @@ -115,7 +115,7 @@ otIp6Address *otSrpClientBuffersGetHostAddressesArray(otInstance *aInstance, uin otSrpClientBuffersServiceEntry *otSrpClientBuffersAllocateService(otInstance *aInstance); /** - * This function frees a previously allocated service entry. + * Frees a previously allocated service entry. * * The @p aService MUST be previously allocated using `otSrpClientBuffersAllocateService()` and not yet freed. Otherwise * the behavior of this function is undefined. @@ -127,7 +127,7 @@ otSrpClientBuffersServiceEntry *otSrpClientBuffersAllocateService(otInstance *aI void otSrpClientBuffersFreeService(otInstance *aInstance, otSrpClientBuffersServiceEntry *aService); /** - * This function frees all previously allocated service entries. + * Frees all previously allocated service entries. * * @param[in] aInstance A pointer to the OpenThread instance. * @@ -135,7 +135,7 @@ void otSrpClientBuffersFreeService(otInstance *aInstance, otSrpClientBuffersServ void otSrpClientBuffersFreeAllServices(otInstance *aInstance); /** - * This function gets the string buffer for service name from a service entry. + * Gets the string buffer for service name from a service entry. * * @param[in] aEntry A pointer to a previously allocated service entry (MUST NOT be NULL). * @param[out] aSize A pointer to a variable to return the size (number of bytes) of the string buffer (MUST NOT be @@ -147,7 +147,7 @@ void otSrpClientBuffersFreeAllServices(otInstance *aInstance); char *otSrpClientBuffersGetServiceEntryServiceNameString(otSrpClientBuffersServiceEntry *aEntry, uint16_t *aSize); /** - * This function gets the string buffer for service instance name from a service entry. + * Gets the string buffer for service instance name from a service entry. * * @param[in] aEntry A pointer to a previously allocated service entry (MUST NOT be NULL). * @param[out] aSize A pointer to a variable to return the size (number of bytes) of the string buffer (MUST NOT be @@ -159,7 +159,7 @@ char *otSrpClientBuffersGetServiceEntryServiceNameString(otSrpClientBuffersServi char *otSrpClientBuffersGetServiceEntryInstanceNameString(otSrpClientBuffersServiceEntry *aEntry, uint16_t *aSize); /** - * This function gets the buffer for TXT record from a service entry. + * Gets the buffer for TXT record from a service entry. * * @param[in] aEntry A pointer to a previously allocated service entry (MUST NOT be NULL). * @param[out] aSize A pointer to a variable to return the size (number of bytes) of the buffer (MUST NOT be NULL). @@ -170,7 +170,7 @@ char *otSrpClientBuffersGetServiceEntryInstanceNameString(otSrpClientBuffersServ uint8_t *otSrpClientBuffersGetServiceEntryTxtBuffer(otSrpClientBuffersServiceEntry *aEntry, uint16_t *aSize); /** - * This function gets the array for service subtype labels from the service entry. + * Gets the array for service subtype labels from the service entry. * * @param[in] aEntry A pointer to a previously allocated service entry (MUST NOT be NULL). * @param[out] aArrayLength A pointer to a variable to return the array length (MUST NOT be NULL). diff --git a/openthread/include/openthread/srp_server.h b/openthread/include/openthread/srp_server.h index 4dceee2030..8f45b0842b 100644 --- a/openthread/include/openthread/srp_server.h +++ b/openthread/include/openthread/srp_server.h @@ -74,65 +74,7 @@ typedef struct otSrpServerService otSrpServerService; typedef uint32_t otSrpServerServiceUpdateId; /** - * The service flag type to indicate which services to include or exclude when searching in (or iterating over) the - * list of SRP services. - * - * This is a combination of bit-flags. The specific bit-flags are defined in the enumeration `OT_SRP_SERVER_FLAG_*`. - * - */ -typedef uint8_t otSrpServerServiceFlags; - -enum -{ - OT_SRP_SERVER_SERVICE_FLAG_BASE_TYPE = 1 << 0, ///< Include base services (not a sub-type). - OT_SRP_SERVER_SERVICE_FLAG_SUB_TYPE = 1 << 1, ///< Include sub-type services. - OT_SRP_SERVER_SERVICE_FLAG_ACTIVE = 1 << 2, ///< Include active (not deleted) services. - OT_SRP_SERVER_SERVICE_FLAG_DELETED = 1 << 3, ///< Include deleted services. -}; - -enum -{ - /** - * This constant defines an `otSrpServerServiceFlags` combination accepting any service (base/sub-type, - * active/deleted). - * - */ - OT_SRP_SERVER_FLAGS_ANY_SERVICE = (OT_SRP_SERVER_SERVICE_FLAG_BASE_TYPE | OT_SRP_SERVER_SERVICE_FLAG_SUB_TYPE | - OT_SRP_SERVER_SERVICE_FLAG_ACTIVE | OT_SRP_SERVER_SERVICE_FLAG_DELETED), - - /** - * This constant defines an `otSrpServerServiceFlags` combination accepting base service only. - * - */ - OT_SRP_SERVER_FLAGS_BASE_TYPE_SERVICE_ONLY = - (OT_SRP_SERVER_SERVICE_FLAG_BASE_TYPE | OT_SRP_SERVER_SERVICE_FLAG_ACTIVE | OT_SRP_SERVER_SERVICE_FLAG_DELETED), - - /** - * This constant defines an `otSrpServerServiceFlags` combination accepting sub-type service only. - * - */ - OT_SRP_SERVER_FLAGS_SUB_TYPE_SERVICE_ONLY = - (OT_SRP_SERVER_SERVICE_FLAG_SUB_TYPE | OT_SRP_SERVER_SERVICE_FLAG_ACTIVE | OT_SRP_SERVER_SERVICE_FLAG_DELETED), - - /** - * This constant defines an `otSrpServerServiceFlags` combination accepting any active service (not deleted). - * - */ - OT_SRP_SERVER_FLAGS_ANY_TYPE_ACTIVE_SERVICE = - (OT_SRP_SERVER_SERVICE_FLAG_BASE_TYPE | OT_SRP_SERVER_SERVICE_FLAG_SUB_TYPE | - OT_SRP_SERVER_SERVICE_FLAG_ACTIVE), - - /** - * This constant defines an `otSrpServerServiceFlags` combination accepting any deleted service. - * - */ - OT_SRP_SERVER_FLAGS_ANY_TYPE_DELETED_SERVICE = - (OT_SRP_SERVER_SERVICE_FLAG_BASE_TYPE | OT_SRP_SERVER_SERVICE_FLAG_SUB_TYPE | - OT_SRP_SERVER_SERVICE_FLAG_ACTIVE), -}; - -/** - * This enumeration represents the state of the SRP server. + * Represents the state of the SRP server. * */ typedef enum @@ -143,7 +85,7 @@ typedef enum } otSrpServerState; /** - * This enumeration represents the address mode used by the SRP server. + * Represents the address mode used by the SRP server. * * Address mode specifies how the address and port number are determined by the SRP server and how this info is * published in the Thread Network Data. @@ -156,7 +98,7 @@ typedef enum otSrpServerAddressMode } otSrpServerAddressMode; /** - * This structure includes SRP server TTL configurations. + * Includes SRP server TTL configurations. * */ typedef struct otSrpServerTtlConfig @@ -166,7 +108,7 @@ typedef struct otSrpServerTtlConfig } otSrpServerTtlConfig; /** - * This structure includes SRP server LEASE and KEY-LEASE configurations. + * Includes SRP server LEASE and KEY-LEASE configurations. * */ typedef struct otSrpServerLeaseConfig @@ -178,7 +120,7 @@ typedef struct otSrpServerLeaseConfig } otSrpServerLeaseConfig; /** - * This structure includes SRP server lease information of a host/service. + * Includes SRP server lease information of a host/service. * */ typedef struct otSrpServerLeaseInfo @@ -190,7 +132,7 @@ typedef struct otSrpServerLeaseInfo } otSrpServerLeaseInfo; /** - * This structure includes the statistics of SRP server responses. + * Includes the statistics of SRP server responses. * */ typedef struct otSrpServerResponseCounters @@ -204,7 +146,7 @@ typedef struct otSrpServerResponseCounters } otSrpServerResponseCounters; /** - * This function returns the domain authorized to the SRP server. + * Returns the domain authorized to the SRP server. * * If the domain if not set by SetDomain, "default.service.arpa." will be returned. * A trailing dot is always appended even if the domain is set without it. @@ -217,10 +159,10 @@ typedef struct otSrpServerResponseCounters const char *otSrpServerGetDomain(otInstance *aInstance); /** - * This function sets the domain on the SRP server. + * Sets the domain on the SRP server. * * A trailing dot will be appended to @p aDomain if it is not already there. - * This function should only be called before the SRP server is enabled. + * Should only be called before the SRP server is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aDomain The domain to be set. MUST NOT be NULL. @@ -234,7 +176,7 @@ const char *otSrpServerGetDomain(otInstance *aInstance); otError otSrpServerSetDomain(otInstance *aInstance, const char *aDomain); /** - * This function returns the state of the SRP server. + * Returns the state of the SRP server. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -244,7 +186,7 @@ otError otSrpServerSetDomain(otInstance *aInstance, const char *aDomain); otSrpServerState otSrpServerGetState(otInstance *aInstance); /** - * This function returns the port the SRP server is listening to. + * Returns the port the SRP server is listening to. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -254,7 +196,7 @@ otSrpServerState otSrpServerGetState(otInstance *aInstance); uint16_t otSrpServerGetPort(otInstance *aInstance); /** - * This function returns the address mode being used by the SRP server. + * Returns the address mode being used by the SRP server. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -264,7 +206,7 @@ uint16_t otSrpServerGetPort(otInstance *aInstance); otSrpServerAddressMode otSrpServerGetAddressMode(otInstance *aInstance); /** - * This function sets the address mode to be used by the SRP server. + * Sets the address mode to be used by the SRP server. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aMode The address mode to use. @@ -276,7 +218,7 @@ otSrpServerAddressMode otSrpServerGetAddressMode(otInstance *aInstance); otError otSrpServerSetAddressMode(otInstance *aInstance, otSrpServerAddressMode aMode); /** - * This function returns the sequence number used with anycast address mode. + * Returns the sequence number used with anycast address mode. * * The sequence number is included in "DNS/SRP Service Anycast Address" entry published in the Network Data. * @@ -288,7 +230,7 @@ otError otSrpServerSetAddressMode(otInstance *aInstance, otSrpServerAddressMode uint8_t otSrpServerGetAnycastModeSequenceNumber(otInstance *aInstance); /** - * This function sets the sequence number used with anycast address mode. + * Sets the sequence number used with anycast address mode. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aSequenceNumber The sequence number to use. @@ -300,7 +242,7 @@ uint8_t otSrpServerGetAnycastModeSequenceNumber(otInstance *aInstance); otError otSrpServerSetAnycastModeSequenceNumber(otInstance *aInstance, uint8_t aSequenceNumber); /** - * This function enables/disables the SRP server. + * Enables/disables the SRP server. * * On a Border Router, it is recommended to use `otSrpServerSetAutoEnableMode()` instead. * @@ -311,9 +253,9 @@ otError otSrpServerSetAnycastModeSequenceNumber(otInstance *aInstance, uint8_t a void otSrpServerSetEnabled(otInstance *aInstance, bool aEnabled); /** - * This function enables/disables the auto-enable mode on SRP server. + * Enables/disables the auto-enable mode on SRP server. * - * This function requires `OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE` feature. + * Requires `OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE` feature. * * When this mode is enabled, the Border Routing Manager controls if/when to enable or disable the SRP server. * SRP sever is auto-enabled if/when Border Routing is started and it is done with the initial prefix and route @@ -327,15 +269,15 @@ void otSrpServerSetEnabled(otInstance *aInstance, bool aEnabled); * it stays enabled). * * @param[in] aInstance A pointer to an OpenThread instance. - * @param[in] aEnbaled A boolean to enable/disable the auto-enable mode. + * @param[in] aEnabled A boolean to enable/disable the auto-enable mode. * */ void otSrpServerSetAutoEnableMode(otInstance *aInstance, bool aEnabled); /** - * This function indicates whether the auto-enable mode is enabled or disabled. + * Indicates whether the auto-enable mode is enabled or disabled. * - * This function requires `OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE` feature. + * Requires `OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE` feature. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -346,7 +288,7 @@ void otSrpServerSetAutoEnableMode(otInstance *aInstance, bool aEnabled); bool otSrpServerIsAutoEnableMode(otInstance *aInstance); /** - * This function returns SRP server TTL configuration. + * Returns SRP server TTL configuration. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[out] aTtlConfig A pointer to an `otSrpServerTtlConfig` instance. @@ -355,7 +297,7 @@ bool otSrpServerIsAutoEnableMode(otInstance *aInstance); void otSrpServerGetTtlConfig(otInstance *aInstance, otSrpServerTtlConfig *aTtlConfig); /** - * This function sets SRP server TTL configuration. + * Sets SRP server TTL configuration. * * The granted TTL will always be no greater than the max lease interval configured via `otSrpServerSetLeaseConfig()`, * regardless of the minimum and maximum TTL configuration. @@ -370,7 +312,7 @@ void otSrpServerGetTtlConfig(otInstance *aInstance, otSrpServerTtlConfig *aTtlCo otError otSrpServerSetTtlConfig(otInstance *aInstance, const otSrpServerTtlConfig *aTtlConfig); /** - * This function returns SRP server LEASE and KEY-LEASE configurations. + * Returns SRP server LEASE and KEY-LEASE configurations. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[out] aLeaseConfig A pointer to an `otSrpServerLeaseConfig` instance. @@ -379,7 +321,7 @@ otError otSrpServerSetTtlConfig(otInstance *aInstance, const otSrpServerTtlConfi void otSrpServerGetLeaseConfig(otInstance *aInstance, otSrpServerLeaseConfig *aLeaseConfig); /** - * This function sets SRP server LEASE and KEY-LEASE configurations. + * Sets SRP server LEASE and KEY-LEASE configurations. * * When a non-zero LEASE time is requested from a client, the granted value will be * limited in range [aMinLease, aMaxLease]; and a non-zero KEY-LEASE will be granted @@ -396,9 +338,9 @@ void otSrpServerGetLeaseConfig(otInstance *aInstance, otSrpServerLeaseConfig *aL otError otSrpServerSetLeaseConfig(otInstance *aInstance, const otSrpServerLeaseConfig *aLeaseConfig); /** - * This function handles SRP service updates. + * Handles SRP service updates. * - * This function is called by the SRP server to notify that a SRP host and possibly SRP services + * Is called by the SRP server to notify that a SRP host and possibly SRP services * are being updated. It is important that the SRP updates are not committed until the handler * returns the result by calling otSrpServerHandleServiceUpdateResult or times out after @p aTimeout. * @@ -434,7 +376,7 @@ typedef void (*otSrpServerServiceUpdateHandler)(otSrpServerServiceUpdateId aId, void *aContext); /** - * This function sets the SRP service updates handler on SRP server. + * Sets the SRP service updates handler on SRP server. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aServiceHandler A pointer to a service handler. Use NULL to remove the handler. @@ -447,7 +389,7 @@ void otSrpServerSetServiceUpdateHandler(otInstance *aInstanc void *aContext); /** - * This function reports the result of processing a SRP update to the SRP server. + * Reports the result of processing a SRP update to the SRP server. * * The Service Update Handler should call this function to return the result of its * processing of a SRP update. @@ -462,7 +404,7 @@ void otSrpServerSetServiceUpdateHandler(otInstance *aInstanc void otSrpServerHandleServiceUpdateResult(otInstance *aInstance, otSrpServerServiceUpdateId aId, otError aError); /** - * This function returns the next registered host on the SRP server. + * Returns the next registered host on the SRP server. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aHost A pointer to current host; use NULL to get the first host. @@ -473,7 +415,7 @@ void otSrpServerHandleServiceUpdateResult(otInstance *aInstance, otSrpServerServ const otSrpServerHost *otSrpServerGetNextHost(otInstance *aInstance, const otSrpServerHost *aHost); /** - * This function returns the response counters of the SRP server. + * Returns the response counters of the SRP server. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -483,7 +425,7 @@ const otSrpServerHost *otSrpServerGetNextHost(otInstance *aInstance, const otSrp const otSrpServerResponseCounters *otSrpServerGetResponseCounters(otInstance *aInstance); /** - * This function tells if the SRP service host has been deleted. + * Tells if the SRP service host has been deleted. * * A SRP service host can be deleted but retains its name for future uses. * In this case, the host instance is not removed from the SRP server/registry. @@ -496,7 +438,7 @@ const otSrpServerResponseCounters *otSrpServerGetResponseCounters(otInstance *aI bool otSrpServerHostIsDeleted(const otSrpServerHost *aHost); /** - * This function returns the full name of the host. + * Returns the full name of the host. * * @param[in] aHost A pointer to the SRP service host. * @@ -506,7 +448,22 @@ bool otSrpServerHostIsDeleted(const otSrpServerHost *aHost); const char *otSrpServerHostGetFullName(const otSrpServerHost *aHost); /** - * This function returns the addresses of given host. + * Indicates whether the host matches a given host name. + * + * DNS name matches are performed using a case-insensitive string comparison (i.e., "Abc" and "aBc" are considered to + * be the same). + * + * @param[in] aHost A pointer to the SRP service host. + * @param[in] aFullName A full host name. + * + * @retval TRUE If host matches the host name. + * @retval FALSE If host does not match the host name. + * + */ +bool otSrpServerHostMatchesFullName(const otSrpServerHost *aHost, const char *aFullName); + +/** + * Returns the addresses of given host. * * @param[in] aHost A pointer to the SRP service host. * @param[out] aAddressesNum A pointer to where we should output the number of the addresses to. @@ -517,7 +474,7 @@ const char *otSrpServerHostGetFullName(const otSrpServerHost *aHost); const otIp6Address *otSrpServerHostGetAddresses(const otSrpServerHost *aHost, uint8_t *aAddressesNum); /** - * This function returns the LEASE and KEY-LEASE information of a given host. + * Returns the LEASE and KEY-LEASE information of a given host. * * @param[in] aHost A pointer to the SRP server host. * @param[out] aLeaseInfo A pointer to where to output the LEASE and KEY-LEASE information. @@ -526,10 +483,7 @@ const otIp6Address *otSrpServerHostGetAddresses(const otSrpServerHost *aHost, ui void otSrpServerHostGetLeaseInfo(const otSrpServerHost *aHost, otSrpServerLeaseInfo *aLeaseInfo); /** - * This function returns the next service (excluding any sub-type services) of given host. - * - * @note This function is being deprecated and will be removed. `otSrpServerHostFindNextService()` can be used - * instead. + * Returns the next service of given host. * * @param[in] aHost A pointer to the SRP service host. * @param[in] aService A pointer to current SRP service instance; use NULL to get the first service. @@ -541,125 +495,136 @@ const otSrpServerService *otSrpServerHostGetNextService(const otSrpServerHost const otSrpServerService *aService); /** - * This function finds the next matching service on the host. + * Indicates whether or not the SRP service has been deleted. * - * The combination of flags and service and instance names enables iterating over the full list of services and/or a - * subset of them matching certain conditions, or finding a specific service. + * A SRP service can be deleted but retains its name for future uses. + * In this case, the service instance is not removed from the SRP server/registry. + * It is guaranteed that all services are deleted if the host is deleted. + * + * @param[in] aService A pointer to the SRP service. * - * To iterate over all services of a host: - * service = otSrpServerHostFindNextService(host, service, OT_SRP_SERVER_FLAGS_ANY_SERVICE, NULL, NULL); + * @returns TRUE if the service has been deleted, FALSE if not. + * + */ +bool otSrpServerServiceIsDeleted(const otSrpServerService *aService); + +/** + * Returns the full service instance name of the service. * - * To iterate over base services only (exclude sub-types): - * service = otSrpServerHostFindNextService(host, service, OT_SRP_SERVER_FLAGS_BASE_TYPE_SERVICE_ONLY, NULL, NULL); + * @param[in] aService A pointer to the SRP service. * - * To iterate over sub-types of a specific instance name `instanceName`: - * service = otSrpServerHostFindNextService(host, service, OT_SRP_SERVER_FLAGS_SUB_TYPE_SERVICE_ONLY, NULL, - * instanceName); + * @returns A pointer to the null-terminated service instance name string. * - * To find a specific service with service name `serviceName` and service instance name `instanceName`: - * service = otSrpServerHostFindNextService(host, NULL, OT_SRP_SERVER_FLAGS_ANY_SERVICE, serviceName, instanceName); + */ +const char *otSrpServerServiceGetInstanceName(const otSrpServerService *aService); + +/** + * Indicates whether this service matches a given service instance name. * - * To find the base type service with a given service instance name `instanceName`: - * service = otSrpServerHostFindNextService(host, NULL, OT_SRP_SERVER_FLAGS_BASE_TYPE_SERVICE_ONLY, NULL, - * instanceName); + * DNS name matches are performed using a case-insensitive string comparison (i.e., "Abc" and "aBc" are considered to + * be the same). * - * @param[in] aHost A pointer to the SRP service host (MUST NOT be NULL). - * @param[in] aPrevService A pointer to the previous service or NULL to start from the beginning of the list. - * @param[in] aFlags Flags indicating which services to include (base/sub-type, active/deleted). - * @param[in] aServiceName The service name to match. Set to NULL to accept any name. - * @param[in] aInstanceName The service instance name to match. Set to NULL to accept any name. + * @param[in] aService A pointer to the SRP service. + * @param[in] aInstanceName The service instance name. * - * @returns A pointer to the next matching service or NULL if no matching service could be found. + * @retval TRUE If service matches the service instance name. + * @retval FALSE If service does not match the service instance name. * */ -const otSrpServerService *otSrpServerHostFindNextService(const otSrpServerHost *aHost, - const otSrpServerService *aPrevService, - otSrpServerServiceFlags aFlags, - const char *aServiceName, - const char *aInstanceName); +bool otSrpServerServiceMatchesInstanceName(const otSrpServerService *aService, const char *aInstanceName); /** - * This function indicates whether or not the SRP service has been deleted. - * - * A SRP service can be deleted but retains its name for future uses. - * In this case, the service instance is not removed from the SRP server/registry. - * It is guaranteed that all services are deleted if the host is deleted. + * Returns the service instance label (first label in instance name) of the service. * * @param[in] aService A pointer to the SRP service. * - * @returns TRUE if the service has been deleted, FALSE if not. + * @returns A pointer to the null-terminated service instance label string.. * */ -bool otSrpServerServiceIsDeleted(const otSrpServerService *aService); +const char *otSrpServerServiceGetInstanceLabel(const otSrpServerService *aService); /** - * This function indicates whether or not the SRP service is sub-type. + * Returns the full service name of the service. * * @param[in] aService A pointer to the SRP service. * - * @returns TRUE if the service is a sub-type, FALSE if not. + * @returns A pointer to the null-terminated service name string. * */ -bool otSrpServerServiceIsSubType(const otSrpServerService *aService); +const char *otSrpServerServiceGetServiceName(const otSrpServerService *aService); /** - * This function returns the full service instance name of the service. + * Indicates whether this service matches a given service name. * - * @note This function is being deprecated and will be removed. `otSrpServerServiceGetInstanceName()` can be used - * instead. + * DNS name matches are performed using a case-insensitive string comparison (i.e., "Abc" and "aBc" are considered to + * be the same). * - * @param[in] aService A pointer to the SRP service. + * @param[in] aService A pointer to the SRP service. + * @param[in] aServiceName The service name. * - * @returns A pointer to the null-terminated service instance name string. + * @retval TRUE If service matches the service name. + * @retval FALSE If service does not match the service name. * */ -const char *otSrpServerServiceGetFullName(const otSrpServerService *aService); +bool otSrpServerServiceMatchesServiceName(const otSrpServerService *aService, const char *aServiceName); /** - * This function returns the full service instance name of the service. + * Gets the number of sub-types of the service. * * @param[in] aService A pointer to the SRP service. * - * @returns A pointer to the null-terminated service instance name string. + * @returns The number of sub-types of @p aService. * */ -const char *otSrpServerServiceGetInstanceName(const otSrpServerService *aService); +uint16_t otSrpServerServiceGetNumberOfSubTypes(const otSrpServerService *aService); /** - * This function returns the full service name of the service. + * Gets the sub-type service name (full name) of the service at a given index + * + * The full service name for a sub-type service follows "._sub...". * * @param[in] aService A pointer to the SRP service. + * @param[in] aIndex The index to get. * - * @returns A pointer to the null-terminated service name string. + * @returns A pointer to sub-type service name at @p aIndex, or `NULL` if no sub-type at this index. * */ -const char *otSrpServerServiceGetServiceName(const otSrpServerService *aService); +const char *otSrpServerServiceGetSubTypeServiceNameAt(const otSrpServerService *aService, uint16_t aIndex); /** - * This function gets the sub-type label from service name. + * Indicates whether or not the service has a given sub-type. + * + * DNS name matches are performed using a case-insensitive string comparison (i.e., "Abc" and "aBc" are considered to + * be the same). + * + * @param[in] aService A pointer to the SRP service. + * @param[in] aSubTypeServiceName The sub-type service name (full name) to check. * - * This function is intended to be used when the @p aService is a sub-type, i.e., `otSrpServerServiceIsSubType()` for - * the service returns TRUE. If it is not a sub-type this function returns `OT_ERROR_INVALID_ARGS`. + * @retval TRUE Service contains the sub-type @p aSubTypeServiceName. + * @retval FALSE Service does not contain the sub-type @p aSubTypeServiceName. * - * The full service name for a sub-type service follows "._sub...". This function - * copies the `` into the @p aLabel buffer. + */ +bool otSrpServerServiceHasSubTypeServiceName(const otSrpServerService *aService, const char *aSubTypeServiceName); + +/** + * Parses a sub-type service name (full name) and extracts the sub-type label. * - * The @p aLabel is ensured to always be null-terminated after returning even in case of failure. + * The full service name for a sub-type service follows "._sub...". * - * @param[in] aService A pointer to the SRP service. - * @param[out] aLabel A pointer to a buffer to copy the sub-type label name into. - * @param[in] aMaxSize Maximum size of @p aLabel buffer. + * @param[in] aSubTypeServiceName A sub-type service name (full name). + * @param[out] aLabel A pointer to a buffer to copy the extracted sub-type label. + * @param[in] aLabelSize Maximum size of @p aLabel buffer. * - * @retval OT_ERROR_NONE @p aLabel was updated successfully. + * @retval OT_ERROR_NONE Name was successfully parsed and @p aLabel was updated. * @retval OT_ERROR_NO_BUFS The sub-type label could not fit in @p aLabel buffer (number of chars from label * that could fit are copied in @p aLabel ensuring it is null-terminated). - * @retval OT_ERROR_INVALID_ARGS SRP service is not a sub-type. + * @retval OT_ERROR_INVALID_ARGS @p aSubTypeServiceName is not a valid sub-type format. * */ -otError otSrpServerServiceGetServiceSubTypeLabel(const otSrpServerService *aService, char *aLabel, uint8_t aMaxSize); +otError otSrpServerParseSubTypeServiceName(const char *aSubTypeServiceName, char *aLabel, uint8_t aLabelSize); /** - * This function returns the port of the service instance. + * Returns the port of the service instance. * * @param[in] aService A pointer to the SRP service. * @@ -669,7 +634,7 @@ otError otSrpServerServiceGetServiceSubTypeLabel(const otSrpServerService *aServ uint16_t otSrpServerServiceGetPort(const otSrpServerService *aService); /** - * This function returns the weight of the service instance. + * Returns the weight of the service instance. * * @param[in] aService A pointer to the SRP service. * @@ -679,7 +644,7 @@ uint16_t otSrpServerServiceGetPort(const otSrpServerService *aService); uint16_t otSrpServerServiceGetWeight(const otSrpServerService *aService); /** - * This function returns the priority of the service instance. + * Returns the priority of the service instance. * * @param[in] aService A pointer to the SRP service. * @@ -689,7 +654,7 @@ uint16_t otSrpServerServiceGetWeight(const otSrpServerService *aService); uint16_t otSrpServerServiceGetPriority(const otSrpServerService *aService); /** - * This function returns the TTL of the service instance. + * Returns the TTL of the service instance. * * @param[in] aService A pointer to the SRP service. * @@ -699,7 +664,7 @@ uint16_t otSrpServerServiceGetPriority(const otSrpServerService *aService); uint32_t otSrpServerServiceGetTtl(const otSrpServerService *aService); /** - * This function returns the TXT record data of the service instance. + * Returns the TXT record data of the service instance. * * @param[in] aService A pointer to the SRP service. * @param[out] aDataLength A pointer to return the TXT record data length. MUST NOT be NULL. @@ -710,7 +675,7 @@ uint32_t otSrpServerServiceGetTtl(const otSrpServerService *aService); const uint8_t *otSrpServerServiceGetTxtData(const otSrpServerService *aService, uint16_t *aDataLength); /** - * This function returns the host which the service instance reside on. + * Returns the host which the service instance reside on. * * @param[in] aService A pointer to the SRP service. * @@ -720,7 +685,7 @@ const uint8_t *otSrpServerServiceGetTxtData(const otSrpServerService *aService, const otSrpServerHost *otSrpServerServiceGetHost(const otSrpServerService *aService); /** - * This function returns the LEASE and KEY-LEASE information of a given service. + * Returns the LEASE and KEY-LEASE information of a given service. * * @param[in] aService A pointer to the SRP server service. * @param[out] aLeaseInfo A pointer to where to output the LEASE and KEY-LEASE information. diff --git a/openthread/include/openthread/tcp.h b/openthread/include/openthread/tcp.h index 910831a011..caa0d4efdc 100644 --- a/openthread/include/openthread/tcp.h +++ b/openthread/include/openthread/tcp.h @@ -225,11 +225,11 @@ typedef void (*otTcpDisconnected)(otTcpEndpoint *aEndpoint, otTcpDisconnectedRea * opaque in its declaration, is treated as struct tcpcb in the TCP * implementation. */ -#define OT_TCP_ENDPOINT_TCB_SIZE_BASE 368 +#define OT_TCP_ENDPOINT_TCB_SIZE_BASE 392 #define OT_TCP_ENDPOINT_TCB_NUM_PTR 36 /** - * This structure represents a TCP endpoint. + * Represents a TCP endpoint. * * An TCP endpoint acts an endpoint of TCP connection. It can be used to * initiate TCP connections, and, once a TCP connection is established, send @@ -266,7 +266,7 @@ struct otTcpEndpoint }; /** - * This structure contains arguments to the otTcpEndpointInitialize() function. + * Contains arguments to the otTcpEndpointInitialize() function. * */ typedef struct otTcpEndpointInitializeArgs @@ -390,7 +390,7 @@ const otSockAddr *otTcpGetPeerAddress(const otTcpEndpoint *aEndpoint); otError otTcpBind(otTcpEndpoint *aEndpoint, const otSockAddr *aSockName); /** - * This enumeration defines flags passed to otTcpConnect(). + * Defines flags passed to otTcpConnect(). * */ enum @@ -401,11 +401,16 @@ enum /** * Records the remote host and port for this connection. * - * By default TCP Fast Open is used. This means that this function merely - * records the remote host and port, and that the TCP connection establishment - * handshake only happens on the first call to otTcpSendByReference(). TCP Fast - * Open can be explicitly disabled using @p aFlags, in which case the TCP - * connection establishment handshake is initiated immediately. + * TCP Fast Open must be enabled or disabled using @p aFlags. If it is + * disabled, then the TCP connection establishment handshake is initiated + * immediately. If it is enabled, then this function merely records the + * the remote host and port, and the TCP connection establishment handshake + * only happens on the first call to `otTcpSendByReference()`. + * + * If TCP Fast Open is disabled, then the caller must wait for the + * `otTcpEstablished` callback indicating that TCP connection establishment + * handshake is done before it can start sending data e.g., by calling + * `otTcpSendByReference()`. * * @param[in] aEndpoint A pointer to the TCP endpoint structure to connect. * @param[in] aSockName The IP address and port of the host to which to connect. @@ -418,7 +423,7 @@ enum otError otTcpConnect(otTcpEndpoint *aEndpoint, const otSockAddr *aSockName, uint32_t aFlags); /** - * This enumeration defines flags passed to @p otTcpSendByReference. + * Defines flags passed to @p otTcpSendByReference. * */ enum @@ -582,7 +587,7 @@ struct otTcpListener; typedef struct otTcpListener otTcpListener; /** - * This enumeration defines incoming connection actions. + * Defines incoming connection actions. * * This is used in otTcpAcceptReady() callback. * @@ -656,7 +661,7 @@ typedef void (*otTcpAcceptDone)(otTcpListener *aListener, otTcpEndpoint *aEndpoi #define OT_TCP_LISTENER_TCB_NUM_PTR 3 /** - * This structure represents a TCP listener. + * Represents a TCP listener. * * A TCP listener is used to listen for and accept incoming TCP connections. * @@ -681,7 +686,7 @@ struct otTcpListener }; /** - * This structure contains arguments to the otTcpListenerInitialize() function. + * Contains arguments to the otTcpListenerInitialize() function. * */ typedef struct otTcpListenerInitializeArgs diff --git a/openthread/include/openthread/tcp_ext.h b/openthread/include/openthread/tcp_ext.h index 0258ac28bf..9ac705b9f1 100644 --- a/openthread/include/openthread/tcp_ext.h +++ b/openthread/include/openthread/tcp_ext.h @@ -53,7 +53,7 @@ extern "C" { */ /** - * This structure represents a circular send buffer for use with a TCP endpoint. + * Represents a circular send buffer for use with a TCP endpoint. * * Using a circular send buffer is optional. Applications can use a TCP * endpoint to send data by managing otLinkedBuffers directly. However, some @@ -108,7 +108,7 @@ typedef struct otTcpCircularSendBuffer void otTcpCircularSendBufferInitialize(otTcpCircularSendBuffer *aSendBuffer, void *aDataBuffer, size_t aCapacity); /** - * This enumeration defines flags passed to @p otTcpCircularSendBufferWrite. + * Defines flags passed to @p otTcpCircularSendBufferWrite. * */ enum diff --git a/openthread/include/openthread/thread.h b/openthread/include/openthread/thread.h index e541648e94..cb0d6bda24 100644 --- a/openthread/include/openthread/thread.h +++ b/openthread/include/openthread/thread.h @@ -74,7 +74,7 @@ typedef enum } otDeviceRole; /** - * This structure represents an MLE Link Mode configuration. + * Represents an MLE Link Mode configuration. */ typedef struct otLinkModeConfig { @@ -84,13 +84,14 @@ typedef struct otLinkModeConfig } otLinkModeConfig; /** - * This structure holds diagnostic information for a neighboring Thread node + * Holds diagnostic information for a neighboring Thread node * */ typedef struct { otExtAddress mExtAddress; ///< IEEE 802.15.4 Extended Address - uint32_t mAge; ///< Time last heard + uint32_t mAge; ///< Seconds since last heard + uint32_t mConnectionTime; ///< Seconds since link establishment (requires `CONFIG_UPTIME_ENABLE`) uint16_t mRloc16; ///< RLOC16 uint32_t mLinkFrameCounter; ///< Link Frame Counter uint32_t mMleFrameCounter; ///< MLE Frame Counter @@ -112,7 +113,7 @@ typedef struct typedef int16_t otNeighborInfoIterator; ///< Used to iterate through neighbor table. /** - * This structure represents the Thread Leader Data. + * Represents the Thread Leader Data. * */ typedef struct otLeaderData @@ -125,7 +126,7 @@ typedef struct otLeaderData } otLeaderData; /** - * This structure holds diagnostic information for a Thread Router + * Holds diagnostic information for a Thread Router * */ typedef struct @@ -151,7 +152,7 @@ typedef struct } otRouterInfo; /** - * This structure represents the IP level counters. + * Represents the IP level counters. * */ typedef struct otIpCounters @@ -163,7 +164,7 @@ typedef struct otIpCounters } otIpCounters; /** - * This structure represents the Thread MLE counters. + * Represents the Thread MLE counters. * */ typedef struct otMleCounters @@ -202,7 +203,7 @@ typedef struct otMleCounters } otMleCounters; /** - * This structure represents the MLE Parent Response data. + * Represents the MLE Parent Response data. * */ typedef struct otThreadParentResponseInfo @@ -226,7 +227,7 @@ typedef struct otThreadParentResponseInfo typedef void (*otDetachGracefullyCallback)(void *aContext); /** - * This function starts Thread protocol operation. + * Starts Thread protocol operation. * * The interface must be up when calling this function. * @@ -243,7 +244,7 @@ typedef void (*otDetachGracefullyCallback)(void *aContext); otError otThreadSetEnabled(otInstance *aInstance, bool aEnabled); /** - * This function gets the Thread protocol version. + * Gets the Thread protocol version. * * @returns the Thread protocol version. * @@ -251,7 +252,7 @@ otError otThreadSetEnabled(otInstance *aInstance, bool aEnabled); uint16_t otThreadGetVersion(void); /** - * This function indicates whether a node is the only router on the network. + * Indicates whether a node is the only router on the network. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -262,7 +263,9 @@ uint16_t otThreadGetVersion(void); bool otThreadIsSingleton(otInstance *aInstance); /** - * This function starts a Thread Discovery scan. + * Starts a Thread Discovery scan. + * + * @note A successful call to this function enables the rx-on-when-idle mode for the entire scan procedure. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aScanChannels A bit vector indicating which channels to scan (e.g. OT_CHANNEL_11_MASK). @@ -288,7 +291,7 @@ otError otThreadDiscover(otInstance *aInstance, void *aCallbackContext); /** - * This function determines if an MLE Thread Discovery is currently in progress. + * Determines if an MLE Thread Discovery is currently in progress. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -296,7 +299,7 @@ otError otThreadDiscover(otInstance *aInstance, bool otThreadIsDiscoverInProgress(otInstance *aInstance); /** - * This method sets the Thread Joiner Advertisement when discovering Thread network. + * Sets the Thread Joiner Advertisement when discovering Thread network. * * Thread Joiner Advertisement is used to allow a Joiner to advertise its own application-specific information * (such as Vendor ID, Product ID, Discriminator, etc.) via a newly-proposed Joiner Advertisement TLV, @@ -373,7 +376,7 @@ const otExtendedPanId *otThreadGetExtendedPanId(otInstance *aInstance); otError otThreadSetExtendedPanId(otInstance *aInstance, const otExtendedPanId *aExtendedPanId); /** - * This function returns a pointer to the Leader's RLOC. + * Returns a pointer to the Leader's RLOC. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[out] aLeaderRloc A pointer to the Leader's RLOC. @@ -414,7 +417,7 @@ otError otThreadSetLinkMode(otInstance *aInstance, otLinkModeConfig aConfig); * Get the Thread Network Key. * * @param[in] aInstance A pointer to an OpenThread instance. - * @param[out] aNetworkKey A pointer to an `otNetworkkey` to return the Thread Network Key. + * @param[out] aNetworkKey A pointer to an `otNetworkKey` to return the Thread Network Key. * * @sa otThreadSetNetworkKey * @@ -424,7 +427,7 @@ void otThreadGetNetworkKey(otInstance *aInstance, otNetworkKey *aNetworkKey); /** * Get the `otNetworkKeyRef` for Thread Network Key. * - * This function requires the build-time feature `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` to be enabled. + * Requires the build-time feature `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` to be enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -438,7 +441,7 @@ otNetworkKeyRef otThreadGetNetworkKeyRef(otInstance *aInstance); /** * Set the Thread Network Key. * - * This function succeeds only when Thread protocols are disabled. A successful + * Succeeds only when Thread protocols are disabled. A successful * call to this function invalidates the Active and Pending Operational Datasets in * non-volatile memory. * @@ -456,11 +459,11 @@ otError otThreadSetNetworkKey(otInstance *aInstance, const otNetworkKey *aKey); /** * Set the Thread Network Key as a `otNetworkKeyRef`. * - * This function succeeds only when Thread protocols are disabled. A successful + * Succeeds only when Thread protocols are disabled. A successful * call to this function invalidates the Active and Pending Operational Datasets in * non-volatile memory. * - * This function requires the build-time feature `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` to be enabled. + * Requires the build-time feature `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` to be enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aKeyRef Reference to the Thread Network Key. @@ -494,7 +497,7 @@ const otIp6Address *otThreadGetRloc(otInstance *aInstance); const otIp6Address *otThreadGetMeshLocalEid(otInstance *aInstance); /** - * This function returns a pointer to the Mesh Local Prefix. + * Returns a pointer to the Mesh Local Prefix. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -504,9 +507,9 @@ const otIp6Address *otThreadGetMeshLocalEid(otInstance *aInstance); const otMeshLocalPrefix *otThreadGetMeshLocalPrefix(otInstance *aInstance); /** - * This function sets the Mesh Local Prefix. + * Sets the Mesh Local Prefix. * - * This function succeeds only when Thread protocols are disabled. A successful + * Succeeds only when Thread protocols are disabled. A successful * call to this function invalidates the Active and Pending Operational Datasets in * non-volatile memory. * @@ -566,7 +569,7 @@ const otIp6Address *otThreadGetLinkLocalAllThreadNodesMulticastAddress(otInstanc const otIp6Address *otThreadGetRealmLocalAllThreadNodesMulticastAddress(otInstance *aInstance); /** - * This function retrieves the Service ALOC for given Service ID. + * Retrieves the Service ALOC for given Service ID. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aServiceId Service ID to get ALOC for. @@ -592,7 +595,7 @@ const char *otThreadGetNetworkName(otInstance *aInstance); /** * Set the Thread Network Name. * - * This function succeeds only when Thread protocols are disabled. A successful + * Succeeds only when Thread protocols are disabled. A successful * call to this function invalidates the Active and Pending Operational Datasets in * non-volatile memory. * @@ -748,7 +751,7 @@ otError otThreadBecomeDetached(otInstance *aInstance); otError otThreadBecomeChild(otInstance *aInstance); /** - * This function gets the next neighbor information. It is used to go through the entries of + * Gets the next neighbor information. It is used to go through the entries of * the neighbor table. * * @param[in] aInstance A pointer to an OpenThread instance. @@ -788,7 +791,7 @@ otDeviceRole otThreadGetDeviceRole(otInstance *aInstance); const char *otThreadDeviceRoleToString(otDeviceRole aRole); /** - * This function get the Thread Leader Data. + * Get the Thread Leader Data. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[out] aLeaderData A pointer to where the leader data is placed. @@ -899,6 +902,63 @@ const otIpCounters *otThreadGetIp6Counters(otInstance *aInstance); */ void otThreadResetIp6Counters(otInstance *aInstance); +/** + * Gets the time-in-queue histogram for messages in the TX queue. + * + * Requires `OPENTHREAD_CONFIG_TX_QUEUE_STATISTICS_ENABLE`. + * + * Histogram of the time-in-queue of messages in the transmit queue is collected. The time-in-queue is tracked for + * direct transmissions only and is measured as the duration from when a message is added to the transmit queue until + * it is passed to the MAC layer for transmission or dropped. + * + * The histogram is returned as an array of `uint32_t` values with `aNumBins` entries. The first entry in the array + * (at index 0) represents the number of messages with a time-in-queue less than `aBinInterval`. The second entry + * represents the number of messages with a time-in-queue greater than or equal to `aBinInterval`, but less than + * `2 * aBinInterval`. And so on. The last entry represents the number of messages with time-in-queue greater than or + * equal to `(aNumBins - 1) * aBinInterval`. + * + * The collected statistics can be reset by calling `otThreadResetTimeInQueueStat()`. The histogram information is + * collected since the OpenThread instance was initialized or since the last time statistics collection was reset by + * calling the `otThreadResetTimeInQueueStat()`. + * + * Pointers @p aNumBins and @p aBinInterval MUST NOT be NULL. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[out] aNumBins Pointer to return the number of bins in histogram (array length). + * @param[out] aBinInterval Pointer to return the histogram bin interval length in milliseconds. + * + * @returns A pointer to an array of @p aNumBins entries representing the collected histogram info. + * + */ +const uint32_t *otThreadGetTimeInQueueHistogram(otInstance *aInstance, uint16_t *aNumBins, uint32_t *aBinInterval); + +/** + * Gets the maximum time-in-queue for messages in the TX queue. + * + * Requires `OPENTHREAD_CONFIG_TX_QUEUE_STATISTICS_ENABLE`. + * + * The time-in-queue is tracked for direct transmissions only and is measured as the duration from when a message is + * added to the transmit queue until it is passed to the MAC layer for transmission or dropped. + * + * The collected statistics can be reset by calling `otThreadResetTimeInQueueStat()`. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * + * @returns The maximum time-in-queue in milliseconds for all messages in the TX queue (so far). + * + */ +uint32_t otThreadGetMaxTimeInQueue(otInstance *aInstance); + +/** + * Resets the TX queue time-in-queue statistics. + * + * Requires `OPENTHREAD_CONFIG_TX_QUEUE_STATISTICS_ENABLE`. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * + */ +void otThreadResetTimeInQueueStat(otInstance *aInstance); + /** * Gets the Thread MLE counters. * @@ -918,7 +978,9 @@ const otMleCounters *otThreadGetMleCounters(otInstance *aInstance); void otThreadResetMleCounters(otInstance *aInstance); /** - * This function pointer is called every time an MLE Parent Response message is received. + * Pointer is called every time an MLE Parent Response message is received. + * + * This is used in `otThreadRegisterParentResponseCallback()`. * * @param[in] aInfo A pointer to a location on stack holding the stats data. * @param[in] aContext A pointer to callback client-specific context. @@ -927,7 +989,9 @@ void otThreadResetMleCounters(otInstance *aInstance); typedef void (*otThreadParentResponseCallback)(otThreadParentResponseInfo *aInfo, void *aContext); /** - * This function registers a callback to receive MLE Parent Response data. + * Registers a callback to receive MLE Parent Response data. + * + * Requires `OPENTHREAD_CONFIG_MLE_PARENT_RESPONSE_CALLBACK_API_ENABLE`. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aCallback A pointer to a function that is called upon receiving an MLE Parent Response message. @@ -939,7 +1003,7 @@ void otThreadRegisterParentResponseCallback(otInstance *aInst void *aContext); /** - * This structure represents the Thread Discovery Request data. + * Represents the Thread Discovery Request data. * */ typedef struct otThreadDiscoveryRequestInfo @@ -950,7 +1014,7 @@ typedef struct otThreadDiscoveryRequestInfo } otThreadDiscoveryRequestInfo; /** - * This function pointer is called every time an MLE Discovery Request message is received. + * Pointer is called every time an MLE Discovery Request message is received. * * @param[in] aInfo A pointer to the Discovery Request info data. * @param[in] aContext A pointer to callback application-specific context. @@ -959,7 +1023,7 @@ typedef struct otThreadDiscoveryRequestInfo typedef void (*otThreadDiscoveryRequestCallback)(const otThreadDiscoveryRequestInfo *aInfo, void *aContext); /** - * This function sets a callback to receive MLE Discovery Request data. + * Sets a callback to receive MLE Discovery Request data. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aCallback A pointer to a function that is called upon receiving an MLE Discovery Request message. @@ -971,7 +1035,7 @@ void otThreadSetDiscoveryRequestCallback(otInstance *aInsta void *aContext); /** - * This function pointer type defines the callback to notify the outcome of a `otThreadLocateAnycastDestination()` + * Pointer type defines the callback to notify the outcome of a `otThreadLocateAnycastDestination()` * request. * * @param[in] aContext A pointer to an arbitrary context (provided when callback is registered). @@ -989,9 +1053,9 @@ typedef void (*otThreadAnycastLocatorCallback)(void *aContext, uint16_t aRloc16); /** - * This function requests the closest destination of a given anycast address to be located. + * Requests the closest destination of a given anycast address to be located. * - * This function is only available when `OPENTHREAD_CONFIG_TMF_ANYCAST_LOCATOR_ENABLE` is enabled. + * Is only available when `OPENTHREAD_CONFIG_TMF_ANYCAST_LOCATOR_ENABLE` is enabled. * * If a previous request is ongoing, a subsequent call to this function will cancel and replace the earlier request. * @@ -1011,9 +1075,9 @@ otError otThreadLocateAnycastDestination(otInstance *aInstanc void *aContext); /** - * This function indicates whether an anycast locate request is currently in progress. + * Indicates whether an anycast locate request is currently in progress. * - * This function is only available when `OPENTHREAD_CONFIG_TMF_ANYCAST_LOCATOR_ENABLE` is enabled. + * Is only available when `OPENTHREAD_CONFIG_TMF_ANYCAST_LOCATOR_ENABLE` is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -1023,9 +1087,9 @@ otError otThreadLocateAnycastDestination(otInstance *aInstanc bool otThreadIsAnycastLocateInProgress(otInstance *aInstance); /** - * This function sends a Proactive Address Notification (ADDR_NTF.ntf) message. + * Sends a Proactive Address Notification (ADDR_NTF.ntf) message. * - * This function is only available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. + * Is only available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aDestination The destination to send the ADDR_NTF.ntf message. @@ -1039,9 +1103,9 @@ void otThreadSendAddressNotification(otInstance *aInstance, otIp6InterfaceIdentifier *aMlIid); /** - * This function sends a Proactive Backbone Notification (PRO_BB.ntf) message on the Backbone link. + * Sends a Proactive Backbone Notification (PRO_BB.ntf) message on the Backbone link. * - * This function is only available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. + * Is only available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aTarget The target address of the PRO_BB.ntf message. @@ -1058,7 +1122,7 @@ otError otThreadSendProactiveBackboneNotification(otInstance *aIns uint32_t aTimeSinceLastTransaction); /** - * This function notifies other nodes in the network (if any) and then stops Thread protocol operation. + * Notifies other nodes in the network (if any) and then stops Thread protocol operation. * * It sends an Address Release if it's a router, or sets its child timeout to 0 if it's a child. * @@ -1072,6 +1136,28 @@ otError otThreadSendProactiveBackboneNotification(otInstance *aIns */ otError otThreadDetachGracefully(otInstance *aInstance, otDetachGracefullyCallback aCallback, void *aContext); +#define OT_DURATION_STRING_SIZE 21 ///< Recommended size for string representation of `uint32_t` duration in seconds. + +/** + * Converts an `uint32_t` duration (in seconds) to a human-readable string. + * + * Requires `OPENTHREAD_CONFIG_UPTIME_ENABLE` to be enabled. + * + * The string follows the format "::" for hours, minutes, seconds (if duration is shorter than one day) or + * "
d.::" (if longer than a day). + * + * If the resulting string does not fit in @p aBuffer (within its @p aSize characters), the string will be truncated + * but the outputted string is always null-terminated. + * + * Is intended for use with `mAge` or `mConnectionTime` in `otNeighborInfo` or `otChildInfo` structures. + * + * @param[in] aDuration A duration interval in seconds. + * @param[out] aBuffer A pointer to a char array to output the string. + * @param[in] aSize The size of @p aBuffer (in bytes). Recommended to use `OT_DURATION_STRING_SIZE`. + * + */ +void otConvertDurationInSecondsToString(uint32_t aDuration, char *aBuffer, uint16_t aSize); + /** * @} * diff --git a/openthread/include/openthread/thread_ftd.h b/openthread/include/openthread/thread_ftd.h index 994ab48511..0928acc88a 100644 --- a/openthread/include/openthread/thread_ftd.h +++ b/openthread/include/openthread/thread_ftd.h @@ -51,14 +51,15 @@ extern "C" { */ /** - * This structure holds diagnostic information for a Thread Child + * Holds diagnostic information for a Thread Child * */ typedef struct { otExtAddress mExtAddress; ///< IEEE 802.15.4 Extended Address uint32_t mTimeout; ///< Timeout - uint32_t mAge; ///< Time last heard + uint32_t mAge; ///< Seconds since last heard + uint64_t mConnectionTime; ///< Seconds since attach (requires `OPENTHREAD_CONFIG_UPTIME_ENABLE`) uint16_t mRloc16; ///< RLOC16 uint16_t mChildId; ///< Child ID uint8_t mNetworkDataVersion; ///< Network Data Version @@ -68,6 +69,7 @@ typedef struct uint16_t mFrameErrorRate; ///< Frame error rate (0xffff->100%). Requires error tracking feature. uint16_t mMessageErrorRate; ///< (IPv6) msg error rate (0xffff->100%). Requires error tracking feature. uint16_t mQueuedMessageCnt; ///< Number of queued messages for the child. + uint16_t mSupervisionInterval; ///< Supervision interval (in seconds). uint8_t mVersion; ///< MLE version bool mRxOnWhenIdle : 1; ///< rx-on-when-idle bool mFullThreadDevice : 1; ///< Full Thread Device @@ -81,7 +83,7 @@ typedef struct typedef uint16_t otChildIp6AddressIterator; ///< Used to iterate through IPv6 addresses of a Thread Child entry. /** - * This enumeration defines the EID cache entry state. + * Defines the EID cache entry state. * */ typedef enum otCacheEntryState @@ -93,7 +95,7 @@ typedef enum otCacheEntryState } otCacheEntryState; /** - * This structure represents an EID cache entry. + * Represents an EID cache entry. * */ typedef struct otCacheEntryInfo @@ -102,6 +104,7 @@ typedef struct otCacheEntryInfo otShortAddress mRloc16; ///< RLOC16 otCacheEntryState mState; ///< Entry state bool mCanEvict : 1; ///< Indicates whether the entry can be evicted. + bool mRampDown : 1; ///< Whether in ramp-down mode while in `OT_CACHE_ENTRY_STATE_RETRY_QUERY`. bool mValidLastTrans : 1; ///< Indicates whether last transaction time and ML-EID are valid. uint32_t mLastTransTime; ///< Last transaction time (applicable in cached state). otIp6Address mMeshLocalEid; ///< Mesh Local EID (applicable if entry in cached state). @@ -110,7 +113,7 @@ typedef struct otCacheEntryInfo } otCacheEntryInfo; /** - * This type represents an iterator used for iterating through the EID cache table entries. + * Represents an iterator used for iterating through the EID cache table entries. * * To initialize the iterator and start from the first entry in the cache table, set all its fields in the structure to * zero (e.g., `memset` the iterator to zero). @@ -151,7 +154,7 @@ uint16_t otThreadGetMaxAllowedChildren(otInstance *aInstance); otError otThreadSetMaxAllowedChildren(otInstance *aInstance, uint16_t aMaxChildren); /** - * This method indicates whether or not the device is router-eligible. + * Indicates whether or not the device is router-eligible. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -162,7 +165,7 @@ otError otThreadSetMaxAllowedChildren(otInstance *aInstance, uint16_t aMaxChildr bool otThreadIsRouterEligible(otInstance *aInstance); /** - * This function sets whether or not the device is router-eligible. + * Sets whether or not the device is router-eligible. * * If @p aEligible is false and the device is currently operating as a router, this call will cause the device to * detach and attempt to reattach as a child. @@ -195,6 +198,63 @@ otError otThreadSetRouterEligible(otInstance *aInstance, bool aEligible); */ otError otThreadSetPreferredRouterId(otInstance *aInstance, uint8_t aRouterId); +/** + * Represents the power supply property on a device. + * + * This is used as a property in `otDeviceProperties` to calculate the leader weight. + * + */ +typedef enum +{ + OT_POWER_SUPPLY_BATTERY = 0, ///< Battery powered. + OT_POWER_SUPPLY_EXTERNAL = 1, ///< Externally powered (mains-powered). + OT_POWER_SUPPLY_EXTERNAL_STABLE = 2, ///< Stable external power with a battery backup or UPS. + OT_POWER_SUPPLY_EXTERNAL_UNSTABLE = 3, ///< Potentially unstable ext power (e.g. light bulb powered via a switch). +} otPowerSupply; + +/** + * Represents the device properties which are used for calculating the local leader weight on a + * device. + * + * The parameters are set based on device's capability, whether acting as border router, its power supply config, etc. + * + * `mIsUnstable` indicates operational stability of device and is determined via a vendor specific mechanism. It can + * include the following cases: + * - Device internally detects that it loses external power supply more often than usual. What is usual is + * determined by the vendor. + * - Device internally detects that it reboots more often than usual. What is usual is determined by the vendor. + * + */ +typedef struct otDeviceProperties +{ + otPowerSupply mPowerSupply; ///< Power supply config. + bool mIsBorderRouter : 1; ///< Whether device is a border router. + bool mSupportsCcm : 1; ///< Whether device supports CCM (can act as a CCM border router). + bool mIsUnstable : 1; ///< Operational stability of device (vendor specific). + int8_t mLeaderWeightAdjustment; ///< Weight adjustment. Should be -16 to +16 (clamped otherwise). +} otDeviceProperties; + +/** + * Get the current device properties. + * + * Requires `OPENTHREAD_CONFIG_MLE_DEVICE_PROPERTY_LEADER_WEIGHT_ENABLE`. + * + * @returns The device properties `otDeviceProperties`. + * + */ +const otDeviceProperties *otThreadGetDeviceProperties(otInstance *aInstance); + +/** + * Set the device properties which are then used to determine and set the Leader Weight. + * + * Requires `OPENTHREAD_CONFIG_MLE_DEVICE_PROPERTY_LEADER_WEIGHT_ENABLE`. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aDeviceProperties The device properties. + * + */ +void otThreadSetDeviceProperties(otInstance *aInstance, const otDeviceProperties *aDeviceProperties); + /** * Gets the Thread Leader Weight used when operating in the Leader role. * @@ -203,6 +263,7 @@ otError otThreadSetPreferredRouterId(otInstance *aInstance, uint8_t aRouterId); * @returns The Thread Leader Weight value. * * @sa otThreadSetLeaderWeight + * @sa otThreadSetDeviceProperties * */ uint8_t otThreadGetLocalLeaderWeight(otInstance *aInstance); @@ -210,6 +271,9 @@ uint8_t otThreadGetLocalLeaderWeight(otInstance *aInstance); /** * Sets the Thread Leader Weight used when operating in the Leader role. * + * Directly sets the Leader Weight to the new value, replacing its previous value (which may have been + * determined from the current `otDeviceProperties`). + * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aWeight The Thread Leader Weight value. * @@ -304,14 +368,14 @@ uint32_t otThreadGetContextIdReuseDelay(otInstance *aInstance); void otThreadSetContextIdReuseDelay(otInstance *aInstance, uint32_t aDelay); /** - * Get the NETWORK_ID_TIMEOUT parameter used in the Router role. + * Get the `NETWORK_ID_TIMEOUT` parameter. * * @note This API is reserved for testing and demo purposes only. Changing settings with * this API will render a production application non-compliant with the Thread Specification. * * @param[in] aInstance A pointer to an OpenThread instance. * - * @returns The NETWORK_ID_TIMEOUT value. + * @returns The `NETWORK_ID_TIMEOUT` value. * * @sa otThreadSetNetworkIdTimeout * @@ -319,10 +383,13 @@ void otThreadSetContextIdReuseDelay(otInstance *aInstance, uint32_t aDelay); uint8_t otThreadGetNetworkIdTimeout(otInstance *aInstance); /** - * Set the NETWORK_ID_TIMEOUT parameter used in the Leader role. + * Set the `NETWORK_ID_TIMEOUT` parameter. + * + * @note This API is reserved for testing and demo purposes only. Changing settings with + * this API will render a production application non-compliant with the Thread Specification. * * @param[in] aInstance A pointer to an OpenThread instance. - * @param[in] aTimeout The NETWORK_ID_TIMEOUT value. + * @param[in] aTimeout The `NETWORK_ID_TIMEOUT` value. * * @sa otThreadGetNetworkIdTimeout * @@ -511,7 +578,7 @@ otError otThreadGetChildInfoById(otInstance *aInstance, uint16_t aChildId, otChi otError otThreadGetChildInfoByIndex(otInstance *aInstance, uint16_t aChildIndex, otChildInfo *aChildInfo); /** - * This function gets the next IPv6 address (using an iterator) for a given child. + * Gets the next IPv6 address (using an iterator) for a given child. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aChildIndex The child index. @@ -567,7 +634,7 @@ uint8_t otThreadGetMaxRouterId(otInstance *aInstance); otError otThreadGetRouterInfo(otInstance *aInstance, uint16_t aRouterId, otRouterInfo *aRouterInfo); /** - * This function gets the next EID cache entry (using an iterator). + * Gets the next EID cache entry (using an iterator). * * @param[in] aInstance A pointer to an OpenThread instance. * @param[out] aEntryInfo A pointer to where the EID cache entry information is placed. @@ -595,7 +662,7 @@ void otThreadGetPskc(otInstance *aInstance, otPskc *aPskc); /** * Get Key Reference to Thread PSKc stored * - * This function requires the build-time feature `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` to be enabled. + * Requires the build-time feature `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` to be enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -609,7 +676,7 @@ otPskcRef otThreadGetPskcRef(otInstance *aInstance); /** * Set the Thread PSKc * - * This function will only succeed when Thread protocols are disabled. A successful + * Will only succeed when Thread protocols are disabled. A successful * call to this function will also invalidate the Active and Pending Operational Datasets in * non-volatile memory. * @@ -625,12 +692,12 @@ otPskcRef otThreadGetPskcRef(otInstance *aInstance); otError otThreadSetPskc(otInstance *aInstance, const otPskc *aPskc); /** - * Set the Thread PSKc + * Set the Key Reference to the Thread PSKc * - * This function requires the build-time feature `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` to be enabled. + * Requires the build-time feature `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` to be enabled. * - * This function will only succeed when Thread protocols are disabled. A successful - * call to this function will also invalidate the Active and Pending Operational Datasets in + * Will only succeed when Thread protocols are disabled. Upon success, + * this will also invalidate the Active and Pending Operational Datasets in * non-volatile memory. * * @param[in] aInstance A pointer to an OpenThread instance. @@ -709,7 +776,7 @@ uint8_t otThreadGetMaxChildIpAddresses(otInstance *aInstance); otError otThreadSetMaxChildIpAddresses(otInstance *aInstance, uint8_t aMaxIpAddresses); /** - * This enumeration defines the constants used in `otNeighborTableCallback` to indicate changes in neighbor table. + * Defines the constants used in `otNeighborTableCallback` to indicate changes in neighbor table. * */ typedef enum @@ -722,7 +789,7 @@ typedef enum } otNeighborTableEvent; /** - * This type represent a neighbor table entry info (child or router) and is used as a parameter in the neighbor table + * Represent a neighbor table entry info (child or router) and is used as a parameter in the neighbor table * callback `otNeighborTableCallback`. * */ @@ -737,7 +804,7 @@ typedef struct } otNeighborTableEntryInfo; /** - * This function pointer is called to notify that there is a change in the neighbor table. + * Pointer is called to notify that there is a change in the neighbor table. * * @param[in] aEvent A event flag. * @param[in] aEntryInfo A pointer to table entry info. @@ -746,7 +813,7 @@ typedef struct typedef void (*otNeighborTableCallback)(otNeighborTableEvent aEvent, const otNeighborTableEntryInfo *aEntryInfo); /** - * This function registers a neighbor table callback function. + * Registers a neighbor table callback function. * * The provided callback (if non-NULL) will be invoked when there is a change in the neighbor table (e.g., a child or a * router neighbor entry is being added/removed or an existing child's mode is changed). @@ -761,7 +828,7 @@ typedef void (*otNeighborTableCallback)(otNeighborTableEvent aEvent, const otNei void otThreadRegisterNeighborTableCallback(otInstance *aInstance, otNeighborTableCallback aCallback); /** - * This function sets whether the device was commissioned using CCM. + * Sets whether the device was commissioned using CCM. * * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used by Thread Test Harness * to indicate whether this device was commissioned using CCM. @@ -773,7 +840,7 @@ void otThreadRegisterNeighborTableCallback(otInstance *aInstance, otNeighborTabl void otThreadSetCcmEnabled(otInstance *aInstance, bool aEnabled); /** - * This function sets whether the Security Policy TLV version-threshold for routing (VR field) is enabled. + * Sets whether the Security Policy TLV version-threshold for routing (VR field) is enabled. * * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used by Thread Test Harness * to indicate that thread protocol version check VR should be skipped. @@ -785,7 +852,7 @@ void otThreadSetCcmEnabled(otInstance *aInstance, bool aEnabled); void otThreadSetThreadVersionCheckEnabled(otInstance *aInstance, bool aEnabled); /** - * This function gets the range of router IDs that are allowed to assign to nodes within the thread network. + * Gets the range of router IDs that are allowed to assign to nodes within the thread network. * * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used for test purpose. All the * router IDs in the range [aMinRouterId, aMaxRouterId] are allowed. @@ -800,7 +867,7 @@ void otThreadSetThreadVersionCheckEnabled(otInstance *aInstance, bool aEnabled); void otThreadGetRouterIdRange(otInstance *aInstance, uint8_t *aMinRouterId, uint8_t *aMaxRouterId); /** - * This function sets the range of router IDs that are allowed to assign to nodes within the thread network. + * Sets the range of router IDs that are allowed to assign to nodes within the thread network. * * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used for test purpose. All the * router IDs in the range [aMinRouterId, aMaxRouterId] are allowed. @@ -818,7 +885,17 @@ void otThreadGetRouterIdRange(otInstance *aInstance, uint8_t *aMinRouterId, uint otError otThreadSetRouterIdRange(otInstance *aInstance, uint8_t aMinRouterId, uint8_t aMaxRouterId); /** - * This function indicates whether or not a Router ID is currently allocated. + * Gets the current Interval Max value used by Advertisement trickle timer. + * + * This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is intended for testing only. + * + * @returns The Interval Max of Advertisement trickle timer in milliseconds. + * + */ +uint32_t otThreadGetAdvertisementTrickleIntervalMax(otInstance *aInstance); + +/** + * Indicates whether or not a Router ID is currently allocated. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aRouterId The router ID to check. @@ -830,13 +907,13 @@ otError otThreadSetRouterIdRange(otInstance *aInstance, uint8_t aMinRouterId, ui bool otThreadIsRouterIdAllocated(otInstance *aInstance, uint8_t aRouterId); /** - * This function gets the next hop and path cost towards a given RLOC16 destination. + * Gets the next hop and path cost towards a given RLOC16 destination. * - * This function can be used with either @p aNextHopRloc16 or @p aPathCost being NULL indicating caller does not want + * Can be used with either @p aNextHopRloc16 or @p aPathCost being NULL indicating caller does not want * to get the value. * * @param[in] aInstance A pointer to an OpenThread instance. - * @param[in] aDesRloct16 The RLOC16 of destination. + * @param[in] aDestRloc16 The RLOC16 of destination. * @param[out] aNextHopRloc16 A pointer to return RLOC16 of next hop, 0xfffe if no next hop. * @param[out] aPathCost A pointer to return path cost towards destination. * diff --git a/openthread/include/openthread/trel.h b/openthread/include/openthread/trel.h index 6e26e83c71..2358ea26a1 100644 --- a/openthread/include/openthread/trel.h +++ b/openthread/include/openthread/trel.h @@ -57,7 +57,7 @@ extern "C" { */ /** - * This struct represents a TREL peer. + * Represents a TREL peer. * */ typedef struct otTrelPeer @@ -68,7 +68,7 @@ typedef struct otTrelPeer } otTrelPeer; /** - * This type represents an iterator for iterating over TREL peer table entries. + * Represents an iterator for iterating over TREL peer table entries. * */ typedef uint16_t otTrelPeerIterator; @@ -93,34 +93,18 @@ typedef uint16_t otTrelPeerIterator; void otTrelSetEnabled(otInstance *aInstance, bool aEnable); /** - * This function enables TREL operation. - * - * This function initiates an ongoing DNS-SD browse on the service name "_trel._udp" within the local browsing domain - * to discover other devices supporting TREL. Device also registers a new service to be advertised using DNS-SD, - * with the service name is "_trel._udp" indicating its support for TREL. Device is then ready to receive TREL messages - * from peers. - * - * @note By default the OpenThread stack enables the TREL operation on start. + * Indicates whether the TREL operation is enabled. * * @param[in] aInstance The OpenThread instance. * - */ -void otTrelEnable(otInstance *aInstance); - -/** - * This function is deprecated. - * - */ -void otTrelDisable(otInstance *aInstance); - -/** - * This function is deprecated. + * @retval TRUE if the TREL operation is enabled. + * @retval FALSE if the TREL operation is disabled. * */ bool otTrelIsEnabled(otInstance *aInstance); /** - * This function initializes a peer table iterator. + * Initializes a peer table iterator. * * @param[in] aInstance The OpenThread instance. * @param[in] aIterator The iterator to initialize. @@ -129,7 +113,7 @@ bool otTrelIsEnabled(otInstance *aInstance); void otTrelInitPeerIterator(otInstance *aInstance, otTrelPeerIterator *aIterator); /** - * This function iterates over the peer table entries and get the next entry from the table + * Iterates over the peer table entries and get the next entry from the table * * @param[in] aInstance The OpenThread instance. * @param[in] aIterator The iterator. MUST be initialized. @@ -140,7 +124,7 @@ void otTrelInitPeerIterator(otInstance *aInstance, otTrelPeerIterator *aIterator const otTrelPeer *otTrelGetNextPeer(otInstance *aInstance, otTrelPeerIterator *aIterator); /** - * This function sets the filter mode (enables/disables filtering). + * Sets the filter mode (enables/disables filtering). * * When filter mode is enabled, any rx and tx traffic through TREL interface is silently dropped. This is mainly * intended for use during testing. @@ -155,7 +139,7 @@ const otTrelPeer *otTrelGetNextPeer(otInstance *aInstance, otTrelPeerIterator *a void otTrelSetFilterEnabled(otInstance *aInstance, bool aEnable); /** - * This function indicates whether or not the filter mode is enabled. + * Indicates whether or not the filter mode is enabled. * * @param[in] aInstance The OpenThread instance. * diff --git a/openthread/include/openthread/udp.h b/openthread/include/openthread/udp.h index 5a2681320b..3512b7bdc1 100644 --- a/openthread/include/openthread/udp.h +++ b/openthread/include/openthread/udp.h @@ -63,7 +63,7 @@ extern "C" { typedef bool (*otUdpHandler)(void *aContext, const otMessage *aMessage, const otMessageInfo *aMessageInfo); /** - * This structure represents a UDP receiver. + * Represents a UDP receiver. * */ typedef struct otUdpReceiver @@ -74,7 +74,7 @@ typedef struct otUdpReceiver } otUdpReceiver; /** - * This function adds a UDP receiver. + * Adds a UDP receiver. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aUdpReceiver A pointer to the UDP receiver. @@ -86,7 +86,7 @@ typedef struct otUdpReceiver otError otUdpAddReceiver(otInstance *aInstance, otUdpReceiver *aUdpReceiver); /** - * This function removes a UDP receiver. + * Removes a UDP receiver. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aUdpReceiver A pointer to the UDP receiver. @@ -98,14 +98,15 @@ otError otUdpAddReceiver(otInstance *aInstance, otUdpReceiver *aUdpReceiver); otError otUdpRemoveReceiver(otInstance *aInstance, otUdpReceiver *aUdpReceiver); /** - * This function sends a UDP message without socket. + * Sends a UDP message without socket. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aMessage A pointer to a message without UDP header. * @param[in] aMessageInfo A pointer to a message info associated with @p aMessage. * - * @retval OT_ERROR_NONE Successfully enqueued the message into an output interface. - * @retval OT_ERROR_NO_BUFS Insufficient available buffer to add the IPv6 headers. + * @retval OT_ERROR_NONE Successfully enqueued the message into an output interface. + * @retval OT_ERROR_NO_BUFS Insufficient available buffer to add the IPv6 headers. + * @retval OT_ERROR_INVALID_ARGS Invalid arguments are given. * */ otError otUdpSendDatagram(otInstance *aInstance, otMessage *aMessage, otMessageInfo *aMessageInfo); @@ -117,7 +118,7 @@ otError otUdpSendDatagram(otInstance *aInstance, otMessage *aMessage, otMessageI typedef void (*otUdpReceive)(void *aContext, otMessage *aMessage, const otMessageInfo *aMessageInfo); /** - * This structure represents a UDP socket. + * Represents a UDP socket. * */ typedef struct otUdpSocket @@ -131,7 +132,7 @@ typedef struct otUdpSocket } otUdpSocket; /** - * This enumeration defines the OpenThread network interface identifiers. + * Defines the OpenThread network interface identifiers. * */ typedef enum otNetifIdentifier @@ -241,7 +242,7 @@ otError otUdpConnect(otInstance *aInstance, otUdpSocket *aSocket, const otSockAd otError otUdpSend(otInstance *aInstance, otUdpSocket *aSocket, otMessage *aMessage, const otMessageInfo *aMessageInfo); /** - * This function gets the head of linked list of UDP Sockets. + * Gets the head of linked list of UDP Sockets. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -269,7 +270,7 @@ otUdpSocket *otUdpGetSockets(otInstance *aInstance); */ /** - * This function pointer delivers the UDP packet to host and host should send the packet through its own network stack. + * Pointer delivers the UDP packet to host and host should send the packet through its own network stack. * * @param[in] aMessage A pointer to the UDP Message. * @param[in] aPeerPort The destination UDP port. diff --git a/openthread/lib/cortex-m33/hard-float/v1.3/ftd/oberon/libopenthread-cli-ftd.a b/openthread/lib/cortex-m33/hard-float/v1.3/ftd/oberon/libopenthread-cli-ftd.a index 392b52e33f..e4f0b28b98 100644 Binary files a/openthread/lib/cortex-m33/hard-float/v1.3/ftd/oberon/libopenthread-cli-ftd.a and b/openthread/lib/cortex-m33/hard-float/v1.3/ftd/oberon/libopenthread-cli-ftd.a differ diff --git a/openthread/lib/cortex-m33/hard-float/v1.3/ftd/oberon/libopenthread-ftd.a b/openthread/lib/cortex-m33/hard-float/v1.3/ftd/oberon/libopenthread-ftd.a index 66549442f0..da92afe21c 100644 Binary files a/openthread/lib/cortex-m33/hard-float/v1.3/ftd/oberon/libopenthread-ftd.a and b/openthread/lib/cortex-m33/hard-float/v1.3/ftd/oberon/libopenthread-ftd.a differ diff --git a/openthread/lib/cortex-m33/hard-float/v1.3/ftd/oberon/nrf_security_mbedtls_configuration.h b/openthread/lib/cortex-m33/hard-float/v1.3/ftd/oberon/nrf_security_mbedtls_configuration.h index 455b3a9abe..d57610250c 100644 --- a/openthread/lib/cortex-m33/hard-float/v1.3/ftd/oberon/nrf_security_mbedtls_configuration.h +++ b/openthread/lib/cortex-m33/hard-float/v1.3/ftd/oberon/nrf_security_mbedtls_configuration.h @@ -17,22 +17,6 @@ * or disable features selectively, and reduce the global * memory footprint. */ -/* - * Copyright The Mbed TLS Contributors - * SPDX-License-Identifier: Apache-2.0 - * - * Licensed under the Apache License, Version 2.0 (the "License"); you may - * not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ /** * This is an optional version symbol that enables comatibility handling of @@ -1082,7 +1066,7 @@ * * Uncomment this macro to let the buffer allocator print out error messages. */ -//#define MBEDTLS_MEMORY_DEBUG +/* #undef MBEDTLS_MEMORY_DEBUG */ /** * \def MBEDTLS_MEMORY_BACKTRACE @@ -1206,7 +1190,7 @@ * * \note This option is experimental and may be removed without notice. */ -/* #undef MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG */ +#define MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG /** * \def MBEDTLS_PSA_CRYPTO_SPM @@ -2705,7 +2689,7 @@ * on it, and considering stronger message digests instead. * */ -#define MBEDTLS_SHA1_C +/* #undef MBEDTLS_SHA1_C */ /** * \def MBEDTLS_SHA224_C @@ -2772,7 +2756,7 @@ * * This module adds support for SHA-512. */ -#define MBEDTLS_SHA512_C +/* #undef MBEDTLS_SHA512_C */ /** * \def MBEDTLS_SSL_CACHE_C @@ -2794,7 +2778,7 @@ * Module: library/ssl_cookie.c * Caller: */ -#define MBEDTLS_SSL_COOKIE_C +/* #undef MBEDTLS_SSL_COOKIE_C */ /** * \def MBEDTLS_SSL_TICKET_C @@ -2834,7 +2818,7 @@ * * This module is required for SSL/TLS server support. */ -#define MBEDTLS_SSL_SRV_C +/* #undef MBEDTLS_SSL_SRV_C */ /** * \def MBEDTLS_SSL_TLS_C @@ -3024,7 +3008,7 @@ /* MPI / BIGNUM options */ #define MBEDTLS_MPI_WINDOW_SIZE 6 /**< Maximum window size used. */ -#define MBEDTLS_MPI_MAX_SIZE 384 /**< Maximum number of bytes for usable MPIs. */ +#define MBEDTLS_MPI_MAX_SIZE 256 /**< Maximum number of bytes for usable MPIs. */ /* CTR_DRBG options */ //#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 48 /**< Amount of entropy used per seed by default (48 with SHA-512, 32 with SHA-256) */ diff --git a/openthread/lib/cortex-m33/hard-float/v1.3/ftd/oberon/openthread_lib_configuration.txt b/openthread/lib/cortex-m33/hard-float/v1.3/ftd/oberon/openthread_lib_configuration.txt index eddc61efbe..0cff43bbde 100644 --- a/openthread/lib/cortex-m33/hard-float/v1.3/ftd/oberon/openthread_lib_configuration.txt +++ b/openthread/lib/cortex-m33/hard-float/v1.3/ftd/oberon/openthread_lib_configuration.txt @@ -1,17 +1,16 @@ -GCC_version: arm-zephyr-eabi-gcc (Zephyr SDK 0.15.2) 12.1.0 +GCC_version: arm-zephyr-eabi-gcc (Zephyr SDK 0.16.1) 12.2.0 -OpenThread_commit=2060039bbfec52ac00f22a7cc3213c2ab1df138e -NRFXLIB_commit=v2.3.0-rc1-7-g0b135cd6 -MBEDTLS_commit=v3.0.0-1594-gc2a205601 +OpenThread_commit=57ef721eeed2550835c528ab7b8e77671f7039d6 +NRFXLIB_commit=v2.5.0-rc2-0-gbbb718ad +MBEDTLS_commit=v3.3.0-ncs2-rc2-0-gacea48fc8 CONFIG_OPENTHREAD_BUILD_OUTPUT_STRIPPED=y CONFIG_OPENTHREAD_CHANNEL=11 -CONFIG_OPENTHREAD_CHILD_SUPERVISION=y CONFIG_OPENTHREAD_CLI_MAX_LINE_LENGTH=384 CONFIG_OPENTHREAD_COAP=y CONFIG_OPENTHREAD_CONFIG_PLATFORM_INFO=Zephyr -CONFIG_OPENTHREAD_CSL_MIN_RECEIVE_ON=5696 -CONFIG_OPENTHREAD_CSL_RECEIVE_TIME_AHEAD=480 +CONFIG_OPENTHREAD_CSL_RECEIVE_TIME_AHEAD=5000 +CONFIG_OPENTHREAD_CSL_TIMEOUT=100 CONFIG_OPENTHREAD_CUSTOM_PARAMETERS= CONFIG_OPENTHREAD_DEFAULT_TX_POWER=0 CONFIG_OPENTHREAD_DHCP6_CLIENT=y @@ -25,31 +24,38 @@ CONFIG_OPENTHREAD_IP6_MAX_EXT_MCAST_ADDRS=2 CONFIG_OPENTHREAD_IP6_MAX_EXT_UCAST_ADDRS=4 CONFIG_OPENTHREAD_JOINER=y CONFIG_OPENTHREAD_L2_LOG_LEVEL=0 +CONFIG_OPENTHREAD_LIBRARY_AVAILABLE=y CONFIG_OPENTHREAD_LINK_METRICS_INITIATOR=y CONFIG_OPENTHREAD_LINK_METRICS_SUBJECT=y CONFIG_OPENTHREAD_LOG_LEVEL=0 CONFIG_OPENTHREAD_MAC_SOFTWARE_ACK_TIMEOUT_ENABLE=y CONFIG_OPENTHREAD_MAC_SOFTWARE_CSMA_BACKOFF_ENABLE=y CONFIG_OPENTHREAD_MAC_SOFTWARE_RETRANSMIT_ENABLE=y +CONFIG_OPENTHREAD_MAC_SOFTWARE_TX_SECURITY_ENABLE=y CONFIG_OPENTHREAD_MANUAL_START=y CONFIG_OPENTHREAD_MAX_CHILDREN=32 CONFIG_OPENTHREAD_MAX_IP_ADDR_PER_CHILD=6 CONFIG_OPENTHREAD_MAX_STATECHANGE_HANDLERS=2 CONFIG_OPENTHREAD_MBEDTLS_LIB_NAME=mbedtls_external CONFIG_OPENTHREAD_MESSAGE_BUFFER_SIZE=128 +CONFIG_OPENTHREAD_MIN_RECEIVE_ON_AFTER=5504 +CONFIG_OPENTHREAD_MIN_RECEIVE_ON_AHEAD=192 CONFIG_OPENTHREAD_MLR=y -CONFIG_OPENTHREAD_MTD_NETDIAG=y +CONFIG_OPENTHREAD_NETDIAG_CLIENT=y CONFIG_OPENTHREAD_NETWORKKEY= CONFIG_OPENTHREAD_NETWORK_NAME=ot_zephyr CONFIG_OPENTHREAD_NORDIC_LIBRARY_FTD=y CONFIG_OPENTHREAD_NRF_SECURITY=y CONFIG_OPENTHREAD_NRF_SECURITY_CHOICE=y CONFIG_OPENTHREAD_NUM_MESSAGE_BUFFERS=128 +CONFIG_OPENTHREAD_OPERATIONAL_DATASET_AUTO_INIT=y CONFIG_OPENTHREAD_PANID=43981 CONFIG_OPENTHREAD_PING_SENDER=y CONFIG_OPENTHREAD_PKT_LIST_SIZE=10 -CONFIG_OPENTHREAD_PLATFORM_CSL_UNCERT=5 +CONFIG_OPENTHREAD_PLATFORM_CSL_UNCERT=12 CONFIG_OPENTHREAD_PLATFORM_INFO=ZEPHYR +CONFIG_OPENTHREAD_POWER_SUPPLY=EXTERNAL +CONFIG_OPENTHREAD_POWER_SUPPLY_EXTERNAL=y CONFIG_OPENTHREAD_RADIO_LINK_IEEE_802_15_4_ENABLE=y CONFIG_OPENTHREAD_RADIO_WORKQUEUE_STACK_SIZE=1084 CONFIG_OPENTHREAD_SHELL=y @@ -62,8 +68,10 @@ CONFIG_OPENTHREAD_THREAD_STACK_SIZE=6240 CONFIG_OPENTHREAD_THREAD_VERSION=1.3 CONFIG_OPENTHREAD_THREAD_VERSION_1_3=y CONFIG_OPENTHREAD_TMF_ADDRESS_CACHE_ENTRIES=20 +CONFIG_OPENTHREAD_UPTIME=y CONFIG_OPENTHREAD_XPANID=de:ad:00:be:ef:00:ca:fe OT_15_4=ON +OT_ANDROID_NDK= OT_ANYCAST_LOCATOR=OFF OT_APP_CLI=ON OT_APP_NCP=ON @@ -73,15 +81,17 @@ OT_BACKBONE_ROUTER=OFF OT_BACKBONE_ROUTER_DUA_NDPROXYING=OFF OT_BACKBONE_ROUTER_MULTICAST_ROUTING=OFF OT_BORDER_AGENT=OFF +OT_BORDER_AGENT_ID= OT_BORDER_ROUTER=OFF OT_BORDER_ROUTING=OFF OT_BORDER_ROUTING_COUNTERS=OFF +OT_BORDER_ROUTING_DHCP6_PD=OFF OT_BUILD_EXECUTABLES=OFF OT_BUILTIN_MBEDTLS_MANAGEMENT=OFF OT_CHANNEL_MANAGER=OFF OT_CHANNEL_MONITOR=OFF -OT_CHILD_SUPERVISION=ON OT_CLI_TRANSPORT=CONSOLE +OT_CLI_VENDOR_EXTENSION= OT_COAP=ON OT_COAPS=OFF OT_COAP_BLOCK=OFF @@ -94,16 +104,18 @@ OT_CSL_AUTO_SYNC=OFF OT_CSL_DEBUG=OFF OT_CSL_RECEIVER=OFF OT_DATASET_UPDATER=OFF +OT_DEVICE_PROP_LEADER_WEIGHT=OFF OT_DHCP6_CLIENT=ON OT_DHCP6_SERVER=OFF OT_DIAGNOSTIC=OFF OT_DNSSD_SERVER=OFF OT_DNS_CLIENT=ON +OT_DNS_CLIENT_OVER_TCP=OFF OT_DNS_DSO=OFF +OT_DNS_UPSTREAM_QUERY=OFF OT_DOC=OFF OT_DUA=ON OT_ECDSA=ON -OT_EXCLUDE_TCPLP_LIB=OFF OT_EXTERNAL_HEAP=ON OT_EXTERNAL_MBEDTLS=mbedtls_external OT_FIREWALL=OFF @@ -115,7 +127,9 @@ OT_IP6_FRAGM=ON OT_JAM_DETECTION=OFF OT_JOINER=ON OT_LEGACY=OFF +OT_LINKER_MAP=ON OT_LINK_METRICS_INITIATOR=ON +OT_LINK_METRICS_MANAGER=OFF OT_LINK_METRICS_SUBJECT=ON OT_LINK_RAW=OFF OT_LOG_LEVEL= @@ -123,12 +137,12 @@ OT_LOG_LEVEL_DYNAMIC=OFF OT_LOG_OUTPUT= OT_MAC_FILTER=OFF OT_MBEDTLS_THREADING=OFF +OT_MESH_DIAG=OFF OT_MESSAGE_USE_HEAP=OFF OT_MLE_LONG_ROUTES=OFF OT_MLE_MAX_CHILDREN= OT_MLR=ON OT_MTD=OFF -OT_MTD_NETDIAG=ON OT_MULTIPLE_INSTANCE=OFF OT_NAT64_BORDER_ROUTING=OFF OT_NAT64_TRANSLATOR=OFF @@ -136,15 +150,20 @@ OT_NCP_SPI=OFF OT_NCP_VENDOR_HOOK_SOURCE= OT_NEIGHBOR_DISCOVERY_AGENT=OFF OT_NETDATA_PUBLISHER=OFF +OT_NETDIAG_CLIENT=ON +OT_OPERATIONAL_DATASET_AUTO_INIT=ON OT_OTNS=OFF OT_PACKAGE_NAME=OPENTHREAD OT_PACKAGE_VERSION= OT_PING_SENDER=ON OT_PLATFORM=zephyr +OT_PLATFORM_CONFIG= OT_PLATFORM_NETIF=OFF OT_PLATFORM_UDP=OFF +OT_POWER_SUPPLY=EXTERNAL +OT_PROJECT_CONFIG= OT_RCP=ON -OT_RCP_RESTORATION_MAX_COUNT=0 +OT_RCP_RESTORATION_MAX_COUNT= OT_REFERENCE_DEVICE=OFF OT_SERVICE=OFF OT_SETTINGS_RAM=OFF @@ -152,10 +171,15 @@ OT_SLAAC=ON OT_SNTP_CLIENT=ON OT_SRP_CLIENT=ON OT_SRP_SERVER=OFF +OT_TCP=OFF OT_THREAD_VERSION=1.3 OT_TIME_SYNC=OFF OT_TREL=OFF OT_TX_BEACON_PAYLOAD=OFF +OT_TX_QUEUE_STATS=OFF OT_UDP_FORWARD=OFF -OT_UPTIME=OFF +OT_UPTIME=ON OT_VENDOR_EXTENSION= +OT_VENDOR_MODEL= +OT_VENDOR_NAME= +OT_VENDOR_SW_VERSION= diff --git a/openthread/lib/cortex-m33/hard-float/v1.3/mtd/oberon/libopenthread-cli-mtd.a b/openthread/lib/cortex-m33/hard-float/v1.3/mtd/oberon/libopenthread-cli-mtd.a index f3a7c2c5c8..80be4a30e5 100644 Binary files a/openthread/lib/cortex-m33/hard-float/v1.3/mtd/oberon/libopenthread-cli-mtd.a and b/openthread/lib/cortex-m33/hard-float/v1.3/mtd/oberon/libopenthread-cli-mtd.a differ diff --git a/openthread/lib/cortex-m33/hard-float/v1.3/mtd/oberon/libopenthread-mtd.a b/openthread/lib/cortex-m33/hard-float/v1.3/mtd/oberon/libopenthread-mtd.a index cc88fc6267..1016267cb2 100644 Binary files a/openthread/lib/cortex-m33/hard-float/v1.3/mtd/oberon/libopenthread-mtd.a and b/openthread/lib/cortex-m33/hard-float/v1.3/mtd/oberon/libopenthread-mtd.a differ diff --git a/openthread/lib/cortex-m33/hard-float/v1.3/mtd/oberon/nrf_security_mbedtls_configuration.h b/openthread/lib/cortex-m33/hard-float/v1.3/mtd/oberon/nrf_security_mbedtls_configuration.h index 455b3a9abe..d57610250c 100644 --- a/openthread/lib/cortex-m33/hard-float/v1.3/mtd/oberon/nrf_security_mbedtls_configuration.h +++ b/openthread/lib/cortex-m33/hard-float/v1.3/mtd/oberon/nrf_security_mbedtls_configuration.h @@ -17,22 +17,6 @@ * or disable features selectively, and reduce the global * memory footprint. */ -/* - * Copyright The Mbed TLS Contributors - * SPDX-License-Identifier: Apache-2.0 - * - * Licensed under the Apache License, Version 2.0 (the "License"); you may - * not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ /** * This is an optional version symbol that enables comatibility handling of @@ -1082,7 +1066,7 @@ * * Uncomment this macro to let the buffer allocator print out error messages. */ -//#define MBEDTLS_MEMORY_DEBUG +/* #undef MBEDTLS_MEMORY_DEBUG */ /** * \def MBEDTLS_MEMORY_BACKTRACE @@ -1206,7 +1190,7 @@ * * \note This option is experimental and may be removed without notice. */ -/* #undef MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG */ +#define MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG /** * \def MBEDTLS_PSA_CRYPTO_SPM @@ -2705,7 +2689,7 @@ * on it, and considering stronger message digests instead. * */ -#define MBEDTLS_SHA1_C +/* #undef MBEDTLS_SHA1_C */ /** * \def MBEDTLS_SHA224_C @@ -2772,7 +2756,7 @@ * * This module adds support for SHA-512. */ -#define MBEDTLS_SHA512_C +/* #undef MBEDTLS_SHA512_C */ /** * \def MBEDTLS_SSL_CACHE_C @@ -2794,7 +2778,7 @@ * Module: library/ssl_cookie.c * Caller: */ -#define MBEDTLS_SSL_COOKIE_C +/* #undef MBEDTLS_SSL_COOKIE_C */ /** * \def MBEDTLS_SSL_TICKET_C @@ -2834,7 +2818,7 @@ * * This module is required for SSL/TLS server support. */ -#define MBEDTLS_SSL_SRV_C +/* #undef MBEDTLS_SSL_SRV_C */ /** * \def MBEDTLS_SSL_TLS_C @@ -3024,7 +3008,7 @@ /* MPI / BIGNUM options */ #define MBEDTLS_MPI_WINDOW_SIZE 6 /**< Maximum window size used. */ -#define MBEDTLS_MPI_MAX_SIZE 384 /**< Maximum number of bytes for usable MPIs. */ +#define MBEDTLS_MPI_MAX_SIZE 256 /**< Maximum number of bytes for usable MPIs. */ /* CTR_DRBG options */ //#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 48 /**< Amount of entropy used per seed by default (48 with SHA-512, 32 with SHA-256) */ diff --git a/openthread/lib/cortex-m33/hard-float/v1.3/mtd/oberon/openthread_lib_configuration.txt b/openthread/lib/cortex-m33/hard-float/v1.3/mtd/oberon/openthread_lib_configuration.txt index ec8671c928..341d3bccf3 100644 --- a/openthread/lib/cortex-m33/hard-float/v1.3/mtd/oberon/openthread_lib_configuration.txt +++ b/openthread/lib/cortex-m33/hard-float/v1.3/mtd/oberon/openthread_lib_configuration.txt @@ -1,19 +1,18 @@ -GCC_version: arm-zephyr-eabi-gcc (Zephyr SDK 0.15.2) 12.1.0 +GCC_version: arm-zephyr-eabi-gcc (Zephyr SDK 0.16.1) 12.2.0 -OpenThread_commit=2060039bbfec52ac00f22a7cc3213c2ab1df138e -NRFXLIB_commit=v2.3.0-rc1-7-g0b135cd6 -MBEDTLS_commit=v3.0.0-1594-gc2a205601 +OpenThread_commit=57ef721eeed2550835c528ab7b8e77671f7039d6 +NRFXLIB_commit=v2.5.0-rc2-0-gbbb718ad +MBEDTLS_commit=v3.3.0-ncs2-rc2-0-gacea48fc8 CONFIG_OPENTHREAD_BUILD_OUTPUT_STRIPPED=y CONFIG_OPENTHREAD_CHANNEL=11 -CONFIG_OPENTHREAD_CHILD_SUPERVISION=y CONFIG_OPENTHREAD_CLI_MAX_LINE_LENGTH=384 CONFIG_OPENTHREAD_COAP=y CONFIG_OPENTHREAD_CONFIG_PLATFORM_INFO=Zephyr CONFIG_OPENTHREAD_CSL_AUTO_SYNC=y -CONFIG_OPENTHREAD_CSL_MIN_RECEIVE_ON=300 CONFIG_OPENTHREAD_CSL_RECEIVER=y CONFIG_OPENTHREAD_CSL_RECEIVE_TIME_AHEAD=5000 +CONFIG_OPENTHREAD_CSL_TIMEOUT=20 CONFIG_OPENTHREAD_CUSTOM_PARAMETERS= CONFIG_OPENTHREAD_DEFAULT_TX_POWER=0 CONFIG_OPENTHREAD_DHCP6_CLIENT=y @@ -26,30 +25,37 @@ CONFIG_OPENTHREAD_IP6_MAX_EXT_MCAST_ADDRS=2 CONFIG_OPENTHREAD_IP6_MAX_EXT_UCAST_ADDRS=4 CONFIG_OPENTHREAD_JOINER=y CONFIG_OPENTHREAD_L2_LOG_LEVEL=0 +CONFIG_OPENTHREAD_LIBRARY_AVAILABLE=y CONFIG_OPENTHREAD_LINK_METRICS_INITIATOR=y CONFIG_OPENTHREAD_LOG_LEVEL=0 CONFIG_OPENTHREAD_MAC_SOFTWARE_ACK_TIMEOUT_ENABLE=y CONFIG_OPENTHREAD_MAC_SOFTWARE_CSMA_BACKOFF_ENABLE=y CONFIG_OPENTHREAD_MAC_SOFTWARE_RETRANSMIT_ENABLE=y +CONFIG_OPENTHREAD_MAC_SOFTWARE_TX_SECURITY_ENABLE=y CONFIG_OPENTHREAD_MANUAL_START=y -CONFIG_OPENTHREAD_MAX_CHILDREN=1 +CONFIG_OPENTHREAD_MAX_CHILDREN=32 CONFIG_OPENTHREAD_MAX_STATECHANGE_HANDLERS=2 CONFIG_OPENTHREAD_MBEDTLS_LIB_NAME=mbedtls_external CONFIG_OPENTHREAD_MESSAGE_BUFFER_SIZE=128 +CONFIG_OPENTHREAD_MIN_RECEIVE_ON_AFTER=0 +CONFIG_OPENTHREAD_MIN_RECEIVE_ON_AHEAD=104 CONFIG_OPENTHREAD_MLR=y CONFIG_OPENTHREAD_MTD=y -CONFIG_OPENTHREAD_MTD_NETDIAG=y +CONFIG_OPENTHREAD_NETDIAG_CLIENT=y CONFIG_OPENTHREAD_NETWORKKEY= CONFIG_OPENTHREAD_NETWORK_NAME=ot_zephyr CONFIG_OPENTHREAD_NORDIC_LIBRARY_MTD=y CONFIG_OPENTHREAD_NRF_SECURITY=y CONFIG_OPENTHREAD_NRF_SECURITY_CHOICE=y CONFIG_OPENTHREAD_NUM_MESSAGE_BUFFERS=128 +CONFIG_OPENTHREAD_OPERATIONAL_DATASET_AUTO_INIT=y CONFIG_OPENTHREAD_PANID=43981 CONFIG_OPENTHREAD_PING_SENDER=y CONFIG_OPENTHREAD_PKT_LIST_SIZE=10 -CONFIG_OPENTHREAD_PLATFORM_CSL_UNCERT=5 +CONFIG_OPENTHREAD_PLATFORM_CSL_UNCERT=12 CONFIG_OPENTHREAD_PLATFORM_INFO=ZEPHYR +CONFIG_OPENTHREAD_POWER_SUPPLY=EXTERNAL +CONFIG_OPENTHREAD_POWER_SUPPLY_EXTERNAL=y CONFIG_OPENTHREAD_RADIO_LINK_IEEE_802_15_4_ENABLE=y CONFIG_OPENTHREAD_RADIO_WORKQUEUE_STACK_SIZE=1084 CONFIG_OPENTHREAD_SHELL=y @@ -64,6 +70,7 @@ CONFIG_OPENTHREAD_THREAD_VERSION_1_3=y CONFIG_OPENTHREAD_TMF_ADDRESS_CACHE_ENTRIES=20 CONFIG_OPENTHREAD_XPANID=de:ad:00:be:ef:00:ca:fe OT_15_4=ON +OT_ANDROID_NDK= OT_ANYCAST_LOCATOR=OFF OT_APP_CLI=ON OT_APP_NCP=ON @@ -73,15 +80,17 @@ OT_BACKBONE_ROUTER=OFF OT_BACKBONE_ROUTER_DUA_NDPROXYING=OFF OT_BACKBONE_ROUTER_MULTICAST_ROUTING=OFF OT_BORDER_AGENT=OFF +OT_BORDER_AGENT_ID= OT_BORDER_ROUTER=OFF OT_BORDER_ROUTING=OFF OT_BORDER_ROUTING_COUNTERS=OFF +OT_BORDER_ROUTING_DHCP6_PD=OFF OT_BUILD_EXECUTABLES=OFF OT_BUILTIN_MBEDTLS_MANAGEMENT=OFF OT_CHANNEL_MANAGER=OFF OT_CHANNEL_MONITOR=OFF -OT_CHILD_SUPERVISION=ON OT_CLI_TRANSPORT=CONSOLE +OT_CLI_VENDOR_EXTENSION= OT_COAP=ON OT_COAPS=OFF OT_COAP_BLOCK=OFF @@ -94,16 +103,18 @@ OT_CSL_AUTO_SYNC=ON OT_CSL_DEBUG=OFF OT_CSL_RECEIVER=ON OT_DATASET_UPDATER=OFF +OT_DEVICE_PROP_LEADER_WEIGHT=OFF OT_DHCP6_CLIENT=ON OT_DHCP6_SERVER=OFF OT_DIAGNOSTIC=OFF OT_DNSSD_SERVER=OFF OT_DNS_CLIENT=ON +OT_DNS_CLIENT_OVER_TCP=OFF OT_DNS_DSO=OFF +OT_DNS_UPSTREAM_QUERY=OFF OT_DOC=OFF OT_DUA=ON OT_ECDSA=ON -OT_EXCLUDE_TCPLP_LIB=OFF OT_EXTERNAL_HEAP=ON OT_EXTERNAL_MBEDTLS=mbedtls_external OT_FIREWALL=OFF @@ -115,7 +126,9 @@ OT_IP6_FRAGM=ON OT_JAM_DETECTION=OFF OT_JOINER=ON OT_LEGACY=OFF +OT_LINKER_MAP=ON OT_LINK_METRICS_INITIATOR=ON +OT_LINK_METRICS_MANAGER=OFF OT_LINK_METRICS_SUBJECT=OFF OT_LINK_RAW=OFF OT_LOG_LEVEL= @@ -123,12 +136,12 @@ OT_LOG_LEVEL_DYNAMIC=OFF OT_LOG_OUTPUT= OT_MAC_FILTER=OFF OT_MBEDTLS_THREADING=OFF +OT_MESH_DIAG=OFF OT_MESSAGE_USE_HEAP=OFF OT_MLE_LONG_ROUTES=OFF OT_MLE_MAX_CHILDREN= OT_MLR=ON OT_MTD=ON -OT_MTD_NETDIAG=ON OT_MULTIPLE_INSTANCE=OFF OT_NAT64_BORDER_ROUTING=OFF OT_NAT64_TRANSLATOR=OFF @@ -136,15 +149,20 @@ OT_NCP_SPI=OFF OT_NCP_VENDOR_HOOK_SOURCE= OT_NEIGHBOR_DISCOVERY_AGENT=OFF OT_NETDATA_PUBLISHER=OFF +OT_NETDIAG_CLIENT=ON +OT_OPERATIONAL_DATASET_AUTO_INIT=ON OT_OTNS=OFF OT_PACKAGE_NAME=OPENTHREAD OT_PACKAGE_VERSION= OT_PING_SENDER=ON OT_PLATFORM=zephyr +OT_PLATFORM_CONFIG= OT_PLATFORM_NETIF=OFF OT_PLATFORM_UDP=OFF +OT_POWER_SUPPLY=EXTERNAL +OT_PROJECT_CONFIG= OT_RCP=ON -OT_RCP_RESTORATION_MAX_COUNT=0 +OT_RCP_RESTORATION_MAX_COUNT= OT_REFERENCE_DEVICE=OFF OT_SERVICE=OFF OT_SETTINGS_RAM=OFF @@ -152,10 +170,15 @@ OT_SLAAC=ON OT_SNTP_CLIENT=ON OT_SRP_CLIENT=ON OT_SRP_SERVER=OFF +OT_TCP=OFF OT_THREAD_VERSION=1.3 OT_TIME_SYNC=OFF OT_TREL=OFF OT_TX_BEACON_PAYLOAD=OFF +OT_TX_QUEUE_STATS=OFF OT_UDP_FORWARD=OFF OT_UPTIME=OFF OT_VENDOR_EXTENSION= +OT_VENDOR_MODEL= +OT_VENDOR_NAME= +OT_VENDOR_SW_VERSION= diff --git a/openthread/lib/cortex-m4/hard-float/v1.3/ftd/oberon/libopenthread-cli-ftd.a b/openthread/lib/cortex-m4/hard-float/v1.3/ftd/oberon/libopenthread-cli-ftd.a index 18ef15b67c..9045ae2346 100644 Binary files a/openthread/lib/cortex-m4/hard-float/v1.3/ftd/oberon/libopenthread-cli-ftd.a and b/openthread/lib/cortex-m4/hard-float/v1.3/ftd/oberon/libopenthread-cli-ftd.a differ diff --git a/openthread/lib/cortex-m4/hard-float/v1.3/ftd/oberon/libopenthread-ftd.a b/openthread/lib/cortex-m4/hard-float/v1.3/ftd/oberon/libopenthread-ftd.a index 2e99a0350d..4877392e43 100644 Binary files a/openthread/lib/cortex-m4/hard-float/v1.3/ftd/oberon/libopenthread-ftd.a and b/openthread/lib/cortex-m4/hard-float/v1.3/ftd/oberon/libopenthread-ftd.a differ diff --git a/openthread/lib/cortex-m4/hard-float/v1.3/ftd/oberon/nrf_security_mbedtls_configuration.h b/openthread/lib/cortex-m4/hard-float/v1.3/ftd/oberon/nrf_security_mbedtls_configuration.h index 398842e99e..06adbc768d 100644 --- a/openthread/lib/cortex-m4/hard-float/v1.3/ftd/oberon/nrf_security_mbedtls_configuration.h +++ b/openthread/lib/cortex-m4/hard-float/v1.3/ftd/oberon/nrf_security_mbedtls_configuration.h @@ -17,22 +17,6 @@ * or disable features selectively, and reduce the global * memory footprint. */ -/* - * Copyright The Mbed TLS Contributors - * SPDX-License-Identifier: Apache-2.0 - * - * Licensed under the Apache License, Version 2.0 (the "License"); you may - * not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ /** * This is an optional version symbol that enables comatibility handling of @@ -1082,7 +1066,7 @@ * * Uncomment this macro to let the buffer allocator print out error messages. */ -//#define MBEDTLS_MEMORY_DEBUG +/* #undef MBEDTLS_MEMORY_DEBUG */ /** * \def MBEDTLS_MEMORY_BACKTRACE @@ -1206,7 +1190,7 @@ * * \note This option is experimental and may be removed without notice. */ -/* #undef MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG */ +#define MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG /** * \def MBEDTLS_PSA_CRYPTO_SPM @@ -2705,7 +2689,7 @@ * on it, and considering stronger message digests instead. * */ -#define MBEDTLS_SHA1_C +/* #undef MBEDTLS_SHA1_C */ /** * \def MBEDTLS_SHA224_C @@ -2772,7 +2756,7 @@ * * This module adds support for SHA-512. */ -#define MBEDTLS_SHA512_C +/* #undef MBEDTLS_SHA512_C */ /** * \def MBEDTLS_SSL_CACHE_C @@ -2794,7 +2778,7 @@ * Module: library/ssl_cookie.c * Caller: */ -#define MBEDTLS_SSL_COOKIE_C +/* #undef MBEDTLS_SSL_COOKIE_C */ /** * \def MBEDTLS_SSL_TICKET_C @@ -2834,7 +2818,7 @@ * * This module is required for SSL/TLS server support. */ -#define MBEDTLS_SSL_SRV_C +/* #undef MBEDTLS_SSL_SRV_C */ /** * \def MBEDTLS_SSL_TLS_C diff --git a/openthread/lib/cortex-m4/hard-float/v1.3/ftd/oberon/openthread_lib_configuration.txt b/openthread/lib/cortex-m4/hard-float/v1.3/ftd/oberon/openthread_lib_configuration.txt index 3db2c525bc..3946d08a4d 100644 --- a/openthread/lib/cortex-m4/hard-float/v1.3/ftd/oberon/openthread_lib_configuration.txt +++ b/openthread/lib/cortex-m4/hard-float/v1.3/ftd/oberon/openthread_lib_configuration.txt @@ -1,17 +1,16 @@ -GCC_version: arm-zephyr-eabi-gcc (Zephyr SDK 0.15.2) 12.1.0 +GCC_version: arm-zephyr-eabi-gcc (Zephyr SDK 0.16.1) 12.2.0 -OpenThread_commit=2060039bbfec52ac00f22a7cc3213c2ab1df138e -NRFXLIB_commit=v2.3.0-rc1-7-g0b135cd6 -MBEDTLS_commit=v3.0.0-1594-gc2a205601 +OpenThread_commit=57ef721eeed2550835c528ab7b8e77671f7039d6 +NRFXLIB_commit=v2.5.0-rc2-0-gbbb718ad +MBEDTLS_commit=v3.3.0-ncs2-rc2-0-gacea48fc8 CONFIG_OPENTHREAD_BUILD_OUTPUT_STRIPPED=y CONFIG_OPENTHREAD_CHANNEL=11 -CONFIG_OPENTHREAD_CHILD_SUPERVISION=y CONFIG_OPENTHREAD_CLI_MAX_LINE_LENGTH=384 CONFIG_OPENTHREAD_COAP=y CONFIG_OPENTHREAD_CONFIG_PLATFORM_INFO=Zephyr -CONFIG_OPENTHREAD_CSL_MIN_RECEIVE_ON=5696 -CONFIG_OPENTHREAD_CSL_RECEIVE_TIME_AHEAD=480 +CONFIG_OPENTHREAD_CSL_RECEIVE_TIME_AHEAD=5000 +CONFIG_OPENTHREAD_CSL_TIMEOUT=100 CONFIG_OPENTHREAD_CUSTOM_PARAMETERS= CONFIG_OPENTHREAD_DEFAULT_TX_POWER=0 CONFIG_OPENTHREAD_DHCP6_CLIENT=y @@ -25,31 +24,38 @@ CONFIG_OPENTHREAD_IP6_MAX_EXT_MCAST_ADDRS=2 CONFIG_OPENTHREAD_IP6_MAX_EXT_UCAST_ADDRS=4 CONFIG_OPENTHREAD_JOINER=y CONFIG_OPENTHREAD_L2_LOG_LEVEL=0 +CONFIG_OPENTHREAD_LIBRARY_AVAILABLE=y CONFIG_OPENTHREAD_LINK_METRICS_INITIATOR=y CONFIG_OPENTHREAD_LINK_METRICS_SUBJECT=y CONFIG_OPENTHREAD_LOG_LEVEL=0 CONFIG_OPENTHREAD_MAC_SOFTWARE_ACK_TIMEOUT_ENABLE=y CONFIG_OPENTHREAD_MAC_SOFTWARE_CSMA_BACKOFF_ENABLE=y CONFIG_OPENTHREAD_MAC_SOFTWARE_RETRANSMIT_ENABLE=y +CONFIG_OPENTHREAD_MAC_SOFTWARE_TX_SECURITY_ENABLE=y CONFIG_OPENTHREAD_MANUAL_START=y CONFIG_OPENTHREAD_MAX_CHILDREN=32 CONFIG_OPENTHREAD_MAX_IP_ADDR_PER_CHILD=6 CONFIG_OPENTHREAD_MAX_STATECHANGE_HANDLERS=2 CONFIG_OPENTHREAD_MBEDTLS_LIB_NAME=mbedtls_external CONFIG_OPENTHREAD_MESSAGE_BUFFER_SIZE=128 +CONFIG_OPENTHREAD_MIN_RECEIVE_ON_AFTER=5504 +CONFIG_OPENTHREAD_MIN_RECEIVE_ON_AHEAD=192 CONFIG_OPENTHREAD_MLR=y -CONFIG_OPENTHREAD_MTD_NETDIAG=y +CONFIG_OPENTHREAD_NETDIAG_CLIENT=y CONFIG_OPENTHREAD_NETWORKKEY= CONFIG_OPENTHREAD_NETWORK_NAME=ot_zephyr CONFIG_OPENTHREAD_NORDIC_LIBRARY_FTD=y CONFIG_OPENTHREAD_NRF_SECURITY=y CONFIG_OPENTHREAD_NRF_SECURITY_CHOICE=y CONFIG_OPENTHREAD_NUM_MESSAGE_BUFFERS=128 +CONFIG_OPENTHREAD_OPERATIONAL_DATASET_AUTO_INIT=y CONFIG_OPENTHREAD_PANID=43981 CONFIG_OPENTHREAD_PING_SENDER=y CONFIG_OPENTHREAD_PKT_LIST_SIZE=10 -CONFIG_OPENTHREAD_PLATFORM_CSL_UNCERT=5 +CONFIG_OPENTHREAD_PLATFORM_CSL_UNCERT=12 CONFIG_OPENTHREAD_PLATFORM_INFO=ZEPHYR +CONFIG_OPENTHREAD_POWER_SUPPLY=EXTERNAL +CONFIG_OPENTHREAD_POWER_SUPPLY_EXTERNAL=y CONFIG_OPENTHREAD_RADIO_LINK_IEEE_802_15_4_ENABLE=y CONFIG_OPENTHREAD_RADIO_WORKQUEUE_STACK_SIZE=1024 CONFIG_OPENTHREAD_SHELL=y @@ -62,8 +68,10 @@ CONFIG_OPENTHREAD_THREAD_STACK_SIZE=6240 CONFIG_OPENTHREAD_THREAD_VERSION=1.3 CONFIG_OPENTHREAD_THREAD_VERSION_1_3=y CONFIG_OPENTHREAD_TMF_ADDRESS_CACHE_ENTRIES=20 +CONFIG_OPENTHREAD_UPTIME=y CONFIG_OPENTHREAD_XPANID=de:ad:00:be:ef:00:ca:fe OT_15_4=ON +OT_ANDROID_NDK= OT_ANYCAST_LOCATOR=OFF OT_APP_CLI=ON OT_APP_NCP=ON @@ -73,15 +81,17 @@ OT_BACKBONE_ROUTER=OFF OT_BACKBONE_ROUTER_DUA_NDPROXYING=OFF OT_BACKBONE_ROUTER_MULTICAST_ROUTING=OFF OT_BORDER_AGENT=OFF +OT_BORDER_AGENT_ID= OT_BORDER_ROUTER=OFF OT_BORDER_ROUTING=OFF OT_BORDER_ROUTING_COUNTERS=OFF +OT_BORDER_ROUTING_DHCP6_PD=OFF OT_BUILD_EXECUTABLES=OFF OT_BUILTIN_MBEDTLS_MANAGEMENT=OFF OT_CHANNEL_MANAGER=OFF OT_CHANNEL_MONITOR=OFF -OT_CHILD_SUPERVISION=ON OT_CLI_TRANSPORT=CONSOLE +OT_CLI_VENDOR_EXTENSION= OT_COAP=ON OT_COAPS=OFF OT_COAP_BLOCK=OFF @@ -94,16 +104,18 @@ OT_CSL_AUTO_SYNC=OFF OT_CSL_DEBUG=OFF OT_CSL_RECEIVER=OFF OT_DATASET_UPDATER=OFF +OT_DEVICE_PROP_LEADER_WEIGHT=OFF OT_DHCP6_CLIENT=ON OT_DHCP6_SERVER=OFF OT_DIAGNOSTIC=OFF OT_DNSSD_SERVER=OFF OT_DNS_CLIENT=ON +OT_DNS_CLIENT_OVER_TCP=OFF OT_DNS_DSO=OFF +OT_DNS_UPSTREAM_QUERY=OFF OT_DOC=OFF OT_DUA=ON OT_ECDSA=ON -OT_EXCLUDE_TCPLP_LIB=OFF OT_EXTERNAL_HEAP=ON OT_EXTERNAL_MBEDTLS=mbedtls_external OT_FIREWALL=OFF @@ -115,7 +127,9 @@ OT_IP6_FRAGM=ON OT_JAM_DETECTION=OFF OT_JOINER=ON OT_LEGACY=OFF +OT_LINKER_MAP=ON OT_LINK_METRICS_INITIATOR=ON +OT_LINK_METRICS_MANAGER=OFF OT_LINK_METRICS_SUBJECT=ON OT_LINK_RAW=OFF OT_LOG_LEVEL= @@ -123,12 +137,12 @@ OT_LOG_LEVEL_DYNAMIC=OFF OT_LOG_OUTPUT= OT_MAC_FILTER=OFF OT_MBEDTLS_THREADING=OFF +OT_MESH_DIAG=OFF OT_MESSAGE_USE_HEAP=OFF OT_MLE_LONG_ROUTES=OFF OT_MLE_MAX_CHILDREN= OT_MLR=ON OT_MTD=OFF -OT_MTD_NETDIAG=ON OT_MULTIPLE_INSTANCE=OFF OT_NAT64_BORDER_ROUTING=OFF OT_NAT64_TRANSLATOR=OFF @@ -136,15 +150,20 @@ OT_NCP_SPI=OFF OT_NCP_VENDOR_HOOK_SOURCE= OT_NEIGHBOR_DISCOVERY_AGENT=OFF OT_NETDATA_PUBLISHER=OFF +OT_NETDIAG_CLIENT=ON +OT_OPERATIONAL_DATASET_AUTO_INIT=ON OT_OTNS=OFF OT_PACKAGE_NAME=OPENTHREAD OT_PACKAGE_VERSION= OT_PING_SENDER=ON OT_PLATFORM=zephyr +OT_PLATFORM_CONFIG= OT_PLATFORM_NETIF=OFF OT_PLATFORM_UDP=OFF +OT_POWER_SUPPLY=EXTERNAL +OT_PROJECT_CONFIG= OT_RCP=ON -OT_RCP_RESTORATION_MAX_COUNT=0 +OT_RCP_RESTORATION_MAX_COUNT= OT_REFERENCE_DEVICE=OFF OT_SERVICE=OFF OT_SETTINGS_RAM=OFF @@ -152,10 +171,15 @@ OT_SLAAC=ON OT_SNTP_CLIENT=ON OT_SRP_CLIENT=ON OT_SRP_SERVER=OFF +OT_TCP=OFF OT_THREAD_VERSION=1.3 OT_TIME_SYNC=OFF OT_TREL=OFF OT_TX_BEACON_PAYLOAD=OFF +OT_TX_QUEUE_STATS=OFF OT_UDP_FORWARD=OFF -OT_UPTIME=OFF +OT_UPTIME=ON OT_VENDOR_EXTENSION= +OT_VENDOR_MODEL= +OT_VENDOR_NAME= +OT_VENDOR_SW_VERSION= diff --git a/openthread/lib/cortex-m4/hard-float/v1.3/master/oberon/libopenthread-cli-ftd.a b/openthread/lib/cortex-m4/hard-float/v1.3/master/oberon/libopenthread-cli-ftd.a index 5b840cfec2..4d5c14ed19 100644 Binary files a/openthread/lib/cortex-m4/hard-float/v1.3/master/oberon/libopenthread-cli-ftd.a and b/openthread/lib/cortex-m4/hard-float/v1.3/master/oberon/libopenthread-cli-ftd.a differ diff --git a/openthread/lib/cortex-m4/hard-float/v1.3/master/oberon/libopenthread-ftd.a b/openthread/lib/cortex-m4/hard-float/v1.3/master/oberon/libopenthread-ftd.a index 860590c2c8..8d5bcdd525 100644 Binary files a/openthread/lib/cortex-m4/hard-float/v1.3/master/oberon/libopenthread-ftd.a and b/openthread/lib/cortex-m4/hard-float/v1.3/master/oberon/libopenthread-ftd.a differ diff --git a/openthread/lib/cortex-m4/hard-float/v1.3/master/oberon/nrf_security_mbedtls_configuration.h b/openthread/lib/cortex-m4/hard-float/v1.3/master/oberon/nrf_security_mbedtls_configuration.h index 398842e99e..f347f1a968 100644 --- a/openthread/lib/cortex-m4/hard-float/v1.3/master/oberon/nrf_security_mbedtls_configuration.h +++ b/openthread/lib/cortex-m4/hard-float/v1.3/master/oberon/nrf_security_mbedtls_configuration.h @@ -17,22 +17,6 @@ * or disable features selectively, and reduce the global * memory footprint. */ -/* - * Copyright The Mbed TLS Contributors - * SPDX-License-Identifier: Apache-2.0 - * - * Licensed under the Apache License, Version 2.0 (the "License"); you may - * not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ /** * This is an optional version symbol that enables comatibility handling of @@ -710,7 +694,7 @@ * MBEDTLS_TLS_PSK_WITH_CAMELLIA_128_GCM_SHA256 * MBEDTLS_TLS_PSK_WITH_CAMELLIA_128_CBC_SHA256 */ -/* #undef MBEDTLS_KEY_EXCHANGE_PSK_ENABLED */ +#define MBEDTLS_KEY_EXCHANGE_PSK_ENABLED /** * \def MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED @@ -1082,7 +1066,7 @@ * * Uncomment this macro to let the buffer allocator print out error messages. */ -//#define MBEDTLS_MEMORY_DEBUG +/* #undef MBEDTLS_MEMORY_DEBUG */ /** * \def MBEDTLS_MEMORY_BACKTRACE @@ -1206,7 +1190,7 @@ * * \note This option is experimental and may be removed without notice. */ -/* #undef MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG */ +#define MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG /** * \def MBEDTLS_PSA_CRYPTO_SPM @@ -2705,7 +2689,7 @@ * on it, and considering stronger message digests instead. * */ -#define MBEDTLS_SHA1_C +/* #undef MBEDTLS_SHA1_C */ /** * \def MBEDTLS_SHA224_C @@ -2772,7 +2756,7 @@ * * This module adds support for SHA-512. */ -#define MBEDTLS_SHA512_C +/* #undef MBEDTLS_SHA512_C */ /** * \def MBEDTLS_SSL_CACHE_C diff --git a/openthread/lib/cortex-m4/hard-float/v1.3/master/oberon/openthread_lib_configuration.txt b/openthread/lib/cortex-m4/hard-float/v1.3/master/oberon/openthread_lib_configuration.txt index a85cbe119d..5444b6459a 100644 --- a/openthread/lib/cortex-m4/hard-float/v1.3/master/oberon/openthread_lib_configuration.txt +++ b/openthread/lib/cortex-m4/hard-float/v1.3/master/oberon/openthread_lib_configuration.txt @@ -1,21 +1,20 @@ -GCC_version: arm-zephyr-eabi-gcc (Zephyr SDK 0.15.2) 12.1.0 +GCC_version: arm-zephyr-eabi-gcc (Zephyr SDK 0.16.1) 12.2.0 -OpenThread_commit=2060039bbfec52ac00f22a7cc3213c2ab1df138e -NRFXLIB_commit=v2.3.0-rc1-7-g0b135cd6 -MBEDTLS_commit=v3.0.0-1594-gc2a205601 +OpenThread_commit=57ef721eeed2550835c528ab7b8e77671f7039d6 +NRFXLIB_commit=v2.5.0-rc2-0-gbbb718ad +MBEDTLS_commit=v3.3.0-ncs2-rc2-0-gacea48fc8 CONFIG_OPENTHREAD_BUILD_OUTPUT_STRIPPED=y CONFIG_OPENTHREAD_CHANNEL=11 -CONFIG_OPENTHREAD_CHILD_SUPERVISION=y CONFIG_OPENTHREAD_CLI_MAX_LINE_LENGTH=384 CONFIG_OPENTHREAD_COAP=y CONFIG_OPENTHREAD_COAPS=y CONFIG_OPENTHREAD_COMMISSIONER=y CONFIG_OPENTHREAD_CONFIG_PLATFORM_INFO=Zephyr CONFIG_OPENTHREAD_CSL_AUTO_SYNC=y -CONFIG_OPENTHREAD_CSL_MIN_RECEIVE_ON=300 CONFIG_OPENTHREAD_CSL_RECEIVER=y CONFIG_OPENTHREAD_CSL_RECEIVE_TIME_AHEAD=5000 +CONFIG_OPENTHREAD_CSL_TIMEOUT=20 CONFIG_OPENTHREAD_CUSTOM_PARAMETERS= CONFIG_OPENTHREAD_DEFAULT_TX_POWER=0 CONFIG_OPENTHREAD_DHCP6_CLIENT=y @@ -40,25 +39,31 @@ CONFIG_OPENTHREAD_MAC_FILTER=y CONFIG_OPENTHREAD_MAC_SOFTWARE_ACK_TIMEOUT_ENABLE=y CONFIG_OPENTHREAD_MAC_SOFTWARE_CSMA_BACKOFF_ENABLE=y CONFIG_OPENTHREAD_MAC_SOFTWARE_RETRANSMIT_ENABLE=y +CONFIG_OPENTHREAD_MAC_SOFTWARE_TX_SECURITY_ENABLE=y CONFIG_OPENTHREAD_MANUAL_START=y CONFIG_OPENTHREAD_MAX_CHILDREN=32 CONFIG_OPENTHREAD_MAX_IP_ADDR_PER_CHILD=6 CONFIG_OPENTHREAD_MAX_STATECHANGE_HANDLERS=2 CONFIG_OPENTHREAD_MBEDTLS_LIB_NAME=mbedtls_external CONFIG_OPENTHREAD_MESSAGE_BUFFER_SIZE=128 +CONFIG_OPENTHREAD_MIN_RECEIVE_ON_AFTER=0 +CONFIG_OPENTHREAD_MIN_RECEIVE_ON_AHEAD=104 CONFIG_OPENTHREAD_MLR=y -CONFIG_OPENTHREAD_MTD_NETDIAG=y +CONFIG_OPENTHREAD_NETDIAG_CLIENT=y CONFIG_OPENTHREAD_NETWORKKEY= CONFIG_OPENTHREAD_NETWORK_NAME=ot_zephyr CONFIG_OPENTHREAD_NORDIC_LIBRARY_MASTER=y CONFIG_OPENTHREAD_NRF_SECURITY=y CONFIG_OPENTHREAD_NRF_SECURITY_CHOICE=y CONFIG_OPENTHREAD_NUM_MESSAGE_BUFFERS=128 +CONFIG_OPENTHREAD_OPERATIONAL_DATASET_AUTO_INIT=y CONFIG_OPENTHREAD_PANID=43981 CONFIG_OPENTHREAD_PING_SENDER=y CONFIG_OPENTHREAD_PKT_LIST_SIZE=10 -CONFIG_OPENTHREAD_PLATFORM_CSL_UNCERT=5 +CONFIG_OPENTHREAD_PLATFORM_CSL_UNCERT=12 CONFIG_OPENTHREAD_PLATFORM_INFO=ZEPHYR +CONFIG_OPENTHREAD_POWER_SUPPLY=EXTERNAL +CONFIG_OPENTHREAD_POWER_SUPPLY_EXTERNAL=y CONFIG_OPENTHREAD_RADIO_LINK_IEEE_802_15_4_ENABLE=y CONFIG_OPENTHREAD_RADIO_WORKQUEUE_STACK_SIZE=1024 CONFIG_OPENTHREAD_RAW=y @@ -73,8 +78,10 @@ CONFIG_OPENTHREAD_THREAD_VERSION=1.3 CONFIG_OPENTHREAD_THREAD_VERSION_1_3=y CONFIG_OPENTHREAD_TMF_ADDRESS_CACHE_ENTRIES=20 CONFIG_OPENTHREAD_UDP_FORWARD=y +CONFIG_OPENTHREAD_UPTIME=y CONFIG_OPENTHREAD_XPANID=de:ad:00:be:ef:00:ca:fe OT_15_4=ON +OT_ANDROID_NDK= OT_ANYCAST_LOCATOR=OFF OT_APP_CLI=ON OT_APP_NCP=ON @@ -84,15 +91,17 @@ OT_BACKBONE_ROUTER=OFF OT_BACKBONE_ROUTER_DUA_NDPROXYING=OFF OT_BACKBONE_ROUTER_MULTICAST_ROUTING=OFF OT_BORDER_AGENT=OFF +OT_BORDER_AGENT_ID= OT_BORDER_ROUTER=OFF OT_BORDER_ROUTING=OFF OT_BORDER_ROUTING_COUNTERS=OFF +OT_BORDER_ROUTING_DHCP6_PD=OFF OT_BUILD_EXECUTABLES=OFF OT_BUILTIN_MBEDTLS_MANAGEMENT=OFF OT_CHANNEL_MANAGER=OFF OT_CHANNEL_MONITOR=OFF -OT_CHILD_SUPERVISION=ON OT_CLI_TRANSPORT=CONSOLE +OT_CLI_VENDOR_EXTENSION= OT_COAP=ON OT_COAPS=ON OT_COAP_BLOCK=OFF @@ -105,16 +114,18 @@ OT_CSL_AUTO_SYNC=ON OT_CSL_DEBUG=OFF OT_CSL_RECEIVER=ON OT_DATASET_UPDATER=OFF +OT_DEVICE_PROP_LEADER_WEIGHT=OFF OT_DHCP6_CLIENT=ON OT_DHCP6_SERVER=ON OT_DIAGNOSTIC=ON OT_DNSSD_SERVER=OFF OT_DNS_CLIENT=ON +OT_DNS_CLIENT_OVER_TCP=OFF OT_DNS_DSO=OFF +OT_DNS_UPSTREAM_QUERY=OFF OT_DOC=OFF OT_DUA=ON OT_ECDSA=ON -OT_EXCLUDE_TCPLP_LIB=OFF OT_EXTERNAL_HEAP=ON OT_EXTERNAL_MBEDTLS=mbedtls_external OT_FIREWALL=OFF @@ -126,7 +137,9 @@ OT_IP6_FRAGM=ON OT_JAM_DETECTION=ON OT_JOINER=ON OT_LEGACY=OFF +OT_LINKER_MAP=ON OT_LINK_METRICS_INITIATOR=ON +OT_LINK_METRICS_MANAGER=OFF OT_LINK_METRICS_SUBJECT=ON OT_LINK_RAW=ON OT_LOG_LEVEL= @@ -134,12 +147,12 @@ OT_LOG_LEVEL_DYNAMIC=OFF OT_LOG_OUTPUT= OT_MAC_FILTER=ON OT_MBEDTLS_THREADING=OFF +OT_MESH_DIAG=OFF OT_MESSAGE_USE_HEAP=OFF OT_MLE_LONG_ROUTES=OFF OT_MLE_MAX_CHILDREN= OT_MLR=ON OT_MTD=OFF -OT_MTD_NETDIAG=ON OT_MULTIPLE_INSTANCE=OFF OT_NAT64_BORDER_ROUTING=OFF OT_NAT64_TRANSLATOR=OFF @@ -147,15 +160,20 @@ OT_NCP_SPI=OFF OT_NCP_VENDOR_HOOK_SOURCE= OT_NEIGHBOR_DISCOVERY_AGENT=OFF OT_NETDATA_PUBLISHER=OFF +OT_NETDIAG_CLIENT=ON +OT_OPERATIONAL_DATASET_AUTO_INIT=ON OT_OTNS=OFF OT_PACKAGE_NAME=OPENTHREAD OT_PACKAGE_VERSION= OT_PING_SENDER=ON OT_PLATFORM=zephyr +OT_PLATFORM_CONFIG= OT_PLATFORM_NETIF=OFF OT_PLATFORM_UDP=OFF +OT_POWER_SUPPLY=EXTERNAL +OT_PROJECT_CONFIG= OT_RCP=ON -OT_RCP_RESTORATION_MAX_COUNT=0 +OT_RCP_RESTORATION_MAX_COUNT= OT_REFERENCE_DEVICE=OFF OT_SERVICE=ON OT_SETTINGS_RAM=OFF @@ -163,10 +181,15 @@ OT_SLAAC=ON OT_SNTP_CLIENT=ON OT_SRP_CLIENT=ON OT_SRP_SERVER=OFF +OT_TCP=OFF OT_THREAD_VERSION=1.3 OT_TIME_SYNC=OFF OT_TREL=OFF OT_TX_BEACON_PAYLOAD=OFF +OT_TX_QUEUE_STATS=OFF OT_UDP_FORWARD=ON -OT_UPTIME=OFF +OT_UPTIME=ON OT_VENDOR_EXTENSION= +OT_VENDOR_MODEL= +OT_VENDOR_NAME= +OT_VENDOR_SW_VERSION= diff --git a/openthread/lib/cortex-m4/hard-float/v1.3/mtd/oberon/libopenthread-cli-mtd.a b/openthread/lib/cortex-m4/hard-float/v1.3/mtd/oberon/libopenthread-cli-mtd.a index 878e67129c..f77b9a28c3 100644 Binary files a/openthread/lib/cortex-m4/hard-float/v1.3/mtd/oberon/libopenthread-cli-mtd.a and b/openthread/lib/cortex-m4/hard-float/v1.3/mtd/oberon/libopenthread-cli-mtd.a differ diff --git a/openthread/lib/cortex-m4/hard-float/v1.3/mtd/oberon/libopenthread-mtd.a b/openthread/lib/cortex-m4/hard-float/v1.3/mtd/oberon/libopenthread-mtd.a index 40ebcf97d2..ffdb815226 100644 Binary files a/openthread/lib/cortex-m4/hard-float/v1.3/mtd/oberon/libopenthread-mtd.a and b/openthread/lib/cortex-m4/hard-float/v1.3/mtd/oberon/libopenthread-mtd.a differ diff --git a/openthread/lib/cortex-m4/hard-float/v1.3/mtd/oberon/nrf_security_mbedtls_configuration.h b/openthread/lib/cortex-m4/hard-float/v1.3/mtd/oberon/nrf_security_mbedtls_configuration.h index 398842e99e..06adbc768d 100644 --- a/openthread/lib/cortex-m4/hard-float/v1.3/mtd/oberon/nrf_security_mbedtls_configuration.h +++ b/openthread/lib/cortex-m4/hard-float/v1.3/mtd/oberon/nrf_security_mbedtls_configuration.h @@ -17,22 +17,6 @@ * or disable features selectively, and reduce the global * memory footprint. */ -/* - * Copyright The Mbed TLS Contributors - * SPDX-License-Identifier: Apache-2.0 - * - * Licensed under the Apache License, Version 2.0 (the "License"); you may - * not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ /** * This is an optional version symbol that enables comatibility handling of @@ -1082,7 +1066,7 @@ * * Uncomment this macro to let the buffer allocator print out error messages. */ -//#define MBEDTLS_MEMORY_DEBUG +/* #undef MBEDTLS_MEMORY_DEBUG */ /** * \def MBEDTLS_MEMORY_BACKTRACE @@ -1206,7 +1190,7 @@ * * \note This option is experimental and may be removed without notice. */ -/* #undef MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG */ +#define MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG /** * \def MBEDTLS_PSA_CRYPTO_SPM @@ -2705,7 +2689,7 @@ * on it, and considering stronger message digests instead. * */ -#define MBEDTLS_SHA1_C +/* #undef MBEDTLS_SHA1_C */ /** * \def MBEDTLS_SHA224_C @@ -2772,7 +2756,7 @@ * * This module adds support for SHA-512. */ -#define MBEDTLS_SHA512_C +/* #undef MBEDTLS_SHA512_C */ /** * \def MBEDTLS_SSL_CACHE_C @@ -2794,7 +2778,7 @@ * Module: library/ssl_cookie.c * Caller: */ -#define MBEDTLS_SSL_COOKIE_C +/* #undef MBEDTLS_SSL_COOKIE_C */ /** * \def MBEDTLS_SSL_TICKET_C @@ -2834,7 +2818,7 @@ * * This module is required for SSL/TLS server support. */ -#define MBEDTLS_SSL_SRV_C +/* #undef MBEDTLS_SSL_SRV_C */ /** * \def MBEDTLS_SSL_TLS_C diff --git a/openthread/lib/cortex-m4/hard-float/v1.3/mtd/oberon/openthread_lib_configuration.txt b/openthread/lib/cortex-m4/hard-float/v1.3/mtd/oberon/openthread_lib_configuration.txt index 8c5d3f2e15..c67f3aabd7 100644 --- a/openthread/lib/cortex-m4/hard-float/v1.3/mtd/oberon/openthread_lib_configuration.txt +++ b/openthread/lib/cortex-m4/hard-float/v1.3/mtd/oberon/openthread_lib_configuration.txt @@ -1,19 +1,18 @@ -GCC_version: arm-zephyr-eabi-gcc (Zephyr SDK 0.15.2) 12.1.0 +GCC_version: arm-zephyr-eabi-gcc (Zephyr SDK 0.16.1) 12.2.0 -OpenThread_commit=2060039bbfec52ac00f22a7cc3213c2ab1df138e -NRFXLIB_commit=v2.3.0-rc1-7-g0b135cd6 -MBEDTLS_commit=v3.0.0-1594-gc2a205601 +OpenThread_commit=57ef721eeed2550835c528ab7b8e77671f7039d6 +NRFXLIB_commit=v2.5.0-rc2-0-gbbb718ad +MBEDTLS_commit=v3.3.0-ncs2-rc2-0-gacea48fc8 CONFIG_OPENTHREAD_BUILD_OUTPUT_STRIPPED=y CONFIG_OPENTHREAD_CHANNEL=11 -CONFIG_OPENTHREAD_CHILD_SUPERVISION=y CONFIG_OPENTHREAD_CLI_MAX_LINE_LENGTH=384 CONFIG_OPENTHREAD_COAP=y CONFIG_OPENTHREAD_CONFIG_PLATFORM_INFO=Zephyr CONFIG_OPENTHREAD_CSL_AUTO_SYNC=y -CONFIG_OPENTHREAD_CSL_MIN_RECEIVE_ON=300 CONFIG_OPENTHREAD_CSL_RECEIVER=y CONFIG_OPENTHREAD_CSL_RECEIVE_TIME_AHEAD=5000 +CONFIG_OPENTHREAD_CSL_TIMEOUT=20 CONFIG_OPENTHREAD_CUSTOM_PARAMETERS= CONFIG_OPENTHREAD_DEFAULT_TX_POWER=0 CONFIG_OPENTHREAD_DHCP6_CLIENT=y @@ -26,30 +25,37 @@ CONFIG_OPENTHREAD_IP6_MAX_EXT_MCAST_ADDRS=2 CONFIG_OPENTHREAD_IP6_MAX_EXT_UCAST_ADDRS=4 CONFIG_OPENTHREAD_JOINER=y CONFIG_OPENTHREAD_L2_LOG_LEVEL=0 +CONFIG_OPENTHREAD_LIBRARY_AVAILABLE=y CONFIG_OPENTHREAD_LINK_METRICS_INITIATOR=y CONFIG_OPENTHREAD_LOG_LEVEL=0 CONFIG_OPENTHREAD_MAC_SOFTWARE_ACK_TIMEOUT_ENABLE=y CONFIG_OPENTHREAD_MAC_SOFTWARE_CSMA_BACKOFF_ENABLE=y CONFIG_OPENTHREAD_MAC_SOFTWARE_RETRANSMIT_ENABLE=y +CONFIG_OPENTHREAD_MAC_SOFTWARE_TX_SECURITY_ENABLE=y CONFIG_OPENTHREAD_MANUAL_START=y -CONFIG_OPENTHREAD_MAX_CHILDREN=1 +CONFIG_OPENTHREAD_MAX_CHILDREN=32 CONFIG_OPENTHREAD_MAX_STATECHANGE_HANDLERS=2 CONFIG_OPENTHREAD_MBEDTLS_LIB_NAME=mbedtls_external CONFIG_OPENTHREAD_MESSAGE_BUFFER_SIZE=128 +CONFIG_OPENTHREAD_MIN_RECEIVE_ON_AFTER=0 +CONFIG_OPENTHREAD_MIN_RECEIVE_ON_AHEAD=104 CONFIG_OPENTHREAD_MLR=y CONFIG_OPENTHREAD_MTD=y -CONFIG_OPENTHREAD_MTD_NETDIAG=y +CONFIG_OPENTHREAD_NETDIAG_CLIENT=y CONFIG_OPENTHREAD_NETWORKKEY= CONFIG_OPENTHREAD_NETWORK_NAME=ot_zephyr CONFIG_OPENTHREAD_NORDIC_LIBRARY_MTD=y CONFIG_OPENTHREAD_NRF_SECURITY=y CONFIG_OPENTHREAD_NRF_SECURITY_CHOICE=y CONFIG_OPENTHREAD_NUM_MESSAGE_BUFFERS=128 +CONFIG_OPENTHREAD_OPERATIONAL_DATASET_AUTO_INIT=y CONFIG_OPENTHREAD_PANID=43981 CONFIG_OPENTHREAD_PING_SENDER=y CONFIG_OPENTHREAD_PKT_LIST_SIZE=10 -CONFIG_OPENTHREAD_PLATFORM_CSL_UNCERT=5 +CONFIG_OPENTHREAD_PLATFORM_CSL_UNCERT=12 CONFIG_OPENTHREAD_PLATFORM_INFO=ZEPHYR +CONFIG_OPENTHREAD_POWER_SUPPLY=EXTERNAL +CONFIG_OPENTHREAD_POWER_SUPPLY_EXTERNAL=y CONFIG_OPENTHREAD_RADIO_LINK_IEEE_802_15_4_ENABLE=y CONFIG_OPENTHREAD_RADIO_WORKQUEUE_STACK_SIZE=1024 CONFIG_OPENTHREAD_SHELL=y @@ -64,6 +70,7 @@ CONFIG_OPENTHREAD_THREAD_VERSION_1_3=y CONFIG_OPENTHREAD_TMF_ADDRESS_CACHE_ENTRIES=20 CONFIG_OPENTHREAD_XPANID=de:ad:00:be:ef:00:ca:fe OT_15_4=ON +OT_ANDROID_NDK= OT_ANYCAST_LOCATOR=OFF OT_APP_CLI=ON OT_APP_NCP=ON @@ -73,15 +80,17 @@ OT_BACKBONE_ROUTER=OFF OT_BACKBONE_ROUTER_DUA_NDPROXYING=OFF OT_BACKBONE_ROUTER_MULTICAST_ROUTING=OFF OT_BORDER_AGENT=OFF +OT_BORDER_AGENT_ID= OT_BORDER_ROUTER=OFF OT_BORDER_ROUTING=OFF OT_BORDER_ROUTING_COUNTERS=OFF +OT_BORDER_ROUTING_DHCP6_PD=OFF OT_BUILD_EXECUTABLES=OFF OT_BUILTIN_MBEDTLS_MANAGEMENT=OFF OT_CHANNEL_MANAGER=OFF OT_CHANNEL_MONITOR=OFF -OT_CHILD_SUPERVISION=ON OT_CLI_TRANSPORT=CONSOLE +OT_CLI_VENDOR_EXTENSION= OT_COAP=ON OT_COAPS=OFF OT_COAP_BLOCK=OFF @@ -94,16 +103,18 @@ OT_CSL_AUTO_SYNC=ON OT_CSL_DEBUG=OFF OT_CSL_RECEIVER=ON OT_DATASET_UPDATER=OFF +OT_DEVICE_PROP_LEADER_WEIGHT=OFF OT_DHCP6_CLIENT=ON OT_DHCP6_SERVER=OFF OT_DIAGNOSTIC=OFF OT_DNSSD_SERVER=OFF OT_DNS_CLIENT=ON +OT_DNS_CLIENT_OVER_TCP=OFF OT_DNS_DSO=OFF +OT_DNS_UPSTREAM_QUERY=OFF OT_DOC=OFF OT_DUA=ON OT_ECDSA=ON -OT_EXCLUDE_TCPLP_LIB=OFF OT_EXTERNAL_HEAP=ON OT_EXTERNAL_MBEDTLS=mbedtls_external OT_FIREWALL=OFF @@ -115,7 +126,9 @@ OT_IP6_FRAGM=ON OT_JAM_DETECTION=OFF OT_JOINER=ON OT_LEGACY=OFF +OT_LINKER_MAP=ON OT_LINK_METRICS_INITIATOR=ON +OT_LINK_METRICS_MANAGER=OFF OT_LINK_METRICS_SUBJECT=OFF OT_LINK_RAW=OFF OT_LOG_LEVEL= @@ -123,12 +136,12 @@ OT_LOG_LEVEL_DYNAMIC=OFF OT_LOG_OUTPUT= OT_MAC_FILTER=OFF OT_MBEDTLS_THREADING=OFF +OT_MESH_DIAG=OFF OT_MESSAGE_USE_HEAP=OFF OT_MLE_LONG_ROUTES=OFF OT_MLE_MAX_CHILDREN= OT_MLR=ON OT_MTD=ON -OT_MTD_NETDIAG=ON OT_MULTIPLE_INSTANCE=OFF OT_NAT64_BORDER_ROUTING=OFF OT_NAT64_TRANSLATOR=OFF @@ -136,15 +149,20 @@ OT_NCP_SPI=OFF OT_NCP_VENDOR_HOOK_SOURCE= OT_NEIGHBOR_DISCOVERY_AGENT=OFF OT_NETDATA_PUBLISHER=OFF +OT_NETDIAG_CLIENT=ON +OT_OPERATIONAL_DATASET_AUTO_INIT=ON OT_OTNS=OFF OT_PACKAGE_NAME=OPENTHREAD OT_PACKAGE_VERSION= OT_PING_SENDER=ON OT_PLATFORM=zephyr +OT_PLATFORM_CONFIG= OT_PLATFORM_NETIF=OFF OT_PLATFORM_UDP=OFF +OT_POWER_SUPPLY=EXTERNAL +OT_PROJECT_CONFIG= OT_RCP=ON -OT_RCP_RESTORATION_MAX_COUNT=0 +OT_RCP_RESTORATION_MAX_COUNT= OT_REFERENCE_DEVICE=OFF OT_SERVICE=OFF OT_SETTINGS_RAM=OFF @@ -152,10 +170,15 @@ OT_SLAAC=ON OT_SNTP_CLIENT=ON OT_SRP_CLIENT=ON OT_SRP_SERVER=OFF +OT_TCP=OFF OT_THREAD_VERSION=1.3 OT_TIME_SYNC=OFF OT_TREL=OFF OT_TX_BEACON_PAYLOAD=OFF +OT_TX_QUEUE_STATS=OFF OT_UDP_FORWARD=OFF OT_UPTIME=OFF OT_VENDOR_EXTENSION= +OT_VENDOR_MODEL= +OT_VENDOR_NAME= +OT_VENDOR_SW_VERSION=