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     * ======== UIAMessage.xdc ========
    35     */
    36    
    37    import xdc.runtime.Diags;
    38    
    39    /*!
    40     * UIA Message Events
    41     *
    42     * The UIAMessage module defines events that allow
    43     * tooling to monitor messages between tasks and CPUs.
    44     *
    45     *  The generation of UIAMessage events is controlled by a module's diagnostics
    46     *  mask, which is described in details in `{@link xdc.runtime.Diags}`.
    47     * `UIAMessage` info events are generated only when the Diags.INFO bit is set
    48     *  in the module's diagnostics mask.
    49     *
    50     *  The following configuration script demonstrates how to enable use of
    51     *  UIAMessage events within an application. The Diags.INFO bitmust be explicitly set
    52     *  in order to enable these events.
    53     *
    54     *  This is part of the XDC configuration file for the application:
    55     *
    56     *  @p(code)
    57     *  var UIAMessage = xdc.useModule('ti.uia.events.UIAMessage');
    58     *  var Diags = xdc.useModule('xdc.runtime.Diags');
    59     *  var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
    60     *  var Defaults = xdc.useModule('xdc.runtime.Defaults');
    61     *  var logger = LoggerSys.create();
    62     *
    63     *  Defaults.common$.logger = logger;
    64     *  Defaults.common$.diags_INFO = Diags.ALWAYS_ON;
    65     *  @p
    66     *
    67     *  @p(html)
    68     *  <hr />
    69     *  @p
    70     *
    71     *  Example 2: The following example configures a module to support logging
    72     *  of STATUS events and INFO events, but defers the actual activation and deactivation of the
    73     *  logging until runtime. See the `{@link Diags#setMask Diags_setMask()}`
    74     *  function for details on specifying the control string.
    75     *
    76     *  This is a part of the XDC configuration file for the application:
    77     *
    78     *  @p(code)
    79     *  var UIAMessage = xdc.useModule('ti.uia.events.UIAMessage');
    80     *  var Diags = xdc.useModule('xdc.runtime.Diags');
    81     *  var Mod = xdc.useModule('my.pkg.Mod');
    82     *
    83     *  Mod.common$.diags_STATUS = Diags.RUNTIME_OFF;
    84     *  Mod.common$.diags_INFO = Diags.RUNTIME_OFF;
    85     *  @p
    86     *
    87     *  This is a part of the C code for the application:
    88     *
    89     *  @p(code)
    90     *  // turn on logging of STATUS events (S) and INFO events (F)
    91     *  // in the module
    92     *  Diags_setMask("my.pkg.Mod+SF");
    93     *
    94     *  // turn off logging of STATUS events and INFO events in the module
    95     *  Diags_setMask("my.pkg.Mod-SF");
    96     *  @p
    97     */
    98    module UIAMessage inherits IUIAEvent {
    99    
   100        /*! ======= msgSent ======
   101         * Message Sent event
   102         *  @a(Example)
   103         *   The following C code shows how to log a msgSent event
   104         *
   105         *  @p(code)
   106         *  #include <xdc/runtime/Log.h>
   107         *  #include <ti/uia/events/UIAMessage.h>
   108         *  ...
   109         *  Log_write7(UIAMessage_msgSent, numBytes,flags,msgId,destProcId,replyProcId,srcProcId,heapId);
   110         *  ...
   111         *  @p  The following text is an example of what will be displayed for the event:
   112         *  @p(code)
   113         *  "Msg Sent [NumBytes]0x32 [Flags]0xF [MsgId]0x8357 [Dest(ProcID)]0x2 [Reply(ProcID)]0x3 [Src(ProcID)]0x1 [HeapId]0x56"
   114         *
   115         * @param(NumBytes) length of the message in bytes
   116         * @param(Flags) any flags associated with the message
   117         * @param(MsgId) the message ID for the message
   118         * @param(Destination ProcID) the procID for the message destination
   119         * @param(Reply ProcID) the procID that the reply will be sent to
   120         * @param(Source ProcID) the procID of the message sender
   121         * @param(HeapId) the HeapID associated with the message
   122         */
   123        config xdc.runtime.Log.Event msgSent = {
   124            mask: Diags.INFO,
   125            msg: "Msg Sent [NumBytes]0x%x [Flags]0x%x [MsgId]0x%x [Dest(ProcID)]0x%x [Reply(ProcID)]0x%x [Src(ProcID)]0x%x [HeapId]0x%x"
   126        };
   127    
   128        /*! ======= msgReceived ======
   129         * Message Received event
   130         *  @a(Example)
   131         *   The following C code shows how to log a msgReceived event
   132         *
   133         *  @p(code)
   134         *  #include <xdc/runtime/Log.h>
   135         *  #include <ti/uia/events/UIAMessage.h>
   136         *  ...
   137         *  Log_write7(UIAMessage_msgReceived, numBytes,flags,msgId,destProcId,replyProcId,srcProcId,heapId);
   138         *  ...
   139         *  @p  The following text is an example of what will be displayed for the event:
   140         *  @p(code)
   141         *  "Msg Received [NumBytes]0x32 [Flags]0xF [MsgId]0x8357 [Dest(ProcID)]0x2 [Reply(ProcID)]0x3 [Src(ProcID)]0x1 [HeapId]0x56"
   142         *
   143         * @param(NumBytes) length of the message in bytes
   144         * @param(Flags) any flags associated with the message
   145         * @param(MsgId) the message ID for the message
   146         * @param(Destination ProcID) the procID for the message destination
   147         * @param(Reply ProcID) the procID that the reply will be sent to
   148         * @param(Source ProcID) the procID of the message sender
   149         * @param(HeapId) the HeapID associated with the message
   150         */
   151        config xdc.runtime.Log.Event msgReceived = {
   152            mask: Diags.INFO,
   153            msg: "Msg Received [NumBytes]0x%x [Flags]0x%x [MsgId]0x%x [Dest(ProcID)]0x%x [Reply(ProcID)]0x%x [Src(ProcID)]0x%x [HeapId]0x%x"
   154        };
   155    
   156        /*! ======= replySent ======
   157         * Reply Sent event
   158         *  @a(Example)
   159         *   The following C code shows how to log a msgSent event
   160         *
   161         *  @p(code)
   162         *  #include <xdc/runtime/Log.h>
   163         *  #include <ti/uia/events/UIAMessage.h>
   164         *  ...
   165         *  Log_write7(UIAMessage_replySent, numBytes,flags,msgId,destProcId,replyProcId,srcProcId,heapId);
   166         *  ...
   167         *  @p  The following text is an example of what will be displayed for the event:
   168         *  @p(code)
   169         *  "Reply Sent [NumBytes]0x32 [Flags]0xF [MsgId]0x8357 [Dest(ProcID)]0x2 [Reply(ProcID)]0x3 [Src(ProcID)]0x1 [HeapId]0x56"
   170         *
   171    
   172         * @param(NumBytes) length of the message in bytes
   173         * @param(Flags) any flags associated with the message
   174         * @param(MsgId) the message ID for the message
   175         * @param(Destination ProcID) the procID for the message destination
   176         * @param(Reply ProcID) the procID that the reply will be sent to
   177         * @param(Source ProcID) the procID of the message sender
   178         * @param(HeapId) the HeapID associated with the message
   179         */
   180        config xdc.runtime.Log.Event replySent = {
   181            mask: Diags.INFO,
   182            msg: "Reply Sent [NumBytes]0x%x [Flags]0x%x [MsgId]0x%x [Dest(ProcID)]0x%x [Reply(ProcID)]0x%x [Src(ProcID)]0x%x [HeapId]0x%x"
   183        };
   184    
   185        /*! ======= replyReceived ======
   186         * Reply Received event
   187         *  @a(Example)
   188         *   The following C code shows how to log a msgSent event
   189         *
   190         *  @p(code)
   191         *  #include <xdc/runtime/Log.h>
   192         *  #include <ti/uia/events/UIAMessage.h>
   193         *  ...
   194         *  Log_write5(UIAMessage_replyReceived,msgId,replyId,numBytes,senderProcId,destProcId);
   195         *  ...
   196         *  @p  The following text is an example of what will be displayed for the event:
   197         *  @p(code)
   198         *  "Msg Sent [MsgId]0x8357 [NumBytes]0x32 [Flags]0xF [Dest(ProcID)]0x2 [Reply(ProcID)]0x3 [Src(ProcID)]0x1 [HeapId]0x56"
   199         *
   200         * @param(MsgId) the message ID for the message
   201         * @param(ReplyId) the reply's message ID
   202         * @param(NumBytes) length of the message in bytes
   203         * @param(Sender ProcID) the procID that the reply will be sent to
   204         * @param(Destination ProcID) the procID for the message destination
   205         */
   206        config xdc.runtime.Log.Event replyReceived = {
   207            mask: Diags.INFO,
   208            msg: "Reply Recieved [MsgId]0x%x [ReplyId]0x%x [NumBytes]0x%x [Sender]0x%x [Dest]0x%x "
   209        };
   210    
   211    }