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     *  ======== Rta.xdc ========
    35     *  UIA RealTime Analysis module
    36     *
    37     *  Responsible for collecting Log events and sending them to
    38     *  an instrumentation host. Rta only services loggers that inherit from
    39     *  the {@link ti.uia.runtime.IUIATransfer} interface (e.g.
    40     *   {@link ti.uia.runtime.LoggerCircBuf}.
    41     *
    42     *  Rta sends records to the host from one logger instance at a
    43     *  time--it will finish one logger before moving on to the next one.
    44     *
    45     *  The Rta service runs in the framework of the UIA ServiceMgr framework.
    46     *  Configuration of the how the logs are actually moved off the target
    47     *  is managed by the {@link ti.uia.runtime.ServiceMgr} modules.
    48     *
    49     *  Before sending the records to the host, the agent will copy them into
    50     *  a transfer buffer. The size of this transfer buffer is configurable using
    51     *  the {@link ti.uia.runtime.ServiceMgr} module.
    52     *
    53     *  Because the application may generate logs faster than the agent can send
    54     *  them to the host, there is a limit to how many records the agent will send
    55     *  from one logger before moving on to the next one. The limit is
    56     *  approximately the size of the logger instance.
    57     *
    58     *  The rate at which the logs are sent up depends on two configuration
    59     *  parameters, {@link #period} and
    60     *  {@link ti.uia.runtime.ServiceMgr#transferAgentPriority}.
    61     *  The period does not guarantee that the collection will run
    62     *  at this rate. Even if the period has expired, the collection
    63     *  will not occur until the current running Task has yielded and there
    64     *  are no other higher priority Tasks ready.
    65     *
    66     *  The Rta module also responds to commands from the host to configure logging
    67     *  dynamically on the target, such as changing modules' diagnostic masks and
    68     *  enabling or disabling loggers.
    69     *
    70     *  To enable Rta, simply do an xdc.useModule in your configuration file.
    71     *  @p(code)
    72     *  var Rta = xdc.useModule('ti.uia.services.Rta');
    73     *  @p
    74     *  The ServiceMgr is brought in automatically be this statement. If the
    75     *  configuration of the ServiceMgr needs to be changed, the application must
    76     *  do an xdc.useModule on ti.uia.runtime.ServiceMgr and configured it as
    77     *  needed.
    78     */
    79    
    80    import xdc.runtime.Diags;
    81    import xdc.runtime.Log;
    82    import ti.uia.runtime.ServiceMgr;
    83    import ti.uia.runtime.UIAPacket;
    84    import ti.uia.runtime.IUIATransfer;
    85    import xdc.rov.ViewInfo;
    86    
    87    module Rta
    88    {
    89        /*!
    90         *  @_nodoc
    91         *  ======== ModuleView ========
    92         */
    93        metaonly struct ModuleView {
    94            Int         serviceId;
    95            Bool        enabled;
    96            Bool        snapshotMode;
    97            Int         period;
    98            UInt        numLoggers;
    99            String      loggers[];
   100            Bits16      sequence;
   101            UInt        totalPacketsSent;
   102        }
   103    
   104        /*!
   105         *  @_nodoc
   106         *  ======== rovViewInfo ========
   107         */
   108        @Facet
   109        metaonly config ViewInfo.Instance rovViewInfo =
   110            ViewInfo.create({
   111                viewMap: [['Module',   {type: ViewInfo.MODULE,
   112                                        viewInitFxn: 'viewInitModule',
   113                                        structName: 'ModuleView'}
   114                          ]]
   115            });
   116    
   117        /*! Logged on every packet is sent call from the Rta */
   118        config Log.Event LD_recordsSent = {
   119            mask: Diags.USER2,
   120            msg: "LD_recordsSent: Sent %d bytes from logger [%d] 0x%x"
   121        };
   122    
   123        /*! Logged when the Rta receives a command */
   124        config Log.Event LD_cmdRcvd = {
   125            mask: Diags.USER2,
   126            msg: "LD_cmdRcvd: Received command: %d, arg0: 0x%x, arg1: 0x%x"
   127        };
   128    
   129        /*! Logged when a diags mask is changed */
   130        config Log.Event LD_writeMask = {
   131            mask: Diags.USER2,
   132            msg: "LD_writeMask: Mask addres: 0x%x, New mask value: 0x%x"
   133        };
   134    
   135        /*!
   136         *  ======== periodInMs ========
   137         *  Period in miliseconds of the RTA Transfer Agent
   138         *
   139         *  Configures how often the RTA should collect events. The minimum
   140         *  value is 100ms.
   141         *
   142         *  This value does not guarantee that the collection will run
   143         *  at this rate. Even if the period has expired, the collection
   144         *  will not occur until the current running Task has yielded and there
   145         *  are no other higher priority Tasks ready.
   146         *
   147         *  Setting the period to 0, disables all collection of events. There
   148         *  must be a setPeriod message sent from an instrumentation host to
   149         *  Rta to enable it.
   150         *
   151         *  Default is 100 milliseconds.
   152         */
   153        config Int periodInMs = 100;
   154    
   155        /*! @_nodoc
   156         *  ======== processCallback ========
   157         *  Function registered with the ServiceMgr module
   158         */
   159        Void processCallback(ServiceMgr.Reason reason, UIAPacket.Hdr *cmd);
   160    
   161        /*! @_nodoc
   162         *  ======== registerLoggers ========
   163         *  Register all loggers instances with the Agent so that it can service
   164         *  them on the target.
   165         */
   166        metaonly function registerLoggers(modObj);
   167    
   168        /*!
   169         *  ======== disableAllLogs ========
   170         *  Function to disable all the logs being processed by Rta
   171         *
   172         *  Runtime function to disable all the logs that are being
   173         *  processed/read by Rta. When disabled, all new Log records
   174         *  are discarded.
   175         *
   176         *  Please realize that external instrumentation host (e.g.
   177         *  System Analyzer) might be sending down similar requests.
   178         */
   179        Void disableAllLogs();
   180    
   181        /*!
   182         *  ======== enableAllLogs ========
   183         *  Function to enable all the logs being processed by Rta
   184         *
   185         *  Runtime function to enable disable all the logs that are being
   186         *  processed/read by Rta.
   187         *
   188         *  Please realize that external instrumentation host (e.g.
   189         *  System Analyzer) might be sending down similar requests
   190         */
   191        Void enableAllLogs();
   192    
   193        /*!
   194         *  ======== snapshotAllLogs ========
   195         *  Function to delay processing of the Rta service
   196         *
   197         *  This function informs Rta to delay for the specified waitPeriod (in ms).
   198         *  After the waitPeriod has expired, Rta will process all the loggers
   199         *  that it manages. The state of Rta (e.g. started or stopped) will
   200         *  be maintained after the waitPeriod is expired and all the logs
   201         *  processed.
   202         *
   203         *  The reset flag determines whether to reset all the loggers at the
   204         *  start of the waitPeriod (true -> reset). The state of the loggers
   205         *  (e.g. enabled or disabled) is not changed by this flag.
   206         *
   207         *  @param(reset)   Flag to denote whether to reset the loggers or not.
   208         *                  TRUE means reset all the loggers processed by Rta.
   209         *                  FALSE means do not reset any of the loggers processed
   210         *                  by Rta.
   211         *
   212         *  @param(waitPeriod) Duration in milliseconds to wait to run the Rta
   213         *                     service.
   214         */
   215        Void snapshotAllLogs(UArg reset, UArg waitPeriod);
   216    
   217        /*!
   218         *  ======== resetAllLogs ========
   219         *  Function to resets enable all the logs being processed by Rta
   220         *
   221         *  Runtime function to enable resets all the logs that are being
   222         *  processed/read by Rta. All records in the logs are discarded.
   223         *  The state of the logger (e.g. enabled or disabled) is not changed.
   224         *
   225         *  Please realize that external instrumentation host (e.g.
   226         *  System Analyzer) might be sending down similar requests
   227         */
   228        Void resetAllLogs();
   229    
   230        /*!
   231         *  ======== startDataTx ========
   232         *  Function to start the Rta service
   233         *
   234         *  This function allows the Rta service to be turned on.
   235         *
   236         *  Please realize that external instrumentation host (e.g.
   237         *  System Analyzer) might be sending down similar requests
   238         */
   239        Void startDataTx();
   240    
   241        /*!
   242         *  ======== stopDataTx ========
   243         *  Function to stop the Rta service
   244         *
   245         *  This function allows the Rta service to be turned off.
   246         *
   247         *  Please realize that external instrumentation host (e.g.
   248         *  System Analyzer) might be sending down similar requests
   249         */
   250        Void stopDataTx();
   251    
   252    internal:
   253    
   254        /*
   255         *  ======== SERVICEID ========
   256         *  Method to obtain serviceId
   257         */
   258        readonly config ServiceMgr.ServiceId SERVICEID;
   259    
   260    
   261        /*
   262         *  ======== sendEvents ========
   263         *  Send out events
   264         */
   265        Void sendEvents();
   266    
   267        /*
   268         *  ======== processMsg ========
   269         *  Process an incoming message
   270         */
   271        Void processMsg(UIAPacket.Hdr *cmd);
   272    
   273        /*
   274         *  ======== flushLogger ========
   275         *  Flushes a logger.
   276         * @param(logger) the handle of the logger to flush
   277         * @param(loggerNum) the logger's InstanceId
   278         */
   279        Void flushLogger(IUIATransfer.Handle logger, UInt loggerNum);
   280    
   281        /* Control APIs */
   282        Void acknowledgeCmd(Packet *resp);
   283        UIAPacket.MsgType readMask(Packet *resp, UArg addr);
   284        UIAPacket.MsgType writeMask(Packet *resp, UArg addr, UArg val);
   285        Void enableLog(UArg log);
   286        Void disableLog(UArg log);
   287        Void getCpuSpeed(Packet *resp);
   288        Void resetLog(UArg log);
   289        Void changePeriod(UArg period);
   290    
   291        /* Command ids */
   292        enum Command {
   293            Command_READ_MASK = 0,
   294            Command_WRITE_MASK = 1,
   295            Command_LOGGER_OFF = 2,
   296            Command_LOGGER_ON = 3,
   297            Command_GET_CPU_SPEED = 4,
   298            Command_RESET_LOGGER = 5,
   299            Command_CHANGE_PERIOD = 6,
   300            Command_START_TX = 7,
   301            Command_STOP_TX = 8,
   302            Command_LOGGER_OFF_ALL = 9,
   303            Command_LOGGER_ON_ALL = 10,
   304            Command_RESET_LOGGER_ALL = 11,
   305            Command_SNAPSHOT_ALL = 12
   306        };
   307    
   308        enum ErrorCode {
   309            ErrorCode_NULLPOINTER = 0
   310        };
   311    
   312        /* Structure of response packet sent back to host */
   313        struct Packet {
   314            UIAPacket.Hdr hdr;
   315            Bits32        arg0;
   316            Bits32        arg1;
   317        }
   318    
   319        struct Module_State {
   320            IUIATransfer.Handle  loggers[];
   321            UInt                 numLoggers;
   322            UInt                 totalPacketsSent;
   323            Int                  period;
   324            Bits16               seq;
   325            Bool                 txData;
   326            Bool                 snapshot;
   327        };
   328    }