1    /* 
     2     * Copyright (c) 2010, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== INotifyDriver.xdc ========
    34     *  
    35     */
    36    
    37    /*!
    38     *  ======== INotifyDriver ========
    39     *  Notify driver interface
    40     *
    41     *  Interface implemented by all drivers for the notify module.  Modules that
    42     *  implement this interface expect the eventId arguments to be valid.
    43     */
    44    
    45    interface INotifyDriver {
    46        
    47    instance:
    48    
    49        /*!
    50         *  ======== registerEvent ========
    51         *  Register a callback to an event
    52         *
    53         *  This driver function is called by the Notify_registerEvent function 
    54         *  within the Notify module gate. Refer to its documentation for more 
    55         *  details.  
    56         *
    57         *  @param(eventId)      Number of event that is being registered
    58         */
    59        Void registerEvent(UInt32 eventId);
    60    
    61        /*!
    62         *  ======== unregisterEvent ========
    63         *  Remove an event listener from an event
    64         *
    65         *  This driver function is called by the Notify_unregisterEvent function
    66         *  within the Notify module gate. Refer to it for more details.
    67         *
    68         *  @param(eventId)      Number of event that is being unregistered
    69         */
    70        Void unregisterEvent(UInt32 eventId);
    71    
    72        /*!
    73         *  ======== sendEvent ========
    74         *  Send a signal to an event
    75         *
    76         *  This interface function is called by the Notify_sendEvent function.
    77         *  Notify_sendEvent does not provide any context protection for
    78         *  INotifyDriver_sendEvent, so appropriate measures must be taken within
    79         *  the driver itself.
    80         *
    81         *  @param(eventId)      Number of event to signal
    82         *  @param(payload)      Payload (optional) to pass to callback function
    83         *  @param(waitClear)    If TRUE, have the NotifyDriver wait for
    84         *                       acknowledgement back from the destination
    85         *                       processor.
    86         *
    87         *  @b(returns)          Notify status
    88         */
    89        Int sendEvent(UInt32 eventId, UInt32 payload, Bool waitClear);
    90    
    91        /*!
    92         *  ======== disable ========
    93         *  Disable a NotifyDriver instance
    94         *
    95         *  Disables the ability of a Notify driver to receive events for a given
    96         *  processor. This interface function is called by the Notify_disable
    97         *  function. Refer to its documentation for more details.
    98         */
    99        Void disable();
   100    
   101        /*!
   102         *  ======== enable ========
   103         *  Enable a NotifyDriver instance
   104         *
   105         *  Enables the ability of a Notify driver to receive events for a given
   106         *  processor. This interface function is called by the Notify_restore 
   107         *  function. Refer to its documentation for more details.
   108         */
   109        Void enable();
   110    
   111        /*!
   112         *  ======== disableEvent ========
   113         *  Disable an event
   114         *
   115         *  This interface function is called by the Notify_disableEvent function. 
   116         *  Refer to its documentation for more details.
   117         *
   118         *  The Notify module does validation of the eventId.  The Notify module
   119         *  enters calls this function within the Notify module gate.
   120         *
   121         *  @param(eventId)      Number of event to disable
   122         */
   123        Void disableEvent(UInt32 eventId);
   124    
   125        /*!
   126         *  ======== enableEvent ========
   127         *  Enable an event
   128         *
   129         *  This interface function is called by the Notify_disableEvent function. 
   130         *  Refer to its documentation for more details.
   131         *
   132         *  The Notify module does validation of the eventId.  The Notify module
   133         *  enters calls this function within the Notify module gate.
   134         *
   135         *  @param(eventId)      Number of event to enable
   136         */
   137        Void enableEvent(UInt32 eventId);
   138        
   139        /*! @_nodoc
   140         *  ======== setNotifyHandle ========
   141         *  Called during Notify instance creation to 'send' its handle to its
   142         *  corresponding notify driver instance
   143         */
   144        Void setNotifyHandle(Ptr driverHandle);
   145        
   146    }
   147    /*
   148     *  @(#) ti.sdo.ipc.interfaces; 1, 0, 0, 0,347; 8-10-2010 17:49:16; /db/vtree/library/trees/ipc/ipc-e23x/src/
   149     */
   150