1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */ 2 /* 3 * 4 * (C) COPYRIGHT 2017, 2020-2021 ARM Limited. All rights reserved. 5 * 6 * This program is free software and is provided to you under the terms of the 7 * GNU General Public License version 2 as published by the Free Software 8 * Foundation, and any use by you of this program is subject to the terms 9 * of such GNU license. 10 * 11 * This program is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * GNU General Public License for more details. 15 * 16 * You should have received a copy of the GNU General Public License 17 * along with this program; if not, you can access it online at 18 * http://www.gnu.org/licenses/gpl-2.0.html. 19 * 20 */ 21 22 #ifndef _KERNEL_UTF_HELPERS_USER_H_ 23 #define _KERNEL_UTF_HELPERS_USER_H_ 24 25 /* kutf_helpers.h 26 * Test helper functions for the kernel UTF test infrastructure, whose 27 * implementation mirrors that of similar functions for kutf-userside 28 */ 29 30 #include <kutf/kutf_suite.h> 31 #include <kutf/kutf_helpers.h> 32 33 34 #define KUTF_HELPER_MAX_VAL_NAME_LEN 255 35 36 enum kutf_helper_valtype { 37 KUTF_HELPER_VALTYPE_INVALID, 38 KUTF_HELPER_VALTYPE_U64, 39 KUTF_HELPER_VALTYPE_STR, 40 41 KUTF_HELPER_VALTYPE_COUNT /* Must be last */ 42 }; 43 44 struct kutf_helper_named_val { 45 enum kutf_helper_valtype type; 46 char *val_name; 47 union { 48 u64 val_u64; 49 char *val_str; 50 } u; 51 }; 52 53 /* Extra error values for certain helpers when we want to distinguish between 54 * Linux's own error values too. 55 * 56 * These can only be used on certain functions returning an int type that are 57 * documented as returning one of these potential values, they cannot be used 58 * from functions return a ptr type, since we can't decode it with PTR_ERR 59 * 60 * No negative values are used - Linux error codes should be used instead, and 61 * indicate a problem in accessing the data file itself (are generally 62 * unrecoverable) 63 * 64 * Positive values indicate correct access but invalid parsing (can be 65 * recovered from assuming data in the future is correct) 66 */ 67 enum kutf_helper_err { 68 /* No error - must be zero */ 69 KUTF_HELPER_ERR_NONE = 0, 70 /* Named value parsing encountered an invalid name */ 71 KUTF_HELPER_ERR_INVALID_NAME, 72 /* Named value parsing of string or u64 type encountered extra 73 * characters after the value (after the last digit for a u64 type or 74 * after the string end delimiter for string type) 75 */ 76 KUTF_HELPER_ERR_CHARS_AFTER_VAL, 77 /* Named value parsing of string type couldn't find the string end 78 * delimiter. 79 * 80 * This cannot be encountered when the NAME="value" message exceeds the 81 * textbuf's maximum line length, because such messages are not checked 82 * for an end string delimiter 83 */ 84 KUTF_HELPER_ERR_NO_END_DELIMITER, 85 /* Named value didn't parse as any of the known types */ 86 KUTF_HELPER_ERR_INVALID_VALUE, 87 }; 88 89 90 /* Send named NAME=value pair, u64 value 91 * 92 * NAME must match [A-Z0-9_]\+ and can be up to MAX_VAL_NAME_LEN characters long 93 * 94 * Any failure will be logged on the suite's current test fixture 95 * 96 * Returns 0 on success, non-zero on failure 97 */ 98 int kutf_helper_send_named_u64(struct kutf_context *context, 99 const char *val_name, u64 val); 100 101 /* Get the maximum length of a string that can be represented as a particular 102 * NAME="value" pair without string-value truncation in the kernel's buffer 103 * 104 * Given val_name and the kernel buffer's size, this can be used to determine 105 * the maximum length of a string that can be sent as val_name="value" pair 106 * without having the string value truncated. Any string longer than this will 107 * be truncated at some point during communication to this size. 108 * 109 * It is assumed that val_name is a valid name for 110 * kutf_helper_send_named_str(), and no checking will be made to 111 * ensure this. 112 * 113 * Returns the maximum string length that can be represented, or a negative 114 * value if the NAME="value" encoding itself wouldn't fit in kern_buf_sz 115 */ 116 int kutf_helper_max_str_len_for_kern(const char *val_name, int kern_buf_sz); 117 118 /* Send named NAME="str" pair 119 * 120 * no escaping allowed in str. Any of the following characters will terminate 121 * the string: '"' '\\' '\n' 122 * 123 * NAME must match [A-Z0-9_]\+ and can be up to MAX_VAL_NAME_LEN characters long 124 * 125 * Any failure will be logged on the suite's current test fixture 126 * 127 * Returns 0 on success, non-zero on failure 128 */ 129 int kutf_helper_send_named_str(struct kutf_context *context, 130 const char *val_name, const char *val_str); 131 132 /* Receive named NAME=value pair 133 * 134 * This can receive u64 and string values - check named_val->type 135 * 136 * If you are not planning on dynamic handling of the named value's name and 137 * type, then kutf_helper_receive_check_val() is more useful as a 138 * convenience function. 139 * 140 * String members of named_val will come from memory allocated on the fixture's mempool 141 * 142 * Returns 0 on success. Negative value on failure to receive from the 'run' 143 * file, positive value indicates an enum kutf_helper_err value for correct 144 * reception of data but invalid parsing 145 */ 146 int kutf_helper_receive_named_val( 147 struct kutf_context *context, 148 struct kutf_helper_named_val *named_val); 149 150 /* Receive and validate NAME=value pair 151 * 152 * As with kutf_helper_receive_named_val, but validate that the 153 * name and type are as expected, as a convenience for a common pattern found 154 * in tests. 155 * 156 * NOTE: this only returns an error value if there was actually a problem 157 * receiving data. 158 * 159 * NOTE: If the underlying data was received correctly, but: 160 * - isn't of the expected name 161 * - isn't the expected type 162 * - isn't correctly parsed for the type 163 * then the following happens: 164 * - failure result is recorded 165 * - named_val->type will be KUTF_HELPER_VALTYPE_INVALID 166 * - named_val->u will contain some default value that should be relatively 167 * harmless for the test, including being writable in the case of string 168 * values 169 * - return value will be 0 to indicate success 170 * 171 * The rationale behind this is that we'd prefer to continue the rest of the 172 * test with failures propagated, rather than hitting a timeout 173 */ 174 int kutf_helper_receive_check_val( 175 struct kutf_helper_named_val *named_val, 176 struct kutf_context *context, 177 const char *expect_val_name, 178 enum kutf_helper_valtype expect_val_type); 179 180 /* Output a named value to kmsg */ 181 void kutf_helper_output_named_val(struct kutf_helper_named_val *named_val); 182 183 184 #endif /* _KERNEL_UTF_HELPERS_USER_H_ */ 185