packages/ti/sdo/ipc/Notify.xdc

   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  *  ======== Notify.xdc ========
  34  *
  35  */
  36
  37 package ti.sdo.ipc;
  38
  39 import xdc.runtime.Assert;
  40 import xdc.runtime.Diags;
  41
  42 import xdc.rov.ViewInfo;
  43
  44 import ti.sdo.utils.List;
  45
  46 import ti.sdo.ipc.interfaces.INotifyDriver;
  47
  48 /*!
  49  *  ======== Notify ========
  50  *  Notification manager
  51  *
  52  *  @p(html)
  53  *  This module has a common header that can be found in the {@link ti.ipc}
  54  *  package.  Application code should include the common header file (not the
  55  *  RTSC-generated one):
  56  *
  57  *  <PRE>#include &lt;ti/ipc/Notify.h&gt;</PRE>
  58  *
  59  *  The RTSC module must be used in the application's RTSC configuration file
  60  *  (.cfg) if runtime APIs will be used in the application:
  61  *
  62  *  <PRE>Notify = xdc.useModule('ti.sdo.ipc.Notify');</PRE>
  63  *
  64  *  Documentation for all runtime APIs, instance configuration parameters,
  65  *  error codes macros and type definitions available to the application
  66  *  integrator can be found in the
  67  *  <A HREF="../../../../doxygen/html/files.html">Doxygen documenation</A>
  68  *  for the IPC product.  However, the documentation presented on this page
  69  *  should be referred to for information specific to the RTSC module, such as
  70  *  module configuration, Errors, and Asserts.
  71  *  @p
  72  *
  73  *  The Notify module typically doesn't require much (if any) configuration at
  74  *  static time. However, it is possible to reduce the amount of shared memory
  75  *  used by the Notify subsystem by reducing the value of {@link #numEvents}.
  76  */
  77
  78 @Gated
  79 @ModuleStartup
  80 @InstanceInitError
  81 @InstanceFinalize
  82
  83 module Notify
  84 {
  85     /*! @_nodoc */
  86     metaonly struct BasicView {
  87         UInt        remoteProcId;
  88         String      remoteProcName;
  89         UInt        lineId;
  90         UInt        disabled;
  91     }
  92
  93     /*! @_nodoc */
  94     metaonly struct EventDataView {
  95         UInt        eventId;
  96         String      fnNotifyCbck;
  97         String      cbckArg;
  98     }
  99
 100     /*!
 101      *  ======== rovViewInfo ========
 102      */
 103     @Facet
 104     metaonly config ViewInfo.Instance rovViewInfo =
 105         ViewInfo.create({
 106             viewMap: [
 107                 ['Basic',
 108                     {
 109                         type: ViewInfo.INSTANCE,
 110                         viewInitFxn: 'viewInitBasic',
 111                         structName: 'BasicView'
 112                     }
 113                 ],
 114                 ['EventListeners',
 115                     {
 116                         type: ViewInfo.INSTANCE_DATA,
 117                         viewInitFxn: 'viewInitData',
 118                         structName: 'EventDataView'
 119                     }
 120                 ],
 121             ]
 122         });
 123
 124     /*!
 125      *  Assert raised when trying to re-register for given line and processor
 126      */
 127     config Assert.Id A_alreadyRegistered =
 128         {msg: "A_alreadyRegistered: Notify instance for the processor/line already registered"};
 129
 130     /*!
 131      *  Assert raised when trying to use an unregistered Notify instance
 132      */
 133     config Assert.Id A_notRegistered =
 134         {msg: "A_notRegistered: Notify instance not yet registered for the processor/line"};
 135
 136     /*!
 137      *  Assert raised when trying to improperly use a reserved event
 138      */
 139     config Assert.Id A_reservedEvent =
 140         {msg: "A_reservedEvent: Improper use of a reserved event"};
 141
 142     /*!
 143      *  Assert raised when {@link #restore} called with improper key
 144      */
 145     config Assert.Id A_outOfOrderNesting =
 146         {msg: "A_outOfOrderNesting: Out of order nesting"};
 147
 148     /*!
 149      *  ======== A_invArgument ========
 150      *  Assert raised when an argument is invalid
 151      */
 152     config Assert.Id A_invArgument  = {
 153         msg: "A_invArgument: Invalid argument supplied"
 154     };
 155
 156     /*!
 157      *  ======== A_internal ========
 158      *  Assert raised when an internal error is encountered
 159      */
 160     config Assert.Id A_internal = {
 161         msg: "A_internal: An internal error has occurred"
 162     };
 163
 164     /*!
 165      *  ======== SetupProxy ========
 166      *  Device-specific Notify setup proxy
 167      */
 168     proxy SetupProxy inherits ti.sdo.ipc.interfaces.INotifySetup;
 169
 170     /*! Maximum number of events supported by the Notify module */
 171     const UInt MAXEVENTS = 32;
 172
 173     /*!
 174      *  Number of events supported by Notify
 175      *
 176      *  Lowering this value offers the benefit of lower footprint especially in
 177      *  shared memory.
 178      */
 179     config UInt numEvents = 32;
 180
 181     /*!
 182      *  ======== sendEventPollCount ========
 183      *  Poll for specified amount before sendEvent times out
 184      *
 185      *  Setting a finite value for sendEventPollCount will cause
 186      *  Notify_sendEvent to poll for an amount of time
 187      *  proportional to this value when the 'waitClear' flag is TRUE.
 188      */
 189     config UInt32 sendEventPollCount = -1;
 190
 191     /*! @_nodoc
 192      *  Maximum number of interrupt lines between a single pair of processors
 193      *
 194      *  This config is usually set internally by the NotfiySetup proxy when the
 195      *  proxy is set up to use more than one line.
 196      */
 197     config UInt16 numLines = 1;
 198
 199     /*!
 200      *  Number of reserved event numbers
 201      *
 202      *  The first reservedEvents event numbers are reserved for
 203      *  middleware modules. Attempts to use these reserved events
 204      *  will result in a {@link #A_reservedEvent} assert.
 205      *
 206      *  To use the reserved events, the top 16-bits of the eventId must equal
 207      *  Notify_SYSTEMKEY.
 208      */
 209     config UInt16 reservedEvents = 5;
 210
 211     /*!
 212      *  @_nodoc
 213      *  Detach Notify from a remote processor. Should only be called by the Ipc
 214      *  module during its detach operation.
 215      */
 216     Int detach(UInt16 remoteProcId);
 217
 218 instance:
 219
 220     /*! @_nodoc
 221      *  Register a created Notify driver with the Notify module
 222      *
 223      *  The Notify module stores a copy of the driverHandle in an array
 224      *  indexed by procId and lineId.  Furture references to the procId
 225      *  and lineId in Notify APIs will utilize the driver registered using
 226      *  {@link #create}.
 227      *
 228      *  @param(driverHandle)    Notify driver handle
 229      *  @param(procId)          Remote processor id
 230      *  @param(lineId)          Line id
 231      */
 232     create(INotifyDriver.Handle driverHandle, UInt16 remoteProcId,
 233            UInt16 lineId);
 234
 235     /*! @_nodoc
 236      *  Called internally by the Notify module or notify driver module
 237      *  to execute the callback registered to a specific event.
 238      */
 239     Void exec(UInt32 eventId, UInt32 payload);
 240
 241 internal:
 242
 243     /*!
 244      *  Used to execute a list of callback functions when the callbacks are
 245      *  registered using registerMany.
 246      */
 247     Void execMany(UInt16 remoteProcId, UInt16 lineId, UInt32 eventId, UArg arg,
 248                   UInt32 payload);
 249
 250     struct EventCallback {
 251         Fxn             fnNotifyCbck;
 252         UArg            cbckArg;
 253     }
 254
 255     struct EventListener {
 256         List.Elem       element;          /* List elem         */
 257         EventCallback   callback;
 258     }
 259
 260     struct Instance_State {
 261         UInt                    nesting;        /* Disable/restore nesting    */
 262         INotifyDriver.Handle    driverHandle;   /* Driver handle              */
 263         UInt16                  remoteProcId;   /* Remote MultiProc id        */
 264         UInt16                  lineId;         /* Interrupt line id          */
 265         EventCallback           callbacks[];    /* indexed by eventId         */
 266         List.Object             eventList[];    /* indexed by eventId         */
 267     };
 268
 269     struct Module_State {
 270         Handle        notifyHandles[][]; /* indexed by procId then lineId */
 271
 272         /*
 273          * these fields are used for local/loopback events
 274          */
 275         Bits32        localEnableMask;  /* default to enabled (-1) */
 276     }
 277
 278 }