1 /*
2  * Copyright (C) 2016 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 // Local utilities (macros and free-standing functions).
18 
19 #ifndef LOCAL_UTILS_H_
20 #define LOCAL_UTILS_H_
21 
22 #include <limits>
23 #include <type_traits>
24 
25 #include "android-base/logging.h"
26 
27 // Converts the value SRC to a value of DST_TYPE, in the range of [MIN, MAX].
28 // Values less than MIN are clamped to MIN, and values greater than MAX are
29 // clamped to MAX. Conversions are safe in the sense that the range is checked
30 // to be valid for both SRC and DST_TYPE, at compile-time.
31 //
32 // As compared to static_cast<>, SAFELY_CLAMP is a) more explicit, b) more
33 // flexible, and c) less prone to surprising conversions (e.g. -1 becoming
34 // UINT_MAX).
35 #define SAFELY_CLAMP(SRC, DST_TYPE, MIN, MAX)                                \
36   local_utils::internal::SafelyClamp<decltype(SRC), DST_TYPE, MIN, MAX, MIN, \
37                                      MAX>(SRC)
38 
39 // While attributes are standard in C++11, these attributes are not part of
40 // the standard. We use macros to abstract these attributes, to allow
41 // the code to compile with compilers that don't recognize these attributes.
42 #if defined(__clang__)
43 #define NONNULL [[gnu::nonnull]]                 /* NOLINT(whitespace/braces) */
44 #define RETURNS_NONNULL [[gnu::returns_nonnull]] /* NOLINT ... */
45 #else
46 #define NONNULL
47 #define RETURNS_NONNULL
48 #endif
49 
50 namespace android {
51 namespace wifilogd {
52 namespace local_utils {
53 
54 // Returns the value in |enum_value|, as the integral type underlying the
55 // enum. (E.g. uint8_t, int32_t, etc.)
56 template <typename T>
CastEnumToInteger(T enum_value)57 constexpr auto CastEnumToInteger(T enum_value) {
58   static_assert(std::is_enum<T>::value, "argument must be of an enum type");
59   return static_cast<typename std::underlying_type<T>::type>(enum_value);
60 }
61 
62 // Copies a |T| out of |buf|, aborting if |buf| is too short to hold a |T|.
63 //
64 // As compared to accessing the underlying data using reinterpret_cast<>,
65 // CopyFromBufferOrDie() provides three benefits:
66 // 1. Guarantees that the returned header is properly aligned. While
67 //    many processors support some unaligned reads, there are some
68 //    exceptions. E.g, a 64-bit unaligned read on 32-bit ARM may cause
69 //    a program to abort.
70 // 2. Removes the potential for bugs due to compiler optimizations based
71 //    on type-based alias analysis. (These are the kinds of bugs that
72 //    "strict-aliasing" warnings try to call out.)
73 // 3. Verifies that the source buffer is large enough to contain the
74 //    data we're trying to read out.
75 template <typename T>
CopyFromBufferOrDie(NONNULL const void * buf,size_t buf_len)76 T CopyFromBufferOrDie(NONNULL const void* buf, size_t buf_len) {
77   static_assert(std::is_trivially_copyable<T>::value,
78                 "CopyFromBufferOrDie can only copy trivially copyable types");
79   T out;
80   CHECK(buf_len >= sizeof(out));
81   std::memcpy(&out, buf, sizeof(out));
82   return out;
83 }
84 
85 // Returns the maximal value representable by T. Generates a compile-time
86 // error if T is not an integral type.
87 template <typename T>
GetMaxVal()88 constexpr T GetMaxVal() {
89   // Give a useful error for non-numeric types, and avoid returning zero for
90   // pointers and C-style enums (http://stackoverflow.com/a/9201960).
91   static_assert(std::is_integral<T>::value,
92                 "GetMaxVal requires an integral type");
93   return std::numeric_limits<T>::max();
94 }
95 
96 // Returns the maximal value representable by |t_instance|. Generates a
97 // compile-time error if |t_instance| is not an instance of an integral type.
98 template <typename T>
GetMaxVal(const T &)99 constexpr T GetMaxVal(const T& /* t_instance */) {
100   return GetMaxVal<T>();
101 }
102 
103 // Returns true if |c| is a printable character, for ASCII data.
IsAsciiPrintable(uint8_t c)104 inline bool IsAsciiPrintable(uint8_t c) {
105   return (c == '\t' || c == '\n' || (c >= ' ' && c <= '~'));
106 }
107 
108 namespace internal {
109 
110 // Implements the functionality documented for the SAFELY_CLAMP macro.
111 // This function should be used via the SAFELY_CLAMP macro.
112 template <typename SrcType, typename DstType, SrcType MinAsSrcType,
113           SrcType MaxAsSrcType, DstType MinAsDstType, DstType MaxAsDstType>
SafelyClamp(SrcType input)114 DstType SafelyClamp(SrcType input) {
115   static_assert(std::is_integral<SrcType>::value,
116                 "source type must be integral");
117   static_assert(std::is_integral<DstType>::value,
118                 "destination type must be integral");
119   static_assert(MinAsSrcType < MaxAsSrcType, "invalid source range");
120   static_assert(MinAsDstType < MaxAsDstType, "invalid destination range");
121   // Clients should use the SAFELY_CLAMP macro, in which case this should never
122   // happen. (When the SAFELY_CLAMP macro is used, the values can only be
123   // unequal if there was a narrowing conversion. But, in that case, the value
124   // should have failed to match the template, since narrowing-conversions are
125   // not allowed for non-type template arguments.
126   // http://stackoverflow.com/a/24346350)
127   //
128   // Anyway, these checks provide a fail-safe, in case clients use the template
129   // function directly, and pass in inconsistent values for the range
130   // definition.
131   static_assert(MinAsSrcType == MinAsDstType, "inconsistent range min");
132   static_assert(MaxAsSrcType == MaxAsDstType, "inconsistent range max");
133 
134   if (input < MinAsSrcType) {
135     return MinAsDstType;
136   } else if (input > MaxAsSrcType) {
137     return MaxAsDstType;
138   } else {
139     // - Given that the template has matched, we know that MinAsSrcType,
140     //   MaxAsSrcType, MinAsDstType, and MaxAsDstType are valid for their
141     //   respective types. (See narrowing-conversion comment above.)
142     // - Given the static_assert()s above, we know that a) the ranges are
143     //   well-formed, and that the b) source range is identical to the
144     //   destination range.
145     // - Given the range checks above, we know that |input| is within the range.
146     //
147     // Hence, the value to be returned must be valid for DstType, and the
148     // expression below has the same value as |input|.
149     return static_cast<DstType>(input);
150   }
151 }
152 
153 }  // namespace internal
154 
155 }  // namespace local_utils
156 }  // namespace wifilogd
157 }  // namespace android
158 
159 #endif  // LOCAL_UTILS_H_
160