1*5113495bSYour Name /* 2*5113495bSYour Name * Copyright (c) 2018-2019 The Linux Foundation. All rights reserved. 3*5113495bSYour Name * Copyright (c) 2022 Qualcomm Innovation Center, Inc. All rights reserved. 4*5113495bSYour Name * 5*5113495bSYour Name * Permission to use, copy, modify, and/or distribute this software for 6*5113495bSYour Name * any purpose with or without fee is hereby granted, provided that the 7*5113495bSYour Name * above copyright notice and this permission notice appear in all 8*5113495bSYour Name * copies. 9*5113495bSYour Name * 10*5113495bSYour Name * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL 11*5113495bSYour Name * WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED 12*5113495bSYour Name * WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE 13*5113495bSYour Name * AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL 14*5113495bSYour Name * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR 15*5113495bSYour Name * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER 16*5113495bSYour Name * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 17*5113495bSYour Name * PERFORMANCE OF THIS SOFTWARE. 18*5113495bSYour Name */ 19*5113495bSYour Name 20*5113495bSYour Name /** 21*5113495bSYour Name * DOC: Driver Synchronization Core (DSC) psoc-level APIs 22*5113495bSYour Name */ 23*5113495bSYour Name 24*5113495bSYour Name #ifndef __WLAN_DSC_PSOC_H 25*5113495bSYour Name #define __WLAN_DSC_PSOC_H 26*5113495bSYour Name 27*5113495bSYour Name #include "qdf_status.h" 28*5113495bSYour Name #include "wlan_dsc_driver.h" 29*5113495bSYour Name 30*5113495bSYour Name /* 31*5113495bSYour Name * struct dsc_psoc - opaque dsc psoc context 32*5113495bSYour Name */ 33*5113495bSYour Name struct dsc_psoc; 34*5113495bSYour Name 35*5113495bSYour Name /** 36*5113495bSYour Name * dsc_psoc_create() - create a dsc psoc context 37*5113495bSYour Name * @driver: parent dsc driver context 38*5113495bSYour Name * @out_psoc: opaque double pointer to assign the new context to 39*5113495bSYour Name * 40*5113495bSYour Name * Note: this attaches @out_psoc to @driver 41*5113495bSYour Name * 42*5113495bSYour Name * Return: QDF_STATUS 43*5113495bSYour Name */ 44*5113495bSYour Name QDF_STATUS 45*5113495bSYour Name dsc_psoc_create(struct dsc_driver *driver, struct dsc_psoc **out_psoc); 46*5113495bSYour Name 47*5113495bSYour Name /** 48*5113495bSYour Name * dsc_psoc_destroy() - destroy a dsc psoc context 49*5113495bSYour Name * @out_psoc: opaque double pointer to context to destroy and NULL 50*5113495bSYour Name * 51*5113495bSYour Name * Note, this: 52*5113495bSYour Name * - detaches @out_psoc from its parent driver context 53*5113495bSYour Name * - aborts all queued transitions on @psoc 54*5113495bSYour Name * - asserts @psoc has no attached vdev's 55*5113495bSYour Name * - asserts @psoc has no operations in flight 56*5113495bSYour Name * 57*5113495bSYour Name * Return: None 58*5113495bSYour Name */ 59*5113495bSYour Name void dsc_psoc_destroy(struct dsc_psoc **out_psoc); 60*5113495bSYour Name 61*5113495bSYour Name /** 62*5113495bSYour Name * dsc_psoc_trans_start() - start a transition on @psoc 63*5113495bSYour Name * @psoc: the psoc to start a transition on 64*5113495bSYour Name * @desc: a unique description of the transition to start 65*5113495bSYour Name * 66*5113495bSYour Name * This API immediately aborts if a transition on @psoc is already in flight 67*5113495bSYour Name * 68*5113495bSYour Name * Call dsc_psoc_trans_stop() to complete the transition. 69*5113495bSYour Name * 70*5113495bSYour Name * Return: 71*5113495bSYour Name * QDF_STATUS_SUCCESS - transition started successfully 72*5113495bSYour Name * QDF_STATUS_E_INVAL - invalid request (causes debug panic) 73*5113495bSYour Name * QDF_STATUS_E_AGAIN - transition cannot currently be started 74*5113495bSYour Name * QDF_STATUS_E_ALREADY - transition with @desc already in flight 75*5113495bSYour Name */ 76*5113495bSYour Name QDF_STATUS dsc_psoc_trans_start(struct dsc_psoc *psoc, const char *desc); 77*5113495bSYour Name 78*5113495bSYour Name /** 79*5113495bSYour Name * dsc_psoc_trans_start_wait() - start a transition on @psoc, blocking if a 80*5113495bSYour Name * transition is already in flight 81*5113495bSYour Name * @psoc: the psoc to start a transition on 82*5113495bSYour Name * @desc: a unique description of the transition to start 83*5113495bSYour Name * 84*5113495bSYour Name * Call dsc_psoc_trans_stop() to complete the transition. 85*5113495bSYour Name * 86*5113495bSYour Name * Return: 87*5113495bSYour Name * QDF_STATUS_SUCCESS - transition started successfully 88*5113495bSYour Name * QDF_STATUS_E_INVAL - invalid request (causes debug panic) 89*5113495bSYour Name * QDF_STATUS_E_AGAIN - transition cannot currently be started 90*5113495bSYour Name * QDF_STATUS_E_ALREADY - transition with @desc already queued or in flight 91*5113495bSYour Name * QDF_STATUS_E_ABORTED - transition was aborted 92*5113495bSYour Name */ 93*5113495bSYour Name QDF_STATUS dsc_psoc_trans_start_wait(struct dsc_psoc *psoc, const char *desc); 94*5113495bSYour Name 95*5113495bSYour Name /** 96*5113495bSYour Name * dsc_psoc_trans_stop() - complete current transition in flight on @psoc 97*5113495bSYour Name * @psoc: the psoc to complete the transition on 98*5113495bSYour Name * 99*5113495bSYour Name * Note: this asserts a transition is currently in flight on @psoc 100*5113495bSYour Name * 101*5113495bSYour Name * Return: None 102*5113495bSYour Name */ 103*5113495bSYour Name void dsc_psoc_trans_stop(struct dsc_psoc *psoc); 104*5113495bSYour Name 105*5113495bSYour Name /** 106*5113495bSYour Name * dsc_psoc_assert_trans_protected() - assert @psoc is protected by a transition 107*5113495bSYour Name * @psoc: the psoc to check 108*5113495bSYour Name * 109*5113495bSYour Name * The protecting transition may be in flight on @psoc or its parent. 110*5113495bSYour Name * 111*5113495bSYour Name * Return: None 112*5113495bSYour Name */ 113*5113495bSYour Name void dsc_psoc_assert_trans_protected(struct dsc_psoc *psoc); 114*5113495bSYour Name 115*5113495bSYour Name /** 116*5113495bSYour Name * dsc_psoc_op_start() - start an operation on @psoc 117*5113495bSYour Name * @psoc: the psoc to start an operation on 118*5113495bSYour Name * 119*5113495bSYour Name * Return: 120*5113495bSYour Name * QDF_STATUS_SUCCESS - operation started successfully 121*5113495bSYour Name * QDF_STATUS_E_INVAL - invalid request (causes debug panic) 122*5113495bSYour Name * QDF_STATUS_E_AGAIN - operation cannot currently be started 123*5113495bSYour Name * QDF_STATUS_E_NOMEM - out of memory 124*5113495bSYour Name */ 125*5113495bSYour Name #define dsc_psoc_op_start(psoc) _dsc_psoc_op_start(psoc, __func__) 126*5113495bSYour Name QDF_STATUS _dsc_psoc_op_start(struct dsc_psoc *psoc, const char *func); 127*5113495bSYour Name 128*5113495bSYour Name /** 129*5113495bSYour Name * dsc_psoc_op_stop() - complete operation with matching @func on @psoc 130*5113495bSYour Name * @psoc: the psoc to stop an operation on 131*5113495bSYour Name * 132*5113495bSYour Name * Note: this asserts @func was previously started 133*5113495bSYour Name * 134*5113495bSYour Name * Return: None 135*5113495bSYour Name */ 136*5113495bSYour Name #define dsc_psoc_op_stop(psoc) _dsc_psoc_op_stop(psoc, __func__) 137*5113495bSYour Name void _dsc_psoc_op_stop(struct dsc_psoc *psoc, const char *func); 138*5113495bSYour Name 139*5113495bSYour Name /** 140*5113495bSYour Name * dsc_psoc_wait_for_ops() - blocks until all operations on @psoc have stopped 141*5113495bSYour Name * @psoc: the psoc to wait for operations on 142*5113495bSYour Name * 143*5113495bSYour Name * Note: this asserts that @psoc cannot currently transition 144*5113495bSYour Name * 145*5113495bSYour Name * Return: None 146*5113495bSYour Name */ 147*5113495bSYour Name void dsc_psoc_wait_for_ops(struct dsc_psoc *psoc); 148*5113495bSYour Name 149*5113495bSYour Name #endif /* __WLAN_DSC_PSOC_H */ 150