1    /*
     2     * Copyright (c) 2012, 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    /*
    34     *  ======== Transport.xdc ========
    35     */
    36    
    37    package ti.uia.runtime;
    38    
    39    /*!
    40     *  ======== Transport ========
    41      *  Transport function specification module
    42     *
    43     *  This module defines the function prototypes for the transport functions
    44     *  that can be plugged into the ServiceMgr. UIA ships several
    45     *  implementations of this interface in the ti/uia/sysbios directory.
    46     *
    47     *  The implementations do not have to be XDC modules. They are simply standard
    48     *  'C' functions (i.e look at ti/uia/sysbios/TransportNdk.c). Only one
    49     *  transport set can be used on a target and it needs to be set up at build
    50     *  time via the {@link ti.uia.runtime.ServiceMgr#transportFxns} parameter. The
    51     *  ServiceMgr plugs the transportFxns automatically based on the TransportType
    52     *  {@link ti.uia.runtime.ServiceMgr#transportType}.
    53     *
    54     *  If someone writes an new transport
    55     *  (e.g. RapidIO), they can be plugged in by setting the TransportType
    56     *  to {@link ti.uia.runtime.ServiceMgr#TransportType_USER} and then plugging
    57     *  the transportFxns manually. It must also set up the following parameters
    58     *  as directed by the new transport developer.
    59     *  @p(blist)
    60     *  -ServiceMgr.supportControl: does the transport support receiving messages
    61     *                 from the host. For example TransportFile does not.
    62     *  -ServiceMgr.maxEventPacketSize: Max size of an outgoing event packet. For
    63     *                 example TransportNdk uses 1472 (emac size minus headers)
    64     *  -ServiceMgr.maxCtrlPacketSize: Max size of the message packets. This can
    65     *                 be zero if supportControl is false.
    66     *  @p
    67     *
    68     *  Here is an example of plugging the transport XYZ into the ServiceMgr:
    69     *  @p(code)
    70     *  var ServiceMgr = xdc.useModule('ti.uia.runtime.ServiceMgr');
    71     *  ServiceMgr.transportType = ServiceMgr.TransportType_USER;
    72     *  var xyzTransport = {
    73     *      initFxn: '&TransportXYZ_init',
    74     *      startFxn: '&TransportXYZ_start',
    75     *      recvFxn: '&TransportXYZ_recv',
    76     *      sendFxn: '&TransportXYZ_send',
    77     *      stopFxn: '&TransportXYZ_stop',
    78     *      exitFxn: '&TransportXYZ_exit',
    79     *  };
    80     *  ServiceMgr.transportFxns = xyzTransport;
    81     *
    82     *  ServiceMgr.maxEventPacketSize = 1024
    83     *  ServiceMgr.maxCtrlPacketSize  = 1024;
    84     *  ServiceMgr.supportControl     = true;
    85     *  @p
    86     *
    87     *  @p(html)
    88     *  <a name="transportfxn"></a>
    89     *
    90     *  @a(Transport Functions)
    91     *
    92     *  The following are the transport functions. Note
    93     *  all of these functions
    94     *  are called by the ServiceMgr. The application should not be calling
    95     *  these functions directly.
    96     *  @p(blist)
    97     *  -initFxn:  Called during module startup (which is before main()). Minimal
    98     *             actions can take place here since there are no interrupts and
    99     *             the state of the application is just starting up. Generally only
   100     *             internal initialization is done in this function.
   101     *
   102     *  -startFxn: The start function is called at once or twice after the SYS/BIOS
   103     *             tasks have started to run. The start
   104     *             function is called with UIAPacket_HdrType_EventPkt before any
   105     *             events are sent. This allows the transport to initialize
   106     *             anything needed for event transmission. The function returns a
   107     *             handle to a transport specific structure (or NULL if not needed).
   108     *             This handle is passed into the sendFxn and stopFxn.
   109     *
   110     *             If the transport supports control messages from a host, the
   111     *             start function is called with UIAPacket_HdrType_Msg.
   112     *             This allows the transport to initialize anything needed for
   113     *             msg transmission (both sending and receiving). Again, the
   114     *             transport can return a transport specific structure. This
   115     *             structure can be different from the one returned in the
   116     *             UIAPacket_HdrType_EventPkt start.
   117     *
   118     *  -recvFxn:  The recv function is called to receive incoming messages
   119     *             from the host. The handle returned from the start is passed
   120     *             into the recv. Also passed in is a buffer and its size.
   121     *             The buffer is passed in as a double pointer. This allows
   122     *             the transport to double-buffer. For example, the recv
   123     *             function can return a different buffer than what was
   124     *             passed in. This potentially reduces extra copies of the data.
   125     *
   126     *             The recv can be a blocking call.
   127     *
   128     *             The recv returns the actual number of bytes that are placed into
   129     *             the buffer. If the transport does not
   130     *             support control messages, this function can simply return zero.
   131     *
   132     *  -sendFxn:  The send function is called to send either events or msgs. If
   133     *             send is called to transmit a event, the first parameter is the
   134     *             handle returned from the start(UIAPacket_HdrType_EventPkt).
   135     *             Similiarily, if a message is being sent, the first parameter is
   136     *             the handle returned from the start(UIAPacket_HdrType_Msg).
   137     *             The size of the packet is maintained in the UIAPacket_Hdr.
   138     *
   139     *             The send can be a blocking call.
   140     *
   141     *             This function returns whether the send was successful or not.
   142     *
   143     *             Again a double pointer is used to allow the transport to return
   144     *             a different buffer to allow double-buffering.
   145     *
   146     *  -stopFxn:  The stop function is to counterpart to the start function. The
   147     *             stop will be called the same number of times as the start. The
   148     *             calls will contain handles returned from the start.
   149     *
   150     *  -exitFxn:  The exit function is to counterpart to the init function.
   151     *  @p
   152     *
   153     *  Transport are allowed to have additional functions that can be directly
   154     *  called by the application. For example in ti/uia/sysbiosTransportFile,
   155     *  there is a TransportFile_setFile function. The downside to the extended
   156     *  functions is portability.
   157     */
   158    module Transport
   159    {
   160        /*!
   161         *  Task hook set type definition.
   162         *
   163         *  See {@link #transportfxn Transport Functions} for details.
   164         */
   165        struct FxnSet {
   166            Void  (*initFxn)();
   167            Ptr   (*startFxn)(UIAPacket.HdrType);
   168            SizeT (*recvFxn)(Ptr, UIAPacket.Hdr **, SizeT);
   169            Bool  (*sendFxn)(Ptr, UIAPacket.Hdr **);
   170            Void  (*stopFxn)(Ptr);
   171            Void  (*exitFxn)(Void);
   172        };
   173    }