Line data Source code
1 : /*
2 : *
3 : * Copyright (c) 2022 Project CHIP Authors
4 : *
5 : * Licensed under the Apache License, Version 2.0 (the "License");
6 : * you may not use this file except in compliance with the License.
7 : * You may obtain a copy of the License at
8 : *
9 : * http://www.apache.org/licenses/LICENSE-2.0
10 : *
11 : * Unless required by applicable law or agreed to in writing, software
12 : * distributed under the License is distributed on an "AS IS" BASIS,
13 : * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 : * See the License for the specific language governing permissions and
15 : * limitations under the License.
16 : */
17 :
18 : #pragma once
19 :
20 : #include <lib/support/BitFlags.h>
21 :
22 : namespace chip {
23 :
24 : /**
25 : * Stores bit masks and flags in a more typesafe manner.
26 : *
27 : * Extends BitFlags for boolean flags and also adds support for bit-mask set options.
28 : *
29 : */
30 : template <typename FlagsEnum, typename StorageType = typename std::underlying_type_t<FlagsEnum>>
31 : class BitMask : public BitFlags<FlagsEnum, StorageType>
32 : {
33 : public:
34 : using IntegerType = typename BitFlags<FlagsEnum, StorageType>::IntegerType;
35 :
36 60 : constexpr BitMask() : BitFlags<FlagsEnum, StorageType>() {}
37 : constexpr BitMask(const BitFlags<FlagsEnum, StorageType> & other) : BitFlags<FlagsEnum, StorageType>(other) {}
38 : constexpr BitMask(BitFlags<FlagsEnum, StorageType> && other) : BitFlags<FlagsEnum, StorageType>(std::move(other)) {}
39 : BitMask(const BitMask &) = default;
40 :
41 : explicit BitMask(FlagsEnum value) : BitFlags<FlagsEnum, StorageType>(value) {}
42 : explicit BitMask(IntegerType value) : BitFlags<FlagsEnum, StorageType>(value) {}
43 :
44 : template <typename... Args>
45 : constexpr BitMask(FlagsEnum flag, Args &&... args) : BitFlags<FlagsEnum, StorageType>(flag, std::forward<Args>(args)...)
46 : {}
47 :
48 : template <typename... Args>
49 : constexpr BitMask(IntegerType value, Args &&... args) : BitFlags<FlagsEnum, StorageType>(value, std::forward<Args>(args)...)
50 : {}
51 :
52 : BitMask & operator=(const BitMask &) = default;
53 :
54 : BitMask & operator=(const BitFlags<FlagsEnum, StorageType> & other)
55 : {
56 : BitFlags<FlagsEnum, StorageType>::SetRaw(other.Raw());
57 : return *this;
58 : }
59 :
60 : BitMask & operator=(FlagsEnum value)
61 : {
62 : BitFlags<FlagsEnum, StorageType>::SetRaw(static_cast<StorageType>(value));
63 : return *this;
64 : }
65 :
66 : /**
67 : * Set a field within the bit mask integer.
68 : *
69 : * Fields are assumed to be contiguous bits within the underlying integer, for example:
70 : * A mask of 0x70 == 0b01110000 means that a 3 bit value is encoded at bits [4;6].
71 : *
72 : * Calling SetField(0x70, n) is equivalent to "(value & ~0x70) | (n << 4)"
73 : *
74 : * @param mask The mask, code assumes a continous bit mask
75 : * @param value The value, NOT shifted, MUST fit within the number of bits of the mask
76 : */
77 : constexpr BitMask & SetField(FlagsEnum mask, IntegerType value)
78 : {
79 : IntegerType bitMask = static_cast<IntegerType>(mask);
80 : IntegerType shift = GetShiftToFirstSetBit(bitMask);
81 :
82 : // NOTE: value should be fully contained within the shift mask.
83 : //
84 : // assert((value & (mask >> shift)) == value);
85 :
86 : // Clear bits overlayed by the mask
87 : IntegerType updated = static_cast<IntegerType>(BitFlags<FlagsEnum, StorageType>::Raw() & ~bitMask);
88 :
89 : // Set the right bits
90 : updated = static_cast<IntegerType>(updated | (bitMask & (value << shift)));
91 :
92 : BitFlags<FlagsEnum, StorageType>::SetRaw(updated);
93 :
94 : return *this;
95 : }
96 :
97 : /**
98 : * Gets an underlying field that is contained within a bit subset of the integer.
99 : * Examples:
100 : * GetField(0x70) == GetField(0b01110000) == ((n & 0x70) >> 4) == ((n >> 4) 0x07)
101 : * GetField(0xC0) == GetField(0b11000000) == ((n & 0xC0) >> 6) == ((n >> 6) 0x03)
102 : *
103 : * @param mask The bit mask to be used, assumed to be a contigous bit mask
104 : */
105 : IntegerType GetField(FlagsEnum mask) const
106 : {
107 : IntegerType bitMask = static_cast<IntegerType>(mask);
108 : IntegerType shift = GetShiftToFirstSetBit(bitMask);
109 :
110 : // Forward the right bits
111 : return static_cast<IntegerType>(((BitFlags<FlagsEnum, StorageType>::Raw() & bitMask) >> shift));
112 : }
113 :
114 : protected:
115 : /// Get the shift amount to reach the first non-zero bit in a bitmask
116 : ///
117 : /// Examples:
118 : /// GetShiftToFirstSetBit(0b0000001) == 0
119 : /// GetShiftToFirstSetBit(0b0011100) == 2
120 : /// GetShiftToFirstSetBit(0b0110000) == 4
121 : ///
122 : /// Note: This does NOT validate if the given mask is a valid mask. So:
123 : /// GetShiftToFirstSetBit(0b0100010) == 1
124 : /// GetShiftToFirstSetBit(0b010110100) == 2
125 : static constexpr IntegerType GetShiftToFirstSetBit(IntegerType bitMask)
126 : {
127 : IntegerType count = 0;
128 : IntegerType mask = 0x01;
129 :
130 : if (bitMask == 0)
131 : {
132 : return sizeof(bitMask); // generally invalid value
133 : }
134 :
135 : while ((mask & bitMask) == 0)
136 : {
137 : mask = static_cast<IntegerType>(mask << 1);
138 : count++;
139 : }
140 : return count;
141 : }
142 : };
143 :
144 : } // namespace chip
|
