Merge branch 'openthread:main' into test

.github/workflows/codeql.yml

@@ -66,7 +66,7 @@ jobs:
         sudo apt-get --no-install-recommends install -y ninja-build libreadline-dev libncurses-dev
 
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@6a28655e3dcb49cb0840ea372fd6d17733edd8a4 # v2.21.8
+      uses: github/codeql-action/init@0116bc2df50751f9724a2e35ef1f24d22f90e4e1 # v2.22.3
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -80,6 +80,6 @@ jobs:
         ./script/test build
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@6a28655e3dcb49cb0840ea372fd6d17733edd8a4 # v2.21.8
+      uses: github/codeql-action/analyze@0116bc2df50751f9724a2e35ef1f24d22f90e4e1 # v2.22.3
       with:
         category: "/language:${{matrix.language}}"

.github/workflows/scorecards.yml

@@ -95,6 +95,6 @@ jobs:
 
       # Upload the results to GitHub's code scanning dashboard.
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@6a28655e3dcb49cb0840ea372fd6d17733edd8a4 # v2.1.27
+        uses: github/codeql-action/upload-sarif@0116bc2df50751f9724a2e35ef1f24d22f90e4e1 # v2.1.27
         with:
           sarif_file: results.sarif

.github/workflows/size.yml

@@ -67,3 +67,4 @@ jobs:
           export OT_SIZE_REPORTER=./size-report
         fi
         ./script/check-size
+        cat /tmp/ot-size-report/report_pr >> $GITHUB_STEP_SUMMARY

include/openthread/instance.h

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

include/openthread/ip6.h

@@ -188,6 +188,7 @@ typedef struct otNetifAddress
     bool         mScopeOverrideValid : 1; ///< TRUE if the mScopeOverride value is valid, FALSE otherwise.
     unsigned int mScopeOverride : 4;      ///< The IPv6 scope of this address.
     bool         mRloc : 1;               ///< TRUE if the address is an RLOC, FALSE otherwise.
+    bool         mMeshLocal : 1;          ///< TRUE if the address is mesh-local, FALSE otherwise.
     const struct otNetifAddress *mNext;   ///< A pointer to the next network interface address.
 } otNetifAddress;
 

src/cli/README_DATASET.md

@@ -107,6 +107,117 @@ After the device successfully attaches to a Thread network, the device will retr
    Done
    ```
 
+### Using the Pending Operational Dataset for Delayed Dataset Updates
+
+The Pending Operational Dataset can be used for a delayed update of network parameters on all devices of a Thread Network. If certain Active Operational Dataset parameters need to be changed, but the change would impact the connectivity of the network, delaying the update helps to let all devices receive the new parameters before the update is applied. Examples of such parameters are the channel, PAN ID, certain Security Policy bits, or Network Key.
+
+The delay timer determines the time period after which the Pending Operational Dataset takes effect and becomes the Active Operational Dataset. The following example shows how a Pending Operational Dataset with delay timer can be set at a Leader device. The Leader will initiate the distribution of the Pending Operational Dataset to the rest of the devices in the network.
+
+Normally, an active Commissioner will set a new Pending Operational Dataset. For testing purposes, we will do this in the example directly on the Leader using the CLI - so without using a Commissioner.
+
+1. The main parameter to change is the channel. We can display the current Active Operational Dataset to see that the current channel is 16.
+
+   ```bash
+   > dataset active
+   Active Timestamp: 1691070443
+   Channel: 16
+   Channel Mask: 0x07fff800
+   Ext PAN ID: 324a71d90cdc8345
+   Mesh Local Prefix: fd7d:da74:df5e:80c::/64
+   Network Key: be768535bac1b8d228960038311d6ca2
+   Network Name: OpenThread-bcaf
+   PAN ID: 0xbcaf
+   PSKc: e79b274ab22414a814ed5cce6a30be67
+   Security Policy: 672 onrc 0
+   Done
+   ```
+
+2. Create a new Dataset in the dataset buffer, by copying the Active Operational Dataset. Then change the channel number to 12 and increase the timestamp.
+
+   ```bash
+   > dataset init active
+   Done
+   > dataset activetimestamp 1696177379
+   Done
+   > dataset pendingtimestamp 1696177379
+   Done
+   > dataset channel 12
+   Done
+   ```
+
+3. Set the delay timer parameter to 5 minutes (300000 ms). Show the resulting Dataset that's ready to be used.
+
+   ```bash
+   > dataset delay 300000
+   Done
+   > dataset
+   Pending Timestamp: 1696177379
+   Active Timestamp: 1696177379
+   Channel: 12
+   Channel Mask: 0x07fff800
+   Delay: 300000
+   Ext PAN ID: 324a71d90cdc8345
+   Mesh Local Prefix: fd7d:da74:df5e:80c::/64
+   Network Key: be768535bac1b8d228960038311d6ca2
+   Network Name: OpenThread-bcaf
+   PAN ID: 0xbcaf
+   PSKc: e79b274ab22414a814ed5cce6a30be67
+   Security Policy: 672 onrc 0
+   Done
+   ```
+
+4. Commit the new Dataset as the Pending Operational Dataset. This also starts the delay timer countdown. The Leader then starts the distribution of the Pending Operational Dataset to other devices in the network.
+
+   ```bash
+   > dataset commit pending
+   Done
+   ```
+
+5. To verify that the delay timer is counting down, display the Pending Operational Dataset after a few seconds.
+
+   ```bash
+   > dataset pending
+   Pending Timestamp: 1696177379
+   Active Timestamp: 1696177379
+   Channel: 12
+   Channel Mask: 0x07fff800
+   Delay: 293051
+   Ext PAN ID: 324a71d90cdc8345
+   Mesh Local Prefix: fd7d:da74:df5e:80c::/64
+   Network Key: be768535bac1b8d228960038311d6ca2
+   Network Name: OpenThread-bcaf
+   PAN ID: 0xbcaf
+   PSKc: e79b274ab22414a814ed5cce6a30be67
+   Security Policy: 672 onrc 0
+   Done
+   ```
+
+   This shows that indeed the delay timer has started counting down from its initial value `300000`. The same can be optionally checked on other devices in the network.
+
+6) After about 5 minutes, check that the Pending Operational Dataset has been applied at the Leader. This can also be checked at other devices on the network: these should have applied the new Dataset too, at approximately the same time as the Leader has done this.
+
+   ```bash
+   > dataset active
+   Active Timestamp: 1696177379
+   Channel: 12
+   Channel Mask: 0x07fff800
+   Ext PAN ID: 324a71d90cdc8345
+   Mesh Local Prefix: fd7d:da74:df5e:80c::/64
+   Network Key: be768535bac1b8d228960038311d6ca2
+   Network Name: OpenThread-bcaf
+   PAN ID: 0xbcaf
+   PSKc: e79b274ab22414a814ed5cce6a30be67
+   Security Policy: 672 onrc 0
+   Done
+   ```
+
+   This shows that the Active Operational Dataset has now been updated to use channel 12. And the Pending Operational Dataset is no longer present, as can be seen by this command:
+
+   ```bash
+   > dataset pending
+   Error 23: NotFound
+   ```
+
 ## Command List
 
 - [help](#help)
@@ -199,7 +310,7 @@ Done
 
 Usage: `dataset activetimestamp [timestamp]`
 
-Get active timestamp seconds.
+Get active timestamp seconds. It represents a "Unix time", in number of seconds since Jan 1st, 1970.
 
 ```bash
 > dataset activetimestamp
