Line data    Source code

       1             : /*
       2             :  *
       3             :  *    Copyright (c) 2020-2021 Project CHIP Authors
       4             :  *    Copyright (c) 2017 Nest Labs, Inc.
       5             :  *    All rights reserved.
       6             :  *
       7             :  *    Licensed under the Apache License, Version 2.0 (the "License");
       8             :  *    you may not use this file except in compliance with the License.
       9             :  *    You may obtain a copy of the License at
      10             :  *
      11             :  *        http://www.apache.org/licenses/LICENSE-2.0
      12             :  *
      13             :  *    Unless required by applicable law or agreed to in writing, software
      14             :  *    distributed under the License is distributed on an "AS IS" BASIS,
      15             :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      16             :  *    See the License for the specific language governing permissions and
      17             :  *    limitations under the License.
      18             :  */
      19             : 
      20             : /**
      21             :  *    @file
      22             :  *      This file defines the configuration parameters that are required
      23             :  *      for the CHIP Reliable Messaging Protocol.
      24             :  *
      25             :  */
      26             : #pragma once
      27             : 
      28             : #include <lib/core/CHIPConfig.h>
      29             : #include <lib/core/Optional.h>
      30             : #include <system/SystemClock.h>
      31             : #include <system/SystemConfig.h>
      32             : 
      33             : #if CHIP_SYSTEM_CONFIG_USE_LWIP
      34             : #include <lwip/opt.h>
      35             : #endif // CHIP_SYSTEM_CONFIG_USE_LWIP
      36             : 
      37             : namespace chip {
      38             : 
      39             : /**
      40             :  *  @def CHIP_CONFIG_MRP_LOCAL_ACTIVE_RETRY_INTERVAL
      41             :  *
      42             :  *  @brief Base retry interval of the present node when it is in the active state.
      43             :  *
      44             :  *  Base interval that a peer node should use to calculate the retransmission
      45             :  *  timeout when it sends a message to the present node and the present node is
      46             :  *  perceived by the peer as active.
      47             :  *
      48             :  *  This value is announced to the peer using SAI (Session Active Interval) key
      49             :  *  in the advertised DNS Service Discovery TXT records. Additionally, it is
      50             :  *  exchanged in the initial phase of the PASE/CASE session establishment.
      51             :  *
      52             :  *  In the case of a Thread device, the default value is increased to limit the
      53             :  *  possibility of spurious retransmissions. The assumption is that the average
      54             :  *  round-trip time of a big request-response pair is substantially longer in
      55             :  *  a Thread network that potentially constists of multiple intermediate hops.
      56             :  */
      57             : #ifndef CHIP_CONFIG_MRP_LOCAL_ACTIVE_RETRY_INTERVAL
      58             : #if CHIP_ENABLE_OPENTHREAD && !CHIP_DEVICE_LAYER_TARGET_LINUX
      59             : #define CHIP_CONFIG_MRP_LOCAL_ACTIVE_RETRY_INTERVAL (800_ms32)
      60             : #else
      61             : #define CHIP_CONFIG_MRP_LOCAL_ACTIVE_RETRY_INTERVAL (300_ms32)
      62             : #endif
      63             : #endif // CHIP_CONFIG_MRP_LOCAL_ACTIVE_RETRY_INTERVAL && !CHIP_DEVICE_LAYER_TARGET_LINUX
      64             : 
      65             : /**
      66             :  *  @def CHIP_CONFIG_MRP_LOCAL_IDLE_RETRY_INTERVAL
      67             :  *
      68             :  *  @brief Base retry interval of the present node when it is in the idle state.
      69             :  *
      70             :  *  Base interval that a peer node should use to calculate the retransmission
      71             :  *  timeout when it sends a message to the present node and the present node is
      72             :  *  perceived by the peer as idle.
      73             :  *
      74             :  *  This value is announced to the peer using SII (Session Idle Interval) key
      75             :  *  in the advertised DNS Service Discovery TXT records. Additionally, it is
      76             :  *  exchanged in the initial phase of the PASE/CASE session establishment.
      77             :  *
      78             :  *  In the case of a Thread device, the default value is increased to limit the
      79             :  *  possibility of spurious retransmissions. The assumption is that the average
      80             :  *  round-trip time of a big request-response pair is substantially longer in
      81             :  *  a Thread network that potentially constists of multiple intermediate hops.
      82             :  */
      83             : #ifndef CHIP_CONFIG_MRP_LOCAL_IDLE_RETRY_INTERVAL
      84             : #if CHIP_ENABLE_OPENTHREAD && !CHIP_DEVICE_LAYER_TARGET_LINUX
      85             : #define CHIP_CONFIG_MRP_LOCAL_IDLE_RETRY_INTERVAL (800_ms32)
      86             : #else
      87             : #define CHIP_CONFIG_MRP_LOCAL_IDLE_RETRY_INTERVAL (500_ms32)
      88             : #endif
      89             : #endif // CHIP_CONFIG_MRP_LOCAL_IDLE_RETRY_INTERVAL && !CHIP_DEVICE_LAYER_TARGET_LINUX
      90             : 
      91             : /**
      92             :  *  @def CHIP_CONFIG_RMP_DEFAULT_ACK_TIMEOUT
      93             :  *
      94             :  *  @brief
      95             :  *    The default acknowledgment timeout in milliseconds.
      96             :  *
      97             :  */
      98             : #ifndef CHIP_CONFIG_RMP_DEFAULT_ACK_TIMEOUT
      99             : #define CHIP_CONFIG_RMP_DEFAULT_ACK_TIMEOUT (200_ms32)
     100             : #endif // CHIP_CONFIG_RMP_DEFAULT_ACK_TIMEOUT
     101             : 
     102             : /**
     103             :  *  @def CHIP_CONFIG_RESOLVE_PEER_ON_FIRST_TRANSMIT_FAILURE
     104             :  *
     105             :  *  @brief
     106             :  *    Should an address lookup of the peer happen on every first message that fails
     107             :  *    to send on the link.
     108             :  *
     109             :  *  The default value to not perform lookup was selected because most implementations
     110             :  *  of address lookup are not cache the and a request is sent on the link. Failing
     111             :  *  to deliver the first message is far more likely to happen due to lossy link
     112             :  *  than an actual address change where the peer did not reset. In the lossy link
     113             :  *  situation, doing further DNS resolutions on a degraded link can exacerbate that
     114             :  *  problem greatly. Additionally, every message that arrives from a peer updates the
     115             :  *  address. If the peer has fallen off the link due to any other reason, a re-resolve
     116             :  *  may not achieve an address that is reachable, even if a resolve response occurs.
     117             :  */
     118             : #ifndef CHIP_CONFIG_RESOLVE_PEER_ON_FIRST_TRANSMIT_FAILURE
     119             : #define CHIP_CONFIG_RESOLVE_PEER_ON_FIRST_TRANSMIT_FAILURE 0
     120             : #endif // CHIP_CONFIG_RESOLVE_PEER_ON_FIRST_TRANSMIT_FAILURE
     121             : 
     122             : /**
     123             :  *  @def CHIP_CONFIG_RMP_RETRANS_TABLE_SIZE
     124             :  *
     125             :  *  @brief
     126             :  *    The default size of the ReliableMessageProtocol retransmission table.
     127             :  *
     128             :  */
     129             : #ifndef CHIP_CONFIG_RMP_RETRANS_TABLE_SIZE
     130             : #if CHIP_SYSTEM_CONFIG_USE_LWIP
     131             : 
     132             : #if !LWIP_PBUF_FROM_CUSTOM_POOLS && PBUF_POOL_SIZE != 0
     133             : #define CHIP_CONFIG_RMP_RETRANS_TABLE_SIZE std::min(PBUF_POOL_SIZE, CHIP_CONFIG_MAX_EXCHANGE_CONTEXTS)
     134             : #else
     135             : #define CHIP_CONFIG_RMP_RETRANS_TABLE_SIZE CHIP_CONFIG_MAX_EXCHANGE_CONTEXTS
     136             : #endif // !LWIP_PBUF_FROM_CUSTOM_POOLS && PBUF_POOL_SIZE != 0
     137             : 
     138             : #else // CHIP_SYSTEM_CONFIG_USE_LWIP
     139             : 
     140             : #if CHIP_SYSTEM_CONFIG_PACKETBUFFER_POOL_SIZE != 0
     141             : #define CHIP_CONFIG_RMP_RETRANS_TABLE_SIZE std::min(CHIP_SYSTEM_CONFIG_PACKETBUFFER_POOL_SIZE, CHIP_CONFIG_MAX_EXCHANGE_CONTEXTS)
     142             : #else
     143             : #define CHIP_CONFIG_RMP_RETRANS_TABLE_SIZE CHIP_CONFIG_MAX_EXCHANGE_CONTEXTS
     144             : #endif // CHIP_SYSTEM_CONFIG_PACKETBUFFER_POOL_SIZE != 0
     145             : 
     146             : #endif // CHIP_SYSTEM_CONFIG_USE_LWIP
     147             : #endif // CHIP_CONFIG_RMP_RETRANS_TABLE_SIZE
     148             : 
     149             : /**
     150             :  *  @def CHIP_CONFIG_RMP_DEFAULT_MAX_RETRANS
     151             :  *
     152             :  *  @brief
     153             :  *    The maximum number of retransmissions before giving up.
     154             :  *
     155             :  */
     156             : #ifndef CHIP_CONFIG_RMP_DEFAULT_MAX_RETRANS
     157             : #define CHIP_CONFIG_RMP_DEFAULT_MAX_RETRANS (4)
     158             : #endif // CHIP_CONFIG_RMP_DEFAULT_MAX_RETRANS
     159             : 
     160             : /**
     161             :  *  @def CHIP_CONFIG_MRP_RETRY_INTERVAL_SENDER_BOOST
     162             :  *
     163             :  *  @brief
     164             :  *    A constant value that should be added to the calculated retransmission
     165             :  *    timeout when the present node transmits a message.
     166             :  *
     167             :  *  The purpose for this constant is to limit the possibility of spurious
     168             :  *  retransmissions in the scenario in which a sender that operates in a high-
     169             :  *  latency network (such as Thread) sends a message to a receiver that operates
     170             :  *  in a low-latency network (such as Wi-Fi). In this scenario, the SAI and SII
     171             :  *  parameters advertised by the receiver are low although the average round-
     172             :  *  trip time of a big request-response pair is long due to the nature of the
     173             :  *  sender.
     174             :  */
     175             : #ifndef CHIP_CONFIG_MRP_RETRY_INTERVAL_SENDER_BOOST
     176             : #if CHIP_ENABLE_OPENTHREAD && !CHIP_DEVICE_LAYER_TARGET_LINUX
     177             : #define CHIP_CONFIG_MRP_RETRY_INTERVAL_SENDER_BOOST (500_ms)
     178             : #else
     179             : #define CHIP_CONFIG_MRP_RETRY_INTERVAL_SENDER_BOOST (0_ms)
     180             : #endif
     181             : #endif // CHIP_CONFIG_MRP_RETRY_INTERVAL_SENDER_BOOST
     182             : 
     183             : inline constexpr System::Clock::Milliseconds32 kDefaultActiveTime = System::Clock::Milliseconds16(4000);
     184             : 
     185             : /**
     186             :  *  @brief
     187             :  *    The ReliableMessageProtocol configuration.
     188             :  */
     189             : struct ReliableMessageProtocolConfig
     190             : {
     191      138141 :     ReliableMessageProtocolConfig(System::Clock::Milliseconds32 idleInterval, System::Clock::Milliseconds32 activeInterval,
     192      138141 :                                   System::Clock::Milliseconds16 activeThreshold = kDefaultActiveTime) :
     193      138141 :         mIdleRetransTimeout(idleInterval),
     194      138141 :         mActiveRetransTimeout(activeInterval), mActiveThresholdTime(activeThreshold)
     195      138141 :     {}
     196             : 
     197             :     // Configurable timeout in msec for retransmission of the first sent message.
     198             :     System::Clock::Milliseconds32 mIdleRetransTimeout;
     199             : 
     200             :     // Configurable timeout in msec for retransmission of all subsequent messages.
     201             :     System::Clock::Milliseconds32 mActiveRetransTimeout;
     202             : 
     203             :     // Configurable amount of time the node SHOULD stay active after network activity.
     204             :     System::Clock::Milliseconds16 mActiveThresholdTime;
     205             : 
     206        1694 :     bool operator==(const ReliableMessageProtocolConfig & that) const
     207             :     {
     208        3378 :         return mIdleRetransTimeout == that.mIdleRetransTimeout && mActiveRetransTimeout == that.mActiveRetransTimeout &&
     209        3378 :             mActiveThresholdTime == that.mActiveThresholdTime;
     210             :     }
     211             : };
     212             : 
     213             : /// @brief The default MRP config. The value is defined by spec, and shall be same for all implementations,
     214             : ReliableMessageProtocolConfig GetDefaultMRPConfig();
     215             : 
     216             : /**
     217             :  *  @brief  The custom value of MRP config for the platform.
     218             :  *  @return Missing   If the value is same as default value defined by spec
     219             :  *          Value     The custom value for the platform
     220             :  *
     221             :  *  @note   This value is not used by our MRP manager. The value is advertised via mDNS or during PASE/CASE paring, and our peers
     222             :  *          use it when communicating with us.
     223             :  */
     224             : Optional<ReliableMessageProtocolConfig> GetLocalMRPConfig();
     225             : 
     226             : /**
     227             :  * @brief
     228             :  * Returns the maximum transmission time depending on the last activity time.
     229             :  *
     230             :  * @param[in] activeInterval    The active interval to use for the backoff calculation.
     231             :  * @param[in] idleInterval      The idle interval to use for the backoff calculation.
     232             :  * @param[in] lastActivityTime  The last time some activity has been recorded.
     233             :  * @param[in] activityThreshold The activity threshold for a node to be considered active.
     234             :  *
     235             :  * @return The maximum transmission time
     236             :  */
     237             : System::Clock::Timestamp GetRetransmissionTimeout(System::Clock::Timestamp activeInterval, System::Clock::Timestamp idleInterval,
     238             :                                                   System::Clock::Timestamp lastActivityTime,
     239             :                                                   System::Clock::Timestamp activityThreshold);
     240             : 
     241             : #if CONFIG_BUILD_FOR_HOST_UNIT_TEST
     242             : 
     243             : /**
     244             :  * @brief
     245             :  *
     246             :  * Overrides the local idle and active retransmission timeout parameters (which are usually set through compile
     247             :  * time defines). This is reserved for tests that need the ability to set these at runtime to make certain test scenarios possible.
     248             :  *
     249             :  */
     250             : void OverrideLocalMRPConfig(System::Clock::Timeout idleRetransTimeout, System::Clock::Timeout activeRetransTimeout,
     251             :                             System::Clock::Timeout activeThresholdTime = kDefaultActiveTime);
     252             : 
     253             : /**
     254             :  * @brief
     255             :  *
     256             :  * Disables the overrides set previously in OverrideLocalMRPConfig().
     257             :  *
     258             :  */
     259             : void ClearLocalMRPConfigOverride();
     260             : #endif
     261             : 
     262             : } // namespace chip