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     *  ======== IMessageQTransport.xdc ========
    12     *
    13     *! Revision History
    14     *! ================
    15     */
    16    
    17    /*!
    18     *  ======== IMessageQTransport ========
    19     *  Interface for the transports used by MessageQ
    20     *
    21     *  The transport implementations have to register with
    22     *  {@link ti.sdo.ipc.MessageQ}. This is done via the 
    23     *  {@link ti.sdo.ipc.MessageQ#registerTransport} function.
    24     *
    25     *  If transports need additional processing during startup,
    26     *  there are multiple hook points to run start-up code that
    27     *  the transport implementation can use.
    28     */
    29    
    30    interface IMessageQTransport
    31    {
    32        /*! 
    33         *  Transport return values  
    34         *
    35         *  @p(blist)
    36         *  -{@link #S_SUCCESS}: Operation was successful
    37         *  -{@link #E_FAIL}: Operation resulted in a failure
    38         *  -{@link #E_ERROR}: Operation resulted in an error.
    39         *  @p     
    40         */
    41        enum Status {
    42            S_SUCCESS = 0,
    43            E_FAIL = -1,
    44            E_ERROR = -2
    45        };
    46        
    47        /*! 
    48         *  Reason for error function being called
    49         *
    50         *  First field in the {@link #errFxn}
    51         */
    52        enum Reason {
    53            Reason_FAILEDPUT,
    54            Reason_INTERNALERR,
    55            Reason_PHYSICALERR,
    56            Reason_FAILEDALLOC
    57        };
    58        
    59        /*!
    60         *  Asynchronous error function for the transport module
    61         */
    62        config ErrFxn errFxn = null;
    63        
    64        /*!
    65         *  Typedef for transport error callback function.
    66         *
    67         *  First parameter: Why the error function is being called.
    68         *
    69         *  Second parameter: Handle of transport that had the error. NULL denotes
    70         *  that it is a system error, not a specific transport.
    71         *
    72         *  Third parameter: Pointer to the message. This is only valid for
    73         *  {@link #Reason_FAILEDPUT}.
    74         *     
    75         *  Fourth parameter: Transport specific information. Refer to individual 
    76         *  transports for more details.
    77         */
    78        typedef Void (*ErrFxn)(Reason, Handle, Ptr, UArg);
    79        
    80        /*!
    81         *  ======== setErrFxn ========
    82         *  Sets the asynchronous error function for the transport module
    83         *
    84         *  This API allows the user to set the function that will be called in
    85         *  case of an asynchronous error by the transport.
    86         *
    87         *  @param(errFxn)        Function that is called when an asynchronous
    88         *                        error occurs.     
    89         */
    90        Void setErrFxn(ErrFxn errFxn);
    91        
    92    instance:
    93    
    94        /*!
    95         *  Which priority messages should this transport manage.
    96         */    
    97        config UInt priority = 0;
    98        
    99        /*!
   100         *  ======== create ========
   101         *  Create a Transport instance
   102         *
   103         *  This function creates a transport instance. The transport is 
   104         *  responsible for registering with MessageQ via the 
   105         *  {@link ti.sdo.ipc.MessageQ#registerTransport} API.
   106         *
   107         *  @param(procId)        Remote processor id that this instance 
   108         *                        will communicate with.
   109         */
   110        create(UInt16 procId);
   111    
   112        /*!
   113         *  ======== getStatus ========
   114         *  Status of a Transport instance
   115         *
   116         *  This function returns the status of the transport instance.
   117         *
   118         *  @b(returns)             Returns status of Transport instance
   119         */
   120        Int getStatus();        
   121        
   122        /*!
   123         *  ======== put ========
   124         *  Put the message to the remote processor
   125         *
   126         *  If the transport can accept the message, it returns TRUE. Accepting
   127         *  a message does not mean that it is transmitted. It simply means that 
   128         *  the transport should be able to send the message. If the actual transfer
   129         *  fails, the transport calls the {@#ErrFxn} (assuming it is set up via the 
   130         *  {@#setErrFxn} API. If the {@#ErrFxn} is not set, the message is dropped.
   131         *  (also...should an error be raised or just System_printf?).
   132         *  
   133         *  If the transport cannot send the message, it returns FALSE and a
   134         *  filled in Error_Block. The caller still owns the message.
   135         *
   136         *  @param(msg)             Pointer the message to be sent
   137         *
   138         *  @b(returns)             TRUE denotes acceptance of the message to 
   139         *                          be sent. FALSE denotes the message could not be 
   140         *                          sent.
   141         */
   142        Bool put(Ptr msg);
   143        
   144        /*!
   145         *  ======== Control ========
   146         *  Send a control command to the transport instance
   147         *
   148         *  This is function allows transport to specify control commands. Refer
   149         *  to individual transport implementions for more details.
   150         *
   151         *  @param(cmd)             Requested command
   152         *  @param(cmdArgs)         Accompanying field for the command. This is 
   153         *                          command specific.
   154         *
   155         *  @b(returns)             TRUE denotes acceptance of the command. FALSE 
   156         *                          denotes failure of the command. 
   157         */  
   158        Bool control(UInt cmd, UArg cmdArg);
   159    }