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