soc_async.h (6631B)
1 /* 2 * 3 * This license is set out in https://raw.githubusercontent.com/Broadcom-Network-Switching-Software/OpenBCM/master/Legal/LICENSE file. 4 * 5 * Copyright 2007-2019 Broadcom Inc. All rights reserved. 6 * 7 * 8 * File: soc_async.h 9 * Purpose: This file implements the async frame work 10 * used by various soc cimix modules. Async framework 11 * facilitates the message queuing and call back notification 12 * mechanism is multi threaded environment. 13 */ 14 15 #ifndef _SOC_ASYNC_H 16 #define _SOC_ASYNC_H 17 18 #include <soc/defs.h> 19 #include <soc/types.h> 20 #include <sal/types.h> 21 #include <soc/error.h> 22 23 /* Enum representing async proc type */ 24 25 typedef enum soc_async_proc { 26 p_sbus_dma = 0, 27 p_packet_dma, 28 p_fifo_dma, 29 p_schan_fifo, 30 p_schan_pio 31 } soc_async_p_type; 32 33 34 /* typedefs */ 35 36 /*DMA/ SCHAN message processing function */ 37 typedef int (*soc_async_msg_proc_f)(int unit, void *data, void *cookie); 38 39 /* Wait to complete the message process either 40 * interrupt based or polling based. 41 */ 42 typedef int (*soc_async_wait_complete_f)(int unit, void *data, void *cookie); 43 44 /* Callback function pointer passed by the upper 45 * layer need to be called to notify on completion. 46 */ 47 typedef void (*soc_async_cb_f)(int unit, void *data, void *cookie, int status); 48 49 /* Handle returned from the Async frame work init function */ 50 typedef void *soc_async_handle_t; 51 52 /* This message structure will be populated by subsystem 53 * e.g. SBUS, SCHAN, Packet DMA etc to queue the message 54 * to the associated queue for async handling. 55 */ 56 typedef struct { 57 int unit; /* Unit */ 58 soc_async_p_type type; /* Message queue type */ 59 void *data; /* abstract data for processing */ 60 void *cookie; /* abstract cookie, application/driver use */ 61 soc_async_msg_proc_f proc_f; /* message processing function */ 62 soc_async_wait_complete_f wait_f; /* wait to complete processing */ 63 soc_async_cb_f cb_f; /* Application call back function */ 64 }soc_async_msg_t; 65 66 typedef struct { 67 soc_async_p_type type; /*Message queue type */ 68 size_t q_size; /* queue size */ 69 unsigned int threads; /* # of threads */ 70 int prio; /* Priority of threads */ 71 }soc_async_prop_t; 72 73 /******************************************* 74 * @function soc_async_proc_init 75 * @purpose Initialize the async proc. 76 * 77 * @param unit [in] unit number 78 * @param prop [in] property of <soc_async_prop_t> 79 *@param prop [out] property of <soc_async_handle_t>, This handle is required 80 * to access async access functions 81 * 82 * @returns SOC_E_NONE 83 * @returns SOC_E_XXX 84 * 85 * @comments The function will allocate resources , create thread safe 86 * queues and processing threads. This will return handle to caller 87 * 88 * @end 89 */ 90 extern int soc_async_proc_init( 91 int unit, 92 soc_async_prop_t *prop, 93 soc_async_handle_t *handle); 94 95 /******************************************* 96 * @function soc_async_msg_queue 97 * purpose Queue the message 98 * 99 * @param handle [in] Async handle of type soc_async_handle_t 100 * @param msg [in] message pointer 101 102 * @returns SOC_E_NONE 103 * @returns SOC_E_XXX 104 * 105 * @comments This will queue the message "soc_async_msg_t" and 106 trigger the event so that associated thread is unblocked, 107 dequeue and process the message. 108 * 109 * @end 110 */ 111 extern int soc_async_msg_queue( 112 soc_async_handle_t handle, 113 soc_async_msg_t *msg); 114 115 /******************************************* 116 * @function soc_async_msg_dequeue 117 * purpose Dequeue the message 118 * 119 * @param handle [in] Async handle of type soc_async_handle_t 120 * @param msg [out] message pointer to get the message 121 * 122 * @returns SOC_E_NONE 123 * @returns SOC_E_XXX 124 * 125 * @comments The processing Threads will call this function to 126 * dequeue the message from the thread safe message queue to 127 * process it further. 128 * 129 * @end 130 */ 131 extern int soc_async_msg_dequeue( 132 soc_async_handle_t handle, 133 soc_async_msg_t **msg); 134 135 /******************************************* 136 * @function soc_async_flush_queue 137 * purpose Flush the message queue 138 * 139 * @param handle [in] Async handle of type soc_async_handle_t 140 * 141 * @returns SOC_E_NONE 142 * @returns SOC_E_XXX 143 * 144 * @comments Discard all the messages in the queue and make it empty/reset. 145 * 146 * @end 147 */ 148 extern int soc_async_flush_queue(soc_async_handle_t handle); 149 150 151 /******************************************* 152 * @function soc_async_proc_deinit 153 * purpose Deinit async proc. 154 * 155 * @param handle [in] Async handle of type soc_async_handle_t 156 * 157 * @returns SOC_E_NONE 158 * @returns SOC_E_XXX 159 * 160 * @comments The function will destroy message queues and processing 161 * threads, unbind associated channels and free resources. 162 * 163 * @end 164 */ 165 extern int soc_async_proc_deinit(soc_async_handle_t handle); 166 167 /******************************************* 168 * @function soc_async_msg_count 169 * purpose Get the number of messages in the queue 170 * 171 * @param handle [in] Async handle of type soc_async_handle_t 172 * @param count [out] returns message count 173 * 174 * @returns SOC_E_NONE 175 * 176 * @end 177 */ 178 extern int soc_async_msg_count(soc_async_handle_t handle, int *count); 179 180 /******************************************* 181 * @function soc_async_msg_alloc 182 * purpose Allocate the message 183 * 184 * @param handle [in] Async handle of type soc_async_handle_t 185 * @param msg [in] pointer to pointer of message 186 187 * @returns SOC_E_NONE 188 * @returns SOC_E_MEMORY 189 * 190 * @end 191 */ 192 extern int soc_async_msg_alloc( 193 soc_async_handle_t handle, 194 soc_async_msg_t **msg); 195 196 /******************************************* 197 * @function soc_async_msg_free 198 * purpose Free the previously allocated the message 199 * 200 * @param handle [in] Async handle of type soc_async_handle_t 201 * @param msg [in] pointer of message 202 203 * @returns SOC_E_NONE 204 * @returns SOC_E_PARAM 205 * 206 * @end 207 */ 208 extern int soc_async_msg_free( 209 soc_async_handle_t handle, 210 soc_async_msg_t *msg); 211 212 /******************************************* 213 * @function soc_async_msg_start 214 * purpose start the message queue processing 215 * 216 * @param handle [in] Async handle of type soc_async_handle_t 217 * 218 * @returns SOC_E_NONE 219 * 220 * @end 221 */ 222 extern int 223 soc_async_msg_start(soc_async_handle_t handle); 224 225 /******************************************* 226 * @function soc_async_msg_stop 227 * purpose Stop the message queue processing 228 * 229 * @param handle [in] Async handle of type soc_async_handle_t 230 * 231 * @returns SOC_E_NONE 232 * 233 * @end 234 */ 235 extern int 236 soc_async_msg_stop(soc_async_handle_t handle); 237 238 239 #endif 240 241