1    /*
     2     * Copyright (c) 2012-2013, 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        @DirectCall
    60        Void registerEvent(UInt32 eventId);
    61    
    62        /*!
    63         *  ======== unregisterEvent ========
    64         *  Remove an event listener from an event
    65         *
    66         *  This driver function is called by the Notify_unregisterEvent function
    67         *  within the Notify module gate. Refer to it for more details.
    68         *
    69         *  @param(eventId)      Number of event that is being unregistered
    70         */
    71        @DirectCall
    72        Void unregisterEvent(UInt32 eventId);
    73    
    74        /*!
    75         *  ======== sendEvent ========
    76         *  Send a signal to an event
    77         *
    78         *  This interface function is called by the Notify_sendEvent function.
    79         *  Notify_sendEvent does not provide any context protection for
    80         *  INotifyDriver_sendEvent, so appropriate measures must be taken within
    81         *  the driver itself.
    82         *
    83         *  @param(eventId)      Number of event to signal
    84         *  @param(payload)      Payload (optional) to pass to callback function
    85         *  @param(waitClear)    If TRUE, have the NotifyDriver wait for
    86         *                       acknowledgement back from the destination
    87         *                       processor.
    88         *
    89         *  @b(returns)          Notify status
    90         */
    91        @DirectCall
    92        Int sendEvent(UInt32 eventId, UInt32 payload, Bool waitClear);
    93    
    94        /*!
    95         *  ======== disable ========
    96         *  Disable a NotifyDriver instance
    97         *
    98         *  Disables the ability of a Notify driver to receive events for a given
    99         *  processor. This interface function is called by the Notify_disable
   100         *  function. Refer to its documentation for more details.
   101         */
   102        @DirectCall
   103        Void disable();
   104    
   105        /*!
   106         *  ======== enable ========
   107         *  Enable a NotifyDriver instance
   108         *
   109         *  Enables the ability of a Notify driver to receive events for a given
   110         *  processor. This interface function is called by the Notify_restore
   111         *  function. Refer to its documentation for more details.
   112         */
   113        @DirectCall
   114        Void enable();
   115    
   116        /*!
   117         *  ======== disableEvent ========
   118         *  Disable an event
   119         *
   120         *  This interface function is called by the Notify_disableEvent function.
   121         *  Refer to its documentation for more details.
   122         *
   123         *  The Notify module does validation of the eventId.  The Notify module
   124         *  enters calls this function within the Notify module gate.
   125         *
   126         *  @param(eventId)      Number of event to disable
   127         */
   128        @DirectCall
   129        Void disableEvent(UInt32 eventId);
   130    
   131        /*!
   132         *  ======== enableEvent ========
   133         *  Enable an event
   134         *
   135         *  This interface function is called by the Notify_disableEvent function.
   136         *  Refer to its documentation for more details.
   137         *
   138         *  The Notify module does validation of the eventId.  The Notify module
   139         *  enters calls this function within the Notify module gate.
   140         *
   141         *  @param(eventId)      Number of event to enable
   142         */
   143        @DirectCall
   144        Void enableEvent(UInt32 eventId);
   145    
   146        /*! @_nodoc
   147         *  ======== setNotifyHandle ========
   148         *  Called during Notify instance creation to 'send' its handle to its
   149         *  corresponding notify driver instance
   150         */
   151        @DirectCall
   152        Void setNotifyHandle(Ptr driverHandle);
   153    
   154    }