1 /* SPDX-License-Identifier: GPL-2.0 */ 2 /* 3 * Assertion and expectation serialization API. 4 * 5 * Copyright (C) 2019, Google LLC. 6 * Author: Brendan Higgins <[email protected]> 7 */ 8 9 #ifndef _KUNIT_ASSERT_H 10 #define _KUNIT_ASSERT_H 11 12 #include <linux/err.h> 13 #include <linux/printk.h> 14 15 struct kunit; 16 struct string_stream; 17 18 /** 19 * enum kunit_assert_type - Type of expectation/assertion. 20 * @KUNIT_ASSERTION: Used to denote that a kunit_assert represents an assertion. 21 * @KUNIT_EXPECTATION: Denotes that a kunit_assert represents an expectation. 22 * 23 * Used in conjunction with a &struct kunit_assert to denote whether it 24 * represents an expectation or an assertion. 25 */ 26 enum kunit_assert_type { 27 KUNIT_ASSERTION, 28 KUNIT_EXPECTATION, 29 }; 30 31 /** 32 * struct kunit_assert - Data for printing a failed assertion or expectation. 33 * @type: the type (either an expectation or an assertion) of this kunit_assert. 34 * @line: the source code line number that the expectation/assertion is at. 35 * @file: the file path of the source file that the expectation/assertion is in. 36 * @message: an optional message to provide additional context. 37 * @format: a function which formats the data in this kunit_assert to a string. 38 * 39 * Represents a failed expectation/assertion. Contains all the data necessary to 40 * format a string to a user reporting the failure. 41 */ 42 struct kunit_assert { 43 enum kunit_assert_type type; 44 int line; 45 const char *file; 46 struct va_format message; 47 void (*format)(const struct kunit_assert *assert, 48 struct string_stream *stream); 49 }; 50 51 /** 52 * KUNIT_INIT_VA_FMT_NULL - Default initializer for struct va_format. 53 * 54 * Used inside a struct initialization block to initialize struct va_format to 55 * default values where fmt and va are null. 56 */ 57 #define KUNIT_INIT_VA_FMT_NULL { .fmt = NULL, .va = NULL } 58 59 /** 60 * KUNIT_INIT_ASSERT_STRUCT() - Initializer for a &struct kunit_assert. 61 * @assert_type: The type (assertion or expectation) of this kunit_assert. 62 * @fmt: The formatting function which builds a string out of this kunit_assert. 63 * 64 * The base initializer for a &struct kunit_assert. 65 */ 66 #define KUNIT_INIT_ASSERT_STRUCT(assert_type, fmt) { \ 67 .type = assert_type, \ 68 .file = __FILE__, \ 69 .line = __LINE__, \ 70 .message = KUNIT_INIT_VA_FMT_NULL, \ 71 .format = fmt \ 72 } 73 74 void kunit_base_assert_format(const struct kunit_assert *assert, 75 struct string_stream *stream); 76 77 void kunit_assert_print_msg(const struct kunit_assert *assert, 78 struct string_stream *stream); 79 80 /** 81 * struct kunit_fail_assert - Represents a plain fail expectation/assertion. 82 * @assert: The parent of this type. 83 * 84 * Represents a simple KUNIT_FAIL/KUNIT_ASSERT_FAILURE that always fails. 85 */ 86 struct kunit_fail_assert { 87 struct kunit_assert assert; 88 }; 89 90 void kunit_fail_assert_format(const struct kunit_assert *assert, 91 struct string_stream *stream); 92 93 /** 94 * KUNIT_INIT_FAIL_ASSERT_STRUCT() - Initializer for &struct kunit_fail_assert. 95 * @type: The type (assertion or expectation) of this kunit_assert. 96 * 97 * Initializes a &struct kunit_fail_assert. Intended to be used in 98 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 99 */ 100 #define KUNIT_INIT_FAIL_ASSERT_STRUCT(type) { \ 101 .assert = KUNIT_INIT_ASSERT_STRUCT(type, \ 102 kunit_fail_assert_format) \ 103 } 104 105 /** 106 * struct kunit_unary_assert - Represents a KUNIT_{EXPECT|ASSERT}_{TRUE|FALSE} 107 * @assert: The parent of this type. 108 * @condition: A string representation of a conditional expression. 109 * @expected_true: True if of type KUNIT_{EXPECT|ASSERT}_TRUE, false otherwise. 110 * 111 * Represents a simple expectation or assertion that simply asserts something is 112 * true or false. In other words, represents the expectations: 113 * KUNIT_{EXPECT|ASSERT}_{TRUE|FALSE} 114 */ 115 struct kunit_unary_assert { 116 struct kunit_assert assert; 117 const char *condition; 118 bool expected_true; 119 }; 120 121 void kunit_unary_assert_format(const struct kunit_assert *assert, 122 struct string_stream *stream); 123 124 /** 125 * KUNIT_INIT_UNARY_ASSERT_STRUCT() - Initializes &struct kunit_unary_assert. 126 * @type: The type (assertion or expectation) of this kunit_assert. 127 * @cond: A string representation of the expression asserted true or false. 128 * @expect_true: True if of type KUNIT_{EXPECT|ASSERT}_TRUE, false otherwise. 129 * 130 * Initializes a &struct kunit_unary_assert. Intended to be used in 131 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 132 */ 133 #define KUNIT_INIT_UNARY_ASSERT_STRUCT(type, cond, expect_true) { \ 134 .assert = KUNIT_INIT_ASSERT_STRUCT(type, \ 135 kunit_unary_assert_format), \ 136 .condition = cond, \ 137 .expected_true = expect_true \ 138 } 139 140 /** 141 * struct kunit_ptr_not_err_assert - An expectation/assertion that a pointer is 142 * not NULL and not a -errno. 143 * @assert: The parent of this type. 144 * @text: A string representation of the expression passed to the expectation. 145 * @value: The actual evaluated pointer value of the expression. 146 * 147 * Represents an expectation/assertion that a pointer is not null and is does 148 * not contain a -errno. (See IS_ERR_OR_NULL().) 149 */ 150 struct kunit_ptr_not_err_assert { 151 struct kunit_assert assert; 152 const char *text; 153 const void *value; 154 }; 155 156 void kunit_ptr_not_err_assert_format(const struct kunit_assert *assert, 157 struct string_stream *stream); 158 159 /** 160 * KUNIT_INIT_PTR_NOT_ERR_ASSERT_STRUCT() - Initializes a 161 * &struct kunit_ptr_not_err_assert. 162 * @type: The type (assertion or expectation) of this kunit_assert. 163 * @txt: A string representation of the expression passed to the expectation. 164 * @val: The actual evaluated pointer value of the expression. 165 * 166 * Initializes a &struct kunit_ptr_not_err_assert. Intended to be used in 167 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 168 */ 169 #define KUNIT_INIT_PTR_NOT_ERR_STRUCT(type, txt, val) { \ 170 .assert = KUNIT_INIT_ASSERT_STRUCT(type, \ 171 kunit_ptr_not_err_assert_format), \ 172 .text = txt, \ 173 .value = val \ 174 } 175 176 /** 177 * struct kunit_binary_assert - An expectation/assertion that compares two 178 * non-pointer values (for example, KUNIT_EXPECT_EQ(test, 1 + 1, 2)). 179 * @assert: The parent of this type. 180 * @operation: A string representation of the comparison operator (e.g. "=="). 181 * @left_text: A string representation of the expression in the left slot. 182 * @left_value: The actual evaluated value of the expression in the left slot. 183 * @right_text: A string representation of the expression in the right slot. 184 * @right_value: The actual evaluated value of the expression in the right slot. 185 * 186 * Represents an expectation/assertion that compares two non-pointer values. For 187 * example, to expect that 1 + 1 == 2, you can use the expectation 188 * KUNIT_EXPECT_EQ(test, 1 + 1, 2); 189 */ 190 struct kunit_binary_assert { 191 struct kunit_assert assert; 192 const char *operation; 193 const char *left_text; 194 long long left_value; 195 const char *right_text; 196 long long right_value; 197 }; 198 199 void kunit_binary_assert_format(const struct kunit_assert *assert, 200 struct string_stream *stream); 201 202 /** 203 * KUNIT_INIT_BINARY_ASSERT_STRUCT() - Initializes a 204 * &struct kunit_binary_assert. 205 * @type: The type (assertion or expectation) of this kunit_assert. 206 * @op_str: A string representation of the comparison operator (e.g. "=="). 207 * @left_str: A string representation of the expression in the left slot. 208 * @left_val: The actual evaluated value of the expression in the left slot. 209 * @right_str: A string representation of the expression in the right slot. 210 * @right_val: The actual evaluated value of the expression in the right slot. 211 * 212 * Initializes a &struct kunit_binary_assert. Intended to be used in 213 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 214 */ 215 #define KUNIT_INIT_BINARY_ASSERT_STRUCT(type, \ 216 op_str, \ 217 left_str, \ 218 left_val, \ 219 right_str, \ 220 right_val) { \ 221 .assert = KUNIT_INIT_ASSERT_STRUCT(type, \ 222 kunit_binary_assert_format), \ 223 .operation = op_str, \ 224 .left_text = left_str, \ 225 .left_value = left_val, \ 226 .right_text = right_str, \ 227 .right_value = right_val \ 228 } 229 230 /** 231 * struct kunit_binary_ptr_assert - An expectation/assertion that compares two 232 * pointer values (for example, KUNIT_EXPECT_PTR_EQ(test, foo, bar)). 233 * @assert: The parent of this type. 234 * @operation: A string representation of the comparison operator (e.g. "=="). 235 * @left_text: A string representation of the expression in the left slot. 236 * @left_value: The actual evaluated value of the expression in the left slot. 237 * @right_text: A string representation of the expression in the right slot. 238 * @right_value: The actual evaluated value of the expression in the right slot. 239 * 240 * Represents an expectation/assertion that compares two pointer values. For 241 * example, to expect that foo and bar point to the same thing, you can use the 242 * expectation KUNIT_EXPECT_PTR_EQ(test, foo, bar); 243 */ 244 struct kunit_binary_ptr_assert { 245 struct kunit_assert assert; 246 const char *operation; 247 const char *left_text; 248 const void *left_value; 249 const char *right_text; 250 const void *right_value; 251 }; 252 253 void kunit_binary_ptr_assert_format(const struct kunit_assert *assert, 254 struct string_stream *stream); 255 256 /** 257 * KUNIT_INIT_BINARY_PTR_ASSERT_STRUCT() - Initializes a 258 * &struct kunit_binary_ptr_assert. 259 * @type: The type (assertion or expectation) of this kunit_assert. 260 * @op_str: A string representation of the comparison operator (e.g. "=="). 261 * @left_str: A string representation of the expression in the left slot. 262 * @left_val: The actual evaluated value of the expression in the left slot. 263 * @right_str: A string representation of the expression in the right slot. 264 * @right_val: The actual evaluated value of the expression in the right slot. 265 * 266 * Initializes a &struct kunit_binary_ptr_assert. Intended to be used in 267 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 268 */ 269 #define KUNIT_INIT_BINARY_PTR_ASSERT_STRUCT(type, \ 270 op_str, \ 271 left_str, \ 272 left_val, \ 273 right_str, \ 274 right_val) { \ 275 .assert = KUNIT_INIT_ASSERT_STRUCT(type, \ 276 kunit_binary_ptr_assert_format), \ 277 .operation = op_str, \ 278 .left_text = left_str, \ 279 .left_value = left_val, \ 280 .right_text = right_str, \ 281 .right_value = right_val \ 282 } 283 284 /** 285 * struct kunit_binary_str_assert - An expectation/assertion that compares two 286 * string values (for example, KUNIT_EXPECT_STREQ(test, foo, "bar")). 287 * @assert: The parent of this type. 288 * @operation: A string representation of the comparison operator (e.g. "=="). 289 * @left_text: A string representation of the expression in the left slot. 290 * @left_value: The actual evaluated value of the expression in the left slot. 291 * @right_text: A string representation of the expression in the right slot. 292 * @right_value: The actual evaluated value of the expression in the right slot. 293 * 294 * Represents an expectation/assertion that compares two string values. For 295 * example, to expect that the string in foo is equal to "bar", you can use the 296 * expectation KUNIT_EXPECT_STREQ(test, foo, "bar"); 297 */ 298 struct kunit_binary_str_assert { 299 struct kunit_assert assert; 300 const char *operation; 301 const char *left_text; 302 const char *left_value; 303 const char *right_text; 304 const char *right_value; 305 }; 306 307 void kunit_binary_str_assert_format(const struct kunit_assert *assert, 308 struct string_stream *stream); 309 310 /** 311 * KUNIT_INIT_BINARY_STR_ASSERT_STRUCT() - Initializes a 312 * &struct kunit_binary_str_assert. 313 * @type: The type (assertion or expectation) of this kunit_assert. 314 * @op_str: A string representation of the comparison operator (e.g. "=="). 315 * @left_str: A string representation of the expression in the left slot. 316 * @left_val: The actual evaluated value of the expression in the left slot. 317 * @right_str: A string representation of the expression in the right slot. 318 * @right_val: The actual evaluated value of the expression in the right slot. 319 * 320 * Initializes a &struct kunit_binary_str_assert. Intended to be used in 321 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 322 */ 323 #define KUNIT_INIT_BINARY_STR_ASSERT_STRUCT(type, \ 324 op_str, \ 325 left_str, \ 326 left_val, \ 327 right_str, \ 328 right_val) { \ 329 .assert = KUNIT_INIT_ASSERT_STRUCT(type, \ 330 kunit_binary_str_assert_format), \ 331 .operation = op_str, \ 332 .left_text = left_str, \ 333 .left_value = left_val, \ 334 .right_text = right_str, \ 335 .right_value = right_val \ 336 } 337 338 #endif /* _KUNIT_ASSERT_H */ 339