00001 /** ============================================================================ 00002 * @file notify.h 00003 * 00004 * @path $(DSPLINK)/gpp/inc/usr/ 00005 * 00006 * @brief Defines the interface of the Notify component. 00007 * 00008 * @ver 1.65.00.03 00009 * ============================================================================ 00010 * @copyright Copyright (C) 2002-2009, Texas Instruments Incorporated - 00011 * http://www.ti.com/ 00012 * 00013 * Redistribution and use in source and binary forms, with or without 00014 * modification, are permitted provided that the following conditions 00015 * are met: 00016 * 00017 * * Redistributions of source code must retain the above copyright 00018 * notice, this list of conditions and the following disclaimer. 00019 * 00020 * * Redistributions in binary form must reproduce the above copyright 00021 * notice, this list of conditions and the following disclaimer in the 00022 * documentation and/or other materials provided with the distribution. 00023 * 00024 * * Neither the name of Texas Instruments Incorporated nor the names of 00025 * its contributors may be used to endorse or promote products derived 00026 * from this software without specific prior written permission. 00027 * 00028 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 00029 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 00030 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 00031 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 00032 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 00033 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 00034 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 00035 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 00036 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 00037 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 00038 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00039 * ============================================================================ 00040 */ 00041 00042 00043 #if !defined (NOTIFY_H) 00044 #define NOTIFY_H 00045 00046 00047 /* ----------------------------------- DSP/BIOS Link */ 00048 #include <dsplink.h> 00049 00050 /* ----------------------------------- Profiling */ 00051 #if defined (DDSP_PROFILE) 00052 #include <profile.h> 00053 #endif /* #if defined (DDSP_PROFILE)*/ 00054 00055 #if defined (__cplusplus) 00056 extern "C" { 00057 #endif /* defined (__cplusplus) */ 00058 00059 00060 /** ============================================================================ 00061 * @name FnNotifyCbck 00062 * 00063 * @brief Signature of the callback function to be registered with the NOTIFY 00064 * component. 00065 * 00066 * @param eventNo 00067 * Event number associated with the callback being invoked. 00068 * @param arg 00069 * Fixed argument registered with the IPS component along with 00070 * the callback function. 00071 * @param info 00072 * Run-time information provided to the upper layer by the NOTIFY 00073 * component. This information is specific to the IPS being 00074 * implemented. 00075 * 00076 * @return None. 00077 * 00078 * @pre None. 00079 * 00080 * @post None. 00081 * 00082 * @see IPS_register () 00083 * ============================================================================ 00084 */ 00085 typedef Void (*FnNotifyCbck) (IN Uint32 eventNo, 00086 IN Pvoid arg, 00087 IN Pvoid info) ; 00088 00089 00090 /** ============================================================================ 00091 * @func NOTIFY_register 00092 * 00093 * @brief This function registers a callback for a specific event with the 00094 * NOTIFY component. 00095 * 00096 * @param dspId 00097 * DSP Identifier. 00098 * @param ipsId 00099 * IPS Identifier. 00100 * @param eventNo 00101 * Event No to be registered. 00102 * @param fnNotifyCbck 00103 * Callback function to be registered for the specified event. 00104 * @param cbckArg 00105 * Optional argument to the callback function to be registered for 00106 * the specified event. This argument shall be passed to each 00107 * invocation of the callback function. 00108 * 00109 * @return DSP_SOK 00110 * Operation successfully completed. 00111 * DSP_EWRONGSTATE 00112 * IPS not initialized. 00113 * DSP_EINVALIDARG 00114 * Invalid arguments. 00115 * DSP_ENOTSUPPORTED 00116 * IPS is not supported in DSP->GPP direction. 00117 * DSP_RESOURCE 00118 * Specified ips id, event number is reserved for LINK protocols 00119 * like MSGQ, CHNL, RingIO etc. 00120 * DSP_EFAIL 00121 * General failure. 00122 * 00123 * @pre The fnNotifyCbck argument must be valid. 00124 * The event must be supported by the IPS component. 00125 * dspId must be valid. 00126 * PROC_attach has been successful. 00127 * 00128 * @post On success, the event must be registered with the IPS component. 00129 * 00130 * @see FnNotifyCbck, NOTIFY_unregister () 00131 * ============================================================================ 00132 */ 00133 EXPORT_API 00134 DSP_STATUS 00135 NOTIFY_register (IN ProcessorId dspId, 00136 IN Uint32 ipsId, 00137 IN Uint32 eventNo, 00138 IN FnNotifyCbck fnNotifyCbck, 00139 IN Pvoid cbckArg) ; 00140 00141 00142 /** ============================================================================ 00143 * @func NOTIFY_unregister 00144 * 00145 * @brief This function unregisters a callback for a specific event with the 00146 * NOTIFY component. 00147 * 00148 * @param dspId 00149 * DSP Identifier. 00150 * @param ipsId 00151 * IPS Identifier. 00152 * @param event 00153 * Event to be unregistered. 00154 * @param fnNotifyCbck 00155 * Callback function to be registered for the specified event. 00156 * @param cbckArg 00157 * Optional argument to the callback function registered for the 00158 * the specified event. 00159 * 00160 * @return DSP_SOK 00161 * Operation successfully completed. 00162 * DSP_EWRONGSTATE 00163 * IPS not initialized. 00164 * DSP_EINVALIDARG 00165 * Invalid arguments. 00166 * DSP_ENOTSUPPORTED 00167 * IPS is not supported in DSP->GPP direction. 00168 * DSP_EFAIL 00169 * General failure. 00170 * 00171 * @pre The event must be supported by the NOTIFY component. 00172 * The event must have been registered with the NOTIFY component 00173 * earlier. 00174 * The fnNotifyCbck argument must be valid. 00175 * All Notifications are complete. 00176 * 00177 * @post On success, the event must be unregistered from the IPS component 00178 * 00179 * @see NOTIFY_register () 00180 * ============================================================================ 00181 */ 00182 EXPORT_API 00183 DSP_STATUS 00184 NOTIFY_unregister (IN ProcessorId dspId, 00185 IN Uint32 ipsId, 00186 IN Uint32 eventNo, 00187 IN FnNotifyCbck fnNotifyCbck, 00188 IN Pvoid cbckArg) ; 00189 00190 00191 /** ============================================================================ 00192 * @func NOTIFY_notify 00193 * 00194 * @brief This function sends a notification of an event to the DSP. 00195 * 00196 * @param dspId 00197 * DSP Identifier. 00198 * @param ipsId 00199 * IPS Identifier. 00200 * @param eventno 00201 * Event to be notified to the DSP. 00202 * @param payload 00203 * Data to be sent with Event (Optional). 00204 * 00205 * @return DSP_SOK 00206 * Operation successfully completed. 00207 * DSP_EFAIL 00208 * General failure. 00209 * DSP_EWRONGSTATE 00210 * IPS not initialized. 00211 * DSP_ENOTSUPPORTED 00212 * IPS is not supported in GPP->DSP direction. 00213 * DSP_EINVALIDARG 00214 * Invalid arguments. 00215 * 00216 * @pre The event must be supported by the NOTIFY component. 00217 * The notification component must be initialized. 00218 * NOTIFY_register has been successful. 00219 * 00220 * @post None. 00221 * 00222 * @see None. 00223 * ============================================================================ 00224 */ 00225 EXPORT_API 00226 DSP_STATUS 00227 NOTIFY_notify (IN ProcessorId dspId, 00228 IN Uint32 ipsId, 00229 IN Uint32 eventno, 00230 IN Uint32 payload) ; 00231 00232 00233 #if defined (DDSP_PROFILE) 00234 /** ============================================================================ 00235 * @func NOTIFY_instrument 00236 * 00237 * @brief Gets the instrumentation information related to IPS's 00238 * 00239 * @param dspId 00240 * DSP Identifier. 00241 * @param ipsId 00242 * IPS Identifier. 00243 * @param retVal 00244 * Instrumentation structure. 00245 * 00246 * @return DSP_SOK 00247 * Operation successfully completed. 00248 * DSP_EFAIL 00249 * General failure. 00250 * DSP_EINVALIDARG 00251 * Invalid arguments. 00252 * 00253 * @pre The dspId, retVal must be valid. 00254 * PROC_setup and PROC_attach have been successful. 00255 * Profiling has been selected in the configuration. 00256 * 00257 * 00258 * @post None. 00259 * 00260 * @see None. 00261 * 00262 * @modif None. 00263 * ============================================================================ 00264 */ 00265 EXPORT_API 00266 DSP_STATUS 00267 NOTIFY_instrument (IN ProcessorId dspId, 00268 IN Uint32 ipsId, 00269 OUT IPS_Instrument * retVal) ; 00270 #endif /* defined (DDSP_PROFILE) */ 00271 00272 00273 #if defined (__cplusplus) 00274 } 00275 #endif /* defined (__cplusplus) */ 00276 00277 00278 #endif /* !defined (NOTIFY_H) */