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_loc - Identifies the source location of a line of code. 33 * @line: the line number in the file. 34 * @file: the file name. 35 */ 36 struct kunit_loc { 37 int line; 38 const char *file; 39 }; 40 41 #define KUNIT_CURRENT_LOC { .file = __FILE__, .line = __LINE__ } 42 43 /** 44 * struct kunit_assert - Data for printing a failed assertion or expectation. 45 * @format: a function which formats the data in this kunit_assert to a string. 46 * 47 * Represents a failed expectation/assertion. Contains all the data necessary to 48 * format a string to a user reporting the failure. 49 */ 50 struct kunit_assert { 51 void (*format)(const struct kunit_assert *assert, 52 const struct va_format *message, 53 struct string_stream *stream); 54 }; 55 56 void kunit_assert_prologue(const struct kunit_loc *loc, 57 enum kunit_assert_type type, 58 struct string_stream *stream); 59 60 /** 61 * struct kunit_fail_assert - Represents a plain fail expectation/assertion. 62 * @assert: The parent of this type. 63 * 64 * Represents a simple KUNIT_FAIL/KUNIT_ASSERT_FAILURE that always fails. 65 */ 66 struct kunit_fail_assert { 67 struct kunit_assert assert; 68 }; 69 70 void kunit_fail_assert_format(const struct kunit_assert *assert, 71 const struct va_format *message, 72 struct string_stream *stream); 73 74 /** 75 * KUNIT_INIT_FAIL_ASSERT_STRUCT - Initializer for &struct kunit_fail_assert. 76 * 77 * Initializes a &struct kunit_fail_assert. Intended to be used in 78 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 79 */ 80 #define KUNIT_INIT_FAIL_ASSERT_STRUCT { \ 81 .assert = { .format = kunit_fail_assert_format }, \ 82 } 83 84 /** 85 * struct kunit_unary_assert - Represents a KUNIT_{EXPECT|ASSERT}_{TRUE|FALSE} 86 * @assert: The parent of this type. 87 * @condition: A string representation of a conditional expression. 88 * @expected_true: True if of type KUNIT_{EXPECT|ASSERT}_TRUE, false otherwise. 89 * 90 * Represents a simple expectation or assertion that simply asserts something is 91 * true or false. In other words, represents the expectations: 92 * KUNIT_{EXPECT|ASSERT}_{TRUE|FALSE} 93 */ 94 struct kunit_unary_assert { 95 struct kunit_assert assert; 96 const char *condition; 97 bool expected_true; 98 }; 99 100 void kunit_unary_assert_format(const struct kunit_assert *assert, 101 const struct va_format *message, 102 struct string_stream *stream); 103 104 /** 105 * KUNIT_INIT_UNARY_ASSERT_STRUCT() - Initializes &struct kunit_unary_assert. 106 * @cond: A string representation of the expression asserted true or false. 107 * @expect_true: True if of type KUNIT_{EXPECT|ASSERT}_TRUE, false otherwise. 108 * 109 * Initializes a &struct kunit_unary_assert. Intended to be used in 110 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 111 */ 112 #define KUNIT_INIT_UNARY_ASSERT_STRUCT(cond, expect_true) { \ 113 .assert = { .format = kunit_unary_assert_format }, \ 114 .condition = cond, \ 115 .expected_true = expect_true \ 116 } 117 118 /** 119 * struct kunit_ptr_not_err_assert - An expectation/assertion that a pointer is 120 * not NULL and not a -errno. 121 * @assert: The parent of this type. 122 * @text: A string representation of the expression passed to the expectation. 123 * @value: The actual evaluated pointer value of the expression. 124 * 125 * Represents an expectation/assertion that a pointer is not null and is does 126 * not contain a -errno. (See IS_ERR_OR_NULL().) 127 */ 128 struct kunit_ptr_not_err_assert { 129 struct kunit_assert assert; 130 const char *text; 131 const void *value; 132 }; 133 134 void kunit_ptr_not_err_assert_format(const struct kunit_assert *assert, 135 const struct va_format *message, 136 struct string_stream *stream); 137 138 /** 139 * KUNIT_INIT_PTR_NOT_ERR_ASSERT_STRUCT() - Initializes a 140 * &struct kunit_ptr_not_err_assert. 141 * @txt: A string representation of the expression passed to the expectation. 142 * @val: The actual evaluated pointer value of the expression. 143 * 144 * Initializes a &struct kunit_ptr_not_err_assert. Intended to be used in 145 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 146 */ 147 #define KUNIT_INIT_PTR_NOT_ERR_STRUCT(txt, val) { \ 148 .assert = { .format = kunit_ptr_not_err_assert_format }, \ 149 .text = txt, \ 150 .value = val \ 151 } 152 153 /** 154 * struct kunit_binary_assert - An expectation/assertion that compares two 155 * non-pointer values (for example, KUNIT_EXPECT_EQ(test, 1 + 1, 2)). 156 * @assert: The parent of this type. 157 * @operation: A string representation of the comparison operator (e.g. "=="). 158 * @left_text: A string representation of the expression in the left slot. 159 * @left_value: The actual evaluated value of the expression in the left slot. 160 * @right_text: A string representation of the expression in the right slot. 161 * @right_value: The actual evaluated value of the expression in the right slot. 162 * 163 * Represents an expectation/assertion that compares two non-pointer values. For 164 * example, to expect that 1 + 1 == 2, you can use the expectation 165 * KUNIT_EXPECT_EQ(test, 1 + 1, 2); 166 */ 167 struct kunit_binary_assert { 168 struct kunit_assert assert; 169 const char *operation; 170 const char *left_text; 171 long long left_value; 172 const char *right_text; 173 long long right_value; 174 }; 175 176 void kunit_binary_assert_format(const struct kunit_assert *assert, 177 const struct va_format *message, 178 struct string_stream *stream); 179 180 /** 181 * KUNIT_INIT_BINARY_ASSERT_STRUCT() - Initializes a 182 * &struct kunit_binary_assert. 183 * @op_str: A string representation of the comparison operator (e.g. "=="). 184 * @left_str: A string representation of the expression in the left slot. 185 * @left_val: The actual evaluated value of the expression in the left slot. 186 * @right_str: A string representation of the expression in the right slot. 187 * @right_val: The actual evaluated value of the expression in the right slot. 188 * 189 * Initializes a &struct kunit_binary_assert. Intended to be used in 190 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 191 */ 192 #define KUNIT_INIT_BINARY_ASSERT_STRUCT(op_str, \ 193 left_str, \ 194 left_val, \ 195 right_str, \ 196 right_val) { \ 197 .assert = { .format = kunit_binary_assert_format }, \ 198 .operation = op_str, \ 199 .left_text = left_str, \ 200 .left_value = left_val, \ 201 .right_text = right_str, \ 202 .right_value = right_val \ 203 } 204 205 /** 206 * struct kunit_binary_ptr_assert - An expectation/assertion that compares two 207 * pointer values (for example, KUNIT_EXPECT_PTR_EQ(test, foo, bar)). 208 * @assert: The parent of this type. 209 * @operation: A string representation of the comparison operator (e.g. "=="). 210 * @left_text: A string representation of the expression in the left slot. 211 * @left_value: The actual evaluated value of the expression in the left slot. 212 * @right_text: A string representation of the expression in the right slot. 213 * @right_value: The actual evaluated value of the expression in the right slot. 214 * 215 * Represents an expectation/assertion that compares two pointer values. For 216 * example, to expect that foo and bar point to the same thing, you can use the 217 * expectation KUNIT_EXPECT_PTR_EQ(test, foo, bar); 218 */ 219 struct kunit_binary_ptr_assert { 220 struct kunit_assert assert; 221 const char *operation; 222 const char *left_text; 223 const void *left_value; 224 const char *right_text; 225 const void *right_value; 226 }; 227 228 void kunit_binary_ptr_assert_format(const struct kunit_assert *assert, 229 const struct va_format *message, 230 struct string_stream *stream); 231 232 /** 233 * KUNIT_INIT_BINARY_PTR_ASSERT_STRUCT() - Initializes a 234 * &struct kunit_binary_ptr_assert. 235 * @type: The type (assertion or expectation) of this kunit_assert. 236 * @op_str: A string representation of the comparison operator (e.g. "=="). 237 * @left_str: A string representation of the expression in the left slot. 238 * @left_val: The actual evaluated value of the expression in the left slot. 239 * @right_str: A string representation of the expression in the right slot. 240 * @right_val: The actual evaluated value of the expression in the right slot. 241 * 242 * Initializes a &struct kunit_binary_ptr_assert. Intended to be used in 243 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 244 */ 245 #define KUNIT_INIT_BINARY_PTR_ASSERT_STRUCT(op_str, \ 246 left_str, \ 247 left_val, \ 248 right_str, \ 249 right_val) { \ 250 .assert = { .format = kunit_binary_ptr_assert_format }, \ 251 .operation = op_str, \ 252 .left_text = left_str, \ 253 .left_value = left_val, \ 254 .right_text = right_str, \ 255 .right_value = right_val \ 256 } 257 258 /** 259 * struct kunit_binary_str_assert - An expectation/assertion that compares two 260 * string values (for example, KUNIT_EXPECT_STREQ(test, foo, "bar")). 261 * @assert: The parent of this type. 262 * @operation: A string representation of the comparison operator (e.g. "=="). 263 * @left_text: A string representation of the expression in the left slot. 264 * @left_value: The actual evaluated value of the expression in the left slot. 265 * @right_text: A string representation of the expression in the right slot. 266 * @right_value: The actual evaluated value of the expression in the right slot. 267 * 268 * Represents an expectation/assertion that compares two string values. For 269 * example, to expect that the string in foo is equal to "bar", you can use the 270 * expectation KUNIT_EXPECT_STREQ(test, foo, "bar"); 271 */ 272 struct kunit_binary_str_assert { 273 struct kunit_assert assert; 274 const char *operation; 275 const char *left_text; 276 const char *left_value; 277 const char *right_text; 278 const char *right_value; 279 }; 280 281 void kunit_binary_str_assert_format(const struct kunit_assert *assert, 282 const struct va_format *message, 283 struct string_stream *stream); 284 285 /** 286 * KUNIT_INIT_BINARY_STR_ASSERT_STRUCT() - Initializes a 287 * &struct kunit_binary_str_assert. 288 * @op_str: A string representation of the comparison operator (e.g. "=="). 289 * @left_str: A string representation of the expression in the left slot. 290 * @left_val: The actual evaluated value of the expression in the left slot. 291 * @right_str: A string representation of the expression in the right slot. 292 * @right_val: The actual evaluated value of the expression in the right slot. 293 * 294 * Initializes a &struct kunit_binary_str_assert. Intended to be used in 295 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 296 */ 297 #define KUNIT_INIT_BINARY_STR_ASSERT_STRUCT(op_str, \ 298 left_str, \ 299 left_val, \ 300 right_str, \ 301 right_val) { \ 302 .assert = { .format = kunit_binary_str_assert_format }, \ 303 .operation = op_str, \ 304 .left_text = left_str, \ 305 .left_value = left_val, \ 306 .right_text = right_str, \ 307 .right_value = right_val \ 308 } 309 310 #endif /* _KUNIT_ASSERT_H */ 311