/*
 * This file and its contents are supplied under the terms of the
 * Common Development and Distribution License ("CDDL"), version 1.0.
 * You may only use this file in accordance with the terms of version
 * 1.0 of the CDDL.
 *
 * A full copy of the text of the CDDL should have accompanied this
 * source.  A copy of the CDDL is also available via the Internet at
 * http://www.illumos.org/license/CDDL.
 */

/*
 * Copyright 2023 Oxide Computer Company
 * Copyright 2024 Ryan Zezeski
 */

/*
 * This file defines both the userspace ioctl API/ABI as well as the
 * ktest module API/ABI. The latter is everything hidden behind the
 * _KERNEL guard.
 */
#ifndef	_SYS_KTEST_H
#define	_SYS_KTEST_H

#include <sys/ddi.h>
#include <sys/sunddi.h>
#include <sys/modctl.h>
#include <sys/param.h>
#include <sys/types.h>

#ifdef __cplusplus
extern "C" {
#endif

#define	KTEST_SEPARATOR		":"
#define	KTEST_DEF_TRIPLE	"*:*:*"
#define	KTEST_DEF_TRIPLE_SZ	6
#define	KTEST_MAX_NAME_LEN	64
#define	KTEST_MAX_TRIPLE_LEN	((KTEST_MAX_NAME_LEN * 3) + 3)
#define	KTEST_MAX_LOG_LEN	4096
#define	KTEST_NAME_KEY		"name"
#define	KTEST_MODULE_KEY	"module"
#define	KTEST_MODULE_SUITES_KEY	"suites"
#define	KTEST_SUITE_KEY		"suite"
#define	KTEST_SUITE_TESTS_KEY	"tests"
#define	KTEST_TEST_KEY		"test"
#define	KTEST_TEST_INPUT_KEY	"input_required"
#define	KTEST_GMATCH_CHARS	"*?[]"

#define	KTEST_SER_FMT_KEY	"ser_fmt_version"
#define	KTEST_SER_FMT_VSN	1ULL

/*
 * The maximum amount of memory a user ioctl could require ktest to
 * allocate in order to respond to the request. This doesn't include
 * the actions of the test themselves. It's more to prevent a
 * negligent ioctl directly causing ktest to kmem_alloc(9F) an
 * arbitrarily large buffer.
 *
 * This also currently includes any input streams for a test, thus the
 * cap is larger than you might expect it would be. In the future we
 * should have the ktest driver directly read the file from kernel
 * space, but for now we pass them as part of the packed nvlist via
 * the ioctl interface.
 */
#define	KTEST_IOCTL_MAX_LEN	(64 * 1024 * 1024)

#define	KTEST_IOCTL	(('k' << 16) | ('t' << 8))

typedef enum ktest_ioctl {
	KTEST_IOCTL_RUN_TEST	= (KTEST_IOCTL | 1),
	KTEST_IOCTL_LIST_TESTS	= (KTEST_IOCTL | 2),
} ktest_ioctl_t;

/*
 * Flags used to alter the behavior of ktest or convey additional
 * information about the test. Passed as the final argument to
 * ktest_add_test(9F).
 *
 * KTEST_FLAG_INPUT
 *
 *    This test requires an input stream.
 *
 */
typedef enum ktest_test_flags {
	KTEST_FLAG_NONE	= 0,
	KTEST_FLAG_INPUT	= (1 << 0),
} ktest_test_flags_t;

/*
 * See the ktest architecture comment in ktest.c for the semantics of
 * these values. The KTEST_RESULT_NONE value indicates that the test
 * failed to set a result and should be considered a bug in the test.
 */
typedef enum ktest_result_type {
	KTEST_RESULT_NONE,
	KTEST_RESULT_PASS,
	KTEST_RESULT_FAIL,
	KTEST_RESULT_SKIP,
	KTEST_RESULT_ERROR
} ktest_result_type_t;

/* The result of a single test. */
typedef struct ktest_result {
	char			kr_msg_prepend[KTEST_MAX_LOG_LEN];
	char			kr_msg[KTEST_MAX_LOG_LEN];
	ktest_result_type_t	kr_type;
	int			kr_line;
} ktest_result_t;

typedef struct ktest_run_op {
	char		kro_module[KTEST_MAX_NAME_LEN];
	char		kro_suite[KTEST_MAX_NAME_LEN];
	char		kro_test[KTEST_MAX_NAME_LEN];
	char		kro_input_path[MAXPATHLEN];
	uchar_t		*kro_input_bytes;
	uint64_t	kro_input_len;
	ktest_result_t	kro_result;
} ktest_run_op_t;

typedef struct ktest_list_op {
	char		*klo_resp;
	size_t		klo_resp_len;
} ktest_list_op_t;

/*
 * The following API/ABI is for the ktest modules.
 */
#ifdef _KERNEL

typedef struct __ktest_module_hdl ktest_module_hdl_t;
typedef struct __ktest_suite_hdl ktest_suite_hdl_t;
typedef struct __ktest_test_hdl ktest_test_hdl_t;
typedef struct __ktest_ctx_hdl ktest_ctx_hdl_t;

typedef void (*ktest_fn_t)(ktest_ctx_hdl_t *);

/*
 * Module, suite, and test creation/registration.
 */
int ktest_create_module(const char *, ktest_module_hdl_t **);
int ktest_add_suite(ktest_module_hdl_t *, const char *, ktest_suite_hdl_t **);
int ktest_add_test(ktest_suite_hdl_t *, const char *, ktest_fn_t,
    ktest_test_flags_t);
int ktest_register_module(ktest_module_hdl_t *);
void ktest_unregister_module(const char *);
void ktest_free_module(ktest_module_hdl_t *);

/*
 * Utility for getting a handle to static functions.
 */
int ktest_hold_mod(const char *, ddi_modhandle_t *);
void ktest_release_mod(ddi_modhandle_t);
int ktest_get_fn(ddi_modhandle_t, const char *, void **);

/*
 * Retrieve the input stream for a test.
 */
void ktest_get_input(const ktest_ctx_hdl_t *, uchar_t **, size_t *);

/*
 * Set the test result.
 */
void ktest_result_skip(ktest_ctx_hdl_t *, int, const char *, ...);
void ktest_result_fail(ktest_ctx_hdl_t *, int, const char *, ...);
void ktest_result_error(ktest_ctx_hdl_t *, int, const char *, ...);
void ktest_result_pass(ktest_ctx_hdl_t *, int);
void ktest_msg_clear(ktest_ctx_hdl_t *);
void ktest_msg_prepend(ktest_ctx_hdl_t *, const char *fmt, ...);

/*
 * Note: All the macros wrap the stringizing parameters in parentheses,
 * otherwise make check complains "preprocessor statement not in column 1".
 */

#define	KT_PASS(ctx)	ktest_result_pass((ctx), __LINE__)

#define	KT_FAIL(ctx, msg, ...)						\
	ktest_result_fail((ctx), __LINE__, (msg), ##__VA_ARGS__)

#define	KT_ERROR(ctx, msg, ...)						\
	ktest_result_error((ctx), __LINE__, (msg), ##__VA_ARGS__)

#define	KT_SKIP(ctx, msg, ...)						\
	ktest_result_skip((ctx), __LINE__, (msg), ##__VA_ARGS__)

/*
 * KTest ASSERT
 *
 * If the expression fails, then stash the failure message in ctx and
 * return from the calling function.
 */
#define	KT_ASSERT_IMPL(LEFT, OP, RIGHT, TYPE, ctx) do {			\
	const TYPE __left = (TYPE)(LEFT);				\
	const TYPE __right = (TYPE)(RIGHT);				\
	const boolean_t __res = __left OP __right;			\
	if (!__res) {							\
		ktest_result_fail((ctx), __LINE__,			\
		    "%s %s %s"						\
		    " (0x%" PRIxMAX " %s 0x%" PRIxMAX ")",		\
		    (#LEFT), (#OP), (#RIGHT),				\
		    (uintmax_t)__left, (#OP), (uintmax_t)__right);	\
		return;							\
	}								\
	_NOTE(CONSTCOND)  } while (0)

#define	KT_ASSERT3S(l, op, r, ctx)			\
	KT_ASSERT_IMPL(l, op, r, int64_t, ctx)

#define	KT_ASSERT3U(l, op, r, ctx)			\
	KT_ASSERT_IMPL(l, op, r, uint64_t, ctx)

#define	KT_ASSERT3P(l, op, r, ctx)			\
	KT_ASSERT_IMPL(l, op, r, uintptr_t, ctx)

#define	KT_ASSERT(exp, ctx)				\
	KT_ASSERT_IMPL(exp, ==, B_TRUE, boolean_t, ctx)

#define	KT_ASSERT0(exp, ctx)				\
	KT_ASSERT_IMPL(exp, ==, 0, uintmax_t, ctx)

/*
 * KTest ASSERT Goto
 *
 * If the expression fails, then stash the failure message in ctx and
 * goto label.
 */
#define	KT_ASSERTG_IMPL(LEFT, OP, RIGHT, TYPE, ctx, label) do {		\
	const TYPE __left = (TYPE)(LEFT);				\
	const TYPE __right = (TYPE)(RIGHT);				\
	const boolean_t __res = __left OP __right;			\
	if (!__res) {							\
		ktest_result_fail((ctx), __LINE__,			\
		    "%s %s %s"						\
		    " (0x%" PRIxMAX " %s 0x%" PRIxMAX ")",		\
		    (#LEFT), (#OP), (#RIGHT),				\
		    (uintmax_t)__left, (#OP), (uintmax_t)__right);	\
		goto label;						\
	}								\
	_NOTE(CONSTCOND)  } while (0)

#define	KT_ASSERT3SG(l, op, r, ctx, label)			\
	KT_ASSERTG_IMPL(l, op, r, int64_t, ctx, label)

#define	KT_ASSERT3UG(l, op, r, ctx, label)			\
	KT_ASSERTG_IMPL(l, op, r, uint64_t, ctx, label)

#define	KT_ASSERT3PG(l, op, r, ctx, label)			\
	KT_ASSERTG_IMPL(l, op, r, uintptr_t, ctx, label)

#define	KT_ASSERTG(exp, ctx, label)				\
	KT_ASSERTG_IMPL(exp, ==, B_TRUE, boolean_t, ctx, label)

#define	KT_ASSERT0G(x, ctx, label)				\
	KT_ASSERTG_IMPL(x, ==, 0, uintmax_t, ctx, label)

/*
 * KTest ERROR Macros
 *
 * These are modeled after the KTest ASSERT macros, but are instead
 * used to check for error conditions.
 */
#define	KT_EASSERT_IMPL(LEFT, OP, RIGHT, TYPE, ctx) do {		\
	const TYPE __left = (TYPE)(LEFT);				\
	const TYPE __right = (TYPE)(RIGHT);				\
	const boolean_t __res = __left OP __right;			\
	if (!__res) {							\
		ktest_result_error((ctx), __LINE__,			\
		    "%s %s %s"						\
		    " (0x%" PRIxMAX " %s 0x%" PRIxMAX ")",		\
		    (#LEFT), (#OP), (#RIGHT),				\
		    (uintmax_t)__left, #OP, (uintmax_t)__right);	\
		return;							\
	}								\
	_NOTE(CONSTCOND)  } while (0)

#define	KT_EASSERT3S(l, op, r, ctx)			\
	KT_EASSERT_IMPL(l, op, r, int64_t, ctx)

#define	KT_EASSERT3U(l, op, r, ctx)			\
	KT_EASSERT_IMPL(l, op, r, uint64_t, ctx)

#define	KT_EASSERT3P(l, op, r, ctx)			\
	KT_EASSERT_IMPL(l, op, r, uintptr_t, ctx)

#define	KT_EASSERT(exp, ctx)				\
	KT_EASSERT_IMPL(exp, ==, B_TRUE, boolean_t, ctx)

#define	KT_EASSERT0(exp, ctx)				\
	KT_EASSERT_IMPL(exp, ==, 0, uintmax_t, ctx)

/*
 * KTest ERROR Goto
 *
 * These are modeled after the KTest ASSERT Goto macros, but are
 * instead used to check for error conditions.
 */
#define	KT_EASSERTG_IMPL(LEFT, OP, RIGHT, TYPE, ctx, label) do {	\
	const TYPE __left = (TYPE)(LEFT);				\
	const TYPE __right = (TYPE)(RIGHT);				\
	const boolean_t __res = __left OP __right;			\
	if (!__res) {							\
		ktest_result_error((ctx), __LINE__,			\
		    "%s %s %s"						\
		    " (0x%" PRIxMAX " %s 0x%" PRIxMAX ")",		\
		    (#LEFT), (#OP), (#RIGHT),				\
		    (uintmax_t)__left, #OP, (uintmax_t)__right);	\
		goto label;						\
	}								\
	_NOTE(CONSTCOND)  } while (0)

#define	KT_EASSERT3SG(l, op, r, ctx, label)			\
	KT_EASSERTG_IMPL(l, op, r, int64_t, ctx, label)

#define	KT_EASSERT3UG(l, op, r, ctx, label)			\
	KT_EASSERTG_IMPL(l, op, r, uint64_t, ctx, label)

#define	KT_EASSERT3PG(l, op, r, ctx, label)			\
	KT_EASSERTG_IMPL(l, op, r, uintptr_t, ctx, label)

#define	KT_EASSERTG(exp, ctx, label)				\
	KT_EASSERTG_IMPL(exp, ==, B_TRUE, boolean_t, ctx, label)

#define	KT_EASSERT0G(x, ctx, label)				\
	KT_EASSERTG_IMPL(x, ==, 0, uintmax_t, ctx, label)

#endif	/* _KERNEL */

#ifdef __cplusplus
}
#endif

#endif /* _SYS_KTEST_H */