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     *  ======== ILoggerSnapshot.xdc ========
    35     */
    36    import xdc.runtime.Types;
    37    import xdc.runtime.Log;
    38    
    39    /*!
    40     *  ======== ILoggerSnapshot ========
    41     *  Interface to service LogSnapshot events
    42     *
    43     *  A loggerSnapshot is responsible for recording, transmitting, or otherwise
    44     *  handling `{@link LogSnapshot#EventDesc LogSnapshot Events}` generated by clients of the
    45     *  `{@link LogSnapshot}` module. The `LogSnapshot` module uses modules that implement the
    46     *  `ILoggerSnapshot` interface to record the log events. Most application code will
    47     *  use the `LogSnapshot` module instead of directly calling the specific `ILoggerSnapshot`
    48     *  module implementation.
    49     *
    50     *  All loggerSnapshot implementations must inherit from this interface. The
    51     *  derived implementations must implement the functions defined in this
    52     *  interface but may also add additional configuration parameters and
    53     *  functions.
    54     *
    55     *  Since this interface inherits {@link xdc.runtime.ILogger}, loggerSnapshots
    56     *  can also be used to support events logged by the `{@link Log}` module and other
    57     *  modules that log events based on the ILogger interface.
    58     */
    59    interface ILoggerSnapshot inherits IUIATransfer {
    60    
    61    instance:
    62        /*!
    63         *  ======== writeMemoryRange ========
    64         *  Log an event along with values from a range of memory addresses
    65         *
    66         *  If the mask in the specified `LogSnapshot` event has any bit set which is
    67         *  also set in the current module's diagnostics mask, then this call to
    68         *  write will "raise" the given `LogSnapshot` event.
    69         *
    70         *  Note that this API supports null terminated strings, arrays of characters and
    71         *  memory mapped registgers as well as blocks of memory.  The LogSnapshot module provides macros that
    72         *  map the appropriate values to the writeMemoryRange API's arguments
    73         *
    74         *  @param(evt)         event to be logged
    75         *  @param(snapshotId)  0 = no other snapshot groups, Use value from
    76         *                      LogSnapshot.getSnapshotId() for all snapshots to be grouped.
    77         *  @param(fileName)    __FILE__ result
    78         *  @param(lineNum)     __LINE__ result
    79         *  @param(fmt)         a `printf` style format string
    80         *  @param(startAdrs)   value for first format conversion character
    81         *  @param(lengthInMAUs) value for second format conversion character
    82         *
    83         *  @see Log#Event
    84         *  @see Log#EventDesc
    85         *  @see Text#ropeText
    86         *  @see Types#getEventId
    87         */
    88        @DirectCall
    89        Void writeMemoryRange(Log.Event evt, Types.ModuleId mid, UInt32 snapshotId,
    90                             IArg fileName, IArg LineNum, IArg fmt, IArg startAdrs,
    91                             UInt32 lengthInMAUs);
    92    }