1    /* --COPYRIGHT--,TI
     2     * Copyright (c) $(CPYYEAR)
     3     * Texas Instruments
     4     *
     5     *  All rights reserved.  Property of Texas Instruments
     6     *  Restricted rights to use, duplicate or disclose this code are
     7     *  granted through contract.
     8     *
     9     * --/COPYRIGHT--*/
    10    /*
    11     *  ======== Notify.xdc ========
    12     *
    13     *! Revision History
    14     *! ================
    15     *! 23-Mar-2010 skp     cdoc updates, .xdc cleanup
    16     *! 04-Mar-2010 skp     Fix SDOCM00067516 (default # of events should be 32)
    17     *! 21-Jan-2010 skp     Fix SDOCM00066064 (misc notify bugs)
    18     *! 12-Jan-2010 skp     'reservedEvents' moved out of internal: section
    19     *! 09-Dec-2009 skp     Common-header changes
    20     *! 01-Dec-2009 skp     Default number of events changed to '8' from '32'
    21     *! 19-Nov-2009 skp     Fixed high interrupt latency issue
    22     *! 16-Nov-2009 skp     ROV re-implemented for multiple/single callbacks
    23     *! 14-Nov-2009 skp     cleanup/cbFxn removed from driver
    24     *! 05-Nov-2009 kw      reworked and added 'Many' APIs, keep Lists in Notify
    25     *! 26-Oct-2009 skp     ROV views, cleanup
    26     *! 24-Oct-2009 skp     cdoc changes, cleanup
    27     *! 30-Jul-2009 skp     static support, ROV views, logging added
    28     *! 06-Feb-2009 yogesh  modified to incorporate review comments
    29     *! 08-Jan-2009 yogesh  created
    30     */
    31    
    32    package ti.sdo.ipc;
    33    
    34    import xdc.runtime.Assert;
    35    import xdc.runtime.Diags;
    36    
    37    import xdc.rov.ViewInfo;
    38    
    39    import ti.sdo.utils.List;
    40    
    41    import ti.sdo.ipc.interfaces.INotifyDriver;
    42    
    43    /*!
    44     *  ======== Notify ========
    45     *  Notification manager
    46     *
    47     *  This module has a common header that can be found in the {@link ti.ipc}
    48     *  package.  Application code should include the common header file (not the 
    49     *  RTSC-generated one):
    50     *
    51     *  <PRE>#include &lt;ti/ipc/Notify.h></PRE>
    52     *   
    53     *  The RTSC module must be used in the application's RTSC configuration file 
    54     *  (.cfg) if runtime APIs will be used in the application:
    55     *  
    56     *  <PRE>Notify = xdc.useModule('ti.sdo.ipc.Notify');</PRE>
    57     *
    58     *  Documentation for all runtime APIs, instance configuration parameters, 
    59     *  error codes macros and type definitions available to the application 
    60     *  integrator can be found in the 
    61     *  <A HREF="../../../../doxygen/html/files.html">Doxygen documenation</A>
    62     *  for the IPC product.  However, the documentation presented on this page 
    63     *  should be referred to for information specific to the RTSC module, such as
    64     *  module configuration, Errors, and Asserts.
    65     *  @p
    66     *
    67     *  The Notify module typically doesn't require much (if any) configuration at  
    68     *  static time. However, it is possible to reduce the amount of shared memory
    69     *  used by the Notify subsystem by reducing the value of {@link #numEvents}.
    70     */
    71     
    72    @Gated
    73    @ModuleStartup
    74    @InstanceInitError
    75    @InstanceFinalize
    76    
    77    module Notify
    78    {
    79        /*! @_nodoc */
    80        metaonly struct BasicView {
    81            UInt        remoteProcId;
    82            String      remoteProcName;
    83            UInt        lineId;
    84            UInt        disabled;
    85        }
    86    
    87        /*! @_nodoc */
    88        metaonly struct EventDataView {
    89            UInt        eventId;
    90            String      fnNotifyCbck;
    91            String      cbckArg;
    92        }
    93    
    94        /*!
    95         *  ======== rovViewInfo ========
    96         */
    97        @Facet
    98        metaonly config ViewInfo.Instance rovViewInfo =
    99            ViewInfo.create({
   100                viewMap: [
   101                    ['Basic',
   102                        {
   103                            type: ViewInfo.INSTANCE,
   104                            viewInitFxn: 'viewInitBasic',
   105                            structName: 'BasicView'
   106                        }
   107                    ],
   108                    ['EventListeners',
   109                        {
   110                            type: ViewInfo.INSTANCE_DATA,
   111                            viewInitFxn: 'viewInitData',
   112                            structName: 'EventDataView'
   113                        }
   114                    ],
   115                ]
   116            });
   117    
   118        /*!
   119         *  Assert raised when trying to re-register for given line and processor
   120         */
   121        config Assert.Id A_alreadyRegistered =
   122            {msg: "A_alreadyRegistered: Notify instance for the processor/line already registered"};
   123    
   124        /*!
   125         *  Assert raised when trying to use an unregistered Notify instance
   126         */
   127        config Assert.Id A_notRegistered =
   128            {msg: "A_notRegistered: Notify instance not yet registered for the processor/line"};
   129    
   130        /*!
   131         *  Assert raised when trying to improperly use a reserved event
   132         */
   133        config Assert.Id A_reservedEvent =
   134            {msg: "A_reservedEvent: Improper use of a reserved event"};
   135    
   136        /*!
   137         *  Assert raised when {@link #restore} called with improper key
   138         */
   139        config Assert.Id A_outOfOrderNesting =
   140            {msg: "A_outOfOrderNesting: Out of order nesting"};
   141    
   142        /*!
   143         *  ======== SetupProxy ========
   144         *  Device-specific Notify setup proxy
   145         */
   146        proxy SetupProxy inherits ti.sdo.ipc.interfaces.INotifySetup;
   147    
   148        /*! Maximum number of events supported by the Notify module */
   149        const UInt MAXEVENTS = 32;
   150    
   151        /*!
   152         *  Number of events supported by Notify
   153         *
   154         *  Lowering this value offers the benefit of lower footprint especially in
   155         *  shared memory.
   156         */
   157        config UInt numEvents = 32;
   158        
   159        /*!
   160         *  ======== sendEventPollCount ========
   161         *  Poll for specified amount before sendEvent times out
   162         *
   163         *  Setting a finite value for sendEventPollCount will cause 
   164         *  Notify_sendEvent to poll for an amount of time
   165         *  proportional to this value.
   166         */
   167        config UInt32 sendEventPollCount = -1;
   168    
   169        /*! @_nodoc
   170         *  Maximum number of interrupt lines between a single pair of processors
   171         *
   172         *  This config is usually set internally by the NotfiySetup proxy when the
   173         *  proxy is set up to use more than one line.
   174         */
   175        config UInt16 numLines = 1;
   176        
   177        /*!
   178         *  Number of reserved event numbers
   179         *
   180         *  The first reservedEvents event numbers are reserved for
   181         *  middleware modules. Attempts to use these reserved events
   182         *  will result in a {@link #A_reservedEvent} assert.
   183         *
   184         *  To use the reserved events, the top 16-bits of the eventId must have the
   185         *  {@link #SYSTEMKEY} OR'd in.
   186         */
   187        config UInt16 reservedEvents = 3;
   188    
   189        /*!
   190         *  @_nodoc
   191         *  Detach Notify from a remote processor. Should only be called by the Ipc
   192         *  module during its detach operation.
   193         */
   194        Int detach(UInt16 remoteProcId);
   195    
   196    instance:
   197    
   198        /*! @_nodoc
   199         *  Register a created Notify driver with the Notify module
   200         *
   201         *  The Notify module stores a copy of the driverHandle in an array
   202         *  indexed by procId and lineId.  Furture references to the procId
   203         *  and lineId in Notify APIs will utilize the driver registered using
   204         *  {@link #create}.
   205         *
   206         *  @param(driverHandle)    Notify driver handle
   207         *  @param(procId)          Remote processor id
   208         *  @param(lineId)          Line id
   209         */
   210        create(INotifyDriver.Handle driverHandle, UInt16 remoteProcId,
   211               UInt16 lineId);
   212    
   213        /*! @_nodoc
   214         *  Called internally by the Notify module or notify driver module 
   215         *  to execute the callback registered to a specific event.
   216         */
   217        Void exec(UInt32 eventId, UInt32 payload);
   218    
   219    internal:
   220    
   221        /*!
   222         *  Used to execute a list of callback functions when the callbacks are
   223         *  registered using registerMany.
   224         */
   225        Void execMany(UInt16 remoteProcId, UInt16 lineId, UInt32 eventId, UArg arg, 
   226                      UInt32 payload);
   227    
   228        struct EventCallback {
   229            Fxn             fnNotifyCbck;
   230            UArg            cbckArg;
   231        }
   232    
   233        struct EventListener {
   234            List.Elem       element;          /* List elem         */
   235            EventCallback   callback;
   236        }
   237    
   238        struct Instance_State {
   239            UInt                    nesting;        /* Disable/restore nesting    */
   240            INotifyDriver.Handle    driverHandle;   /* Driver handle              */
   241            UInt16                  remoteProcId;   /* Remote MultiProc id        */
   242            UInt16                  lineId;         /* Interrupt line id          */
   243            EventCallback           callbacks[];    /* indexed by eventId         */
   244            List.Object             eventList[];    /* indexed by eventId         */
   245        };
   246    
   247        struct Module_State {
   248            Handle        notifyHandles[][]; /* indexed by procId then lineId */
   249    
   250            /*
   251             * these fields are used for local/loopback events
   252             */
   253            Bits32        localEnableMask;  /* default to enabled (-1) */
   254        }
   255    
   256    }