src/lib/core/CHIPTLVTags.h

   1 /*
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *    Copyright (c) 2013-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 definitions for working with CHIP TLV tags.
  22  *
  23  */
  24
  25 #pragma once
  26
  27 namespace chip {
  28 namespace TLV {
  29
  30 enum TLVCommonProfiles
  31 {
  32     /**
  33      * Used to indicate the absence of a profile id in a variable or member.
  34      * This is essentially the same as kCHIPProfile_NotSpecified defined in CHIPProfiles.h
  35      */
  36     kProfileIdNotSpecified = 0xFFFFFFFF,
  37
  38     // TODO: Replace with chip::Profiles::kCHIPProfile_Common
  39     kCommonProfileId = 0
  40 };
  41
  42 // TODO: Move to private namespace
  43 enum TLVTagFields
  44 {
  45     kProfileIdMask    = 0xFFFFFFFF00000000ULL,
  46     kProfileIdShift   = 32,
  47     kVendorIdShift    = 48,
  48     kProfileNumShift  = 32,
  49     kTagNumMask       = 0x00000000FFFFFFFFULL,
  50     kSpecialTagMarker = 0xFFFFFFFF00000000ULL,
  51     kContextTagMaxNum = 256
  52 };
  53
  54 // TODO: Move to private namespace
  55 enum class TLVTagControl : uint8_t
  56 {
  57     // IMPORTANT: All values here must have no bits in common with specified
  58     // values of TLVElementType.
  59     Anonymous              = 0x00,
  60     ContextSpecific        = 0x20,
  61     CommonProfile_2Bytes   = 0x40,
  62     CommonProfile_4Bytes   = 0x60,
  63     ImplicitProfile_2Bytes = 0x80,
  64     ImplicitProfile_4Bytes = 0xA0,
  65     FullyQualified_6Bytes  = 0xC0,
  66     FullyQualified_8Bytes  = 0xE0
  67 };
  68
  69 template <typename T>
  70 inline uint8_t operator>>(TLVTagControl lhs, const T & rhs)
  71 {
  72     return static_cast<uint8_t>(static_cast<uint8_t>(lhs) >> rhs);
  73 }
  74
  75 // TODO: Move to private namespace
  76 enum
  77 {
  78     kTLVTagControlMask  = 0xE0,
  79     kTLVTagControlShift = 5
  80 };
  81
  82 /**
  83  * Generates the API representation of a profile-specific TLV tag from a profile id and tag number
  84  *
  85  * @param[in]   profileId       The id of the profile within which the tag is defined.
  86  * @param[in]   tagNum          The profile-specific tag number assigned to the tag.
  87  * @return                      A 64-bit integer representing the tag.
  88  */
  89 inline uint64_t ProfileTag(uint32_t profileId, uint32_t tagNum)
  90 {
  91     return ((static_cast<uint64_t>(profileId)) << kProfileIdShift) | tagNum;
  92 }
  93
  94 /**
  95  * Generates the API representation of a profile-specific TLV tag from a vendor id, profile number and tag number
  96  *
  97  * @param[in]   vendorId        The id of the vendor that defined the tag.
  98  * @param[in]   profileNum      The vendor assigned number for the profile within which the tag is defined.
  99  * @param[in]   tagNum          The profile-specific tag number assigned to the tag.
 100  * @return                      A 64-bit integer representing the tag.
 101  */
 102 inline uint64_t ProfileTag(uint16_t vendorId, uint16_t profileNum, uint32_t tagNum)
 103 {
 104     return ((static_cast<uint64_t>(vendorId)) << kVendorIdShift) | ((static_cast<uint64_t>(profileNum)) << kProfileNumShift) |
 105         tagNum;
 106 }
 107
 108 /**
 109  * Generates the API representation for of context-specific TLV tag
 110  *
 111  * @param[in]   tagNum          The context-specific tag number assigned to the tag.
 112  * @return                      A 64-bit integer representing the tag.
 113  */
 114 inline uint64_t ContextTag(uint8_t tagNum)
 115 {
 116     return kSpecialTagMarker | tagNum;
 117 }
 118
 119 /**
 120  * Generates the API representation of a common profile TLV tag
 121  *
 122  * @param[in]   tagNum          The common profile tag number assigned to the tag.
 123  * @return                      A 64-bit integer representing the tag.
 124  */
 125 inline uint64_t CommonTag(uint32_t tagNum)
 126 {
 127     return ProfileTag(kCommonProfileId, tagNum);
 128 }
 129
 130 enum
 131 {
 132     /**
 133      * A value signifying a TLV element that has no tag (i.e. an anonymous element).
 134      */
 135     AnonymousTag = kSpecialTagMarker | 0x00000000FFFFFFFFULL,
 136
 137     // TODO: Move to private namespace
 138     UnknownImplicitTag = kSpecialTagMarker | 0x00000000FFFFFFFEULL
 139 };
 140
 141 /**
 142  * Returns the profile id from a TLV tag
 143  *
 144  * @note The behavior of this function is undefined if the supplied tag is not a profile-specific tag.
 145  *
 146  * @param[in]   tag             The API representation of a profile-specific TLV tag.
 147  * @return                      The profile id.
 148  */
 149 inline uint32_t ProfileIdFromTag(uint64_t tag)
 150 {
 151     return static_cast<uint32_t>((tag & kProfileIdMask) >> kProfileIdShift);
 152 }
 153
 154 /**
 155  * Returns the profile number from a TLV tag
 156  *
 157  * @note The behavior of this function is undefined if the supplied tag is not a profile-specific tag.
 158  *
 159  * @param[in]   tag             The API representation of a profile-specific TLV tag.
 160  * @return                      The associated profile number.
 161  */
 162 inline uint16_t ProfileNumFromTag(uint64_t tag)
 163 {
 164     return static_cast<uint16_t>((tag & kProfileIdMask) >> kProfileIdShift);
 165 }
 166
 167 /**
 168  * Returns the tag number from a TLV tag
 169  *
 170  * @note The behavior of this function is undefined if the supplied tag is not a profile-specific
 171  * or context-specific tag.
 172  *
 173  * @sa IsProfileTag() and IsContextTag()
 174  *
 175  * @param[in]   tag             The API representation of a profile-specific or context-specific TLV tag.
 176  * @return                      The associated tag number.
 177  */
 178 inline uint32_t TagNumFromTag(uint64_t tag)
 179 {
 180     return static_cast<uint32_t>(tag & kTagNumMask);
 181 }
 182
 183 /**
 184  * Returns the vendor id from a TLV tag
 185  *
 186  * @note The behavior of this function is undefined if the supplied tag is not a profile-specific tag.
 187  *
 188  * @param[in]   tag             The API representation of a profile-specific TLV tag.
 189  * @return                      The associated vendor id.
 190  */
 191 inline uint16_t VendorIdFromTag(uint64_t tag)
 192 {
 193     return static_cast<uint16_t>((tag & kProfileIdMask) >> kVendorIdShift);
 194 }
 195
 196 /**
 197  * Returns true of the supplied tag is a profile-specific tag.
 198  */
 199 inline bool IsProfileTag(uint64_t tag)
 200 {
 201     return (tag & kProfileIdMask) != kSpecialTagMarker;
 202 }
 203
 204 /**
 205  * Returns true if the supplied tag is a context-specific tag.
 206  */
 207 inline bool IsContextTag(uint64_t tag)
 208 {
 209     return (tag & kProfileIdMask) == kSpecialTagMarker && TagNumFromTag(tag) < kContextTagMaxNum;
 210 }
 211
 212 // TODO: move to private namespace
 213 inline bool IsSpecialTag(uint64_t tag)
 214 {
 215     return (tag & kProfileIdMask) == kSpecialTagMarker;
 216 }
 217
 218 } // namespace TLV
 219 } // namespace chip