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     *  ======== Adaptor.xdc ========
    35     */
    36    
    37    package ti.uia.sysbios;
    38    
    39    import xdc.runtime.Assert;
    40    import xdc.rov.ViewInfo;
    41    import ti.uia.runtime.UIAPacket;
    42    import ti.sysbios.knl.Clock;
    43    import ti.sysbios.knl.Task;
    44    import ti.sysbios.knl.Event;
    45    import ti.sysbios.knl.Semaphore;
    46    import ti.sysbios.knl.Queue;
    47    import ti.sysbios.syncs.SyncEvent;
    48    
    49    /*!
    50     *  ======== Adaptor ========
    51     *  Single core IServiceMgrSupport implementation
    52     *
    53     *  This module implements the IServiceMgrSupport interface
    54     *  and is used by the ServiceMgr on single cores. This module
    55     *  routes UIA data between the instrumentation host and the services
    56     *  via the {@link Transport} implementations. It maintains lists of
    57     *  free events and contrl message buffers via BIOS Semaphores and Queues.
    58     *
    59     *  There is a Transfer Agent task (transferAgentTaskFxn). This task
    60     *  sends data to the instrumentation host. This task uses the
    61     *  {@link ServiceMgr#transportFxns} functions communicate to the host. These functions
    62     *  are setup by default based on the device.
    63     *
    64     *  If {@link ti.uia.runtime.ServiceMgr#supportControl} is true, this module
    65     *  also creates the Receive Task (rxTaskFxn). The Receive Task receives
    66     *  control messages from the instrumentation host via the
    67     *  {@link ServiceMgr#transportFxns} functions. This task is not needed if no control
    68     *  messages are coming from the host.
    69     *
    70     *  The majority of the configuration parameters are defined in the ServiceMgr.
    71     *  For example, the {@link ti.uia.runtime.ServiceMgr#transferAgentPriority}
    72     *  dictates priority of the Adaptor's Transfer Agent task. Here is the list of
    73     *  the ServiceMgr parameter used by the Adaptor module:
    74     *  @p(blist)
    75     *  - numEventPacketBufs
    76     *  - maxEventPacketSize
    77     *  - transferAgentStackSection
    78     *  - transferAgentStackSize
    79     *  - transferAgentPriority
    80     *  - supportControl
    81     *  - maxCtrlPacketSize
    82     *  - numIncomingCtrlPacketBufs
    83     *  - numOutgoingCtrlPacketBufs
    84     *  - rxTaskStackSize
    85     *  - rxTaskStackSection
    86     *  - rxTaskPriority
    87     *  @p
    88     */
    89    
    90    @ModuleStartup      /* Initialize static instances */
    91    
    92    module Adaptor inherits ti.uia.runtime.IServiceMgrSupport
    93    {
    94    
    95        /*!
    96         *  ======== packetSection ========
    97         *  Memory section for UIA packets.
    98         *
    99         *  If this parameter is not set then the
   100         *  ServiceMgr.transferAgentStackSection parameter is used for the events
   101         *  and the ServiceMgr.rxTaskStackSection parameter is used for the control
   102         *  messages.
   103         */
   104        metaonly config String packetSection;
   105    
   106        /*!
   107         *  @_nodoc
   108         *  ======== rxTaskFxn ========
   109         *  Function used for the Receive Task.
   110         */
   111        @DirectCall
   112        Void rxTaskFxn(UArg arg0, UArg arg1);
   113    
   114        /*!
   115         *  @_nodoc
   116         *  ======== transferAgentFxn ========
   117         *  Function used for the transfer agent Task.
   118         */
   119        @DirectCall
   120        Void transferAgentTaskFxn(UArg arg0, UArg arg1);
   121    
   122        /*!
   123         *  @_nodoc
   124         *  ======== clockFxn ========
   125         *  Function used to drive transfer agent's event polling
   126         */
   127        @DirectCall
   128        Void clockFxn(UArg arg0);
   129    
   130    internal:
   131    
   132        /*!
   133         *  ======== Entry ========
   134         *  Structure used to place packets on a free queues
   135         */
   136        struct Entry {
   137            Queue.Elem     elem;
   138            UIAPacket.Hdr  packet;
   139        }
   140    
   141        /*!
   142         *  ======== eventBuf ========
   143         *  Buffer of event packets
   144         */
   145        config Char eventBuf[];
   146    
   147        /*!
   148         *  ======== msgBuf ========
   149         *  Buffer of control message packets
   150         */
   151        config Char msgBuf[];
   152    
   153        /*!
   154         *  ======== period ========
   155         *  Each Service's period
   156         *
   157         *  Stored as ticks. Zero defaults do not poll.
   158         */
   159        config UInt32 period[];
   160    
   161        /*!
   162         *  ======== scheduled ========
   163         *  Next time when the service should be polled for new events
   164         *
   165         *  Stored as ticks. Zero defaults do not poll.
   166         */
   167        config UInt32 scheduled[];
   168    
   169        /*!
   170         *  ======== reqEnergy ========
   171         *  Flag to denote that a service has requested energy.
   172         */
   173        config Bool reqEnergy[];
   174    
   175        /*!
   176         *  ======== giveEnergy ========
   177         *  Internal helper function
   178         */
   179        @DirectCall
   180        Void giveEnergy();
   181    
   182        /*!
   183         *  ======== sendToHost ========
   184         *  Internal helper function
   185         */
   186        @DirectCall
   187        Bool sendToHost(UIAPacket.Hdr *packet);
   188    
   189        /*!
   190         *  ======== sendToService ========
   191         *  Internal helper function
   192         */
   193        @DirectCall
   194        Void sendToService(Entry *entry);
   195    
   196        /*!
   197         *  ======== runScheduledServices ========
   198         *  Internal helper function
   199         */
   200        @DirectCall
   201        Void runScheduledServices();
   202    
   203        /*!
   204         *  ======== Module_State ========
   205         *  The four queues are used as following:
   206         *  freeEventQ: holds "free" event packets
   207         *  freeMsgQ:   holds "free" control message packets (both
   208         *              incoming and outgoing ones)
   209         *  incomingQ:  holds all filled-in incoming messages
   210         *  outgoingQ:  holds all filled-in outgoing messages
   211         */
   212        struct Module_State {
   213            Event.Handle            event;
   214            Clock.Handle            clock;
   215            Semaphore.Handle        freeEventSem;
   216            Semaphore.Handle        freeMsgSem;
   217            Semaphore.Handle        incomingSem;
   218            Queue.Handle            freeEventQ;
   219            Queue.Handle            freeMsgQ;
   220            Queue.Handle            incomingQ;
   221            Queue.Handle            outgoingQ;
   222            SyncEvent.Handle        syncEvent01;
   223            Task.Handle             transferAgentHandle;
   224            Ptr                     transportMsgHandle;
   225            Ptr                     transportEventHandle;
   226            Int                     numMsgPacketsSent;
   227            Int                     numMsgPacketsFailed;
   228            Int                     numEventPacketsSent;
   229            Int                     numEventPacketsFailed;
   230        };
   231    }