1 /* 2 * Copyright 2017, NXP 3 * All rights reserved. 4 * 5 * 6 * SPDX-License-Identifier: BSD-3-Clause 7 */ 8 9 #ifndef __SRTM_DISPATCHER__ 10 #define __SRTM_DISPATCHER__ 11 12 #include "srtm_defs.h" 13 14 /*! 15 * @addtogroup srtm 16 * @{ 17 */ 18 19 /******************************************************************************* 20 * Definitions 21 ******************************************************************************/ 22 /** 23 * @brief SRTM response callback function 24 */ 25 typedef void (*srtm_dispatcher_resp_cb_t)(srtm_dispatcher_t disp, srtm_message_t req, srtm_message_t resp, void *param); 26 27 /******************************************************************************* 28 * API 29 ******************************************************************************/ 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 34 /*! 35 * @brief Create SRTM dispatcher object. 36 * 37 * @return SRTM dispacher handle, or NULL on failure. 38 */ 39 srtm_dispatcher_t SRTM_Dispatcher_Create(void); 40 41 /*! 42 * @brief Destroy SRTM dispatcher object. 43 * 44 * @param disp SRTM dispatcher handle. 45 */ 46 void SRTM_Dispatcher_Destroy(srtm_dispatcher_t disp); 47 48 /*! 49 * @brief Start SRTM dispatcher. 50 * 51 * @param disp SRTM dispatcher handle. 52 * @return SRTM_Status_Success on success and others on failure. 53 */ 54 srtm_status_t SRTM_Dispatcher_Start(srtm_dispatcher_t disp); 55 56 /*! 57 * @brief Stop SRTM dispatcher. 58 * 59 * @param disp SRTM dispatcher handle. 60 * @return SRTM_Status_Success on success and others on failure. 61 */ 62 srtm_status_t SRTM_Dispatcher_Stop(srtm_dispatcher_t disp); 63 64 /*! 65 * @brief Run SRTM dispatcher. Loop inside and never return. 66 * 67 * @param disp SRTM dispatcher handle. 68 */ 69 void SRTM_Dispatcher_Run(srtm_dispatcher_t disp); 70 71 /*! 72 * @brief Add peer core to the SRTM dispatcher. 73 * 74 * @param disp SRTM dispatcher handle. 75 * @param core SRTM peer core to add. 76 * @return SRTM_Status_Success on success and others on failure. 77 */ 78 srtm_status_t SRTM_Dispatcher_AddPeerCore(srtm_dispatcher_t disp, srtm_peercore_t core); 79 80 /*! 81 * @brief Remove peer core from the SRTM dispatcher. 82 * 83 * @param disp SRTM dispatcher handle. 84 * @param core SRTM peer core to remove. 85 * @return SRTM_Status_Success on success and others on failure. 86 */ 87 srtm_status_t SRTM_Dispatcher_RemovePeerCore(srtm_dispatcher_t disp, srtm_peercore_t core); 88 89 /*! 90 * @brief Register service to the SRTM dispatcher to handle corresponding request/notification. 91 * 92 * @param disp SRTM dispatcher handle. 93 * @param service SRTM service to register. 94 * @return SRTM_Status_Success on success and others on failure. 95 */ 96 srtm_status_t SRTM_Dispatcher_RegisterService(srtm_dispatcher_t disp, srtm_service_t service); 97 98 /*! 99 * @brief Remove peer core from the SRTM dispatcher. 100 * 101 * @param disp SRTM dispatcher handle. 102 * @param service SRTM service to unregister. 103 * @return SRTM_Status_Success on success and others on failure. 104 */ 105 srtm_status_t SRTM_Dispatcher_UnregisterService(srtm_dispatcher_t disp, srtm_service_t service); 106 107 /*! 108 * @brief Send request to peer core and wait for the response. 109 * 110 * The request is created by user, and the response is created by SRTM dispatcher. User need to destroy 111 * both to avoid memory leakage. 112 * 113 * @param disp SRTM dispatcher handle. 114 * @param req SRTM request to send to peer core. 115 * @param pResp SRTM response got from peer core. If request fails, the pResponse points to NULL. 116 * @param timeout Maximum milliseconds to wait for the response. 117 * @return SRTM_Status_Success on success and others on failure. 118 */ 119 srtm_status_t SRTM_Dispatcher_Request(srtm_dispatcher_t disp, 120 srtm_request_t req, 121 srtm_response_t *pResp, 122 uint32_t timeout); 123 124 /*! 125 * @brief Deliver request to peer core and return immediately. 126 * 127 * The request is created by user, and transferred to SRTM dispatcher. When dispatcher receives the 128 * response, it will call the user provided callback. User doesn't need to destroy either request 129 * or response in the callback. They will both be destroyed after callback returns. 130 * In case something wrong, user can get the error code with SRTM_Request_GetErrorCode(req) in 131 * callback function. 132 * 133 * @param disp SRTM dispatcher handle. 134 * @param req SRTM request to send to peer core. 135 * @param callback User function to get the response. 136 * @param param User paramter to be used in callback. 137 * @return SRTM_Status_Success on success and others on failure. 138 */ 139 srtm_status_t SRTM_Dispatcher_DeliverRequest(srtm_dispatcher_t disp, 140 srtm_request_t req, 141 srtm_dispatcher_resp_cb_t callback, 142 void *param); 143 144 /*! 145 * @brief Deliver response to peer core and return immediately. 146 * 147 * The response is created by user, and transferred to SRTM dispatcher. No response required. 148 * User doesn't need to destroy the response. It will be destroyed after the message is sent. 149 * 150 * @param disp SRTM dispatcher handle. 151 * @param resp SRTM response to send to peer core. 152 * @return SRTM_Status_Success on success and others on failure. 153 */ 154 srtm_status_t SRTM_Dispatcher_DeliverResponse(srtm_dispatcher_t disp, srtm_response_t resp); 155 156 /*! 157 * @brief Deliver notification to peer core and return immediately. 158 * 159 * The notification is created by user, and transferred to SRTM dispatcher. No response required. 160 * User doesn't need to destroy the notification. It will be destroyed after the message is sent. 161 * 162 * @param disp SRTM dispatcher handle. 163 * @param notif SRTM notification to send to peer core. 164 * @return SRTM_Status_Success on success and others on failure. 165 */ 166 srtm_status_t SRTM_Dispatcher_DeliverNotification(srtm_dispatcher_t disp, srtm_notification_t notif); 167 168 /*! 169 * @brief Deliver raw data message to peer core and return immediately. 170 * 171 * The raw data message is created by user, and transferred to SRTM dispatcher. No response 172 * required. User doesn't need to destroy the raw data message. It will be destroyed after 173 * the message is sent. 174 * 175 * @param disp SRTM dispatcher handle. 176 * @param data Raw data message to send to peer core. 177 * @return SRTM_Status_Success on success and others on failure. 178 */ 179 srtm_status_t SRTM_Dispatcher_DeliverRawData(srtm_dispatcher_t disp, srtm_rawdata_t data); 180 181 /*! 182 * @brief Deliver procedure message to dispatcher and return after the procedure is called. 183 * 184 * The procedure message is created by user. User need to destroy the message to avoid memory leakage after return. 185 * 186 * @param disp SRTM dispatcher handle. 187 * @param proc SRTM procedure message to be called. 188 * @param timeout Maximum milliseconds to wait for the response. 189 * Note the actual max wait time is "timeout" + "duration of the procedure" 190 * @return SRTM_Status_Success on success and others on failure. 191 */ 192 srtm_status_t SRTM_Dispatcher_CallProc(srtm_dispatcher_t disp, srtm_procedure_t proc, uint32_t timeout); 193 194 /*! 195 * @brief Deliver local procedure message to dispatcher and return immediately. 196 * 197 * The procedure message is created by user, and transferred to SRTM dispatcher. No response 198 * required. User doesn't need to destroy the procedure message. It will be destroyed after 199 * the procedure finishes. 200 * 201 * @param disp SRTM dispatcher handle. 202 * @param proc Procedure message to dispatch. 203 * @return SRTM_Status_Success on success and others on failure. 204 */ 205 srtm_status_t SRTM_Dispatcher_PostProc(srtm_dispatcher_t disp, srtm_procedure_t proc); 206 207 #ifdef __cplusplus 208 } 209 #endif 210 211 /*! @} */ 212 213 #endif /* __SRTM_DISPATCHER__ */ 214
