00001 /** ============================================================================ 00002 * @file notify.h 00003 * 00004 * @path $(DSPLINK)/dsp/inc/ 00005 * 00006 * @brief Defines the interface of 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 Headers */ 00048 #include <dsplink.h> 00049 00050 00051 #if defined (__cplusplus) 00052 extern "C" { 00053 #endif /* defined (__cplusplus) */ 00054 00055 00056 /** ============================================================================ 00057 * @name FnNotifyCbck 00058 * 00059 * @brief Signature of the callback function to be registered with the Notify 00060 * component. 00061 * 00062 * @param eventNo 00063 * Event number associated with the callback being invoked. 00064 * @param arg 00065 * Fixed argument registered with the NOTIFY component along with 00066 * the callback function. 00067 * @param info 00068 * Run-time information provided to the upper layer by the NOTIFY 00069 * component. This information is specific to the NOTIFY being 00070 * implemented. 00071 * 00072 * @return None. 00073 * 00074 * @pre None. 00075 * 00076 * @post None. 00077 * 00078 * @see NOTIFY_register () 00079 * ============================================================================ 00080 */ 00081 typedef Void (*FnNotifyCbck) (IN Uint32 eventNo, IN Ptr arg, IN Ptr info) ; 00082 00083 00084 /** ============================================================================ 00085 * @func NOTIFY_register 00086 * 00087 * @brief This function registers a callback for a specific event with the 00088 * NOTIFY component. 00089 * 00090 * @param procId 00091 * Identifier of the processor from which the notifications shall 00092 * be received. 00093 * @param ipsId 00094 * IPS Identifier. 00095 * @param eventNo 00096 * Event No to be registered. 00097 * @param fnNotifyCbck 00098 * Callback function to be registered for the specified event. 00099 * @param cbckArg 00100 * Optional argument to the callback function to be registered for 00101 * the specified event. This argument shall be passed to each 00102 * invocation of the callback function. 00103 * 00104 * @return SYS_OK 00105 * Operation successfully completed. 00106 * SYS_EINVAL 00107 * Invalid argument. 00108 * SYS_EALLOC 00109 * Memory allocation failure. 00110 * SYS_EMODE 00111 * IPS is not supported for GPP->DSP mode. 00112 * SYS_EBUSY 00113 * Specified ips id, event number is reserved for LINK protocols 00114 * like MSGQ, CHNL, RingIO etc. 00115 * 00116 * @pre The NOTIFY component must be initialized before calling this 00117 * function. 00118 * 00119 * @post On success, the event must be registered with the NOTIFY component. 00120 * 00121 * @see FnNotifyCbck, NOTIFY_unregister () 00122 * ============================================================================ 00123 */ 00124 Int 00125 NOTIFY_register (IN Uint32 procId, 00126 IN Uint32 ipsId, 00127 IN Uint32 eventNo, 00128 IN FnNotifyCbck fnNotifyCbck, 00129 IN Ptr cbckArg) ; 00130 00131 00132 /** ============================================================================ 00133 * @func NOTIFY_unregister 00134 * 00135 * @brief This function unregisters a callback for a specific event with the 00136 * NOTIFY component. 00137 * 00138 * @param procId 00139 * Identifier of the processor from which the notifications shall 00140 * no longer be received. 00141 * @param ipsId 00142 * IPS Identifier. 00143 * @param eventNo 00144 * Event to be unregistered. 00145 * @param fnNotifyCbck 00146 * Callback function to be registered for the specified event. 00147 * @param cbckArg 00148 * Optional argument to the callback function registered for the 00149 * the specified event. 00150 * 00151 * @return SYS_OK 00152 * Operation successfully completed. 00153 * SYS_ENOTFOUND 00154 * Registered event not found. 00155 * SYS_EMODE 00156 * IPS is not supported for GPP->DSP mode. 00157 * 00158 * @pre The NOTIFY component must be initialized before calling this 00159 * function. 00160 * The fnNotifyCbck argument must be valid. 00161 * 00162 * @post On success, the event must be unregistered from the NOTIFY component 00163 * 00164 * @see NOTIFY_register () 00165 * ============================================================================ 00166 */ 00167 Int 00168 NOTIFY_unregister (IN Uint32 procId, 00169 IN Uint32 ipsId, 00170 IN Uint32 eventNo, 00171 IN FnNotifyCbck fnNotifyCbck, 00172 IN Void * cbckArg) ; 00173 00174 00175 /** ============================================================================ 00176 * @func NOTIFY_notify 00177 * 00178 * @brief This function sends a notification of an event to the processor. 00179 * 00180 * @param procId 00181 * Identifier of the processor to which the notification is to be 00182 * sent. 00183 * @param ipsId 00184 * IPS Identifier. 00185 * @param eventNo 00186 * Event to be notified to the processor. 00187 * @param payload 00188 * Data to be sent with Event. 00189 * 00190 * @return SYS_OK 00191 * Operation successfully completed. 00192 * SYS_ENODEV 00193 * Event is not registered on the remote processor. 00194 * SYS_EINVAL 00195 * Invalid argument. 00196 * SYS_EMODE 00197 * IPS is not supported for DSP->GPP mode. 00198 * 00199 * @pre The NOTIFY component must be initialized before calling this 00200 * function. 00201 * The event must be supported by the NOTIFY component. 00202 * 00203 * @post None. 00204 * 00205 * @see None. 00206 * ============================================================================ 00207 */ 00208 Int 00209 NOTIFY_notify (IN Uint32 procId, 00210 IN Uint32 ipsId, 00211 IN Uint32 eventNo, 00212 IN Uint32 payload) ; 00213 00214 00215 #if defined (__cplusplus) 00216 } 00217 #endif /* defined (__cplusplus) */ 00218 00219 00220 #endif /* !defined (NOTIFY_H_) */ 00221