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

dsp/inc/notify.h

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

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