1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2023 Oxide Computer Company 13.\" Copyright 2024 Ryan Zezeski 14.\" 15.Dd February 8, 2024 16.Dt KTEST_CREATE_MODULE 9F 17.Os 18.Sh NAME 19.Nm ktest_create_module , 20.Nm ktest_add_suite , 21.Nm ktest_add_test , 22.Nm ktest_register_module , 23.Nm ktest_unregister_module , 24.Nm ktest_free_module 25.Nd create and register ktest test modules 26.Sh SYNOPSIS 27.In sys/ktest.h 28.Ft int 29.Fo ktest_create_module 30.Fa "const char *name" 31.Fa "ktest_module_hdl_t **km_hdl" 32.Fc 33.Ft int 34.Fo ktest_add_suite 35.Fa "ktest_module_hdl_t *km_hdl" 36.Fa "const char *name" 37.Fa "ktest_suite_hdl_t **ks_hdl" 38.Fc 39.Ft int 40.Fo ktest_add_test 41.Fa "ktest_suite_hdl_t *ks_hdl" 42.Fa "const char *name" 43.Fa "ktest_fn_t fn" 44.Fa "ktest_test_flags_t flags" 45.Fc 46.Ft int 47.Fo ktest_register_module 48.Fa "ktest_module_hdl_t *km_hdl" 49.Fc 50.Ft void 51.Fo ktest_unregister_module 52.Fa "const char *name" 53.Fc 54.Ft void 55.Fo ktest_free_module 56.Fa "ktest_module_hdl_t *km_hdl" 57.Fc 58.Sh INTERFACE LEVEL 59.Sy Volatile - 60This interface is still evolving in illumos. 61API and ABI stability is not guaranteed. 62.Sh PARAMETERS 63.Bl -tag -width Fa 64.It Fa name 65The name of the module, suite, or test. 66See the "Names" section below. 67.It Fa km_hdl 68The handle to a ktest module. 69.It Fa ks_hdl 70The handle to a ktest suite. 71.It Fa fn 72A pointer to the test function. 73.It Fa flags 74The set of test flags. 75See the 76.Xr ktest 9 77page for a description of the valid flags. 78.El 79.Sh DESCRIPTION 80A ktest test module is created by building up a module object and 81registering it with the ktest facility. 82The module object consists of a name and one or more suite objects. 83The suite object consists of a name and one or more test objects. 84Each test object consists of a name, a function pointer to the test 85function, and a set of test flags. 86.Pp 87Test module object creation and registration should happen as part of 88the test module's 89.Xr _init 9E 90routine. 91The sequence of calls inside a test module's 92.Xr _init 9E 93should proceed in the following order. 94.Bl -enum -offset 4m 95.It 96.Fn ktest_create_module 97.It 98.Fn ktest_add_suite 99.It 100.Fn ktest_add_test , 1011 or more times 102.It 103back to step 2 if more than one suite 104.It 105.Fn ktest_register_module 106.El 107.Pp 108Conversely, the test module should unregister its test module object 109as part of its 110.Xr _fini 9E 111routine. 112.Ss Names 113The 114.Fa name 115is the string used to reference a particular module, suite, or test. 116Any given test is uniquely identified by the combination of its 117module, suite, and test name -- also referred to as its "triple". 118This triple is how the user identifies a test when making use of the 119.Xr ktest 8 120command. 121.Pp 122The module name may be the same as the module-under-test, but that 123isn't a requirement. 124At the end of the day, the test module's name is simply a string used 125to organize suites of tests in some logical manner. 126In some cases it makes sense to name the test module something other 127than the module-under-test. 128For example, when the module-under-test is large, such as genunix. 129Or when the test module is testing a property of the larger system 130that spans more than a single module. 131.Pp 132Module names must be unique. 133Suite names must be unique for a given module. 134Test names must be unique for a given suite. 135That implies that suite and test names may be reused so long as they 136are unique within their given namespace. 137.Ss Test Flags 138.Bl -tag -width 4m 139.It Sy KTEST_FLAG_NONE 140No flags specified. 141.It Sy KTEST_FLAG_INPUT 142This test requires an input stream. 143.El 144.Ss Functions 145.Bl -tag -width 2m 146.It Sy ktest_create_module() 147Create a module object. 148Return failure if the name is not valid, or if the object could not be 149allocated. 150.It Sy ktest_add_suite() 151Create a suite object and add it to the module object referenced by 152.Fa km_hdl . 153Return failure if the name is already in use, the name is not valid, 154or if the object could not be allocated. 155.It Sy ktest_add_test() 156Create a test object and add it to the suite object referenced by 157.Fa ks_hdl . 158The 159.Fa fn 160should be a pointer to the test function and 161.Fa flags 162should contain a value derived from a bitwise-OR of one or more test flag 163values. 164Return failure if the name is already in use, the name is not valid, 165or if the object could not be allocated. 166.It Sy ktest_register_module() 167Register the test module object referenced by 168.Fa km_hdl . 169Return failure if the module name already exists. 170.It Sy ktest_unregister_module() 171Unregister the test module object that maps to the 172.Fa name . 173.It Sy ktest_free_module() 174Used to free the module along with its contained suites and tests in 175the event that the module failed to register. 176.El 177.Sh RETURN VALUES 178The 179.Fn ktest_create_module , 180.Fn ktest_add_suite , 181.Fn ktest_add_test , 182and 183.Fn ktest_register_module 184functions return 0 on success or an error value for failure. 185.Sh EXAMPLES 186The following example provides a template for how one would typically 187organize the source code of a test module. 188.Bd -literal 189#include <sys/ktest.h> 190 191void 192foo_test1(ktest_ctx_hdl_t *ctx) 193{ 194 ... 195} 196 197void 198foo_test2(ktest_ctx_hdl_t *ctx) 199{ 200 ... 201} 202 203void 204foo_test3(ktest_ctx_hdl_t *ctx) 205{ 206 ... 207} 208 209static struct modlmisc foo_test_modlmisc = { 210 .misc_modops = &mod_miscops, 211 .misc_linkinfo = "foo ktest module" 212}; 213 214static struct modlinkage foo_test_modlinkage = { 215 .ml_rev = MODREV_1, 216 .ml_linkage = { &foo_test_modlmisc, NULL } 217}; 218 219int 220_init() 221{ 222 int ret; 223 ktest_module_hdl_t *km = NULL; 224 ktest_suite_hdl_t *ks = NULL; 225 226 VERIFY0(ktest_create_module("foo", &km)); 227 VERIFY0(ktest_add_suite("suite1", &ks)); 228 VERIFY0(ktest_add_test(ks, "foo_test1", foo_test1, 229 KTEST_FLAG_NONE)); 230 VERIFY0(ktest_add_test(ks, "foo_test2", foo_test2, 231 KTEST_FLAG_NONE)); 232 VERIFY0(ktest_add_test(ks, "foo_test3", foo_test3, 233 KTEST_FLAG_INPUT)); 234 235 if ((ret = ktest_register_module(km)) != 0) { 236 ktest_free_module(km); 237 return (ret); 238 } 239 240 if ((ret = mod_install(&foo_test_modlinkage)) != 0) { 241 ktest_unregister_module("foo"); 242 return (ret); 243 } 244 245 return (0); 246} 247 248int 249_fini(void) 250{ 251 ktest_unregister_module("foo"); 252 return (mod_remove(&mac_test_modlinkage)); 253} 254.Ed 255.Sh ERRORS 256.Bl -tag -width 4m 257.It Er EEXIST 258The name already exists. 259.It Er EINVAL 260The name contains illegal characters. 261.It Er ENOMEM 262The module, suite, or test object could not be allocated. 263.It Er EOVERFLOW 264The 265.Fa name 266value is too long. 267.El 268.Sh SEE ALSO 269.Xr ktest 8 , 270.Xr ktest 9 , 271.Xr _fini 9E , 272.Xr _init 9E 273