1 /* SPDX-License-Identifier: GPL-2.0 */ 1 /* SPDX-License-Identifier: GPL-2.0 */
2 /* 2 /*
3 * Assertion and expectation serialization API 3 * Assertion and expectation serialization API.
4 * 4 *
5 * Copyright (C) 2019, Google LLC. 5 * Copyright (C) 2019, Google LLC.
6 * Author: Brendan Higgins <brendanhiggins@goo 6 * Author: Brendan Higgins <brendanhiggins@google.com>
7 */ 7 */
8 8
9 #ifndef _KUNIT_ASSERT_H 9 #ifndef _KUNIT_ASSERT_H
10 #define _KUNIT_ASSERT_H 10 #define _KUNIT_ASSERT_H
11 11
12 #include <linux/err.h> 12 #include <linux/err.h>
13 #include <linux/printk.h> 13 #include <linux/printk.h>
14 14
15 struct kunit; 15 struct kunit;
16 struct string_stream; 16 struct string_stream;
17 17
18 /** 18 /**
19 * enum kunit_assert_type - Type of expectatio 19 * enum kunit_assert_type - Type of expectation/assertion.
20 * @KUNIT_ASSERTION: Used to denote that a kun 20 * @KUNIT_ASSERTION: Used to denote that a kunit_assert represents an assertion.
21 * @KUNIT_EXPECTATION: Denotes that a kunit_as 21 * @KUNIT_EXPECTATION: Denotes that a kunit_assert represents an expectation.
22 * 22 *
23 * Used in conjunction with a &struct kunit_as 23 * Used in conjunction with a &struct kunit_assert to denote whether it
24 * represents an expectation or an assertion. 24 * represents an expectation or an assertion.
25 */ 25 */
26 enum kunit_assert_type { 26 enum kunit_assert_type {
27 KUNIT_ASSERTION, 27 KUNIT_ASSERTION,
28 KUNIT_EXPECTATION, 28 KUNIT_EXPECTATION,
29 }; 29 };
30 30
31 /** 31 /**
32 * struct kunit_loc - Identifies the source lo 32 * struct kunit_loc - Identifies the source location of a line of code.
33 * @line: the line number in the file. 33 * @line: the line number in the file.
34 * @file: the file name. 34 * @file: the file name.
35 */ 35 */
36 struct kunit_loc { 36 struct kunit_loc {
37 int line; 37 int line;
38 const char *file; 38 const char *file;
39 }; 39 };
40 40
41 #define KUNIT_CURRENT_LOC { .file = __FILE__, 41 #define KUNIT_CURRENT_LOC { .file = __FILE__, .line = __LINE__ }
42 42
43 /** 43 /**
44 * struct kunit_assert - Data for printing a f 44 * struct kunit_assert - Data for printing a failed assertion or expectation.
45 * 45 *
46 * Represents a failed expectation/assertion. 46 * Represents a failed expectation/assertion. Contains all the data necessary to
47 * format a string to a user reporting the fai 47 * format a string to a user reporting the failure.
48 */ 48 */
49 struct kunit_assert {}; 49 struct kunit_assert {};
50 50
51 typedef void (*assert_format_t)(const struct k 51 typedef void (*assert_format_t)(const struct kunit_assert *assert,
52 const struct v 52 const struct va_format *message,
53 struct string_ 53 struct string_stream *stream);
54 54
55 void kunit_assert_prologue(const struct kunit_ 55 void kunit_assert_prologue(const struct kunit_loc *loc,
56 enum kunit_assert_t 56 enum kunit_assert_type type,
57 struct string_strea 57 struct string_stream *stream);
58 58
59 /** 59 /**
60 * struct kunit_fail_assert - Represents a pla 60 * struct kunit_fail_assert - Represents a plain fail expectation/assertion.
61 * @assert: The parent of this type. 61 * @assert: The parent of this type.
62 * 62 *
63 * Represents a simple KUNIT_FAIL/KUNIT_FAIL_A !! 63 * Represents a simple KUNIT_FAIL/KUNIT_ASSERT_FAILURE that always fails.
64 */ 64 */
65 struct kunit_fail_assert { 65 struct kunit_fail_assert {
66 struct kunit_assert assert; 66 struct kunit_assert assert;
67 }; 67 };
68 68
69 void kunit_fail_assert_format(const struct kun 69 void kunit_fail_assert_format(const struct kunit_assert *assert,
70 const struct va_ 70 const struct va_format *message,
71 struct string_st 71 struct string_stream *stream);
72 72
73 /** 73 /**
74 * struct kunit_unary_assert - Represents a KU 74 * struct kunit_unary_assert - Represents a KUNIT_{EXPECT|ASSERT}_{TRUE|FALSE}
75 * @assert: The parent of this type. 75 * @assert: The parent of this type.
76 * @condition: A string representation of a co 76 * @condition: A string representation of a conditional expression.
77 * @expected_true: True if of type KUNIT_{EXPE 77 * @expected_true: True if of type KUNIT_{EXPECT|ASSERT}_TRUE, false otherwise.
78 * 78 *
79 * Represents a simple expectation or assertio 79 * Represents a simple expectation or assertion that simply asserts something is
80 * true or false. In other words, represents t 80 * true or false. In other words, represents the expectations:
81 * KUNIT_{EXPECT|ASSERT}_{TRUE|FALSE} 81 * KUNIT_{EXPECT|ASSERT}_{TRUE|FALSE}
82 */ 82 */
83 struct kunit_unary_assert { 83 struct kunit_unary_assert {
84 struct kunit_assert assert; 84 struct kunit_assert assert;
85 const char *condition; 85 const char *condition;
86 bool expected_true; 86 bool expected_true;
87 }; 87 };
88 88
89 void kunit_unary_assert_format(const struct ku 89 void kunit_unary_assert_format(const struct kunit_assert *assert,
90 const struct va 90 const struct va_format *message,
91 struct string_s 91 struct string_stream *stream);
92 92
93 /** 93 /**
94 * struct kunit_ptr_not_err_assert - An expect 94 * struct kunit_ptr_not_err_assert - An expectation/assertion that a pointer is
95 * not NULL and not a -errno. 95 * not NULL and not a -errno.
96 * @assert: The parent of this type. 96 * @assert: The parent of this type.
97 * @text: A string representation of the expre 97 * @text: A string representation of the expression passed to the expectation.
98 * @value: The actual evaluated pointer value 98 * @value: The actual evaluated pointer value of the expression.
99 * 99 *
100 * Represents an expectation/assertion that a 100 * Represents an expectation/assertion that a pointer is not null and is does
101 * not contain a -errno. (See IS_ERR_OR_NULL() 101 * not contain a -errno. (See IS_ERR_OR_NULL().)
102 */ 102 */
103 struct kunit_ptr_not_err_assert { 103 struct kunit_ptr_not_err_assert {
104 struct kunit_assert assert; 104 struct kunit_assert assert;
105 const char *text; 105 const char *text;
106 const void *value; 106 const void *value;
107 }; 107 };
108 108
109 void kunit_ptr_not_err_assert_format(const str 109 void kunit_ptr_not_err_assert_format(const struct kunit_assert *assert,
110 const str 110 const struct va_format *message,
111 struct st 111 struct string_stream *stream);
112 112
113 /** 113 /**
114 * struct kunit_binary_assert_text - holds str 114 * struct kunit_binary_assert_text - holds strings for &struct
115 * kunit_binary_assert and friends to try 115 * kunit_binary_assert and friends to try and make the structs smaller.
116 * @operation: A string representation of the 116 * @operation: A string representation of the comparison operator (e.g. "==").
117 * @left_text: A string representation of the 117 * @left_text: A string representation of the left expression (e.g. "2+2").
118 * @right_text: A string representation of the 118 * @right_text: A string representation of the right expression (e.g. "2+2").
119 */ 119 */
120 struct kunit_binary_assert_text { 120 struct kunit_binary_assert_text {
121 const char *operation; 121 const char *operation;
122 const char *left_text; 122 const char *left_text;
123 const char *right_text; 123 const char *right_text;
124 }; 124 };
125 125
126 /** 126 /**
127 * struct kunit_binary_assert - An expectation 127 * struct kunit_binary_assert - An expectation/assertion that compares two
128 * non-pointer values (for example, KUNIT 128 * non-pointer values (for example, KUNIT_EXPECT_EQ(test, 1 + 1, 2)).
129 * @assert: The parent of this type. 129 * @assert: The parent of this type.
130 * @text: Holds the textual representations of 130 * @text: Holds the textual representations of the operands and op (e.g. "==").
131 * @left_value: The actual evaluated value of 131 * @left_value: The actual evaluated value of the expression in the left slot.
132 * @right_value: The actual evaluated value of 132 * @right_value: The actual evaluated value of the expression in the right slot.
133 * 133 *
134 * Represents an expectation/assertion that co 134 * Represents an expectation/assertion that compares two non-pointer values. For
135 * example, to expect that 1 + 1 == 2, you can 135 * example, to expect that 1 + 1 == 2, you can use the expectation
136 * KUNIT_EXPECT_EQ(test, 1 + 1, 2); 136 * KUNIT_EXPECT_EQ(test, 1 + 1, 2);
137 */ 137 */
138 struct kunit_binary_assert { 138 struct kunit_binary_assert {
139 struct kunit_assert assert; 139 struct kunit_assert assert;
140 const struct kunit_binary_assert_text 140 const struct kunit_binary_assert_text *text;
141 long long left_value; 141 long long left_value;
142 long long right_value; 142 long long right_value;
143 }; 143 };
144 144
145 void kunit_binary_assert_format(const struct k 145 void kunit_binary_assert_format(const struct kunit_assert *assert,
146 const struct v 146 const struct va_format *message,
147 struct string_ 147 struct string_stream *stream);
148 148
149 /** 149 /**
150 * struct kunit_binary_ptr_assert - An expecta 150 * struct kunit_binary_ptr_assert - An expectation/assertion that compares two
151 * pointer values (for example, KUNIT_EXP 151 * pointer values (for example, KUNIT_EXPECT_PTR_EQ(test, foo, bar)).
152 * @assert: The parent of this type. 152 * @assert: The parent of this type.
153 * @text: Holds the textual representations of 153 * @text: Holds the textual representations of the operands and op (e.g. "==").
154 * @left_value: The actual evaluated value of 154 * @left_value: The actual evaluated value of the expression in the left slot.
155 * @right_value: The actual evaluated value of 155 * @right_value: The actual evaluated value of the expression in the right slot.
156 * 156 *
157 * Represents an expectation/assertion that co 157 * Represents an expectation/assertion that compares two pointer values. For
158 * example, to expect that foo and bar point t 158 * example, to expect that foo and bar point to the same thing, you can use the
159 * expectation KUNIT_EXPECT_PTR_EQ(test, foo, 159 * expectation KUNIT_EXPECT_PTR_EQ(test, foo, bar);
160 */ 160 */
161 struct kunit_binary_ptr_assert { 161 struct kunit_binary_ptr_assert {
162 struct kunit_assert assert; 162 struct kunit_assert assert;
163 const struct kunit_binary_assert_text 163 const struct kunit_binary_assert_text *text;
164 const void *left_value; 164 const void *left_value;
165 const void *right_value; 165 const void *right_value;
166 }; 166 };
167 167
168 void kunit_binary_ptr_assert_format(const stru 168 void kunit_binary_ptr_assert_format(const struct kunit_assert *assert,
169 const stru 169 const struct va_format *message,
170 struct str 170 struct string_stream *stream);
171 171
172 /** 172 /**
173 * struct kunit_binary_str_assert - An expecta 173 * struct kunit_binary_str_assert - An expectation/assertion that compares two
174 * string values (for example, KUNIT_EXPE 174 * string values (for example, KUNIT_EXPECT_STREQ(test, foo, "bar")).
175 * @assert: The parent of this type. 175 * @assert: The parent of this type.
176 * @text: Holds the textual representations of 176 * @text: Holds the textual representations of the operands and comparator.
177 * @left_value: The actual evaluated value of 177 * @left_value: The actual evaluated value of the expression in the left slot.
178 * @right_value: The actual evaluated value of 178 * @right_value: The actual evaluated value of the expression in the right slot.
179 * 179 *
180 * Represents an expectation/assertion that co 180 * Represents an expectation/assertion that compares two string values. For
181 * example, to expect that the string in foo i 181 * example, to expect that the string in foo is equal to "bar", you can use the
182 * expectation KUNIT_EXPECT_STREQ(test, foo, " 182 * expectation KUNIT_EXPECT_STREQ(test, foo, "bar");
183 */ 183 */
184 struct kunit_binary_str_assert { 184 struct kunit_binary_str_assert {
185 struct kunit_assert assert; 185 struct kunit_assert assert;
186 const struct kunit_binary_assert_text 186 const struct kunit_binary_assert_text *text;
187 const char *left_value; 187 const char *left_value;
188 const char *right_value; 188 const char *right_value;
189 }; 189 };
190 190
191 void kunit_binary_str_assert_format(const stru 191 void kunit_binary_str_assert_format(const struct kunit_assert *assert,
192 const stru 192 const struct va_format *message,
193 struct str 193 struct string_stream *stream);
194 194
195 /** 195 /**
196 * struct kunit_mem_assert - An expectation/as 196 * struct kunit_mem_assert - An expectation/assertion that compares two
197 * memory blocks. 197 * memory blocks.
198 * @assert: The parent of this type. 198 * @assert: The parent of this type.
199 * @text: Holds the textual representations of 199 * @text: Holds the textual representations of the operands and comparator.
200 * @left_value: The actual evaluated value of 200 * @left_value: The actual evaluated value of the expression in the left slot.
201 * @right_value: The actual evaluated value of 201 * @right_value: The actual evaluated value of the expression in the right slot.
202 * @size: Size of the memory block analysed in 202 * @size: Size of the memory block analysed in bytes.
203 * 203 *
204 * Represents an expectation/assertion that co 204 * Represents an expectation/assertion that compares two memory blocks. For
205 * example, to expect that the first three byt 205 * example, to expect that the first three bytes of foo is equal to the
206 * first three bytes of bar, you can use the e 206 * first three bytes of bar, you can use the expectation
207 * KUNIT_EXPECT_MEMEQ(test, foo, bar, 3); 207 * KUNIT_EXPECT_MEMEQ(test, foo, bar, 3);
208 */ 208 */
209 struct kunit_mem_assert { 209 struct kunit_mem_assert {
210 struct kunit_assert assert; 210 struct kunit_assert assert;
211 const struct kunit_binary_assert_text 211 const struct kunit_binary_assert_text *text;
212 const void *left_value; 212 const void *left_value;
213 const void *right_value; 213 const void *right_value;
214 const size_t size; 214 const size_t size;
215 }; 215 };
216 216
217 void kunit_mem_assert_format(const struct kuni 217 void kunit_mem_assert_format(const struct kunit_assert *assert,
218 const struct va_f 218 const struct va_format *message,
219 struct string_str 219 struct string_stream *stream);
220 <<
221 #if IS_ENABLED(CONFIG_KUNIT) <<
222 void kunit_assert_print_msg(const struct va_fo <<
223 struct string_stre <<
224 bool is_literal(const char *text, long long va <<
225 bool is_str_literal(const char *text, const ch <<
226 void kunit_assert_hexdump(struct string_stream <<
227 const void *buf, <<
228 const void *compared <<
229 const size_t len); <<
230 #endif <<
231 220
232 #endif /* _KUNIT_ASSERT_H */ 221 #endif /* _KUNIT_ASSERT_H */
233 222
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.