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_PSOC_SYNC_H 21 #define __OSIF_PSOC_SYNC_H 22 23 #include "linux/device.h" 24 #include "wlan_dsc_driver.h" 25 #include "qdf_types.h" 26 27 /* 28 * struct osif_psoc_sync - opaque synchronization handle for a psoc 29 */ 30 struct osif_psoc_sync; 31 32 /** 33 * osif_psoc_sync_create() - create a psoc synchronization context 34 * @out_psoc_sync: out parameter for the new synchronization context 35 * 36 * Return: Errno 37 */ 38 qdf_must_check int 39 osif_psoc_sync_create(struct osif_psoc_sync **out_psoc_sync); 40 41 /** 42 * osif_psoc_sync_create_and_trans() - create a psoc synchronization context 43 * @out_psoc_sync: out parameter for the new synchronization context 44 * 45 * For protecting the device creation process. 46 * 47 * Return: Errno 48 */ 49 #define osif_psoc_sync_create_and_trans(out_psoc_sync) \ 50 __osif_psoc_sync_create_and_trans(out_psoc_sync, __func__) 51 52 qdf_must_check int 53 __osif_psoc_sync_create_and_trans(struct osif_psoc_sync **out_psoc_sync, 54 const char *desc); 55 56 /** 57 * osif_psoc_sync_destroy() - destroy a psoc synchronization context 58 * @psoc_sync: the context to destroy 59 * 60 * Return: none 61 */ 62 void osif_psoc_sync_destroy(struct osif_psoc_sync *psoc_sync); 63 64 /** 65 * osif_psoc_sync_register() - register a psoc for operations/transitions 66 * @dev: the device to use as the operation/transition lookup key 67 * @psoc_sync: the psoc synchronization context to register 68 * 69 * Return: none 70 */ 71 void osif_psoc_sync_register(struct device *dev, 72 struct osif_psoc_sync *psoc_sync); 73 74 /** 75 * osif_psoc_sync_unregister() - unregister a psoc for operations/transitions 76 * @dev: the device originally used to register the psoc_sync context 77 * 78 * Return: the psoc synchronization context that was registered for @dev 79 */ 80 struct osif_psoc_sync *osif_psoc_sync_unregister(struct device *dev); 81 82 /** 83 * osif_psoc_sync_trans_start() - attempt to start a transition on @dev 84 * @dev: the device to transition 85 * @out_psoc_sync: out parameter for the synchronization context registered with 86 * @dev, populated on success 87 * 88 * Return: Errno 89 */ 90 #define osif_psoc_sync_trans_start(dev, out_psoc_sync) \ 91 __osif_psoc_sync_trans_start(dev, out_psoc_sync, __func__) 92 93 qdf_must_check int 94 __osif_psoc_sync_trans_start(struct device *dev, 95 struct osif_psoc_sync **out_psoc_sync, 96 const char *desc); 97 98 /** 99 * osif_psoc_sync_trans_start_wait() - attempt to start a transition on @dev, 100 * blocking if a conflicting transition is in flight 101 * @dev: the device to transition 102 * @out_psoc_sync: out parameter for the synchronization context registered with 103 * @dev, populated on success 104 * 105 * Return: Errno 106 */ 107 #define osif_psoc_sync_trans_start_wait(dev, out_psoc_sync) \ 108 __osif_psoc_sync_trans_start_wait(dev, out_psoc_sync, __func__) 109 110 qdf_must_check int 111 __osif_psoc_sync_trans_start_wait(struct device *dev, 112 struct osif_psoc_sync **out_psoc_sync, 113 const char *desc); 114 115 /** 116 * osif_psoc_sync_trans_resume() - resume a transition on @dev 117 * @dev: the device under transition 118 * @out_psoc_sync: out parameter for the synchronization context registered with 119 * @dev, populated on success 120 * 121 * Return: Errno 122 */ 123 int osif_psoc_sync_trans_resume(struct device *dev, 124 struct osif_psoc_sync **out_psoc_sync); 125 126 /** 127 * osif_psoc_sync_trans_stop() - stop a transition associated with @psoc_sync 128 * @psoc_sync: the synchronization context tracking the transition 129 * 130 * Return: none 131 */ 132 void osif_psoc_sync_trans_stop(struct osif_psoc_sync *psoc_sync); 133 134 /** 135 * osif_psoc_sync_assert_trans_protected() - assert that @dev is currently 136 * protected by a transition 137 * @dev: the device to check 138 * 139 * Return: none 140 */ 141 void osif_psoc_sync_assert_trans_protected(struct device *dev); 142 143 /** 144 * osif_psoc_sync_op_start() - attempt to start an operation on @dev 145 * @dev: the device to operate against 146 * @out_psoc_sync: out parameter for the synchronization context registered with 147 * @dev, populated on success 148 * 149 * Return: Errno 150 */ 151 #define osif_psoc_sync_op_start(dev, out_psoc_sync) \ 152 __osif_psoc_sync_op_start(dev, out_psoc_sync, __func__) 153 154 qdf_must_check int 155 __osif_psoc_sync_op_start(struct device *dev, 156 struct osif_psoc_sync **out_psoc_sync, 157 const char *func); 158 159 /** 160 * osif_psoc_sync_op_stop() - stop an operation associated with @psoc_sync 161 * @psoc_sync: the synchronization context tracking the operation 162 * 163 * Return: none 164 */ 165 #define osif_psoc_sync_op_stop(psoc_sync) \ 166 __osif_psoc_sync_op_stop(psoc_sync, __func__) 167 168 void __osif_psoc_sync_op_stop(struct osif_psoc_sync *psoc_sync, 169 const char *func); 170 171 /** 172 * osif_psoc_sync_wait_for_ops() - wait until all @psoc_sync operations complete 173 * @psoc_sync: the synchronization context tracking the operations 174 * 175 * Return: None 176 */ 177 void osif_psoc_sync_wait_for_ops(struct osif_psoc_sync *psoc_sync); 178 179 #endif /* __OSIF_PSOC_SYNC_H */ 180 181