1    /*
     2     * Copyright (c) 2012-2014 Texas Instruments Incorporated - https://www.ti.com
     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    /*
    34     *  ======== IMessageQTransport.xdc ========
    35     */
    36    package ti.sdo.ipc.interfaces;
    37    
    38    /*!
    39     *  ======== IMessageQTransport ========
    40     *  Interface for the transports used by MessageQ
    41     *
    42     *  The transport implementations have to register with
    43     *  {@link ti.sdo.ipc.MessageQ}. This is done via the
    44     *  {@link ti.sdo.ipc.MessageQ#registerTransport} function.
    45     *
    46     *  If transports need additional processing during startup,
    47     *  there are multiple hook points to run start-up code that
    48     *  the transport implementation can use.
    49     */
    50    
    51    interface IMessageQTransport inherits ITransport {
    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        @DirectCall
   141        Int getStatus();
   142    
   143        /*!
   144         *  ======== put ========
   145         *  Put the message to the remote processor
   146         *
   147         *  If the transport can accept the message, it returns TRUE. Accepting
   148         *  a message does not mean that it is transmitted. It simply means that
   149         *  the transport should be able to send the message. If the actual transfer
   150         *  fails, the transport calls the {@#ErrFxn} (assuming it is set up via the
   151         *  {@#setErrFxn} API. If the {@#ErrFxn} is not set, the message is dropped.
   152         *  (also...should an error be raised or just System_printf?).
   153         *
   154         *  If the transport cannot send the message, it returns FALSE and a
   155         *  filled in Error_Block. The caller still owns the message.
   156         *
   157         *  @param(msg)             Pointer the message to be sent
   158         *
   159         *  @b(returns)             TRUE denotes acceptance of the message to
   160         *                          be sent. FALSE denotes the message could not be
   161         *                          sent.
   162         */
   163        @DirectCall
   164        Bool put(Ptr msg);
   165    
   166        /*!
   167         *  ======== Control ========
   168         *  Send a control command to the transport instance
   169         *
   170         *  This is function allows transport to specify control commands. Refer
   171         *  to individual transport implementions for more details.
   172         *
   173         *  @param(cmd)             Requested command
   174         *  @param(cmdArgs)         Accompanying field for the command. This is
   175         *                          command specific.
   176         *
   177         *  @b(returns)             TRUE denotes acceptance of the command. FALSE
   178         *                          denotes failure of the command.
   179         */
   180        @DirectCall
   181        Bool control(UInt cmd, UArg cmdArg);
   182    }