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     *  ======== IUIATransfer ========
    35     */
    36    interface IUIATransfer inherits xdc.runtime.IFilterLogger {
    37    
    38        enum TransferType {
    39            TransferType_RELIABLE = 0,
    40            TransferType_LOSSY = 1
    41        }
    42    
    43        /*!  @_nodoc
    44         * ======== Logger Priority enumeration ========
    45         */
    46        enum Priority {
    47            Priority_LOW = 0,       /*! low priority */
    48            Priority_STANDARD = 1,  /*! default priority */
    49            Priority_HIGH = 2,      /*! use for critical errors, etc. */
    50            Priority_SYNC = 3       /*! used only by LogSync's logger */
    51        };
    52    
    53        /*!
    54         * ======== getPtrToQueueDescriptorMeta ========
    55         * Each logger instance has a unique queue descriptor address that is
    56         * stored in the Event Record header to identify itself to the host.
    57         * This metaonly configuration parameter allows the UIA Metadata to
    58         * determine what the address is for each statically created logger instance
    59         * in order to emit XML code to allow the host to look up information about
    60         * the logger instance (such as its name) based on the queue descriptor
    61         * address that is stored in the event record header.
    62         *
    63         * The pointer is returned per instance of the logger module. The
    64         *  instance object is passed to the function as the first argument.
    65         */
    66         metaonly function getPtrToQueueDescriptorMeta(inst);
    67        /*!
    68         * ======== setPtrToQueueDescriptorMeta ========
    69         * Sets the queue descriptor address in the logger's object instance data.
    70         */
    71         metaonly function setPtrToQueueDescriptorMeta(inst,queueDescriptorAdrs);
    72         /*!
    73         *  ======== getLoggerInstanceId ========
    74         *  returns the id of this logger instance.
    75         */
    76        metaonly function getLoggerInstanceId(inst);
    77    
    78        /*! @_nodoc
    79         *  ======== getLoggerPriority ========
    80         *  returns the priority of this logger instance.
    81         */
    82        metaonly function getLoggerPriority(inst);
    83    
    84        /*! @_nodoc
    85         *  ======== setLoggerPriority ========
    86         *  sets the priority of this logger instance.
    87         */
    88        metaonly function setLoggerPriority(inst, priority);
    89    
    90        /*!
    91         *  ======== MetaData ========
    92         *  This data is added to the RTA MetaData file to support stop mode RTA.
    93         */
    94        @XmlDtd metaonly struct MetaData {
    95            Int instanceId;
    96            Int priority;
    97        }
    98    
    99    instance:
   100        config TransferType transferType = TransferType_LOSSY;
   101        TransferType getTransferType();
   102    
   103        /*!
   104         *  ======== getContents =========
   105         *  Fills buffer that is passed in with unread data, up to size bytes
   106         *  in length.
   107         *
   108         *  The logger is responsible for ensuring that no partial event records
   109         *  are stored in the buffer.  Bytes are in target endianness.
   110         *
   111         *  @param(hdrBuf)   Ptr to a buffer that is at least <size> bytes in length
   112         *  @param(size)     The max number of bytes to be read into the buffer
   113         *  @param(cpSize)   The number of bytes actually copied
   114         *
   115         *  @a(return)       returns false if logger has no more records to read
   116         */
   117        @DirectCall
   118        Bool getContents(Ptr hdrBuf, SizeT size, SizeT *cpSize);
   119    
   120        /*!
   121         *  ======== isEmpty =========
   122         *  Returns true if the transfer buffer has no unread data
   123         *
   124         *  @a(return)  true if no unread data
   125         */
   126        @DirectCall
   127        Bool isEmpty();
   128    
   129        /*!
   130         *  ======== getMaxLength =========
   131         */
   132        @DirectCall
   133        SizeT getMaxLength();
   134    
   135        /*!
   136         *  ======== getInstanceId ========
   137         *  Returns an ID value that uniquely identifies this instance of the logger.
   138         *
   139         *  Note that a value of 0 is reserved to indicate that the instance ID has
   140         *  not been initialized yet and a unique value needs to be generated.
   141         */
   142        @DirectCall
   143        UInt16 getInstanceId();
   144    
   145        /*! @_nodoc
   146         *  ======== priority ========
   147         *  The priority of the logger is used to detrmine which event packets to
   148         *  transfer to the host first.
   149         *
   150         *  A value of Priority_STANDARD (default) indicates normal priority.
   151         *  Higher values indicate higher priority.
   152         *  @see #Priority
   153         */
   154        config IUIATransfer.Priority priority = Priority_STANDARD;
   155    
   156        /*! @_nodoc
   157         *  ======== getPriority ========
   158         *  Returns a 2b value that identifies the relative priority of the event
   159         *  log.
   160         *
   161         *  A value of 1 (default) indicates normal priority.  Higher values indicate
   162         *  higher priority.
   163         *  @see #Priority
   164         */
   165        @DirectCall
   166        Priority getPriority();
   167    
   168    
   169        /*! @_nodoc
   170         *  ======== setPriority ========
   171         *  Sets a 2b value that identifies the relative priority of the event
   172         *  log.
   173         *
   174         *  A value of 1 (default) indicates normal priority.  Higher values indicate
   175         *  higher priority.
   176         *  @see #Priority
   177         */
   178        @DirectCall
   179        Void setPriority(Priority priority);
   180    
   181        /*!
   182         *  ======== reset ========
   183         *  Reset a log to empty state and enable it
   184         *
   185         *  @a(WARNING)  This method is not synchronized with other instance
   186         *  methods and, as a result, it must never be called when there is a
   187         *  chance that another instance method is currently in operation or
   188         *  when another method on this instance may preempt this call.
   189         */
   190        Void reset();
   191    
   192        metaonly config Ptr ptrToQueueDescriptorMeta = null;
   193    }