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