packages/ti/sdo/ipc/interfaces/IMessageQTransport.xdc

   1 /*
   2  * Copyright (c) 2012-2014 Texas Instruments Incorporated - http://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 }