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    import ti.sdo.ipc.interfaces.IMessageQTransport;
    38    
    39    import xdc.rov.ViewInfo;
    40    
    41    /*!
    42     *  ======== TransportCirc ========
    43     *  Transport for MessageQ that uses a circular buffer.
    44     *
    45     *  This is a {@link ti.sdo.ipc.MessageQ} transport that utilizes shared
    46     *  memory for passing messages between multiple processors.
    47     *
    48     *  The transport utilizes shared memory in the manner indicated by the
    49     *  following diagram.
    50     *
    51     *  @p(code)
    52     *
    53     *  NOTE: Processor '0' corresponds to the M3 and '1' corresponds to the C28
    54     *
    55     * sharedAddr -> --------------------------- bytes
    56     *               |  entry0  (0) [Put]      | msgSize
    57     *               |  entry1  (0)            | msgSize
    58     *               |  ...                    |
    59     *               |  entryN  (0)            | msgSize
    60     *               |                         |
    61     *               |-------------------------|
    62     *               |  putWriteIndex (0)      | 4
    63     *               |                         |
    64     *               |-------------------------|
    65     *               |  getReadIndex (1)       | 4
    66     *               |                         |
    67     *               |-------------------------|
    68     *               |  entry0  (1) [Get]      | msgSize
    69     *               |  entry1  (1)            | msgSize
    70     *               |  ...                    |
    71     *               |  entryN  (1)            | msgSize
    72     *               |                         |
    73     *               |-------------------------|
    74     *               |  putWriteIndex (1)      | 4
    75     *               |                         |
    76     *               |-------------------------|
    77     *               |  getReadIndex (0)       | 4
    78     *               |                         |
    79     *               |-------------------------|
    80     *
    81     *
    82     *  Legend:
    83     *  (0), (1) : belongs to the respective processor
    84     *  (N)      : length of buffer
    85     *
    86     *  @p
    87     */
    88    
    89    @InstanceFinalize
    90    @InstanceInitError
    91    
    92    module TransportCirc inherits IMessageQTransport
    93    {
    94        /*! @_nodoc */
    95        metaonly struct BasicView {
    96            String      remoteProcName;
    97        }
    98    
    99        /*! @_nodoc */
   100        metaonly struct EventDataView {
   101            UInt        index;
   102            String      buffer;
   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        /*!
   165         *  ======== swiPriority ========
   166         *  The priority of the Transport Swi object created
   167         */
   168        config UInt swiPriority = 1;
   169    
   170        /*! @_nodoc
   171         *  ======== sharedMemReq ========
   172         *  Amount of shared memory required for creation of each instance
   173         *
   174         *  @param(params)      Pointer to the parameters that will be used in
   175         *                      create.
   176         *
   177         *  @a(returns)         Number of MAUs needed to create the instance.
   178         */
   179        SizeT sharedMemReq(const Params *params);
   180    
   181        /*! @_nodoc
   182         *  ======== sharedMemReqMeta ========
   183         *  Amount of shared memory required for creation of each instance
   184         *
   185         *  @param(params)      Pointer to the parameters that will be used in
   186         *                      create.
   187         *
   188         *  @a(returns)         Size of shared memory in MAUs on local processor.
   189         */
   190        metaonly SizeT sharedMemReqMeta(const Params *params);
   191    
   192    instance:
   193    
   194        /*! @_nodoc
   195         *  ======== openFlag ========
   196         *  Set to 'true' by the open() call. No one else should touch this!
   197         */
   198        config Bool openFlag = false;
   199    
   200        /*!
   201         *  ======== readAddr ========
   202         *  Physical address of the read address in shared memory
   203         *
   204         *  This address should be specified in the local processor's memory
   205         *  space.  It must point to the same physical write address of the
   206         *  remote processor its communicating with.
   207         */
   208        config Ptr readAddr = null;
   209    
   210        /*!
   211         *  ======== writeAddr ========
   212         *  Physical address of the write address in shared memory
   213         *
   214         *  This address should be specified in the local processor's memory
   215         *  space.  It must point to the same physical read address of the
   216         *  remote processor its communicating with.
   217         */
   218        config Ptr writeAddr = null;
   219    
   220    internal:
   221    
   222        /*! The max index set to (numMsgs - 1) */
   223        config UInt maxIndex;
   224    
   225        /*!
   226         *  The message size calculated based on the target.
   227         */
   228        config UInt msgSize;
   229    
   230        /*!
   231         *  ======== defaultErrFxn ========
   232         *  This is the default error function.
   233         *
   234         *  This function is an empty function that does nothing.
   235         *
   236         *  @param(reason)  reason for error function
   237         *  @param(handle)  handle of transport that had error
   238         *  @param(ptr)     pointer to the message
   239         *  @param(arg)     argument passed to error function
   240         */
   241        Void defaultErrFxn(IMessageQTransport.Reason reason,
   242                           IMessageQTransport.Handle handle, Ptr ptr, UArg arg);
   243    
   244        /*!
   245         *  ======== swiFxn ========
   246         *  This function takes the messages from the transport ListMP and
   247         *  calls MessageQ_put to send them to their destination queue.
   248         *  This function is posted by the NotifyFxn.
   249         *
   250         *  @param(arg)     argument for the function
   251         */
   252        Void swiFxn(UArg arg);
   253    
   254        /*!
   255         *  ======== notifyFxn ========
   256         *  This is a callback function registered with Notify.  It is called
   257         *  when a remote processor does a Notify_sendEvent().  It is executed
   258         *  at ISR level.  It posts the instance Swi object to execute swiFxn.
   259         *
   260         *  @param(procId)  remote processor id
   261         *  @param(lineId)  Notify line id
   262         *  @param(eventId) Notify event id
   263         *  @param(arg)     argument for the function
   264         *  @param(payload) 32-bit payload value.
   265         */
   266        Void notifyFxn(UInt16 procId, UInt16 lineId, UInt32 eventId, UArg arg,
   267                       UInt32 payload);
   268    
   269        /* Instance State object */
   270        struct Instance_State {
   271            Ptr             *putBuffer;     /* buffer used to put message       */
   272            Bits32          *putReadIndex;  /* ptr to readIndex for put buffer  */
   273            Bits32          *putWriteIndex; /* ptr to writeIndex for put buffer */
   274            Ptr             *getBuffer;     /* buffer used to get message       */
   275            Bits32          *getReadIndex;  /* ptr to readIndex for get buffer  */
   276            Bits32          *getWriteIndex; /* ptr to writeIndex for put buffer */
   277            Swi.Object      swiObj;         /* Each instance has a swi          */
   278            SizeT           allocSize;      /* Shared memory allocated          */
   279            UInt16          remoteProcId;   /* dst proc id                      */
   280            UInt16          priority;       /* priority to register             */
   281        };
   282    
   283        struct Module_State {
   284            ErrFxn errFxn;                  /* error function */
   285        };
   286    }