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