Main Page | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

gpp/inc/notify.h

Go to the documentation of this file.
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) */

Generated on Fri Jul 16 14:34:02 2010 for DSP/BIOSLink by  doxygen 1.4.4