1    /* --COPYRIGHT--,BSD
     2     * Copyright (c) $(CPYYEAR), 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     * --/COPYRIGHT--*/
    32    /*
    33     *  ======== TransportShm.xdc ========
    34     */
    35     
    36    import xdc.runtime.Error;
    37    import ti.sdo.ipc.Ipc;
    38    import ti.sdo.ipc.GateMP;
    39    import ti.sdo.ipc.ListMP;
    40    import ti.sdo.ipc.SharedRegion;
    41    import ti.sysbios.knl.Swi;
    42    
    43    /*!
    44     *  ======== TransportShm ========
    45     *  Shared-memory MessageQ transport that uses ListMP to queue messages 
    46     *  
    47     *  Messages sent via TransportShm are temporarily queued in a shared memory 
    48     *  {@link ti.sdo.ipc.ListMP} instance before the messages are moved by the 
    49     *  receiver to the destination queue.
    50     */
    51    @InstanceFinalize
    52    @InstanceInitError
    53    
    54    module TransportShm inherits ti.sdo.ipc.interfaces.IMessageQTransport 
    55    {   
    56        /*! @_nodoc
    57         *  ======== openByAddr ========
    58         *  Open a created TransportShm instance by address
    59         *
    60         *  Just like {@link #open}, openByAddr returns a handle to a created
    61         *  TransportShm instance.  This function is used to open a
    62         *  TransportShm using a shared address instead of a name.  
    63         *  While {@link #open} should generally be used to open transport
    64         *  instances that have been either locally or remotely created, openByAddr
    65         *  may be used to bypass a NameServer query that would typically be  
    66         *  required of an {@link #open} call.
    67         *  
    68         *  Opening by address requires that the created instance was created
    69         *  by supplying a {@link #sharedAddr} parameter rather than a
    70         *  {@link #regionId} parameter.
    71         *
    72         *  A status value of Status_SUCCESS is returned if the instance
    73         *  is successfully opened.  Status_FAIL indicates that the instance
    74         *  is not yet ready to be opened.  Status_ERROR indicates that
    75         *  an error was raised in the error block.
    76         *
    77         *  Call {@link #close} when the opened instance is no longer needed.
    78         *
    79         *  @param(sharedAddr)  Shared address for the instance
    80         *  @param(handlePtr)   Pointer to handle to be opened
    81         *  @param(eb)          Pointer to error block
    82         *
    83         *  @a(returns)         TransportShm status
    84         */
    85        Int openByAddr(Ptr sharedAddr, Handle *handlePtr, Error.Block *eb);
    86    
    87        /*!
    88         *  ======== close ========
    89         *  Close an opened instance
    90         *
    91         *  Closing an instance will free local memory consumed by the opened
    92         *  instance.  Instances that are opened should be closed before the
    93         *  instance is deleted.
    94         *
    95         *  @param(handle)  handle that is returned from an {@link #openByAddr}
    96         */
    97        Void close(Handle *handle);
    98    
    99        /*! @_nodoc
   100         *  ======== sharedMemReq ========
   101         *  Amount of shared memory required for creation of each instance
   102         *
   103         *  Can be used to make sure the {link #sharedAddr} buffer is large 
   104         *  enough before calling create.
   105         *
   106         *  The {@link #sharedAddr} needs to be
   107         *  supplied because the cache alignment settings for the region
   108         *  may affect the total amount of shared memory required.
   109         *
   110         *  @param(params)      Pointer to the parameters that will be used in
   111         *                      the create.
   112         *
   113         *  @a(returns)         Number of MAUs needed to create the instance.
   114         */
   115        SizeT sharedMemReq(const Params *params);
   116        
   117        /*!
   118         *  ======== notifyEventId ========
   119         *  Notify event ID for transport.
   120         */
   121        config UInt16 notifyEventId = 2;
   122    
   123    instance:
   124    
   125        /*!
   126         *  ======== gate ========
   127         *  GateMP used for critical region management of the shared memory
   128         */
   129        config GateMP.Handle gate = null;
   130        
   131        /*! @_nodoc
   132         *  ======== openFlag ========
   133         *  Set to 'true' by the open() call. No one else should touch this!
   134         */
   135        config Bool openFlag = false;
   136        
   137        /*!
   138         *  ======== sharedAddr ========
   139         *  Physical address of the shared memory
   140         *
   141         *  The creator must supply the shared memory that is used to maintain
   142         *  shared state information.
   143         */
   144        config Ptr sharedAddr = null;
   145    
   146    internal:
   147    
   148        /*! 
   149         *  Constants that all delegate writers need.
   150         */    
   151        const UInt32 UP = 0xBADC0FFE;    
   152    
   153        /*!
   154         *  ======== swiFxn ========
   155         *  This function takes the messages from the transport ListMP and
   156         *  calls MessageQ_put to send them to their destination queue.
   157         *  This function is posted by the NotifyFxn.
   158         *
   159         *  @param(arg)     argument for the function
   160         */
   161        Void swiFxn(UArg arg);
   162        
   163        /*!
   164         *  ======== notifyFxn ========
   165         *  This is a callback function registered with Notify.  It is called
   166         *  when a remote processor does a Notify_sendEvent().  It is executed
   167         *  at ISR level.  It posts the instance Swi object to execute swiFxn.
   168         *
   169         *  @param(eventId) Notify event id
   170         *  @param(arg)     argument for the function
   171         *  @param(payload) 32-bit payload value.
   172         */
   173        Void notifyFxn(UInt16 procId, UInt16 lineId, UInt32 eventId, UArg arg, 
   174                       UInt32 payload);
   175    
   176        /* Structure of attributes in shared memory */
   177        struct Attrs {
   178            Bits32              flag;
   179            Bits32              creatorProcId;
   180            Bits32              notifyEventId;
   181            Bits16              priority;
   182            SharedRegion.SRPtr  gateMPAddr;
   183        };
   184        
   185        /* Instance State object */
   186        struct Instance_State {
   187            Attrs           *self;         /* Attrs in shared memory        */
   188            Attrs           *other;        /* Only flag field is used       */
   189            ListMP.Handle   localList;     /* ListMP to my processor        */
   190            ListMP.Handle   remoteList;    /* ListMP to remote processor    */
   191            Swi.Object      swiObj;        /* Each instance has a swi       */
   192            Int             status;        /* Current status                */
   193            Ipc.ObjType     objType;       /* Static/Dynamic? open/creator? */
   194            SizeT           allocSize;     /* Shared memory allocated       */
   195            Bool            cacheEnabled;  /* Whether to do cache calls     */
   196            UInt16          regionId;      /* the shared region id          */
   197            UInt16          remoteProcId;  /* dst proc id                   */
   198            UInt16          priority;      /* priority to register          */
   199            GateMP.Handle   gate;          /* Gate for critical regions     */
   200        };    
   201        
   202    }