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