blob: e147cbb90154d23d79e1557da83ca02bbf399f89 [file] [log] [blame]
/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
* (C) COPYRIGHT 2017, 2020-2021 ARM Limited. All rights reserved.
* This program is free software and is provided to you under the terms of the
* GNU General Public License version 2 as published by the Free Software
* Foundation, and any use by you of this program is subject to the terms
* of such GNU license.
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* GNU General Public License for more details.
* You should have received a copy of the GNU General Public License
* along with this program; if not, you can access it online at
/* kutf_helpers.h
* Test helper functions for the kernel UTF test infrastructure, whose
* implementation mirrors that of similar functions for kutf-userside
#include <kutf/kutf_suite.h>
#include <kutf/kutf_helpers.h>
enum kutf_helper_valtype {
struct kutf_helper_named_val {
enum kutf_helper_valtype type;
char *val_name;
union {
u64 val_u64;
char *val_str;
} u;
/* Extra error values for certain helpers when we want to distinguish between
* Linux's own error values too.
* These can only be used on certain functions returning an int type that are
* documented as returning one of these potential values, they cannot be used
* from functions return a ptr type, since we can't decode it with PTR_ERR
* No negative values are used - Linux error codes should be used instead, and
* indicate a problem in accessing the data file itself (are generally
* unrecoverable)
* Positive values indicate correct access but invalid parsing (can be
* recovered from assuming data in the future is correct)
enum kutf_helper_err {
/* No error - must be zero */
/* Named value parsing encountered an invalid name */
/* Named value parsing of string or u64 type encountered extra
* characters after the value (after the last digit for a u64 type or
* after the string end delimiter for string type)
/* Named value parsing of string type couldn't find the string end
* delimiter.
* This cannot be encountered when the NAME="value" message exceeds the
* textbuf's maximum line length, because such messages are not checked
* for an end string delimiter
/* Named value didn't parse as any of the known types */
/* Send named NAME=value pair, u64 value
* NAME must match [A-Z0-9_]\+ and can be up to MAX_VAL_NAME_LEN characters long
* Any failure will be logged on the suite's current test fixture
* Returns 0 on success, non-zero on failure
int kutf_helper_send_named_u64(struct kutf_context *context,
const char *val_name, u64 val);
/* Get the maximum length of a string that can be represented as a particular
* NAME="value" pair without string-value truncation in the kernel's buffer
* Given val_name and the kernel buffer's size, this can be used to determine
* the maximum length of a string that can be sent as val_name="value" pair
* without having the string value truncated. Any string longer than this will
* be truncated at some point during communication to this size.
* It is assumed that val_name is a valid name for
* kutf_helper_send_named_str(), and no checking will be made to
* ensure this.
* Returns the maximum string length that can be represented, or a negative
* value if the NAME="value" encoding itself wouldn't fit in kern_buf_sz
int kutf_helper_max_str_len_for_kern(const char *val_name, int kern_buf_sz);
/* Send named NAME="str" pair
* no escaping allowed in str. Any of the following characters will terminate
* the string: '"' '\\' '\n'
* NAME must match [A-Z0-9_]\+ and can be up to MAX_VAL_NAME_LEN characters long
* Any failure will be logged on the suite's current test fixture
* Returns 0 on success, non-zero on failure
int kutf_helper_send_named_str(struct kutf_context *context,
const char *val_name, const char *val_str);
/* Receive named NAME=value pair
* This can receive u64 and string values - check named_val->type
* If you are not planning on dynamic handling of the named value's name and
* type, then kutf_helper_receive_check_val() is more useful as a
* convenience function.
* String members of named_val will come from memory allocated on the fixture's mempool
* Returns 0 on success. Negative value on failure to receive from the 'run'
* file, positive value indicates an enum kutf_helper_err value for correct
* reception of data but invalid parsing
int kutf_helper_receive_named_val(
struct kutf_context *context,
struct kutf_helper_named_val *named_val);
/* Receive and validate NAME=value pair
* As with kutf_helper_receive_named_val, but validate that the
* name and type are as expected, as a convenience for a common pattern found
* in tests.
* NOTE: this only returns an error value if there was actually a problem
* receiving data.
* NOTE: If the underlying data was received correctly, but:
* - isn't of the expected name
* - isn't the expected type
* - isn't correctly parsed for the type
* then the following happens:
* - failure result is recorded
* - named_val->type will be KUTF_HELPER_VALTYPE_INVALID
* - named_val->u will contain some default value that should be relatively
* harmless for the test, including being writable in the case of string
* values
* - return value will be 0 to indicate success
* The rationale behind this is that we'd prefer to continue the rest of the
* test with failures propagated, rather than hitting a timeout
int kutf_helper_receive_check_val(
struct kutf_helper_named_val *named_val,
struct kutf_context *context,
const char *expect_val_name,
enum kutf_helper_valtype expect_val_type);
/* Output a named value to kmsg */
void kutf_helper_output_named_val(struct kutf_helper_named_val *named_val);