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