@@ -278,7 +389,7 @@ Done
 
 Usage: `dataset delay [delay]`
 
-Get delay timer value.
+Get delay timer value. The timer value is in milliseconds.
 
 ```bash
 > dataset delay
@@ -289,7 +400,7 @@ Done
 Set delay timer value.
 
 ```bash
-> dataset delay 1000
+> dataset delay 100000
 Done
 ```
 
@@ -318,13 +429,27 @@ Done
 
 Usage: `dataset init <active|new|pending|tlvs <hex-encoded TLVs>>`
 
-Initialize operational dataset buffer.
+Initialize operational dataset buffer. Use `new` to initialize with randomly selected values:
 
 ```bash
 > dataset init new
 Done
 ```
 
+Use `active` or `pending` to initialize the dataset buffer with a copy of the current Active Operational Dataset or Pending Operational Dataset, respectively:
+
+```bash
+> dataset init active
+Done
+```
+
+Use the `tlvs` option to initialize the dataset buffer from a string of hex-encoded TLVs:
+
+```bash
+> dataset init tlvs 0e080000000000010000000300001235060004001fffe002088665f03e6e42e7750708fda576e5f9a5bd8c0510506071d8391be671569e080d52870fd5030f4f70656e5468726561642d633538640102c58d04108a926cf8b13275a012ceedeeae40910d0c0402a0f7f8
+Done
+```
+
 ### meshlocalprefix
 
 Usage: `dataset meshlocalprefix [prefix]`
@@ -460,7 +585,7 @@ Done
 
 Usage: `dataset pendingtimestamp [timestamp]`
 
-Get pending timestamp seconds.
+Get pending timestamp seconds. It represents a "Unix time", in number of seconds since Jan 1st, 1970.
 
 ```bash
 > dataset pendingtimestamp
@@ -479,17 +604,17 @@ Done
 
 Usage: `pskc [-p] [<key>|<passphrase>]`
 
-Get pskc.
+Get PSKc.
 
 ```bash
 > dataset pskc
 67c0c203aa0b042bfb5381c47aef4d9e
 Done
 ```
 
-Set pskc.
+Set PSKc.
 
