packages/ti/sdo/ipc/nsremote/NameServerRemoteNotify.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  *  ======== NameServerRemoteNotify.xdc ========
  34  */
  35
  36 import xdc.runtime.Error;
  37 import xdc.runtime.Assert;
  38
  39 import xdc.rov.ViewInfo;
  40
  41 import ti.sysbios.knl.Swi;
  42 import ti.sysbios.knl.Semaphore;
  43 import ti.sdo.ipc.GateMP;
  44 import ti.sdo.utils.INameServerRemote;
  45
  46 /*!
  47  *  ======== NameServerRemoteNotify ========
  48  *  Used by NameServer to communicate to remote processors.
  49  *
  50  *  This module is used by {@link #ti.sdo.utils.NameServer} to communicate
  51  *  to remote processors using {@link ti.sdo.ipc.Notify} and shared memory.
  52  *  There needs to be one instance between each two cores in the system.
  53  *  Interrupts must be enabled before using this module.  For critical
  54  *  memory management, a GateMP {@link #gate} can be specified.  Currently
  55  *  supports transferring up to 300-bytes between two cores.
  56  */
  57 @InstanceInitError
  58 @InstanceFinalize
  59
  60 module NameServerRemoteNotify inherits INameServerRemote
  61 {
  62     /*! @_nodoc */
  63     metaonly struct BasicView {
  64         UInt        remoteProcId;
  65         String      remoteProcName;
  66         String      localRequestStatus;
  67         String      localInstanceName;
  68         String      localName;
  69         String      localValue;
  70         String      remoteRequestStatus;
  71         String      remoteInstanceName;
  72         String      remoteName;
  73         String      remoteValue;
  74     }
  75
  76     /*!
  77      *  ======== rovViewInfo ========
  78      */
  79     @Facet
  80     metaonly config ViewInfo.Instance rovViewInfo =
  81         ViewInfo.create({
  82             viewMap: [
  83                 ['Basic',
  84                     {
  85                         type: ViewInfo.INSTANCE,
  86                         viewInitFxn: 'viewInitBasic',
  87                         structName: 'BasicView'
  88                     }
  89                 ],
  90             ]
  91         });
  92
  93     /* structure in shared memory for retrieving value */
  94     struct Message {
  95         Bits32  requestStatus;      /* if request sucessful set to 1    */
  96         Bits32  value;              /* holds value if len <= 4          */
  97         Bits32  valueLen;           /* len of value                     */
  98         Bits32  instanceName[8];    /* name of NameServer instance      */
  99         Bits32  name[8];            /* name of NameServer entry         */
 100         Bits32  valueBuf[77];       /* padded to fill 128-B cache line  */
 101     };
 102
 103     /*!
 104      *  Assert raised when length of value larger then 300 bytes.
 105      */
 106     config xdc.runtime.Assert.Id A_invalidValueLen =
 107         {msg: "A_invalidValueLen: Invalid valueLen (too large)"};
 108
 109     /*!
 110      *  Message structure size is not aligned on cache line size.
 111      *
 112      *  The message structure size must be an exact multiple of the
 113      *  cache line size.
 114      */
 115     config xdc.runtime.Assert.Id A_messageSize =
 116         {msg: "A_messageSize: message size not aligned with cache line size."};
 117
 118     /*!
 119      *  ======== notifyEventId ========
 120      *  The Notify event ID.
 121      */
 122     config UInt notifyEventId = 4;
 123
 124     /*!
 125      *  ======== timeoutInMicroSecs ========
 126      *  The timeout value in terms of microseconds
 127      *
 128      *  A NameServer request will return after this amout of time
 129      *  without a response. The default timeout value is to wait forever.
 130      *  To not wait, use the value of '0'.
 131      */
 132     config UInt timeoutInMicroSecs = ~(0);
 133
 134 instance:
 135
 136     /*!
 137      *  ======== sharedAddr ========
 138      *  Physical address of the shared memory
 139      *
 140      *  The shared memory that will be used for maintaining shared state
 141      *  information.  This value must be the same for both processors when
 142      *  creating the instance between a pair of processors.
 143      */
 144     config Ptr sharedAddr = null;
 145
 146     /*!
 147      *  ======== gate ========
 148      *  GateMP used for critical region management of the shared memory
 149      *
 150      *  Using the default value of NULL will result in the default GateMP
 151      *  being used for context protection.
 152      */
 153     config GateMP.Handle gate = null;
 154
 155 internal:
 156
 157     /*
 158      *  ======== timeout ========
 159      *  The timeout value to pass into Semaphore_pend
 160      *
 161      *  This value is calculated based on timeoutInMicroSecs and the
 162      *  SYSBIOS clock.tickPeriod.
 163      */
 164     config UInt timeout;
 165
 166     /*!
 167      *  ======== cbFxn ========
 168      *  The call back function registered with Notify.
 169      *
 170      *  This function is registered with Notify as a call back function
 171      *  when the specified event is triggered.  This function simply posts
 172      *  a Swi which will process the event.
 173      *
 174      *  @param(procId)          Source proc id
 175      *  @param(lineId)          Interrupt line id
 176      *  @param(eventId)         the Notify event id.
 177      *  @param(arg)             the argument for the function.
 178      *  @param(payload)         a 32-bit payload value.
 179      */
 180     Void cbFxn(UInt16 procId, UInt16 lineId, UInt32 eventId, UArg arg,
 181                UInt32 payload);
 182
 183     /*!
 184      *  ======== swiFxnRequest ========
 185      *  The swi function which handles a request message
 186      *
 187      *  @param(arg)     pointer to the instance object
 188      */
 189     Void swiFxnRequest(UArg arg);
 190
 191     /*!
 192      *  ======== swiFxnResponse ========
 193      *  The swi function that which handles a response message
 194      *
 195      *  @param(arg)     pointer to the instance object
 196      */
 197     Void swiFxnResponse(UArg arg);
 198
 199     /*! no pending messages */
 200     const UInt8 IDLE = 0;
 201
 202     /*! sending a request message to another processor */
 203     const UInt8 SEND_REQUEST = 1;
 204
 205     /*! receiving a response message (in reply to a sent request) */
 206     const UInt8 RECEIVE_RESPONSE = 2;
 207
 208     /*! receiving a request from a remote processor (unsolicited message) */
 209     const UInt8 RECEIVE_REQUEST = 1;
 210
 211     /*! sending a response message (in reply to a received request) */
 212     const UInt8 SEND_RESPONSE = 2;
 213
 214     /* instance state */
 215     struct Instance_State {
 216         Message             *msg[2];        /* Ptrs to messages in shared mem */
 217         UInt16              regionId;       /* SharedRegion ID                */
 218         UInt8               localState;     /* state of local message         */
 219         UInt8               remoteState;    /* state of remote message        */
 220         GateMP.Handle       gate;           /* remote and local gate protect  */
 221         UInt16              remoteProcId;   /* remote MultiProc id            */
 222         Bool                cacheEnable;    /* cacheability                   */
 223         Semaphore.Object    semRemoteWait;  /* sem to wait on remote proc     */
 224         Semaphore.Object    semMultiBlock;  /* sem to block multiple threads  */
 225         Swi.Object          swiRequest;     /* handle a request message       */
 226         Swi.Object          swiResponse;    /* handle a response message      */
 227     };
 228 }