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 <brendanhiggins@google.com> 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 * 46 * Represents a failed expectation/assertion. Contains all the data necessary to 47 * format a string to a user reporting the failure. 48 */ 49 struct kunit_assert {}; 50 51 typedef void (*assert_format_t)(const struct kunit_assert *assert, 52 const struct va_format *message, 53 struct string_stream *stream); 54 55 void kunit_assert_prologue(const struct kunit_loc *loc, 56 enum kunit_assert_type type, 57 struct string_stream *stream); 58 59 /** 60 * struct kunit_fail_assert - Represents a plain fail expectation/assertion. 61 * @assert: The parent of this type. 62 * 63 * Represents a simple KUNIT_FAIL/KUNIT_ASSERT_FAILURE that always fails. 64 */ 65 struct kunit_fail_assert { 66 struct kunit_assert assert; 67 }; 68 69 void kunit_fail_assert_format(const struct kunit_assert *assert, 70 const struct va_format *message, 71 struct string_stream *stream); 72 73 /** 74 * struct kunit_unary_assert - Represents a KUNIT_{EXPECT|ASSERT}_{TRUE|FALSE} 75 * @assert: The parent of this type. 76 * @condition: A string representation of a conditional expression. 77 * @expected_true: True if of type KUNIT_{EXPECT|ASSERT}_TRUE, false otherwise. 78 * 79 * Represents a simple expectation or assertion that simply asserts something is 80 * true or false. In other words, represents the expectations: 81 * KUNIT_{EXPECT|ASSERT}_{TRUE|FALSE} 82 */ 83 struct kunit_unary_assert { 84 struct kunit_assert assert; 85 const char *condition; 86 bool expected_true; 87 }; 88 89 void kunit_unary_assert_format(const struct kunit_assert *assert, 90 const struct va_format *message, 91 struct string_stream *stream); 92 93 /** 94 * KUNIT_INIT_UNARY_ASSERT_STRUCT() - Initializes &struct kunit_unary_assert. 95 * @cond: A string representation of the expression asserted true or false. 96 * @expect_true: True if of type KUNIT_{EXPECT|ASSERT}_TRUE, false otherwise. 97 * 98 * Initializes a &struct kunit_unary_assert. Intended to be used in 99 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 100 */ 101 #define KUNIT_INIT_UNARY_ASSERT_STRUCT(cond, expect_true) { \ 102 .condition = cond, \ 103 .expected_true = expect_true \ 104 } 105 106 /** 107 * struct kunit_ptr_not_err_assert - An expectation/assertion that a pointer is 108 * not NULL and not a -errno. 109 * @assert: The parent of this type. 110 * @text: A string representation of the expression passed to the expectation. 111 * @value: The actual evaluated pointer value of the expression. 112 * 113 * Represents an expectation/assertion that a pointer is not null and is does 114 * not contain a -errno. (See IS_ERR_OR_NULL().) 115 */ 116 struct kunit_ptr_not_err_assert { 117 struct kunit_assert assert; 118 const char *text; 119 const void *value; 120 }; 121 122 void kunit_ptr_not_err_assert_format(const struct kunit_assert *assert, 123 const struct va_format *message, 124 struct string_stream *stream); 125 126 /** 127 * KUNIT_INIT_PTR_NOT_ERR_ASSERT_STRUCT() - Initializes a 128 * &struct kunit_ptr_not_err_assert. 129 * @txt: A string representation of the expression passed to the expectation. 130 * @val: The actual evaluated pointer value of the expression. 131 * 132 * Initializes a &struct kunit_ptr_not_err_assert. Intended to be used in 133 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 134 */ 135 #define KUNIT_INIT_PTR_NOT_ERR_STRUCT(txt, val) { \ 136 .text = txt, \ 137 .value = val \ 138 } 139 140 /** 141 * struct kunit_binary_assert_text - holds strings for &struct 142 * kunit_binary_assert and friends to try and make the structs smaller. 143 * @operation: A string representation of the comparison operator (e.g. "=="). 144 * @left_text: A string representation of the left expression (e.g. "2+2"). 145 * @right_text: A string representation of the right expression (e.g. "2+2"). 146 */ 147 struct kunit_binary_assert_text { 148 const char *operation; 149 const char *left_text; 150 const char *right_text; 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 * @text: Holds the textual representations of the operands and op (e.g. "=="). 158 * @left_value: The actual evaluated value of the expression in the left slot. 159 * @right_value: The actual evaluated value of the expression in the right slot. 160 * 161 * Represents an expectation/assertion that compares two non-pointer values. For 162 * example, to expect that 1 + 1 == 2, you can use the expectation 163 * KUNIT_EXPECT_EQ(test, 1 + 1, 2); 164 */ 165 struct kunit_binary_assert { 166 struct kunit_assert assert; 167 const struct kunit_binary_assert_text *text; 168 long long left_value; 169 long long right_value; 170 }; 171 172 void kunit_binary_assert_format(const struct kunit_assert *assert, 173 const struct va_format *message, 174 struct string_stream *stream); 175 176 /** 177 * KUNIT_INIT_BINARY_ASSERT_STRUCT() - Initializes a binary assert like 178 * kunit_binary_assert, kunit_binary_ptr_assert, etc. 179 * 180 * @text_: Pointer to a kunit_binary_assert_text. 181 * @left_val: The actual evaluated value of the expression in the left slot. 182 * @right_val: The actual evaluated value of the expression in the right slot. 183 * 184 * Initializes a binary assert like kunit_binary_assert, 185 * kunit_binary_ptr_assert, etc. This relies on these structs having the same 186 * fields but with different types for left_val/right_val. 187 * This is ultimately used by binary assertion macros like KUNIT_EXPECT_EQ, etc. 188 */ 189 #define KUNIT_INIT_BINARY_ASSERT_STRUCT(text_, \ 190 left_val, \ 191 right_val) { \ 192 .text = text_, \ 193 .left_value = left_val, \ 194 .right_value = right_val \ 195 } 196 197 /** 198 * struct kunit_binary_ptr_assert - An expectation/assertion that compares two 199 * pointer values (for example, KUNIT_EXPECT_PTR_EQ(test, foo, bar)). 200 * @assert: The parent of this type. 201 * @text: Holds the textual representations of the operands and op (e.g. "=="). 202 * @left_value: The actual evaluated value of the expression in the left slot. 203 * @right_value: The actual evaluated value of the expression in the right slot. 204 * 205 * Represents an expectation/assertion that compares two pointer values. For 206 * example, to expect that foo and bar point to the same thing, you can use the 207 * expectation KUNIT_EXPECT_PTR_EQ(test, foo, bar); 208 */ 209 struct kunit_binary_ptr_assert { 210 struct kunit_assert assert; 211 const struct kunit_binary_assert_text *text; 212 const void *left_value; 213 const void *right_value; 214 }; 215 216 void kunit_binary_ptr_assert_format(const struct kunit_assert *assert, 217 const struct va_format *message, 218 struct string_stream *stream); 219 220 /** 221 * struct kunit_binary_str_assert - An expectation/assertion that compares two 222 * string values (for example, KUNIT_EXPECT_STREQ(test, foo, "bar")). 223 * @assert: The parent of this type. 224 * @text: Holds the textual representations of the operands and comparator. 225 * @left_value: The actual evaluated value of the expression in the left slot. 226 * @right_value: The actual evaluated value of the expression in the right slot. 227 * 228 * Represents an expectation/assertion that compares two string values. For 229 * example, to expect that the string in foo is equal to "bar", you can use the 230 * expectation KUNIT_EXPECT_STREQ(test, foo, "bar"); 231 */ 232 struct kunit_binary_str_assert { 233 struct kunit_assert assert; 234 const struct kunit_binary_assert_text *text; 235 const char *left_value; 236 const char *right_value; 237 }; 238 239 void kunit_binary_str_assert_format(const struct kunit_assert *assert, 240 const struct va_format *message, 241 struct string_stream *stream); 242 243 #endif /* _KUNIT_ASSERT_H */ 244