1 /* 2 * Copyright (c) 2018-2019, 2021 The Linux Foundation. All rights reserved. 3 * Copyright (c) 2022-2023 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) vdev-level APIs 22 */ 23 24 #ifndef __WLAN_DSC_VDEV_H 25 #define __WLAN_DSC_VDEV_H 26 27 #include "qdf_status.h" 28 #include "wlan_dsc_psoc.h" 29 30 /* 31 * struct dsc_vdev - opaque dsc vdev context 32 */ 33 struct dsc_vdev; 34 35 /** 36 * dsc_vdev_create() - create a dsc vdev context 37 * @psoc: parent dsc psoc context 38 * @out_vdev: opaque double pointer to assign the new context to 39 * 40 * Note: this attaches @out_vdev to @psoc 41 * 42 * Return: QDF_STATUS 43 */ 44 QDF_STATUS dsc_vdev_create(struct dsc_psoc *psoc, struct dsc_vdev **out_vdev); 45 46 /** 47 * dsc_vdev_destroy() - destroy a dsc vdev context 48 * @out_vdev: opaque double pointer to context to destroy and NULL 49 * 50 * Note, this: 51 * - detaches @out_vdev from its parent psoc context 52 * - aborts all queued transitions on @vdev 53 * - asserts @vdev has no operations in flight 54 * 55 * Return: None 56 */ 57 void dsc_vdev_destroy(struct dsc_vdev **out_vdev); 58 59 /** 60 * dsc_vdev_trans_start() - start a transition on @vdev 61 * @vdev: the vdev to start a transition on 62 * @desc: a unique description of the transition to start 63 * 64 * This API immediately aborts if a transition on @vdev is already in flight 65 * 66 * Call dsc_vdev_trans_stop() to complete the transition. 67 * 68 * Return: 69 * QDF_STATUS_SUCCESS - transition started successfully 70 * QDF_STATUS_E_INVAL - invalid request (causes debug panic) 71 * QDF_STATUS_E_AGAIN - transition cannot currently be started 72 * QDF_STATUS_E_ALREADY - transition with @desc already in flight 73 */ 74 QDF_STATUS dsc_vdev_trans_start(struct dsc_vdev *vdev, const char *desc); 75 76 /** 77 * dsc_vdev_trans_start_wait() - start a transition on @vdev, blocking if a 78 * transition is already in flight 79 * @vdev: the vdev to start a transition on 80 * @desc: a unique description of the transition to start 81 * 82 * Call dsc_vdev_trans_stop() to complete the transition. 83 * 84 * Return: 85 * QDF_STATUS_SUCCESS - transition started successfully 86 * QDF_STATUS_E_INVAL - invalid request (causes debug panic) 87 * QDF_STATUS_E_AGAIN - transition cannot currently be started 88 * QDF_STATUS_E_ALREADY - transition with @desc already queued or in flight 89 * QDF_STATUS_E_ABORTED - transition was aborted 90 */ 91 QDF_STATUS dsc_vdev_trans_start_wait(struct dsc_vdev *vdev, const char *desc); 92 93 /** 94 * dsc_vdev_trans_stop() - complete current transition in flight on @vdev 95 * @vdev: the vdev to complete the transition on 96 * 97 * Note: this asserts a transition is currently in flight on @vdev 98 * 99 * Return: None 100 */ 101 void dsc_vdev_trans_stop(struct dsc_vdev *vdev); 102 103 /** 104 * dsc_vdev_assert_trans_protected() - assert @vdev is protected by a transition 105 * @vdev: the vdev to check 106 * 107 * The protecting transition may be in flight on @vdev or its ancestors. 108 * 109 * Return: None 110 */ 111 void dsc_vdev_assert_trans_protected(struct dsc_vdev *vdev); 112 113 /** 114 * dsc_vdev_op_start() - start an operation on @vdev 115 * @vdev: the vdev to start an operation on 116 * 117 * Return: 118 * QDF_STATUS_SUCCESS - operation started successfully 119 * QDF_STATUS_E_INVAL - invalid request (causes debug panic) 120 * QDF_STATUS_E_AGAIN - operation cannot currently be started 121 * QDF_STATUS_E_NOMEM - out of memory 122 */ 123 #define dsc_vdev_op_start(vdev) _dsc_vdev_op_start(vdev, __func__) 124 QDF_STATUS _dsc_vdev_op_start(struct dsc_vdev *vdev, const char *func); 125 126 /** 127 * dsc_vdev_op_stop() - complete operation with matching @func on @vdev 128 * @vdev: the vdev to stop an operation on 129 * 130 * Note: this asserts @func was previously started 131 * 132 * Return: None 133 */ 134 #define dsc_vdev_op_stop(vdev) _dsc_vdev_op_stop(vdev, __func__) 135 void _dsc_vdev_op_stop(struct dsc_vdev *vdev, const char *func); 136 137 /** 138 * dsc_vdev_wait_for_ops() - blocks until all operations on @vdev have stopped 139 * @vdev: the vdev to wait for operations on 140 * 141 * Note: this asserts that @vdev cannot currently transition 142 * 143 * Return: None 144 */ 145 void dsc_vdev_wait_for_ops(struct dsc_vdev *vdev); 146 147 /** 148 * dsc_vdev_get_cached_cmd() - Get north bound cmd cached during SSR 149 * @vdev: Pointer to the dsc vdev 150 * 151 * This api will be invoked after completion of SSR re-initialization to get 152 * the last north bound command received during SSR 153 * 154 * Return: North bound command ID 155 */ 156 uint8_t dsc_vdev_get_cached_cmd(struct dsc_vdev *vdev); 157 158 /** 159 * dsc_vdev_cache_command() - Cache north bound command during SSR 160 * @vdev: Pointer to the dsc vdev corresponding to the network interface 161 * @cmd_id: North bound command ID 162 * 163 * This api will be invoked when a north bound command is received during SSR 164 * and it should be handled after SSR re-initialization. 165 * 166 * Return: None 167 */ 168 void dsc_vdev_cache_command(struct dsc_vdev *vdev, uint8_t cmd_id); 169 170 /* 171 * dsc_vdev_wait_for_uptree_ops() - Wait for any uptree operations 172 * @vdev: The DSC vdev 173 * 174 * This function checks and waits for any uptree operations if there is any 175 * uptree operation is in progress. 176 * 177 * Return: None. 178 */ 179 180 void dsc_vdev_wait_for_uptree_ops(struct dsc_vdev *vdev); 181 182 #endif /* __WLAN_DSC_VDEV_H */ 183