1    /*
     2     * Copyright (c) 2013, 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    import xdc.runtime.Types;
    63    import xdc.rov.ViewInfo;
    64    
    65    @CustomHeader
    66    module QueueDescriptor {
    67    
    68        /*!
    69         *  @_nodoc
    70         *  ======== ModuleView ========
    71         */
    72        metaonly struct ModuleView {
    73            Ptr mPtrToFirstDescriptor;
    74            UInt mUpdateCount;
    75            UInt16 is5555ifInitialized;
    76        }
    77    
    78        /*!
    79         *  @_nodoc
    80         *  ======== rovViewInfo ========
    81         */
    82        @Facet
    83        metaonly config ViewInfo.Instance rovViewInfo =
    84            ViewInfo.create({
    85                viewMap: [['Module', {type: ViewInfo.MODULE,
    86                                      viewInitFxn: 'viewInitModule',
    87                                      structName: 'ModuleView'}
    88                         ]]
    89            });
    90    
    91        /*!
    92         *  ======== QueueType ========
    93         *  Type of Queue
    94         */
    95        enum QueueType {
    96            QueueType_NONE = 0,
    97            QueueType_TOHOST_CMD_CIRCULAR_BUFFER = 1,
    98            QueueType_FROMHOST_CMD_CIRCULAR_BUFFER = 2,
    99            QueueType_TOHOST_EVENT_CIRCULAR_BUFFER = 3,
   100            QueueType_TOHOST_EVENT_OVERFLOW_BUFFER = 4,
   101            QueueType_TOHOST_DATA_CIRCULAR_BUFFER = 5,
   102            QueueType_FROMHOST_DATA_CIRCULAR_BUFFER = 6
   103        };
   104    
   105        /*!
   106         *  ======== Header ========
   107         *  Structure of the descriptor
   108         *
   109         *  @field(structSize)       Used for version control to determine if newer
   110         *                           fields are available
   111         *  @field(next)             Pointer to the next Header in the list
   112         *  @field(queueType)        Identifies the type of queue and thus who owns
   113         *                           the read and write pointers.
   114         *  @field(readPtr)          Points to the next (word-aligned) byte to be
   115         *                           read from the buffer
   116         *  @field(writePtr)         Points to the next (word-aligned) byte to be
   117         *                           written into
   118         *  @field(queueStartAdrs)   Start address of the buffer (word-aligned)
   119         *  @field(queueSizeInMAUs)  Queue Size in min. addressable units
   120         *                           (buffer size must be word-aligned)
   121         *  @field(instanceId)       16b unique ID that identifies the instance of the module
   122         *                           that owns this queue descriptor.
   123         *                           b15=1 indicates that the logger was dynamically
   124         *                           created. Corresponds to the logger instance Id
   125         *                           in the rta.xml and uia.xml metadata and
   126         *                           UIAPacket event packet header.
   127         *  @field(ownerModuleId)    The module ID of the module that owns this
   128         *                           queue descriptor
   129         *  @field(priority)         The priority of the queue. 0 is normal priority.
   130         *                           The higher the number, the higher the priority.
   131         *                           Used to set the priority field of the UIAPacket
   132         *                           event packet header.
   133         *  @field(numDroppedCtrAdrs) Points to the counter used to count the number
   134         *                           of dropped events.  NULL if no counter available.
   135         */
   136        struct Header {
   137            Int structSize;
   138            Header *next;
   139            QueueType queueType;
   140            Bits32 *readPtr;
   141            Bits32 *writePtr;
   142            Bits32 *queueStartAdrs;
   143            SizeT queueSizeInMAUs;
   144            UInt instanceId;
   145            UInt ownerModuleId;
   146            UInt priority;
   147            Bits32 *numDroppedCtrAdrs;
   148        };
   149    
   150        /*!
   151         *  ======== addToList ========
   152         *  Function to add a descriptor to the global list.
   153         *
   154         *  @param(pHdrToAdd) Descriptor to add
   155         */
   156        @DirectCall
   157        Void addToList(QueueDescriptor.Header *pHdrToAdd);
   158    
   159        /*
   160         *  ======== generateInstanceId ========
   161         *  Returns a unique logger instance ID for use by a logger that
   162         *  implements the IUIATransfer interface.
   163         *
   164         *  Note that all Logger Instance Ids must be non-zero.
   165         *  LoggerInstanceIds with b15=1 are reserved for dynamically created
   166         *  instances of the logger.
   167         */
   168        metaonly UInt16 generateInstanceId();
   169    
   170        /*!
   171         *  ======== initHeader ========
   172         *  Function initialize a descriptor
   173         *
   174         *  @param(pHdr)  Descriptor to initialize
   175         *  @param(start) Start address of the buffer
   176         *  @param(size)  Size of the buffer
   177         *  @param(loggerModuleId) module ID of the logger that owns the buffer
   178         *  @param(loggerInstanceId) instance ID of the logger that owns the buffer
   179         *  @param(loggerPriority) priority of the logger that owns the buffer
   180         *  @param(type)  Type of descriptor
   181         */
   182        @DirectCall
   183        Void initHeader(QueueDescriptor.Header *pHdr, Ptr start,
   184                       SizeT size, UInt loggerModuleId, UInt loggerInstanceId,
   185                       UInt loggerPriority, QueueType type, Ptr pNumDroppedCtr);
   186    
   187        /*!
   188         *  ======== removeFromList ========
   189         *  Function to remove a descriptor from the global list.
   190         *
   191         *  @param(pHdrToRemove) Descriptor to remove
   192         */
   193        @DirectCall
   194        Void removeFromList(QueueDescriptor.Header *pHdrToRemove);
   195    
   196    internal:
   197        metaonly config Int maxId = 0;
   198    
   199        struct Module_State {
   200            Ptr mPtrToFirstDescriptor;
   201            UInt mUpdateCount;
   202    
   203            /*
   204             *  Set to true after pointer to list of queue descriptors has been
   205             *  set.
   206             */
   207            UInt16 is5555ifInitialized;
   208        };
   209    }