1 /* 2 * Copyright (c) 2018 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 /** 21 * DOC: Driver Synchronization Core (DSC) driver-level APIs 22 */ 23 24 #ifndef __WLAN_DSC_DRIVER_H 25 #define __WLAN_DSC_DRIVER_H 26 27 #include "qdf_status.h" 28 29 /* 30 * struct dsc_driver - opaque dsc driver context 31 */ 32 struct dsc_driver; 33 34 /** 35 * dsc_driver_create() - create a dsc driver context 36 * @out_driver: opaque double pointer to assign the new context to 37 * 38 * Return: QDF_STATUS 39 */ 40 QDF_STATUS dsc_driver_create(struct dsc_driver **out_driver); 41 42 /** 43 * dsc_driver_destroy() - destroy a dsc driver context 44 * @out_driver: opaque double pointer to context to destroy and NULL 45 * 46 * Note, this: 47 * - aborts all queued transitions on @driver 48 * - asserts @driver has no attached psoc's 49 * - asserts @driver has no operations in flight 50 * 51 * Return: None 52 */ 53 void dsc_driver_destroy(struct dsc_driver **out_driver); 54 55 /** 56 * dsc_driver_trans_start() - start a transition on @driver 57 * @driver: the driver to start a transition on 58 * @desc: a unique description of the transition to start 59 * 60 * This API immediately aborts if a transition on @driver is already in flight 61 * 62 * Call dsc_driver_trans_stop() to complete the transition. 63 * 64 * Return: 65 * QDF_STATUS_SUCCESS - transition started successfully 66 * QDF_STATUS_E_INVAL - invalid request (causes debug panic) 67 * QDF_STATUS_E_AGAIN - transition cannot currently be started 68 * QDF_STATUS_E_ALREADY - transition with @desc already in flight 69 */ 70 QDF_STATUS dsc_driver_trans_start(struct dsc_driver *driver, const char *desc); 71 72 /** 73 * dsc_driver_trans_start_wait() - start a transition on @driver, blocking if a 74 * transition is already in flight 75 * @driver: the driver to start a transition on 76 * @desc: a unique description of the transition to start 77 * 78 * Call dsc_driver_trans_stop() to complete the transition. 79 * 80 * Return: 81 * QDF_STATUS_SUCCESS - transition started successfully 82 * QDF_STATUS_E_INVAL - invalid request (causes debug panic) 83 * QDF_STATUS_E_AGAIN - transition cannot currently be started 84 * QDF_STATUS_E_ALREADY - transition with @desc already queued or in flight 85 */ 86 QDF_STATUS 87 dsc_driver_trans_start_wait(struct dsc_driver *driver, const char *desc); 88 89 /** 90 * dsc_driver_trans_stop() - complete current transition in flight on @driver 91 * @driver: the driver to complete the transition on 92 * 93 * Note: this asserts a transition is currently in flight on @driver 94 * 95 * Return: None 96 */ 97 void dsc_driver_trans_stop(struct dsc_driver *driver); 98 99 /** 100 * dsc_driver_assert_trans_protected() - assert @driver is protected by a 101 * transition 102 * @driver: the driver to check 103 * 104 * Return: None 105 */ 106 void dsc_driver_assert_trans_protected(struct dsc_driver *driver); 107 108 /** 109 * dsc_driver_op_start() - start an operation on @driver 110 * @driver: the driver to start an operation on 111 * 112 * Return: 113 * QDF_STATUS_SUCCESS - operation started successfully 114 * QDF_STATUS_E_INVAL - invalid request (causes debug panic) 115 * QDF_STATUS_E_AGAIN - operation cannot currently be started 116 * QDF_STATUS_E_NOMEM - out of memory 117 */ 118 #define dsc_driver_op_start(driver) _dsc_driver_op_start(driver, __func__) 119 QDF_STATUS _dsc_driver_op_start(struct dsc_driver *driver, const char *func); 120 121 /** 122 * dsc_driver_op_stop() - complete operation with matching @func on @driver 123 * @driver: the driver to stop an operation on 124 * 125 * Note: this asserts @func was previously started 126 * 127 * Return: None 128 */ 129 #define dsc_driver_op_stop(driver) _dsc_driver_op_stop(driver, __func__) 130 void _dsc_driver_op_stop(struct dsc_driver *driver, const char *func); 131 132 /** 133 * dsc_driver_wait_for_ops() - blocks until all operations on @driver have 134 * stopped 135 * @driver: the driver to wait for operations on 136 * 137 * Note: this asserts that @driver cannot currently transition 138 * 139 * Return: None 140 */ 141 void dsc_driver_wait_for_ops(struct dsc_driver *driver); 142 143 #endif /* __WLAN_DSC_DRIVER_H */ 144