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