1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */ 2 /* 3 * 4 * (C) COPYRIGHT 2014, 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_RESULTSET_H_ 23 #define _KERNEL_UTF_RESULTSET_H_ 24 25 /* kutf_resultset.h 26 * Functions and structures for handling test results and result sets. 27 * 28 * This section of the kernel UTF contains structures and functions used for the 29 * management of Results and Result Sets. 30 */ 31 32 /** 33 * enum kutf_result_status - Status values for a single Test error. 34 * @KUTF_RESULT_BENCHMARK: Result is a meta-result containing benchmark 35 * results. 36 * @KUTF_RESULT_SKIP: The test was skipped. 37 * @KUTF_RESULT_UNKNOWN: The test has an unknown result. 38 * @KUTF_RESULT_PASS: The test result passed. 39 * @KUTF_RESULT_DEBUG: The test result passed, but raised a debug 40 * message. 41 * @KUTF_RESULT_INFO: The test result passed, but raised 42 * an informative message. 43 * @KUTF_RESULT_WARN: The test result passed, but raised a warning 44 * message. 45 * @KUTF_RESULT_FAIL: The test result failed with a non-fatal error. 46 * @KUTF_RESULT_FATAL: The test result failed with a fatal error. 47 * @KUTF_RESULT_ABORT: The test result failed due to a non-UTF 48 * assertion failure. 49 * @KUTF_RESULT_USERDATA: User data is ready to be read, 50 * this is not seen outside the kernel 51 * @KUTF_RESULT_USERDATA_WAIT: Waiting for user data to be sent, 52 * this is not seen outside the kernel 53 * @KUTF_RESULT_TEST_FINISHED: The test has finished, no more results will 54 * be produced. This is not seen outside kutf 55 */ 56 enum kutf_result_status { 57 KUTF_RESULT_BENCHMARK = -3, 58 KUTF_RESULT_SKIP = -2, 59 KUTF_RESULT_UNKNOWN = -1, 60 61 KUTF_RESULT_PASS = 0, 62 KUTF_RESULT_DEBUG = 1, 63 KUTF_RESULT_INFO = 2, 64 KUTF_RESULT_WARN = 3, 65 KUTF_RESULT_FAIL = 4, 66 KUTF_RESULT_FATAL = 5, 67 KUTF_RESULT_ABORT = 6, 68 69 KUTF_RESULT_USERDATA = 7, 70 KUTF_RESULT_USERDATA_WAIT = 8, 71 KUTF_RESULT_TEST_FINISHED = 9 72 }; 73 74 /* The maximum size of a kutf_result_status result when 75 * converted to a string 76 */ 77 #define KUTF_ERROR_MAX_NAME_SIZE 21 78 79 #ifdef __KERNEL__ 80 81 #include <kutf/kutf_mem.h> 82 #include <linux/wait.h> 83 84 struct kutf_context; 85 86 /** 87 * struct kutf_result - Represents a single test result. 88 * @node: Next result in the list of results. 89 * @status: The status summary (pass / warn / fail / etc). 90 * @message: A more verbose status message. 91 */ 92 struct kutf_result { 93 struct list_head node; 94 enum kutf_result_status status; 95 const char *message; 96 }; 97 98 /** 99 * KUTF_RESULT_SET_WAITING_FOR_INPUT - Test is waiting for user data 100 * 101 * This flag is set within a struct kutf_result_set whenever the test is blocked 102 * waiting for user data. Attempts to dequeue results when this flag is set 103 * will cause a dummy %KUTF_RESULT_USERDATA_WAIT result to be produced. This 104 * is used to output a warning message and end of file. 105 */ 106 #define KUTF_RESULT_SET_WAITING_FOR_INPUT 1 107 108 /** 109 * struct kutf_result_set - Represents a set of results. 110 * @results: List head of a struct kutf_result list for storing the results 111 * @waitq: Wait queue signalled whenever new results are added. 112 * @flags: Flags see %KUTF_RESULT_SET_WAITING_FOR_INPUT 113 */ 114 struct kutf_result_set { 115 struct list_head results; 116 wait_queue_head_t waitq; 117 int flags; 118 }; 119 120 /** 121 * kutf_create_result_set() - Create a new result set 122 * to which results can be added. 123 * 124 * Return: The created result set. 125 */ 126 struct kutf_result_set *kutf_create_result_set(void); 127 128 /** 129 * kutf_add_result() - Add a result to the end of an existing result set. 130 * 131 * @context: The kutf context 132 * @status: The result status to add. 133 * @message: The result message to add. 134 * 135 * Return: 0 if the result is successfully added. -ENOMEM if allocation fails. 136 */ 137 int kutf_add_result(struct kutf_context *context, 138 enum kutf_result_status status, const char *message); 139 140 /** 141 * kutf_remove_result() - Remove a result from the head of a result set. 142 * @set: The result set. 143 * 144 * This function will block until there is a result to read. The wait is 145 * interruptible, so this function will return with an ERR_PTR if interrupted. 146 * 147 * Return: result or ERR_PTR if interrupted 148 */ 149 struct kutf_result *kutf_remove_result( 150 struct kutf_result_set *set); 151 152 /** 153 * kutf_destroy_result_set() - Free a previously created result set. 154 * 155 * @results: The result set whose resources to free. 156 */ 157 void kutf_destroy_result_set(struct kutf_result_set *results); 158 159 /** 160 * kutf_set_waiting_for_input() - The test is waiting for userdata 161 * 162 * @set: The result set to update 163 * 164 * Causes the result set to always have results and return a fake 165 * %KUTF_RESULT_USERDATA_WAIT result. 166 */ 167 void kutf_set_waiting_for_input(struct kutf_result_set *set); 168 169 /** 170 * kutf_clear_waiting_for_input() - The test is no longer waiting for userdata 171 * 172 * @set: The result set to update 173 * 174 * Cancels the effect of kutf_set_waiting_for_input() 175 */ 176 void kutf_clear_waiting_for_input(struct kutf_result_set *set); 177 178 #endif /* __KERNEL__ */ 179 180 #endif /* _KERNEL_UTF_RESULTSET_H_ */ 181