1 /* 2 * Copyright (c) 2019 The Linux Foundation. All rights reserved. 3 * Copyright (c) 2022 Qualcomm Innovation Center, Inc. All rights reserved. 4 * 5 * Permission to use, copy, modify, and/or distribute this software for 6 * any purpose with or without fee is hereby granted, provided that the 7 * above copyright notice and this permission notice appear in all 8 * copies. 9 * 10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL 11 * WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED 12 * WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE 13 * AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL 14 * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR 15 * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER 16 * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 17 * PERFORMANCE OF THIS SOFTWARE. 18 */ 19 20 #ifndef __OSIF_DRIVER_SYNC_H 21 #define __OSIF_DRIVER_SYNC_H 22 23 #include "qdf_types.h" 24 25 /* 26 * struct osif_driver_sync - opaque synchronization handle for a driver 27 */ 28 struct osif_driver_sync; 29 30 /** 31 * osif_driver_sync_create() - create a driver synchronization context 32 * @out_driver_sync: out parameter for the new synchronization context 33 * 34 * Return: Errno 35 */ 36 qdf_must_check int 37 osif_driver_sync_create(struct osif_driver_sync **out_driver_sync); 38 39 /** 40 * osif_driver_sync_create_and_trans() - create a driver synchronization context 41 * @out_driver_sync: out parameter for the new synchronization context 42 * 43 * For protecting the driver initialization process. 44 * 45 * Return: Errno 46 */ 47 #define osif_driver_sync_create_and_trans(out_driver_sync) \ 48 __osif_driver_sync_create_and_trans(out_driver_sync, __func__) 49 50 qdf_must_check int 51 __osif_driver_sync_create_and_trans(struct osif_driver_sync **out_driver_sync, 52 const char *desc); 53 54 /** 55 * osif_driver_sync_destroy() - destroy a driver synchronization context 56 * @driver_sync: the context to destroy 57 * 58 * Return: none 59 */ 60 void osif_driver_sync_destroy(struct osif_driver_sync *driver_sync); 61 62 /** 63 * osif_driver_sync_register() - register a driver for operations/transitions 64 * @driver_sync: the driver synchronization context to register 65 * 66 * Return: none 67 */ 68 void osif_driver_sync_register(struct osif_driver_sync *driver_sync); 69 70 /** 71 * osif_driver_sync_unregister() - unregister a driver for 72 * operations/transitions 73 * 74 * Return: the driver synchronization context that was registered for @dev 75 */ 76 struct osif_driver_sync *osif_driver_sync_unregister(void); 77 78 /** 79 * osif_driver_sync_trans_start() - attempt to start a driver transition 80 * @out_driver_sync: out parameter for the synchronization context previously 81 * registered, populated on success 82 * 83 * Return: Errno 84 */ 85 #define osif_driver_sync_trans_start(out_driver_sync) \ 86 __osif_driver_sync_trans_start(out_driver_sync, __func__) 87 88 qdf_must_check int 89 __osif_driver_sync_trans_start(struct osif_driver_sync **out_driver_sync, 90 const char *desc); 91 92 /** 93 * osif_driver_sync_trans_start_wait() - attempt to start a driver transition, 94 * blocking if a conflicting transition is in flight 95 * @out_driver_sync: out parameter for the synchronization context previously 96 * registered, populated on success 97 * 98 * Return: Errno 99 */ 100 #define osif_driver_sync_trans_start_wait(out_driver_sync) \ 101 __osif_driver_sync_trans_start_wait(out_driver_sync, __func__) 102 103 qdf_must_check int 104 __osif_driver_sync_trans_start_wait(struct osif_driver_sync **out_driver_sync, 105 const char *desc); 106 107 /** 108 * osif_driver_sync_trans_stop() - stop a transition associated with 109 * @driver_sync 110 * @driver_sync: the synchronization context tracking the transition 111 * 112 * Return: none 113 */ 114 void osif_driver_sync_trans_stop(struct osif_driver_sync *driver_sync); 115 116 /** 117 * osif_driver_sync_assert_trans_protected() - assert that the driver is 118 * currently protected by a transition 119 * 120 * Return: none 121 */ 122 void osif_driver_sync_assert_trans_protected(void); 123 124 /** 125 * osif_driver_sync_op_start() - attempt to start a driver operation 126 * @out_driver_sync: out parameter for the synchronization context previously 127 * registered, populated on success 128 * 129 * Return: Errno 130 */ 131 #define osif_driver_sync_op_start(out_driver_sync) \ 132 __osif_driver_sync_op_start(out_driver_sync, __func__) 133 134 qdf_must_check int 135 __osif_driver_sync_op_start(struct osif_driver_sync **out_driver_sync, 136 const char *func); 137 138 /** 139 * osif_driver_sync_op_stop() - stop an operation associated with @driver_sync 140 * @driver_sync: the synchronization context tracking the operation 141 * 142 * Return: none 143 */ 144 #define osif_driver_sync_op_stop(driver_sync) \ 145 __osif_driver_sync_op_stop(driver_sync, __func__) 146 147 void __osif_driver_sync_op_stop(struct osif_driver_sync *driver_sync, 148 const char *func); 149 150 /** 151 * osif_driver_sync_wait_for_ops() - wait until all @driver_sync operations 152 * complete 153 * @driver_sync: the synchronization context tracking the operations 154 * 155 * Return: None 156 */ 157 void osif_driver_sync_wait_for_ops(struct osif_driver_sync *driver_sync); 158 159 #endif /* __OSIF_DRIVER_SYNC_H */ 160 161