-With `-p`(**only for FTD**) generate pskc from \<passphrase\> (UTF-8 encoded) together with network name and extended PAN ID in the dataset buffer if set or values in the current stack if not, otherwise set pskc as \<key\> (hex format).
+With `-p`(**only for FTD**) generate PSKc from \<passphrase\> (UTF-8 encoded) together with network name and extended PAN ID in the dataset buffer if set or values in the current stack if not, otherwise set PSKc as \<key\> (hex format).
 
 ```bash
 > dataset pskc 67c0c203aa0b042bfb5381c47aef4d9e

src/core/api/ip6_api.cpp

@@ -141,7 +141,7 @@ otError otIp6Send(otInstance *aInstance, otMessage *aMessage)
 
     VerifyOrExit(!AsCoreType(aMessage).IsOriginThreadNetif(), error = kErrorInvalidArgs);
 
-    error = AsCoreType(aInstance).Get<Ip6::Ip6>().SendRaw(AsCoreType(aMessage));
+    error = AsCoreType(aInstance).Get<Ip6::Ip6>().SendRaw(OwnedPtr<Message>(AsCoreTypePtr(aMessage)));
 
 exit:
     return error;

src/core/backbone_router/bbr_local.cpp

@@ -62,7 +62,7 @@ Local::Local(Instance &aInstance)
     mDomainPrefixConfig.GetPrefix().SetLength(0);
 
     // Primary Backbone Router Aloc
-    mBackboneRouterPrimaryAloc.InitAsThreadOriginRealmLocalScope();
+    mBackboneRouterPrimaryAloc.InitAsThreadOriginMeshLocal();
     mBackboneRouterPrimaryAloc.GetAddress().GetIid().SetToLocator(Mle::kAloc16BackboneRouterPrimary);
 
     // All Network Backbone Routers Multicast Address.
@@ -364,21 +364,14 @@ Error Local::SetDomainPrefix(const NetworkData::OnMeshPrefixConfig &aConfig)
     return error;
 }
 
-void Local::ApplyMeshLocalPrefix(void)
+void Local::ApplyNewMeshLocalPrefix(void)
 {
     VerifyOrExit(IsEnabled());
 
     Get<BackboneTmfAgent>().UnsubscribeMulticast(mAllNetworkBackboneRouters);
     mAllNetworkBackboneRouters.SetMulticastNetworkPrefix(Get<Mle::MleRouter>().GetMeshLocalPrefix());
     Get<BackboneTmfAgent>().SubscribeMulticast(mAllNetworkBackboneRouters);
 
-    if (IsPrimary())
-    {
-        Get<ThreadNetif>().RemoveUnicastAddress(mBackboneRouterPrimaryAloc);
-        mBackboneRouterPrimaryAloc.GetAddress().SetPrefix(Get<Mle::MleRouter>().GetMeshLocalPrefix());
-        Get<ThreadNetif>().AddUnicastAddress(mBackboneRouterPrimaryAloc);
-    }
-
 exit:
     return;
 }

src/core/backbone_router/bbr_local.hpp

@@ -256,7 +256,7 @@ class Local : public InstanceLocator, private NonCopyable
      * Applies the Mesh Local Prefix.
      *
      */
-    void ApplyMeshLocalPrefix(void);
+    void ApplyNewMeshLocalPrefix(void);
 
     /**
      * Updates the subscription of All Domain Backbone Routers Multicast Address.

src/core/common/tlvs.cpp

@@ -271,7 +271,7 @@ template Error Tlv::FindUintTlv<uint8_t>(const Message &aMessage, uint8_t aType,
 template Error Tlv::FindUintTlv<uint16_t>(const Message &aMessage, uint8_t aType, uint16_t &aValue);
 template Error Tlv::FindUintTlv<uint32_t>(const Message &aMessage, uint8_t aType, uint32_t &aValue);
 
-Error Tlv::FindTlv(const Message &aMessage, uint8_t aType, void *aValue, uint8_t aLength)
+Error Tlv::FindTlv(const Message &aMessage, uint8_t aType, void *aValue, uint16_t aLength)
 {
     Error    error;
     uint16_t offset;
@@ -322,4 +322,32 @@ Error Tlv::AppendTlv(Message &aMessage, uint8_t aType, const void *aValue, uint8
     return error;
 }
 
+const Tlv *Tlv::FindTlv(const void *aTlvsStart, uint16_t aTlvsLength, uint8_t aType)
+{
+    const Tlv *tlv;
+    const Tlv *end = reinterpret_cast<const Tlv *>(reinterpret_cast<const uint8_t *>(aTlvsStart) + aTlvsLength);
+
+    for (tlv = reinterpret_cast<const Tlv *>(aTlvsStart); tlv < end; tlv = tlv->GetNext())
+    {
+        VerifyOrExit((tlv + 1) <= end, tlv = nullptr);
+
+        if (tlv->IsExtended())
+        {
+            VerifyOrExit((As<ExtendedTlv>(tlv) + 1) <= As<ExtendedTlv>(end), tlv = nullptr);
+        }
+
+        VerifyOrExit(tlv->GetNext() <= end, tlv = nullptr);
+
+        if (tlv->GetType() == aType)
+        {
+            ExitNow();
+        }
+    }
+
+    tlv = nullptr;
+
+exit:
+    return tlv;
+}
+
 } // namespace ot