[vendor-info] generalize vendor OUI to support variable lengths (openthread#13258)

This commit generalizes the Vendor OUI (Organizationally Unique
Identifier) handling to support IEEE MAC Address Block Large
(MA-L, 24-bit), Medium(MA-M, 28-bit), and Small (MA-S, 36-bit)
assignments.

Key enhancements:

- Backward-Compatible Config Parsing: The
  `OPENTHREAD_CONFIG_NET_DIAG_VENDOR_OUI` configuration remains fully
  backward compatible. If the macro is set to a traditional 24-bit
  integer (e.g., `0x641666`), it is implicitly parsed as a 24-bit
  OUI.

  For larger or variable-length OUIs, a new explicit 48-bit format is
  supported: `0x[BitLengthInHex][5 OUI Bytes]` (e.g. `0x1c001a2b3000ULL`
  for 28-bit, and `0x24001a2b3c40ULL` for 36-bit). This format
  encodes both prefix length and value into a single integer, making
  it trivial to pass through command-line flags (e.g. `-D...`).

- Compile-Time Validation: Introduced `VendorInfo::OuiParser` template
  class to parse and validate the configured OUI at compile-time
  (`static_assert`). It ensures invalid lengths, out-of-range
  configurations, or non-zero trailing bits fail the build
  immediately.

- New APIs: Replaced legacy `uint32_t` representations with the
  `otThreadVendorOui` containing `mBitLength` and a 5-byte buffer
  `mBytes`. Added new public APIs `otThreadGetVendorOuiInfo()` and
  `otThreadSetVendorOuiInfo()`, while deprecating the older 24-bit OUI
  getters and setters.

- Border Agent & CLI Updates:
  - Updated Border Agent TXT data generation (`vo` key) and parsing
    to correctly handling of new OUI lengths.
  - Updated CLI command utilities to output variable-length OUI bytes
    formatted correctly.
  - Added new `test_vendor_oui.cpp` unit tests to thoroughly validate
    compile-time parsing and runtime class logic.

Author: abtink

include/openthread/border_agent_txt_data.h

@@ -42,6 +42,7 @@
 #include <openthread/dataset.h>
 #include <openthread/error.h>
 #include <openthread/ip6.h>
+#include <openthread/netdiag.h>
 #include <openthread/platform/radio.h>
 
 #ifdef __cplusplus
@@ -61,7 +62,6 @@ extern "C" {
 #define OT_BORDER_AGENT_THREAD_VERSION_SIZE (16) ///< Max size of Thread Version string in `otBorderAgentTxtDataInfo`.
 #define OT_BORDER_AGENT_VENDOR_NAME_SIZE (32)    ///< Max size of Vendor Name string in `otBorderAgentTxtDataInfo`.
 #define OT_BORDER_AGENT_MODEL_NAME_SIZE (32)     ///< Max size of Model Name string in `otBorderAgentTxtDataInfo`.
-#define OT_BORDER_AGENT_VENDOR_OUI_SIZE (3)      ///< Size of Vendor OUI (in bytes) in `otBorderAgentTxtDataInfo`.
 
 /**
  * Represents the Connection Mode in a Border Agent State Bitmap.
@@ -169,7 +169,7 @@ typedef struct otBorderAgentTxtDataInfo
     otExtAddress             mExtAddress;                                         ///< Extended Address.
     char                     mVendorName[OT_BORDER_AGENT_VENDOR_NAME_SIZE];       ///< Vendor Name string.
     char                     mModelName[OT_BORDER_AGENT_MODEL_NAME_SIZE];         ///< Model Name string.
-    uint8_t                  mVendorOui[OT_BORDER_AGENT_VENDOR_OUI_SIZE];         ///< Vendor OUI (24-bit).
+    otThreadVendorOui        mVendorOui;                                          ///< Vendor OUI.
 } otBorderAgentTxtDataInfo;
 
 /**

include/openthread/instance.h

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

include/openthread/netdiag.h

@@ -273,6 +273,50 @@ typedef struct otNetworkDiagChildTable
  */
 typedef otBorderRoutingState otNetworkDiagBrState;
 
+/**
+ * Specifies the maximum size of a Thread Vendor OUI in bytes.
+ */
+#define OT_THREAD_VENDOR_OUI_MAX_SIZE 5
+
+/**
+ * Specifies the bit length of a MAC Address Block Large (MA-L) Vendor OUI.
+ */
+#define OT_THREAD_VENDOR_OUI_MA_L_BIT_LENGTH 24
+
+/**
+ * Specifies the bit length of a MAC Address Block Medium (MA-M) Vendor OUI.
+ */
+#define OT_THREAD_VENDOR_OUI_MA_M_BIT_LENGTH 28
+
+/**
+ * Specifies the bit length of a MAC Address Block Small (MA-S) Vendor OUI.
+ */
+#define OT_THREAD_VENDOR_OUI_MA_S_BIT_LENGTH 36
+
+/**
+ * Represents a Thread Vendor OUI (Organizationally Unique Identifier) which can have different lengths.
+ *
+ * A Vendor OUI can be assigned in one of the following formats:
+ *
+ * - 24-bit Prefix (MA-L): Exactly 3 bytes (24 bits).
+ *   Example: `00-1A-2B` is represented with `mBitLength = 24` and `mBytes = [0x00, 0x1A, 0x2B, 0x00, 0x00]`.
+ *
+ * - 28-bit Prefix (MA-M): Exactly 3.5 bytes (28 bits).
+ *   The half-byte (4 bits) at the end of the prefix occupies the Most Significant Nibble of the 4th byte.
+ *   The Least Significant Nibble of the 4th byte is set to zero.
+ *   Example: `00-1A-2B-3` is represented with `mBitLength = 28` and `mBytes = [0x00, 0x1A, 0x2B, 0x30, 0x00]`.
+ *
+ * - 36-bit Prefix (MA-S): Exactly 4.5 bytes (36 bits).
+ *   The half-byte (4 bits) at the end of the prefix occupies the Most Significant Nibble of the 5th byte.
+ *   The Least Significant Nibble of the 5th byte is set to zero.
+ *   Example: `00-1A-2B-3C-4` is represented with `mBitLength = 36` and `mBytes = [0x00, 0x1A, 0x2B, 0x3C, 0x40]`.
+ */
+typedef struct otThreadVendorOui
+{
+    uint8_t mBitLength;                            ///< The OUI prefix length in bits (24, 28, or 36).
+    uint8_t mBytes[OT_THREAD_VENDOR_OUI_MAX_SIZE]; ///< The OUI bytes in big-endian order.
+} otThreadVendorOui;
+
 /**
  * Represents a Network Diagnostic TLV.
  */
@@ -426,19 +470,78 @@ const char *otThreadGetVendorSwVersion(otInstance *aInstance);
 const char *otThreadGetVendorAppUrl(otInstance *aInstance);
 
 /**
- * Represents an unspecified Vendor OUI.
+ * Gets the vendor OUI.
+ *
+ * If no vendor OUI is yet set/configured on device, the `mBitLength` in @p aOui will be zero.
+ *
+ * @param[in]   aInstance  A pointer to an OpenThread instance.
+ * @param[out]  aOui       A pointer to an `otThreadVendorOui` to return the vendor OUI.
+ */
+void otThreadGetVendorOuiInfo(otInstance *aInstance, otThreadVendorOui *aOui);
+
+/**
+ * Sets the vendor OUI.
+ *
+ * Requires `OPENTHREAD_CONFIG_NET_DIAG_VENDOR_INFO_SET_API_ENABLE`.
+ *
+ * @param[in]  aInstance  A pointer to an OpenThread instance.
+ * @param[in]  aOui       A pointer to the `otThreadVendorOui` to set.
+ *
+ * @retval OT_ERROR_NONE           Successfully set the vendor OUI.
+ * @retval OT_ERROR_INVALID_ARGS   @p aOui has an invalid length.
+ */
+otError otThreadSetVendorOuiInfo(otInstance *aInstance, const otThreadVendorOui *aOui);
+
+#define OT_THREAD_VENDOR_OUI_STRING_SIZE 16 ///< Recommended size for string representation of a vendor OUI.
+
+/**
+ * Converts a given vendor OUI to a human-readable string.
+ *
+ * The generated string format is hyphen-separated uppercase hexadecimal bytes (e.g., "00-1A-2B" for a 24-bit OUI).
+ * For 28-bit and 36-bit OUIs, the trailing 4-bit nibble is appended as a single hexadecimal digit (e.g., "00-1A-2B-3"
+ * for a 28-bit OUI). If @p aOui is invalid or unspecified, the string "unspecified" is returned.
+ *
+ * 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.
+ *
+ * @param[in]  aOui      The vendor OUI to convert.
+ * @param[out] aBuffer   A pointer to a char array to output the string (MUST NOT be NULL).
+ * @param[in]  aSize     The size of @p aBuffer (in bytes). Recommended to use `OT_THREAD_VENDOR_OUI_STRING_SIZE`.
  */
-#define OT_THREAD_UNSPECIFIED_VENDOR_OUI (0xffffffff)
+void otThreadVendorOuiToString(const otThreadVendorOui *aOui, char *aBuffer, uint16_t aSize);
+
+#define OT_THREAD_UNSPECIFIED_VENDOR_OUI (0xffffffff) ///< Represents an unspecified Vendor OUI.
 
 /**
- * Get the vendor OUI-24
+ * Gets the vendor OUI-24.
+ *
+ * @deprecated This function is deprecated. Use `otThreadGetVendorOuiInfo()` instead.
+ *
+ * If the configured Vendor OUI has a prefix length greater than 24 bits, this function returns the most significant
+ * 24 bits (first 3 bytes) of the OUI to maintain backward compatibility.
  *
  * @param[in]  aInstance      A pointer to an OpenThread instance.
  *
- * @returns The vendor OUI-24 value in hex format, or `OT_THREAD_UNSPECIFIED_VENDOR_OUI` is not specified.
+ * @returns The vendor OUI-24 value, or `OT_THREAD_UNSPECIFIED_VENDOR_OUI` if not specified.
  */
 uint32_t otThreadGetVendorOui(otInstance *aInstance);
 
+/**
+ * Sets the vendor OUI-24.
+ *
+ * @deprecated This function is deprecated. Use `otThreadSetVendorOuiInfo()` instead.
+ *
+ * Requires `OPENTHREAD_CONFIG_NET_DIAG_VENDOR_INFO_SET_API_ENABLE`.
+ *
+ * @param[in] aInstance    A pointer to an OpenThread instance.
+ * @param[in] aVendorOui   The vendor OUI-24 value in Hexadecimal representation (e.g., OUI 64-16-66 is represented as
+ *                         `0x641666`). Must be a 24-bit value.
+ *
+ * @retval OT_ERROR_NONE          Successfully set the vendor OUI.
+ * @retval OT_ERROR_INVALID_ARGS  @p aVendorOui is not a valid 24-bit value.
+ */
+otError otThreadSetVendorOui(otInstance *aInstance, uint32_t aVendorOui);
+
 /**
  * Set the vendor name string.
  *
@@ -508,20 +611,6 @@ otError otThreadSetVendorSwVersion(otInstance *aInstance, const char *aVendorSwV
  */
 otError otThreadSetVendorAppUrl(otInstance *aInstance, const char *aVendorAppUrl);
 
-/**
- * Set the vendor OUI-24.
- *
- * Requires `OPENTHREAD_CONFIG_NET_DIAG_VENDOR_INFO_SET_API_ENABLE`.
- *
- * @param[in] aInstance    A pointer to an OpenThread instance.
- * @param[in] aVendorOui   The vendor OUI-24 value in Hexadecimal representation (e.g., OUI 64-16-66 is represented as
- *                         `0x641666`). Must be a 24-bit value.
- *
- * @retval OT_ERROR_NONE          Successfully set the vendor OUI.
- * @retval OT_ERROR_INVALID_ARGS  @p aVendorOui is not a valid 24-bit value.
- */
-otError otThreadSetVendorOui(otInstance *aInstance, uint32_t aVendorOui);
-
 /**
  * Callback function pointer to notify when a Network Diagnostic Reset request message is received for the
  * `OT_NETWORK_DIAGNOSTIC_TLV_NON_PREFERRED_CHANNELS` TLV.

src/cli/cli.cpp

@@ -756,8 +756,8 @@ void Interpreter::OutputBorderAgentTxtDataInfo(uint8_t aIndentSize, const otBord
 
     if (aInfo.mHasVendorOui)
     {
-        OutputLine(aIndentSize, "VendorOui: %02X-%02X-%02X", aInfo.mVendorOui[0], aInfo.mVendorOui[1],
-                   aInfo.mVendorOui[2]);
+        OutputFormat(aIndentSize, "VendorOui: ");
+        OutputVendorOuiLine(aInfo.mVendorOui);
     }
 
     if (aInfo.mHasStateBitmap)
@@ -7600,23 +7600,16 @@ template <> otError Interpreter::Process<Cmd("vendor")>(Arg aArgs[])
      * Done
      * @endcode
      * @par api_copy
-     * #otThreadGetVendorOui
+     * #otThreadGetVendorOuiInfo
      */
     else if (aArgs[0] == "oui")
     {
         if (aArgs[1].IsEmpty())
         {
-            uint32_t oui = otThreadGetVendorOui(GetInstancePtr());
+            otThreadVendorOui oui;
 
-            if (oui == OT_THREAD_UNSPECIFIED_VENDOR_OUI)
-            {
-                OutputLine("unspecified");
-            }
-            else
-            {
-                OutputLine("%02X-%02X-%02X", static_cast<uint8_t>((oui >> 16) & 0xff),
-                           static_cast<uint8_t>((oui >> 8) & 0xff), static_cast<uint8_t>(oui & 0xff));
-            }
+            otThreadGetVendorOuiInfo(GetInstancePtr(), &oui);
+            OutputVendorOuiLine(oui);
 
             error = OT_ERROR_NONE;
         }

src/cli/cli_utils.cpp

@@ -231,6 +231,20 @@ void Utils::OutputSockAddrLine(const otSockAddr &aSockAddr)
     OutputNewLine();
 }
 
+void Utils::OutputVendorOui(const otThreadVendorOui &aOui)
+{
+    char string[OT_THREAD_VENDOR_OUI_STRING_SIZE];
+
+    otThreadVendorOuiToString(&aOui, string, sizeof(string));
+    OutputFormat("%s", string);
+}
+
+void Utils::OutputVendorOuiLine(const otThreadVendorOui &aOui)
+{
+    OutputVendorOui(aOui);
+    OutputNewLine();
+}
+
 void Utils::OutputDnsTxtData(const uint8_t *aTxtData, uint16_t aTxtDataLength)
 {
     OutputDnsTxtData(/* aKeyValuePerLine */ false, 0, aTxtData, aTxtDataLength);

src/cli/cli_utils.hpp

@@ -42,6 +42,7 @@
 #include <openthread/border_routing.h>
 #include <openthread/cli.h>
 #include <openthread/joiner.h>
+#include <openthread/netdiag.h>
 #include <openthread/thread.h>
 
 #include "cli_config.h"
@@ -431,6 +432,20 @@ class Utils
      */
     void OutputSockAddrLine(const otSockAddr &aSockAddr);
 
+    /**
+     * Outputs the Vendor OUI to the CLI console.
+     *
+     * @param[in] aOui  A reference to the Vendor OUI.
+     */
+    void OutputVendorOui(const otThreadVendorOui &aOui);
+
+    /**
+     * Outputs the Vendor OUI to the CLI console and appends a newline.
+     *
+     * @param[in] aOui  A reference to the Vendor OUI.
+     */
+    void OutputVendorOuiLine(const otThreadVendorOui &aOui);
+
     /**
      * Outputs DNS TXT data to the CLI console.
      *

src/core/api/netdiag_api.cpp

@@ -85,7 +85,24 @@ const char *otThreadGetVendorAppUrl(otInstance *aInstance)
     return AsCoreType(aInstance).Get<VendorInfo>().GetAppUrl();
 }
 
-uint32_t otThreadGetVendorOui(otInstance *aInstance) { return AsCoreType(aInstance).Get<VendorInfo>().GetOui(); }
+void otThreadGetVendorOuiInfo(otInstance *aInstance, otThreadVendorOui *aOui)
+{
+    AssertPointerIsNotNull(aOui);
+
+    *aOui = AsCoreType(aInstance).Get<VendorInfo>().GetOui();
+}
+
+void otThreadVendorOuiToString(const otThreadVendorOui *aOui, char *aBuffer, uint16_t aSize)
+{
+    AsCoreType(aOui).ToString(aBuffer, aSize);
+}
+
+uint32_t otThreadGetVendorOui(otInstance *aInstance)
+{
+    // This API is deprecated. Use `otThreadGetVendorOuiInfo()` instead
+
+    return AsCoreType(aInstance).Get<VendorInfo>().GetOui().GetAsOui24();
+}
 
 #if OPENTHREAD_CONFIG_NET_DIAG_VENDOR_INFO_SET_API_ENABLE
 
@@ -109,9 +126,28 @@ otError otThreadSetVendorAppUrl(otInstance *aInstance, const char *aVendorAppUrl
     return AsCoreType(aInstance).Get<VendorInfo>().SetAppUrl(aVendorAppUrl);
 }
 
+otError otThreadSetVendorOuiInfo(otInstance *aInstance, const otThreadVendorOui *aOui)
+{
+    return AsCoreType(aInstance).Get<VendorInfo>().SetOui(AsCoreType(aOui));
+}
+
 otError otThreadSetVendorOui(otInstance *aInstance, uint32_t aVendorOui)
 {
-    return AsCoreType(aInstance).Get<VendorInfo>().SetOui(aVendorOui);
+    // This API is deprecated, use `otThreadSetVendorOuiInfo()` instead
+
+    Error           error;
+    VendorInfo::Oui oui;
+
+    VerifyOrExit(aVendorOui <= 0xffffff, error = kErrorInvalidArgs);
+
+    oui.Clear();
+    oui.mBitLength = 24;
+    BigEndian::WriteUint24(aVendorOui, oui.mBytes);
+
+    error = AsCoreType(aInstance).Get<VendorInfo>().SetOui(oui);
+
+exit:
+    return error;
 }
 
 #endif // OPENTHREAD_CONFIG_NET_DIAG_VENDOR_INFO_SET_API_ENABLE

src/core/config/net_diag.h

@@ -91,10 +91,22 @@
 /**
  * @def OPENTHREAD_CONFIG_NET_DIAG_VENDOR_OUI
  *
- * Specifies the default Vendor OUI-24 value in Hexadecimal representation (e.g., OUI 64-16-66  is represented as
- * `0x641666`).
+ * Specifies the default Vendor OUI (Organizationally Unique Identifier) value.
  *
- * The value of `0xffffffff` (UINT32_MAX) is used to indicate OUI is not specified.
+ * This configuration supports multiple layout formats to maintain backward compatibility:
+ *
+ * - 24-bit OUI (MA-L): Hexadecimal representation of a 24-bit value (e.g., OUI 64-16-66 is represented as
+ *   `0x641666`). Values <= `0xffffff` are implicitly treated as a 24-bit OUI.
+ *
+ * - Explicit OUI with various lengths (24, 28, or 36 bits): A 48-bit hexadecimal value where the most significant
+ *   byte (bits 40-47) represents the prefix bit-length, and the lower 5 bytes (bits 0-39) represent the OUI bytes
+ *   in big-endian order:
+ *   - 28-bit OUI `00-1A-2B-3` is represented as    `0x1c001a2b3000ULL`.
+ *   - 36-bit OUI `00-1A-2B-3C-4` is represented as `0x24001a2b3c40ULL`.
+ *
+ * The value of `0xffffffff` (UINT32_MAX) is used to indicate the Vendor OUI is not specified.
+ *
+ * The configured value is validated at compile-time to ensure it conforms to one of the supported prefix lengths.
  */
 #ifndef OPENTHREAD_CONFIG_NET_DIAG_VENDOR_OUI
 #define OPENTHREAD_CONFIG_NET_DIAG_VENDOR_OUI (0xffffffff)