packages/ti/sdo/ipc/family/f28m35x/TransportCirc.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  *  ======== TransportCirc.xdc ========
  34  */
  35
  36 import ti.sysbios.knl.Swi;
  37
  38 import xdc.rov.ViewInfo;
  39
  40 /*!
  41  *  ======== TransportCirc ========
  42  *  Transport for MessageQ that uses a circular buffer.
  43  *
  44  *  This is a {@link ti.sdo.ipc.MessageQ} transport that utilizes shared
  45  *  memory for passing messages between multiple processors.
  46  *
  47  *  The transport utilizes shared memory in the manner indicated by the
  48  *  following diagram.
  49  *
  50  *  @p(code)
  51  *
  52  *  NOTE: Processor '0' corresponds to the M3 and '1' corresponds to the C28
  53  *
  54  * sharedAddr -> --------------------------- bytes
  55  *               |  entry0  (0) [Put]      | 4
  56  *               |  entry1  (0)            | 4
  57  *               |  ...                    |
  58  *               |  entryN  (0)            | 4
  59  *               |                         |
  60  *               |-------------------------|
  61  *               |  putWriteIndex (0)      | 4
  62  *               |                         |
  63  *               |-------------------------|
  64  *               |  getReadIndex (1)       | 4
  65  *               |                         |
  66  *               |-------------------------|
  67  *               |  entry0  (1) [Get]      | 4
  68  *               |  entry1  (1)            | 4
  69  *               |  ...                    |
  70  *               |  entryN  (1)            | 4
  71  *               |                         |
  72  *               |-------------------------|
  73  *               |  putWriteIndex (1)      | 4
  74  *               |                         |
  75  *               |-------------------------|
  76  *               |  getReadIndex (0)       | 4
  77  *               |                         |
  78  *               |-------------------------|
  79  *
  80  *
  81  *  Legend:
  82  *  (0), (1) : belongs to the respective processor
  83  *  (N)      : length of buffer
  84  *
  85  *  @p
  86  */
  87
  88 @InstanceFinalize
  89 @InstanceInitError
  90
  91 module TransportCirc inherits ti.sdo.ipc.interfaces.IMessageQTransport
  92 {
  93     /*! @_nodoc */
  94     metaonly struct BasicView {
  95         String      remoteProcName;
  96     }
  97
  98     /*! @_nodoc */
  99     metaonly struct EventDataView {
 100         UInt        index;
 101         String      buffer;
 102         Ptr         addr;
 103         Ptr         message;
 104     }
 105
 106     /*!
 107      *  ======== rovViewInfo ========
 108      */
 109     @Facet
 110     metaonly config ViewInfo.Instance rovViewInfo =
 111         ViewInfo.create({
 112             viewMap: [
 113                 ['Basic',
 114                     {
 115                         type: ViewInfo.INSTANCE,
 116                         viewInitFxn: 'viewInitBasic',
 117                         structName: 'BasicView'
 118                     }
 119                 ],
 120                 ['Events',
 121                     {
 122                         type: ViewInfo.INSTANCE_DATA,
 123                         viewInitFxn: 'viewInitData',
 124                         structName: 'EventDataView'
 125                     }
 126                 ],
 127             ]
 128         });
 129
 130     /*!
 131      *  ======== close ========
 132      *  Close an opened instance
 133      *
 134      *  Closing an instance will free local memory consumed by the opened
 135      *  instance.  Instances that are opened should be closed before the
 136      *  instance is deleted.
 137      *
 138      *  @param(handle)  handle that is returned from an {@link #openByAddr}
 139      */
 140     Void close(Handle *handle);
 141
 142     /*! @_nodoc
 143      *  ======== notifyEventId ========
 144      *  Notify event ID for transport.
 145      */
 146     config UInt16 notifyEventId = 2;
 147
 148     /*! @_nodoc
 149      *  ======== numMsgs ========
 150      *  The maximum number of outstanding messages
 151      *
 152      *  This number must be greater than 0 and a power of 2.
 153      *  If the transport reaches this threshold, it spins waiting for
 154      *  another message slot to be freed by the remote processor.
 155      */
 156     config UInt numMsgs = 4;
 157
 158     /*! @_nodoc
 159      *  ======== maxMsgSizeInBytes ========
 160      *  The maximum message size (in bytes) that is supported
 161      */
 162     config UInt maxMsgSizeInBytes = 128;
 163
 164     /*! @_nodoc
 165      *  ======== sharedMemReq ========
 166      *  Amount of shared memory required for creation of each instance
 167      *
 168      *  @param(params)      Pointer to the parameters that will be used in
 169      *                      create.
 170      *
 171      *  @a(returns)         Number of MAUs needed to create the instance.
 172      */
 173     SizeT sharedMemReq(const Params *params);
 174
 175     /*! @_nodoc
 176      *  ======== sharedMemReqMeta ========
 177      *  Amount of shared memory required for creation of each instance
 178      *
 179      *  @param(params)      Pointer to the parameters that will be used in
 180      *                      create.
 181      *
 182      *  @a(returns)         Size of shared memory in MAUs on local processor.
 183      */
 184     metaonly SizeT sharedMemReqMeta(const Params *params);
 185
 186 instance:
 187
 188     /*! @_nodoc
 189      *  ======== openFlag ========
 190      *  Set to 'true' by the open() call. No one else should touch this!
 191      */
 192     config Bool openFlag = false;
 193
 194     /*!
 195      *  ======== readAddr ========
 196      *  Physical address of the read address in shared memory
 197      *
 198      *  This address should be specified in the local processor's memory
 199      *  space.  It must point to the same physical write address of the
 200      *  remote processor its communicating with.
 201      */
 202     config Ptr readAddr = null;
 203
 204     /*!
 205      *  ======== writeAddr ========
 206      *  Physical address of the write address in shared memory
 207      *
 208      *  This address should be specified in the local processor's memory
 209      *  space.  It must point to the same physical read address of the
 210      *  remote processor its communicating with.
 211      */
 212     config Ptr writeAddr = null;
 213
 214 internal:
 215
 216     /*! The max index set to (numMsgs - 1) */
 217     config UInt maxIndex;
 218
 219     /*!
 220      *  The message size calculated based on the target.
 221      */
 222     config UInt msgSize;
 223
 224     /*!
 225      *  ======== swiFxn ========
 226      *  This function takes the messages from the transport ListMP and
 227      *  calls MessageQ_put to send them to their destination queue.
 228      *  This function is posted by the NotifyFxn.
 229      *
 230      *  @param(arg)     argument for the function
 231      */
 232     Void swiFxn(UArg arg);
 233
 234     /*!
 235      *  ======== notifyFxn ========
 236      *  This is a callback function registered with Notify.  It is called
 237      *  when a remote processor does a Notify_sendEvent().  It is executed
 238      *  at ISR level.  It posts the instance Swi object to execute swiFxn.
 239      *
 240      *  @param(procId)  remote processor id
 241      *  @param(lineId)  Notify line id
 242      *  @param(eventId) Notify event id
 243      *  @param(arg)     argument for the function
 244      *  @param(payload) 32-bit payload value.
 245      */
 246     Void notifyFxn(UInt16 procId, UInt16 lineId, UInt32 eventId, UArg arg,
 247                    UInt32 payload);
 248
 249     /* Instance State object */
 250     struct Instance_State {
 251         Ptr             *putBuffer;     /* buffer used to put message       */
 252         Bits32          *putReadIndex;  /* ptr to readIndex for put buffer  */
 253         Bits32          *putWriteIndex; /* ptr to writeIndex for put buffer */
 254         Ptr             *getBuffer;     /* buffer used to get message       */
 255         Bits32          *getReadIndex;  /* ptr to readIndex for get buffer  */
 256         Bits32          *getWriteIndex; /* ptr to writeIndex for put buffer */
 257         Swi.Object      swiObj;         /* Each instance has a swi          */
 258         SizeT           allocSize;      /* Shared memory allocated          */
 259         UInt16          remoteProcId;   /* dst proc id                      */
 260         UInt16          priority;       /* priority to register             */
 261     };
 262 }