event_mgr.h (9106B)
1 /*! \file event_mgr.h 2 * 3 * Event manager module definitions and APIs. 4 */ 5 /* 6 * This license is set out in https://raw.githubusercontent.com/Broadcom-Network-Switching-Software/OpenBCM/master/Legal/LICENSE file. 7 * 8 * Copyright 2007-2020 Broadcom Inc. All rights reserved. 9 */ 10 11 #ifndef BCMI_LTSW_EVENT_MGR_H 12 #define BCMI_LTSW_EVENT_MGR_H 13 14 #include <sal/sal_types.h> 15 16 /*! 17 * \brief Initialize the Event Management Module. 18 * 19 * \param [in] unit Unit number. 20 * 21 * \retval SHR_E_NONE No error. 22 * \retval SHR_E_MEMORY Out of memory. 23 */ 24 extern int 25 bcmi_event_mgr_init(int unit); 26 27 /*! 28 * \brief De-initialize the Event Management Module. 29 * 30 * \param [in] unit Unit number. 31 * 32 * \retval SHR_E_NONE No error. 33 * \retval SHR_E_INIT Not initialized. 34 * \retval SHR_E_TIMEOUT Failed to stop assist threads. 35 */ 36 extern int 37 bcmi_event_mgr_deinit(int unit); 38 39 /*! 40 * \brief Callback definition for event notification process. 41 * 42 * The signature of the callback function that processes notifications for 43 * subscribed event or table updates. 44 * 45 * The client can pass a user_data context which will be passed back as input 46 * parameter to the callback notification function. 47 * 48 * \param [in] unit Unit number. 49 * \param [in] event Event/table name. 50 * \param [in] notif_info The table/event notification info. 51 * \param [in] user_data The application context provided at the time of 52 * table subscription (see bcmi_lt_table_subscribe()). 53 * 54 * \return none 55 */ 56 typedef void (*bcmi_ltsw_event_cb)(int unit, 57 const char *event, 58 void *notif_info, 59 void *user_data); 60 61 /*! 62 * \brief Register callback function to receive event. 63 * 64 * This function can be used to receive notifications of the specified event. 65 * 66 * \param [in] unit Unit number. 67 * \param [in] event Event to be associated with. 68 * \param [in] callback Callback function to call when the event being posted. 69 * \param [in] user_data Opaque context for notifications. 70 * 71 * \retval SHR_E_NONE No error. 72 * \retval SHR_E_UNIT Invalid unit. 73 * \retval SHR_E_PARAM Invalid event or callback function. 74 */ 75 extern int bcmi_ltsw_event_register(int unit, 76 const char *event, 77 bcmi_ltsw_event_cb callback, 78 void *user_data); 79 /*! 80 * \name Event attributes. 81 * \anchor BCMI_LTSW_EVENT_xxx 82 */ 83 84 /*! \{ */ 85 /*! Application callback is used to process the event. */ 86 #define BCMI_LTSW_EVENT_APPL_CALLBACK (1 << 0) 87 88 /*! The specificed event has high priority. */ 89 #define BCMI_LTSW_EVENT_HIGH_PRIORITY (1 << 1) 90 91 /*! \} */ 92 93 /*! 94 * \brief Set the attributes of event. 95 * 96 * This function sets attributes of an event. 97 * 98 * \param [in] unit Unit number. 99 * \param [in] event Event to be associated with. 100 * \param [in] attrib The attribute to set. 101 * 102 * \retval SHR_E_NONE No error. 103 * \retval SHR_E_UNIT Invalid unit. 104 * \retval SHR_E_PARAM Invalid event or callback function. 105 */ 106 extern int 107 bcmi_ltsw_event_attrib_set(int unit, const char *event, uint32_t attrib); 108 109 /*! 110 * \brief Deregister a callback to an event. 111 * 112 * \param [in] unit The device number for the table of interest. 113 * \param [in] event Event name. 114 * \param [in] callback The callback function to be deregistered. 115 * 116 * \retval SHR_E_NONE Success. 117 * \retval SHR_E_PARAM Table was not found. 118 */ 119 extern int 120 bcmi_ltsw_event_unregister(int unit, 121 const char *event, 122 bcmi_ltsw_event_cb callback); 123 124 /*! 125 * \brief Notify of an event. 126 * 127 * \param [in] unit Unit number. 128 * \param [in] event Event to be associated with. 129 * \param [in] notif_info Data associated with the event. 130 * \param [in] notif_info_len The length of data associated with the event. 131 * 132 * \return None. 133 */ 134 extern void 135 bcmi_ltsw_event_notify(int unit, 136 const char *event, 137 void *notif_info, 138 int notif_info_len); 139 140 /*! 141 * \name Event status returned by parser callback. 142 * \anchor bcmiLtswEventStatusxxx 143 */ 144 /*! \{ */ 145 typedef enum bcmi_ltsw_event_status_e { 146 147 /*! Pass the notification. */ 148 bcmiLtswEventStatusPassNotif = 0, 149 150 /*! Dismiss the notification.*/ 151 bcmiLtswEventStatusDismissNotif = 1, 152 153 /*! The last one, not valid.*/ 154 bcmiLtswEventStatusCount = 2 155 156 } bcmi_ltsw_event_status_t; 157 158 /*! \} */ 159 160 /*! 161 * \brief Callback definition for table notification parser. 162 * 163 * The signature of the callback function that parses notifications for 164 * subscribed table updates. 165 * 166 * \param [in] unit Unit number. 167 * \param [in] lt_name Table name. 168 * \param [in] entry_hdl Table entry handle. 169 * \param [out] notif_info Parsed notification info. 170 * \param [out] status Parser callback returned status, NULL for not care. 171 * 172 * The notif_info is allocated and freed inside the lt_event_mgr module. 173 * The size of notif_info is given by user when subscribes the table changes 174 * via \ref bcmi_lt_table_subscribe. 175 * The registered notification parser will populate the notif_info, which will 176 * be passed as input parameter to notification process callback 177 * (\ref bcmi_lt_event_cb). 178 * 179 * \return none 180 */ 181 typedef void (*bcmi_lt_parser)(int unit, 182 const char *lt_name, 183 uint32_t entry_hdl, 184 void *notif_info, 185 bcmi_ltsw_event_status_t *status); 186 187 188 /*! 189 * \brief Subscribe for table updates. 190 * 191 * This function registers a callback to get notified on any changes of a 192 * particular table within a unit. 193 * The user may provide a pointer to an context that can be used during the 194 * callback event. 195 * 196 * \param [in] unit The device number for the table of interest. 197 * \param [in] lt_name The table name for subscribing to updates. 198 * \param [in] callback Notification handler to be invoked. 199 * \param [in] user_data Opaque context for notifications. 200 * 201 * \retval SHR_E_NONE Success. 202 * \retval SHR_E_PARAM Table was not found. 203 */ 204 int 205 bcmi_lt_table_subscribe(int unit, 206 const char *lt_name, 207 bcmi_ltsw_event_cb callback, 208 void *user_data); 209 210 /*! 211 * \brief Set the parser of table updates. 212 * 213 * This function registers a callback to parse the table updates. 214 * 215 * \param [in] unit The device number for the table of interest. 216 * \param [in] lt_name The table name for subscribing to updates. 217 * \param [in] parser Notification parser to be invoked. 218 * \param [in] notif_info_len Length of notification info. 219 * 220 * \retval SHR_E_NONE Success. 221 * \retval SHR_E_PARAM Table was not found. 222 */ 223 int 224 bcmi_lt_table_parser_set(int unit, 225 const char *lt_name, 226 bcmi_lt_parser parser, 227 uint32_t notif_info_len); 228 229 /*! 230 * \brief Set the attributes of table change event. 231 * 232 * This function sets attributes of table change event. 233 * 234 * \param [in] unit Unit number. 235 * \param [in] lt_name Table name. 236 * \param [in] attrib The attribute to set. 237 * 238 * \retval SHR_E_NONE No error. 239 * \retval SHR_E_UNIT Invalid unit. 240 * \retval SHR_E_PARAM Invalid event or callback function. 241 */ 242 extern int 243 bcmi_lt_table_attrib_set(int unit, const char *lt_name, uint32_t attrib); 244 245 /*! 246 * \brief Unsubscribe for table updates. 247 * 248 * This function deregisters a callback to get notified on any table updates. 249 * 250 * \param [in] unit The device number for the table of interest. 251 * \param [in] lt_name The table name. 252 * \param [in] callback The callback function to be unregister. 253 * 254 * \retval SHR_E_NONE Success. 255 * \retval SHR_E_PARAM Table was not found. 256 */ 257 int 258 bcmi_lt_table_unsubscribe(int unit, 259 const char *lt_name, 260 bcmi_ltsw_event_cb callback); 261 262 /*! 263 * \brief Get number of message pending in queue for given event. 264 * 265 * \param [in] unit The device number for the table of interest. 266 * \param [in] event Event name. 267 * \param [out] num Number of pending message. 268 * 269 * \retval SHR_E_NONE Success. 270 * \retval SHR_E_PARAM Invalid input parameter. 271 * \retval SHR_E_NOT_FOUND No handle for given event. 272 */ 273 int 274 bcmi_ltsw_event_msg_num_get(int unit, const char *event, uint32_t *num); 275 276 /*! 277 * \brief Set the threshold of message pending in the queue. 278 * 279 * \param [in] unit Unit number. 280 * \param [in] lt_name Table name. 281 * \param [in] threshold Threshold. 282 * 283 * \retval SHR_E_NONE No error. 284 * \retval SHR_E_UNIT Invalid unit. 285 * \retval SHR_E_PARAM Invalid event or callback function. 286 */ 287 extern int 288 bcmi_ltsw_event_msg_threshold_set(int unit, const char *event, 289 uint32_t threshold); 290 291 /*! 292 * \name Event string ID. 293 * \anchor bcmiltswEv<xxx> 294 */ 295 296 /*! \{ */ 297 298 /*! Link state update event for application. */ 299 #define BCMI_LTSW_EV_LS_APPL "evLinkStateAppl" 300 301 /*! L2 event string used for L2 notification */ 302 #define BCMI_LTSW_EV_L2_NOTIF "evL2Notif" 303 304 /*! PFC deadlock recovery event. */ 305 #define BCMI_LTSW_EV_PFC_DEADLOCK "evPfcDeadlock" 306 307 /*! \} */ 308 309 #endif /* BCMI_LT_EVENT_MGR_H */