1 /* 2 * Copyright (c) 2025 Apple Inc. All rights reserved. 3 * 4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. The rights granted to you under the License 10 * may not be used to create, or enable the creation or redistribution of, 11 * unlawful or unlicensed copies of an Apple operating system, or to 12 * circumvent, violate, or enable the circumvention or violation of, any 13 * terms of an Apple operating system software license agreement. 14 * 15 * Please obtain a copy of the License at 16 * http://www.opensource.apple.com/apsl/ and read it before using this file. 17 * 18 * The Original Code and all software distributed under the License are 19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 23 * Please see the License for the specific language governing rights and 24 * limitations under the License. 25 * 26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ 27 */ 28 29 #pragma once 30 31 #include "mock_dynamic.h" 32 #include <arm/pmap_public.h> 33 #include <vm/pmap.h> 34 #include <kern/lock_mtx.h> 35 #include <kern/task.h> 36 37 #include "fibers/fibers.h" 38 39 // Unit tests that wants to use fibers must call with macro in the global scope with val=1 40 #define UT_USE_FIBERS(val) int ut_mocks_use_fibers = (val) 41 // Unit tests using fibers that wants to enable the data race checker must call with macro in the global scope with val=1 42 #define UT_FIBERS_USE_CHECKER(val) int ut_fibers_use_data_race_checker = (val) 43 44 extern int ut_mocks_use_fibers __attribute__((weak)); 45 extern int ut_fibers_use_data_race_checker __attribute__((weak)); 46 47 // You can set the fibers configuration variables either assigning a value to them in the test function (see fibers_test.c) 48 // or using these macros in the global scope 49 #define UT_FIBERS_LOG_LEVEL(val) \ 50 __attribute__((constructor)) \ 51 static void \ 52 _ut_fibers_set_log_level(void) \ 53 { \ 54 fibers_log_level = (val); \ 55 } 56 #define UT_FIBERS_DEBUG(val) \ 57 __attribute__((constructor)) \ 58 static void \ 59 _ut_fibers_set_log_debug(void) \ 60 { \ 61 fibers_debug = (val); \ 62 } 63 #define UT_FIBERS_ABORT_ON_ERROR(val) \ 64 __attribute__((constructor)) \ 65 static void \ 66 _ut_fibers_set_abort_on_error(void) \ 67 { \ 68 fibers_abort_on_error = (val); \ 69 } 70 #define UT_FIBERS_MAY_YIELD_PROB(val) \ 71 __attribute__((constructor)) \ 72 static void \ 73 _ut_fibers_set_may_yield_prob(void) \ 74 { \ 75 fibers_may_yield_probability = (val); \ 76 } 77 78 /* 79 * Writing tests using fibers: 80 * 81 * If UT_USE_FIBERS(1) is used, every test defined in the same test executable will use the threading mocks implemented using the fibers API. 82 * However, this is not sufficient to write a test with multiple "threads", the test itself is reposinsible of creating the fibers. 83 * For some working examples, see the fibers_test.c file. 84 * 85 * The tests file must include the needed headers from mocks/fibers/ depending on what needs to be used. 86 * Fibers API are very similar to pthread, and if FIBERS_PREEMPTION=1 is used at compile time it behaves in a similar way to real threads. 87 * The main different is that developers must be aware that blocking operations are blocking every fiber, 88 * for instance you should not call sleep() in your test and if some kernel function is calling a similar function you should mock it with 89 * a call to one or more fibers_yield() to trigger a context switch. 90 * The scheduler is deterministic, the interleaving can be changed either setting a different seed in the PRNG with random_set_seed() 91 * or with any change to the code itself, as possible context switch points are located inside the fibers API or, even more drastically, 92 * at every memory load/store when FIBERS_PREEMPTION=1. 93 * 94 * Target code in XNU (like sysctl tests) can trigger a fibers context switch using the following API (see mock_attached.c): 95 * void ut_fibers_ctxswitch(void); // Switch to a random fiber 96 * void ut_fibers_ctxswitch_to(int fiber_id); // Switch to a specific fiber by id 97 * int ut_fibers_current_id(void); // Get the current fiber id 98 */ 99 100 extern void fake_init_lock(lck_mtx_t *mtx); 101 extern void fake_init_task(task_t new_task); 102 103 T_MOCK_DYNAMIC_DECLARE( 104 kern_return_t, 105 thread_wakeup_prim, ( 106 event_t event, 107 boolean_t one_thread, 108 wait_result_t result)); 109 110 T_MOCK_DYNAMIC_DECLARE( 111 wait_result_t, 112 thread_block_reason, ( 113 thread_continue_t continuation, 114 void *parameter, 115 ast_t reason)); 116