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    }