diff options
Diffstat (limited to 'mali_kbase/tests/include/kutf/kutf_helpers.h')
| -rw-r--r-- | mali_kbase/tests/include/kutf/kutf_helpers.h | 202 |
1 files changed, 29 insertions, 173 deletions
diff --git a/mali_kbase/tests/include/kutf/kutf_helpers.h b/mali_kbase/tests/include/kutf/kutf_helpers.h index 3f1dfc2..3667687 100644 --- a/mali_kbase/tests/include/kutf/kutf_helpers.h +++ b/mali_kbase/tests/include/kutf/kutf_helpers.h @@ -21,196 +21,52 @@ /* kutf_helpers.h * Test helper functions for the kernel UTF test infrastructure. * - * This collection of helper functions are provided as 'stock' implementation - * helpers for certain features of kutf. Tests can implement common/boilerplate - * functionality using these, whilst still providing them the option of - * implementing completely custom functions themselves to use those kutf - * features. + * These functions provide methods for enqueuing/dequeuing lines of text sent + * by user space. They are used to implement the transfer of "userdata" from + * user space to kernel. */ #include <kutf/kutf_suite.h> -#include <kutf/kutf_mem.h> -#include <linux/wait.h> /** - * enum kutf_helper_textbuf_flag - flags for textbufs - * @KUTF_HELPER_TEXTBUF_FLAG_DYING: Test is dying, textbuf should not allow - * writes, nor block on empty. - */ -enum kutf_helper_textbuf_flag { - KUTF_HELPER_TEXTBUF_FLAG_DYING = (1u << 0), -}; - -/** - * struct kutf_helper_textbuf_line - Structure representing a line of text + * kutf_helper_input_dequeue() - Dequeue a line sent by user space + * @context: KUTF context + * @str_size: Pointer to an integer to receive the size of the string * - * The string itself is stored immediately after this. + * If no line is available then this function will wait (interruptibly) until + * a line is available. * - * @node: List node for the textbuf's textbuf_list - * @str_size: Length of the string buffer, including the \0 terminator - * @str: 'Flexible array' for the string representing the line + * Return: The line dequeued, ERR_PTR(-EINTR) if interrupted or NULL on end + * of data. */ -struct kutf_helper_textbuf_line { - struct list_head node; - int str_size; - char str[]; -}; - -/** - * struct kutf_helper_textbuf - Structure to representing sequential lines of - * text - * @lock: mutex to hold whilst accessing the structure - * @nr_user_clients: Number of userspace clients connected via an open() - * call - * @mempool: mempool for allocating lines - * @scratchpad: scratch area for receiving text of size max_line_size - * @used_bytes: number of valid bytes in the scratchpad - * @prev_pos: Previous position userspace has accessed - * @prev_line_pos: Previous start of line position userspace has accessed - * @textbuf_list: List head to store all the lines of text - * @max_line_size: Maximum size in memory allowed for a line of text - * @max_nr_lines: Maximum number of lines permitted in this textbuf - * @nr_lines: Number of entries in textbuf_list - * @flags: Flags indicating state of the textbuf, using values - * from enum kutf_helper_textbuf_flag - * @user_opened_wq: Waitq for when there's at least one userspace client - * connected to the textbuf via an open() call - * @not_full_wq: Waitq for when the textbuf can be enqueued into/can - * consume data from userspace - * @not_empty_wq: Waitq for when the textbuf can be dequeued from/can - * produce data for userspace - */ - -struct kutf_helper_textbuf { - struct mutex lock; - int nr_user_clients; - struct kutf_mempool *mempool; - char *scratchpad; - int used_bytes; - loff_t prev_pos; - loff_t prev_line_pos; - struct list_head textbuf_list; - int max_line_size; - int max_nr_lines; - int nr_lines; - unsigned long flags; - wait_queue_head_t user_opened_wq; - wait_queue_head_t not_full_wq; - wait_queue_head_t not_empty_wq; - -}; - -/* stock callbacks for userspace to read from/write to the 'data' file as a - * textbuf */ -extern struct kutf_userdata_ops kutf_helper_textbuf_userdata_ops; +char *kutf_helper_input_dequeue(struct kutf_context *context, size_t *str_size); /** - * kutf_helper_textbuf_init() - init a textbuf for use as a 'data' file - * consumer/producer - * @textbuf: textbuf to initialize - * @mempool: mempool to allocate from - * @max_line_size: maximum line size expected to/from userspace - * @max_nr_lines: maximum number of lines to expect to/from userspace + * kutf_helper_input_enqueue() - Enqueue a line sent by user space + * @context: KUTF context + * @str: The user space address of the line + * @size: The length in bytes of the string * - * Initialize a textbuf so that it can consume writes made to the 'data' file, - * and produce reads for userspace on the 'data' file. Tests may then read the - * lines written by userspace, or fill the buffer so it may be read back by - * userspace. + * This function will use copy_from_user to copy the string out of user space. + * The string need not be NULL-terminated (@size should not include the NULL + * termination). * - * The caller should write the @textbuf pointer into the kutf_context's - * userdata_producer_priv or userdata_consumer_priv member during fixture - * creation. + * As a special case @str==NULL and @size==0 is valid to mark the end of input, + * but callers should use kutf_helper_input_enqueue_end_of_data() instead. * - * Usually a test will have separate textbufs for userspace to write to and - * read from. Using the same one for both will echo back to the user what they - * are writing. - * - * Lines are understood as being separated by the '\n' character, but no '\n' - * characters will be observed by the test - * - * @max_line_size puts an upper bound on the size of lines in a textbuf, - * including the \0 terminator. Lines exceeding this will be truncated, - * effectively ignoring incoming data until the next '\n' - * - * Combining this with @max_nr_lines puts an upper bound on the size of the - * file read in - * - * Return: 0 on success, or negative value on error. + * Return: 0 on success, -EFAULT if the line cannot be copied from user space, + * -ENOMEM if out of memory. */ -int kutf_helper_textbuf_init(struct kutf_helper_textbuf *textbuf, - struct kutf_mempool *mempool, int max_line_size, - int max_nr_lines); +int kutf_helper_input_enqueue(struct kutf_context *context, + const char __user *str, size_t size); /** - * kutf_helper_textbuf_wait_for_user() - wait for userspace to open the 'data' - * file - * @textbuf: textbuf to wait on - * - * This can be used to synchronize with userspace so that subsequent calls to - * kutf_helper_textbuf_dequeue() and kutf_helper_textbuf_enqueue() should - * succeed. - * - * Waiting is done on a timeout. - * - * There is of course no guarantee that userspace will keep the file open after - * this, but any error in the dequeue/enqueue functions afterwards can be - * treated as such rather than "we're still waiting for userspace to begin" - * - * Return: 0 if waited successfully, -ETIMEDOUT if we exceeded the - * timeout, or some other negative value if there was an - * error during waiting. - */ - -int kutf_helper_textbuf_wait_for_user(struct kutf_helper_textbuf *textbuf); - - -/** - * kutf_helper_textbuf_dequeue() - dequeue a line from a textbuf - * @textbuf: textbuf dequeue a line as a string from - * @str_size: pointer to storage to receive the size of the string, - * which includes the '\0' terminator, or NULL if not - * required - * - * Dequeue (remove) a line from the start of the textbuf as a string, and - * return it. - * - * If no lines are available, then this will block until a line has been - * submitted. If a userspace client is not connected and there are no remaining - * lines, then this function returns NULL instead. - * - * The memory for the string comes from the kutf_mempool given during - * initialization of the textbuf, and shares the same lifetime as it. - * - * Return: pointer to the next line of the textbuf. NULL indicated - * all userspace clients disconnected. An error value to be - * checked with IS_ERR() family of functions if a signal or - * some other error occurred - */ -char *kutf_helper_textbuf_dequeue(struct kutf_helper_textbuf *textbuf, - int *str_size); - -/** - * kutf_helper_textbuf_enqueue() - enqueue a line to a textbuf - * @textbuf: textbuf to enqueue a line as a string to - * @enqueue_str: pointer to the string to enqueue to the textbuf - * @buf_max_size: maximum size of the buffer holding @enqueue_str - * - * Enqueue (add) a line to the end of a textbuf as a string. - * - * The caller should avoid placing '\n' characters in their strings, as these - * will not be split into multiple lines. - * - * A copy of the string will be made into the textbuf, so @enqueue_str can be - * freed immediately after if.the caller wishes to do so. - * - * If the maximum amount of lines has been reached, then this will block until - * a line has been removed to make space. If a userspace client is not - * connected and there is no space available, then this function returns - * -EBUSY. + * kutf_helper_input_enqueue_end_of_data() - Signal no more data is to be sent + * @context: KUTF context * - * Return: 0 on success, or negative value on error + * After this function has been called, kutf_helper_input_dequeue() will always + * return NULL. */ -int kutf_helper_textbuf_enqueue(struct kutf_helper_textbuf *textbuf, - char *enqueue_str, int buf_max_size); +void kutf_helper_input_enqueue_end_of_data(struct kutf_context *context); #endif /* _KERNEL_UTF_HELPERS_H_ */ |