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     *  ======== QueueDescriptor.xdc ========
    35     *  Module to manage descriptors that are used by an instrumentation host
    36     *
    37     *  The QueueDescriptor module maintains a list of descriptors. Each descriptor
    38     *  contains information that a host tool can use to get debug information
    39     *  about a debug buffer (e.g. LoggerCircBuf instance buffer).
    40     *
    41     *  The QueueDescriptor module contains two global variables that the host
    42     *  can access.
    43     *  @p(blist)
    44     *   - ti_uia_runtime_QueueDescriptor_gPtrToFirstDescriptor:
    45     *     pointer to the first queue descriptor. The rest of the active descriptors
    46     *     are maintained as list off the first one (via the next pointer in the
    47     *     structure).
    48     *     Global variable needed to manage reading / writing the circular buffer
    49     *     from the DebugServer. Initialized to null.  A non-null value indicates
    50     *     that the descriptor it points to has been fully initialized.
    51     *
    52     *  - ti_uia_runtime_QueueDescriptor_gUpdateCount:
    53     *     Integer value read by the host to determine whether it needs to walk the
    54     *     list of descriptors
    55     *     Incremented whenever a queue descriptor is modified, added or removed
    56     *     from the list of descriptors. If the value has not changed, then the host
    57     *     can safely use cached versions of the descriptors.
    58     *  @p
    59     */
    60    package ti.uia.runtime
    61    
    62    
    63    @CustomHeader
    64    module QueueDescriptor {
    65    
    66        /*!
    67         *  ======== QueueType ========
    68         *  Type of Queue
    69         */
    70        enum QueueType {
    71            QueueType_NONE = 0,
    72            QueueType_TOHOST_CMD_CIRCULAR_BUFFER = 1,
    73            QueueType_FROMHOST_CMD_CIRCULAR_BUFFER = 2,
    74            QueueType_TOHOST_EVENT_CIRCULAR_BUFFER = 3,
    75            QueueType_TOHOST_EVENT_OVERFLOW_BUFFER = 4,
    76            QueueType_TOHOST_DATA_CIRCULAR_BUFFER = 5,
    77            QueueType_FROMHOST_DATA_CIRCULAR_BUFFER = 6
    78        };
    79    
    80        /*!
    81         *  ======== Header ========
    82         *  Structure of the descriptor
    83         *
    84         *  @field(structSize)       Used for version control to determine if newer
    85         *                           fields are available
    86         *  @field(next)             Pointer to the next Header in the list
    87         *  @field(queueType)        Identifies the type of queue and thus who owns
    88         *                           the read and write pointers.
    89         *  @field(readPtr)          Points to the next (word-aligned) byte to be
    90         *                           read from the buffer
    91         *  @field(writePtr)         Points to the next (word-aligned) byte to be
    92         *                           written into
    93         *  @field(queueStartAdrs)   Start address of the buffer (word-aligned)
    94         *  @field(queueSizeInMAUs)  Queue Size in min. addressable units
    95         *                           (buffer size must be word-aligned)
    96         *  @field(instanceId)       16b unique ID that identifies the instance of the module
    97         *                           that owns this queue descriptor.
    98         *                           b15=1 indicates that the logger was dynamically
    99         *                           created. Corresponds to the logger instance Id
   100         *                           in the rta.xml and uia.xml metadata and
   101         *                           UIAPacket event packet header.
   102         *  @field(ownerModuleId)    The module ID of the module that owns this
   103         *                           queue descriptor
   104         *  @field(priority)         The priority of the queue. 0 is normal priority.
   105         *                           The higher the number, the higher the priority.
   106         *                           Used to set the priority field of the UIAPacket
   107         *                           event packet header.
   108         *  @field(numDroppedCtrAdrs) Points to the counter used to count the number
   109         *                           of dropped events.  NULL if no counter available.
   110         */
   111        struct Header {
   112            Int structSize;
   113            Header *next;
   114            QueueType queueType;
   115            Bits32 *readPtr;
   116            Bits32 *writePtr;
   117            Bits32 *queueStartAdrs;
   118            SizeT queueSizeInMAUs;
   119            UInt instanceId;
   120            UInt ownerModuleId;
   121            UInt priority;
   122            Bits32 *numDroppedCtrAdrs;
   123        };
   124    
   125        /*!
   126         *  ======== addToList ========
   127         *  Function to add a descriptor to the global list.
   128         *
   129         *  @param(pHdrToAdd) Descriptor to add
   130         */
   131        @DirectCall
   132        Void addToList(QueueDescriptor.Header *pHdrToAdd);
   133    
   134        /*
   135         *  ======== generateInstanceId ========
   136         *  Returns a unique logger instance ID for use by a logger that
   137         *  implements the IUIATransfer interface.
   138         *
   139         *  Note that all Logger Instance Ids must be non-zero.
   140         *  LoggerInstanceIds with b15=1 are reserved for dynamically created
   141         *  instances of the logger.
   142         */
   143        metaonly UInt16 generateInstanceId();
   144    
   145        /*!
   146         *  ======== initHeader ========
   147         *  Function initialize a descriptor
   148         *
   149         *  @param(pHdr)  Descriptor to initialize
   150         *  @param(start) Start address of the buffer
   151         *  @param(size)  Size of the buffer
   152         *  @param(loggerModuleId) module ID of the logger that owns the buffer
   153         *  @param(loggerInstanceId) instance ID of the logger that owns the buffer
   154         *  @param(loggerPriority) priority of the logger that owns the buffer
   155         *  @param(type)  Type of descriptor
   156         */
   157        @DirectCall
   158        Void initHeader(QueueDescriptor.Header *pHdr, Ptr start,
   159                       SizeT size, UInt loggerModuleId, UInt loggerInstanceId,
   160                       UInt loggerPriority, QueueType type, Ptr pNumDroppedCtr);
   161    
   162        /*!
   163         *  ======== removeFromList ========
   164         *  Function to remove a descriptor from the global list.
   165         *
   166         *  @param(pHdrToRemove) Descriptor to remove
   167         */
   168        @DirectCall
   169        Void removeFromList(QueueDescriptor.Header *pHdrToRemove);
   170    
   171    internal:
   172        metaonly config Int maxId = 0;
   173    }