src/lib/core/CHIPTLVData.hpp

   1 /*
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *    Copyright (c) 2015-2017 Nest Labs, Inc.
   5  *
   6  *    Licensed under the Apache License, Version 2.0 (the "License");
   7  *    you may not use this file except in compliance with the License.
   8  *    You may obtain a copy of the License at
   9  *
  10  *        http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  *    Unless required by applicable law or agreed to in writing, software
  13  *    distributed under the License is distributed on an "AS IS" BASIS,
  14  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  *    See the License for the specific language governing permissions and
  16  *    limitations under the License.
  17  */
  18
  19 /**
  20  *    @file
  21  *      This file contains macros to create static CHIP TLV data.
  22  *
  23  *    These macros are designed to be used in statically initializing a byte array
  24  *    containing various TLV elements. TLVWriter can achieve similar functionality
  25  *    but only on RAM, while macros here can be used to create TLV elements in ROM.
  26  *
  27  */
  28
  29 #pragma once
  30
  31 #include <stdint.h>
  32
  33 #include <core/CHIPTLV.h>
  34
  35 /*
  36  *  @brief Integral truncate L to the least significant 32-bit
  37  *
  38  *  @note Integral truncate would take the least significant bits, regardless of hardware endianness.
  39  */
  40 #define CHIP_TLV_GetLower32From64(v) ((uint32_t)(((uint64_t)(v) >> 0) & 0xFFFFFFFFUL))
  41
  42 /*
  43  *  @brief Integral truncate argument X to the next least significant 32-bit
  44  *
  45  *  @note Right bit shift gets rid of the least significant bits, regardless of hardware endianness.
  46  */
  47 #define CHIP_TLV_GetUpper32From64(v) ((uint32_t)(((uint64_t)(v) >> 32) & 0xFFFFFFFFUL))
  48
  49 /*
  50  *  @brief Integral truncate L to the least significant 16-bit
  51  *
  52  *  @note Integral truncate would take the least significant bits, regardless of hardware endianness.
  53  */
  54 #define CHIP_TLV_GetLower16From32(v) ((uint16_t)(((uint32_t)(v) >> 0) & 0xFFFFU))
  55
  56 /*
  57  *  @brief Integral truncate argument X to the next least significant 16-bit
  58  *
  59  *  @note Right bit shift gets rid of the least significant bits, regardless of hardware endianness.
  60  */
  61 #define CHIP_TLV_GetUpper16From32(v) ((uint16_t)(((uint32_t)(v) >> 16) & 0xFFFFU))
  62
  63 /*
  64  *  @brief Integral truncate L to the least significant 8-bit
  65  *
  66  *  @note Integral truncate would take the least significant bits, regardless of hardware endianness.
  67  */
  68 #define CHIP_TLV_GetLower8From16(v) ((uint8_t)(((uint16_t)(v) >> 0) & 0xFFU))
  69
  70 /*
  71  *  @brief Integral truncate argument X to the next least significant 8-bit
  72  *
  73  *  @note Right bit shift gets rid of the least significant bits, regardless of hardware endianness.
  74  */
  75 #define CHIP_TLV_GetUpper8From16(v) ((uint8_t)(((uint16_t)(v) >> 8) & 0xFFU))
  76
  77 /*
  78  *  @brief Integral truncate argument v to 8-bit
  79  *
  80  *  @note Integral truncate would take the least significant bits, regardless of hardware endianness.
  81  */
  82 #define CHIP_TLV_Serialize8(v) ((uint8_t)(v))
  83
  84 /*
  85  *  @brief Integral truncate argument v to 16-bit, and then serialize it using CHIP standard Little Endian order
  86  *
  87  *  @note Integral truncate would preserve the least significant bits, regardless of hardware endianness.
  88  *     Right bit shift gets rid of the least significant bits, regardless of hardware endianness.
  89  */
  90 #define CHIP_TLV_Serialize16(v) CHIP_TLV_GetLower8From16(v), CHIP_TLV_GetUpper8From16(v)
  91
  92 /*
  93  *  @brief Integral truncate argument v to 32-bit, and then serialize it using CHIP standard Little Endian order
  94  */
  95 #define CHIP_TLV_Serialize32(v)                                                                                                    \
  96     CHIP_TLV_Serialize16(CHIP_TLV_GetLower16From32(v)), CHIP_TLV_Serialize16(CHIP_TLV_GetUpper16From32(v))
  97
  98 /*
  99  *  @brief Integral truncate argument v to 64-bit, and then serialize it using CHIP standard Little Endian order
 100  */
 101 #define CHIP_TLV_Serialize64(v)                                                                                                    \
 102     CHIP_TLV_Serialize32(CHIP_TLV_GetLower32From64(v)), CHIP_TLV_Serialize32(CHIP_TLV_GetUpper32From64(v))
 103
 104 /*
 105  *  @brief Specifies an anonymous TLV element, which doesn't have any tag
 106  */
 107 #define CHIP_TLV_TAG_ANONYMOUS chip::TLV::TLVTagControl::Anonymous
 108
 109 /*
 110  *  @brief Specifies a TLV element with a context-specific tag
 111  *  @param Tag      The context-specific tag for this TLV element. Would be truncated to 8 bits.
 112  */
 113 #define CHIP_TLV_TAG_CONTEXT_SPECIFIC(Tag) chip::TLV::TLVTagControl::ContextSpecific, CHIP_TLV_Serialize8(Tag)
 114
 115 /*
 116  *  @brief Specifies a TLV element with a Common Profile tag
 117  *  @param Tag      The tag for this TLV element, defined under Common Profile.
 118  *                  Would be truncated to 16 bites.
 119  */
 120 #define CHIP_TLV_TAG_COMMON_PROFILE_2Bytes(Tag) chip::TLV::TLVTagControl::CommonProfile_2Bytes, CHIP_TLV_Serialize16(Tag)
 121
 122 /*
 123  *  @brief Specifies a TLV element with a Common Profile tag
 124  *  @param Tag      The tag for this TLV element, defined under Common Profile.
 125  *                  Would be truncated to 32 bites.
 126  */
 127 #define CHIP_TLV_TAG_COMMON_PROFILE_4Bytes(Tag) chip::TLV::TLVTagControl::CommonProfile_4Bytes, CHIP_TLV_Serialize32(Tag)
 128
 129 /*
 130  *  @brief Specifies a TLV element with an Implicit Profile tag
 131  *  @param Tag      The tag for this TLV element, defined under the current implicit profile.
 132  *                  Would be truncated to 16 bits.
 133  */
 134 #define CHIP_TLV_TAG_IMPLICIT_PROFILE_2Bytes(Tag) chip::TLV::TLVTagControl::ImplicitProfile_2Bytes, CHIP_TLV_Serialize16(Tag)
 135
 136 /*
 137  *  @brief Specifies a TLV element with an Implicit Profile tag
 138  *  @param Tag      The tag for this TLV element, defined under the current implicit profile.
 139  *                  Would be truncated to 32 bits.
 140  */
 141 #define CHIP_TLV_TAG_IMPLICIT_PROFILE_4Bytes(Tag) chip::TLV::TLVTagControl::ImplicitProfile_4Bytes, CHIP_TLV_Serialize32(Tag)
 142
 143 /*
 144  *  @brief Specifies a TLV element with a Fully Qualified tag
 145  *  @param ProfileId    {Vendor ID, Profile Number}, as in #CHIPProfileId
 146  *  @param Tag          The tag for this TLV element, defined under ProfileId.
 147  *                      Would be truncated to 16 bits.
 148  */
 149 #define CHIP_TLV_TAG_FULLY_QUALIFIED_6Bytes(ProfileId, Tag)                                                                        \
 150     chip::TLV::TLVTagControl::FullyQualified_6Bytes, CHIP_TLV_Serialize16(ProfileId >> 16), CHIP_TLV_Serialize16(ProfileId),       \
 151         CHIP_TLV_Serialize16(Tag)
 152
 153 /*
 154  *  @brief Specifies a TLV element with a Fully Qualified tag
 155  *  @param ProfileId    {Vendor ID, Profile Number}, as in #CHIPProfileId
 156  *  @param Tag          The tag for this TLV element, defined under ProfileId.
 157  *                      Would be truncated to 32 bits.
 158  */
 159 #define CHIP_TLV_TAG_FULLY_QUALIFIED_8Bytes(ProfileId, Tag)                                                                        \
 160     chip::TLV::TLVTagControl::FullyQualified_8Bytes, CHIP_TLV_Serialize16(ProfileId >> 16), CHIP_TLV_Serialize16(ProfileId),       \
 161         CHIP_TLV_Serialize32(Tag)
 162
 163 /*
 164  *  @brief Specifies a NULL TLV element, which has just the tag but no value
 165  *  @param TagSpec      Should be filled with macros begin with CHIP_TLV_TAG_
 166  */
 167 #define CHIP_TLV_NULL(TagSpec) chip::TLV::TLVElementType::Null | TagSpec
 168
 169 /*
 170  *  @brief Specifies a Structure TLV element, marking the beginning of a Structure
 171  *  @param TagSpec      Should be filled with macros begin with CHIP_TLV_TAG_
 172  */
 173 #define CHIP_TLV_STRUCTURE(TagSpec) chip::TLV::TLVElementType::Structure | TagSpec
 174
 175 /*
 176  *  @brief Specifies a Array TLV element, marking the beginning of an Array
 177  *  @param TagSpec      Should be filled with macros begin with CHIP_TLV_TAG_
 178  */
 179 #define CHIP_TLV_ARRAY(TagSpec) chip::TLV::TLVElementType::Array | TagSpec
 180
 181 /*
 182  *  @brief Specifies a Path TLV element, marking the beginning of a Path
 183  *  @param TagSpec      Should be filled with macros begin with CHIP_TLV_TAG_
 184  */
 185 #define CHIP_TLV_PATH(TagSpec) chip::TLV::TLVElementType::Path | TagSpec
 186
 187 /*
 188  *  @brief Specifies a Boolean TLV element, which can be either true or false
 189  *  @param TagSpec      Should be filled with macros begin with CHIP_TLV_TAG_
 190  *  @param Value        Should be either true or false
 191  */
 192 #define CHIP_TLV_BOOL(TagSpec, Value)                                                                                              \
 193     ((Value) ? chip::TLV::TLVElementType::BooleanTrue : chip::TLV::TLVElementType::BooleanFalse) | TagSpec
 194
 195 /**
 196  *  @brief
 197  *    Specifies a Single Precision Floating Point TLV element, marking the beginning of 32-bit data
 198  *
 199  *  @param TagSpec      Should be filled with macros beginning with CHIP_TLV_TAG_
 200  *
 201  *  @param ...          Bytes representing the floating point value to serialize
 202  */
 203 #define CHIP_TLV_FLOAT32(TagSpec, ...) chip::TLV::TLVElementType::FloatingPointNumber32 | TagSpec, ##__VA_ARGS__
 204
 205 /**
 206  *  @brief
 207  *    Specifies a Double Precision Floating Point TLV element, marking the beginning of 64-bit data
 208  *
 209  *  @param TagSpec      Should be filled with macros begin with CHIP_TLV_TAG_
 210  *
 211  *  @param ...          Bytes representing the floating point value to serialize
 212  */
 213 #define CHIP_TLV_FLOAT64(TagSpec, ...) chip::TLV::TLVElementType::FloatingPointNumber64 | TagSpec, ##__VA_ARGS__
 214
 215 /*
 216  *  @brief Specifies a EndOfContainer TLV element, marking the end of a Structure, Array, or Path
 217  */
 218 #define CHIP_TLV_END_OF_CONTAINER chip::TLV::TLVElementType::EndOfContainer | chip::TLV::TLVTagControl::Anonymous
 219
 220 /*
 221  *  @brief Specifies a EndOfContainer TLV element, marking the end of a Structure, Array, or Path
 222  */
 223 #define CHIP_TLV_END_OF_STRUCTURE CHIP_TLV_END_OF_CONTAINER
 224
 225 /*
 226  *  @brief Specifies a EndOfContainer TLV element, marking the end of a Structure, Array, or Path
 227  */
 228 #define CHIP_TLV_END_OF_ARRAY CHIP_TLV_END_OF_CONTAINER
 229
 230 /*
 231  *  @brief Specifies a EndOfContainer TLV element, marking the end of a Structure, Array, or Path
 232  */
 233 #define CHIP_TLV_END_OF_PATH CHIP_TLV_END_OF_CONTAINER
 234
 235 /*
 236  *  @brief Specifies an 8-bit Signed Integer TLV element
 237  *  @param TagSpec      Should be filled with macros begin with CHIP_TLV_TAG_
 238  *  @param Value        Would be first converted to int8_t, and then serialized
 239  */
 240 #define CHIP_TLV_INT8(TagSpec, Value) chip::TLV::TLVElementType::Int8 | TagSpec, CHIP_TLV_Serialize8(int8_t(Value))
 241
 242 /*
 243  *  @brief Specifies a 16-bit Signed Integer TLV element
 244  *  @param TagSpec      Should be filled with macros begin with CHIP_TLV_TAG_
 245  *  @param Value        Would be first converted to int16_t, and then serialized
 246  */
 247 #define CHIP_TLV_INT16(TagSpec, Value) chip::TLV::TLVElementType::Int16 | TagSpec, CHIP_TLV_Serialize16(int16_t(Value))
 248
 249 /*
 250  *  @brief Specifies a 32-bit Signed Integer TLV element
 251  *  @param TagSpec      Should be filled with macros begin with CHIP_TLV_TAG_
 252  *  @param Value        Would be first converted to int32_t, and then serialized
 253  */
 254 #define CHIP_TLV_INT32(TagSpec, Value) chip::TLV::TLVElementType::Int32 | TagSpec, CHIP_TLV_Serialize32(int32_t(Value))
 255
 256 /*
 257  *  @brief Specifies a 32-bit Signed Integer TLV element
 258  *  @param TagSpec      Should be filled with macros begin with CHIP_TLV_TAG_
 259  *  @param Value        Would be first converted to int64_t, and then serialized
 260  */
 261 #define CHIP_TLV_INT64(TagSpec, Value) chip::TLV::TLVElementType::Int64 | TagSpec, CHIP_TLV_Serialize64(int64_t(Value))
 262
 263 /*
 264  *  @brief Specifies an 8-bit Unsigned Integer TLV element
 265  *  @param TagSpec      Should be filled with macros begin with CHIP_TLV_TAG_
 266  *  @param Value        Would be first converted to (uint8_t), and then serialized
 267  */
 268 #define CHIP_TLV_UINT8(TagSpec, Value) chip::TLV::TLVElementType::UInt8 | TagSpec, CHIP_TLV_Serialize8((uint8_t)(Value))
 269
 270 /*
 271  *  @brief Specifies a 16-bit Unsigned Integer TLV element
 272  *  @param TagSpec      Should be filled with macros begin with CHIP_TLV_TAG_
 273  *  @param Value        Would be first converted to (uint16_t), and then serialized
 274  */
 275 #define CHIP_TLV_UINT16(TagSpec, Value) chip::TLV::TLVElementType::UInt16 | TagSpec, CHIP_TLV_Serialize16((uint16_t)(Value))
 276
 277 /*
 278  *  @brief Specifies a 32-bit Unsigned Integer TLV element
 279  *  @param TagSpec      Should be filled with macros begin with CHIP_TLV_TAG_
 280  *  @param Value        Would be first converted to (uint32_t), and then serialized
 281  */
 282 #define CHIP_TLV_UINT32(TagSpec, Value) chip::TLV::TLVElementType::UInt32 | TagSpec, CHIP_TLV_Serialize32((uint32_t)(Value))
 283
 284 /*
 285  *  @brief Specifies a 64-bit Unsigned Integer TLV element
 286  *  @param TagSpec      Should be filled with macros begin with CHIP_TLV_TAG_
 287  *  @param Value        Would be first converted to (uint64_t), and then serialized
 288  */
 289 #define CHIP_TLV_UINT64(TagSpec, Value) chip::TLV::TLVElementType::UInt64 | TagSpec, CHIP_TLV_Serialize64((uint64_t)(Value))
 290
 291 /**
 292  *  @brief
 293  *    Specifies an UTF8 String TLV element, marking the beginning of String data
 294  *
 295  *  @param TagSpec              Should be filled with macros begin with CHIP_TLV_TAG_
 296  *
 297  *  @param StringLength         Number of bytes in this string, must be less than 0x100
 298  *
 299  *  @param ...                  Bytes representing the string characters to serialize
 300  */
 301 #define CHIP_TLV_UTF8_STRING_1ByteLength(TagSpec, StringLength, ...)                                                               \
 302     chip::TLV::TLVElementType::UTF8String_1ByteLength | TagSpec, CHIP_TLV_Serialize8((uint8_t)(StringLength)), ##__VA_ARGS__
 303
 304 /**
 305  *  @brief
 306  *    Specifies an UTF8 String TLV element, marking the beginning of String data
 307  *
 308  *  @param TagSpec              Should be filled with macros begin with CHIP_TLV_TAG_
 309  *
 310  *  @param StringLength         Number of bytes in this string, must be less than 0x10000
 311  *
 312  *  @param ...                  Bytes representing the string characters to serialize
 313  */
 314 #define CHIP_TLV_UTF8_STRING_2ByteLength(TagSpec, StringLength, ...)                                                               \
 315     chip::TLV::TLVElementType::UTF8String_2ByteLength | TagSpec, CHIP_TLV_Serialize16((uint16_t)(StringLength)), ##__VA_ARGS__
 316
 317 /**
 318  *  @brief
 319  *    Specifies an UTF8 String TLV element, marking the beginning of String data
 320  *
 321  *  @param TagSpec              Should be filled with macros begin with CHIP_TLV_TAG_
 322  *
 323  *  @param StringLength         Number of bytes in this string, must be less than 0x100000000
 324  *
 325  *  @param ...                  Bytes representing the string characters to serialize
 326  */
 327 #define CHIP_TLV_UTF8_STRING_4ByteLength(TagSpec, StringLength, ...)                                                               \
 328     chip::TLV::TLVElementType::UTF8String_4ByteLength | TagSpec, CHIP_TLV_Serialize32((uint32_t)(StringLength)), ##__VA_ARGS__
 329
 330 /**
 331  *  @brief
 332  *    Specifies an UTF8 String TLV element, marking the beginning of String data
 333  *
 334  *  @param TagSpec              Should be filled with macros begin with CHIP_TLV_TAG_
 335  *
 336  *  @param StringLength         Number of bytes in this string, must be less than 0x10000000000000000
 337  *
 338  *  @param ...                  Bytes representing the string characters to serialize
 339  */
 340 #define CHIP_TLV_UTF8_STRING_8ByteLength(TagSpec, StringLength, ...)                                                               \
 341     chip::TLV::TLVElementType::UTF8String_8ByteLength | TagSpec, CHIP_TLV_Serialize64((uint64_t)(StringLength)), ##__VA_ARGS__
 342
 343 /**
 344  *  @brief
 345  *    Specifies a BYTE String TLV element, marking the beginning of String data
 346  *
 347  *  @param TagSpec              Should be filled with macros begin with CHIP_TLV_TAG_
 348  *
 349  *  @param StringLength         Number of bytes in this string, must be less than 0x100
 350  *
 351  *  @param ...                  Bytes to serialize
 352  */
 353 #define CHIP_TLV_BYTE_STRING_1ByteLength(TagSpec, StringLength, ...)                                                               \
 354     chip::TLV::TLVElementType::ByteString_1ByteLength | TagSpec, CHIP_TLV_Serialize8((uint8_t)(StringLength)), ##__VA_ARGS__
 355
 356 /**
 357  *  @brief
 358  *    Specifies a BYTE String TLV element, marking the beginning of String data
 359  *
 360  *  @param TagSpec              Should be filled with macros begin with CHIP_TLV_TAG_
 361  *
 362  *  @param StringLength         Number of bytes in this string, must be less than 0x10000
 363  *
 364  *  @param ...                  Bytes to serialize
 365  */
 366 #define CHIP_TLV_BYTE_STRING_2ByteLength(TagSpec, StringLength, ...)                                                               \
 367     chip::TLV::TLVElementType::ByteString_2ByteLength | TagSpec, CHIP_TLV_Serialize16((uint16_t)(StringLength)), ##__VA_ARGS__
 368
 369 /**
 370  *  @brief
 371  *    Specifies a BYTE String TLV element, marking the beginning of String data
 372  *
 373  *  @param TagSpec              Should be filled with macros begin with CHIP_TLV_TAG_
 374  *
 375  *  @param StringLength         Number of bytes in this string, must be less than 0x100000000
 376  *
 377  *  @param ...                  Bytes to serialize
 378  */
 379 #define CHIP_TLV_BYTE_STRING_4ByteLength(TagSpec, StringLength, ...)                                                               \
 380     chip::TLV::TLVElementType::ByteString_4ByteLength | TagSpec, CHIP_TLV_Serialize32((uint32_t)(StringLength)), ##__VA_ARGS__
 381
 382 /**
 383  *  @brief
 384  *    Specifies a BYTE String TLV element, marking the beginning of String data
 385  *
 386  *  @param TagSpec              Should be filled with macros begin with CHIP_TLV_TAG_
 387  *
 388  *  @param StringLength         Number of bytes in this string, must be less than 0x10000000000000000
 389  *
 390  *  @param ...                  Bytes to serialize
 391  */
 392 #define CHIP_TLV_BYTE_STRING_8ByteLength(TagSpec, StringLength, ...)                                                               \
 393     chip::TLV::TLVElementType::ByteString_8ByteLength | TagSpec, CHIP_TLV_Serialize64((uint64_t)(StringLength)), ##__VA_ARGS__