1    /* 
     2     *  Copyright (c) 2008 Texas Instruments and others.
     3     *  All rights reserved. This program and the accompanying materials
     4     *  are made available under the terms of the Eclipse Public License v1.0
     5     *  which accompanies this distribution, and is available at
     6     *  http://www.eclipse.org/legal/epl-v10.html
     7     * 
     8     *  Contributors:
     9     *      Texas Instruments - initial implementation
    10     * 
    11     * 
    12     */
    13    /*
    14     *  ======== StructureDecoder.xdc ========
    15     */
    16    
    17    package xdc.rov;
    18    
    19    /*!
    20     *  ======== StructureDecoder ========
    21     *  Module for retrieving and decoding target structures.  
    22     *
    23     *  The StructureDecoder is responsible for decoding target data given the
    24     *  raw target bytes and the data's type as defined in XDC. It also contains
    25     *  APIs for retrieving data from the target given the data's address.
    26     *  
    27     *  The StructureDecoder relies on the TargetDecoder to decode the raw target 
    28     *  bytes, but is itself responsible for decoding the structure layout. The 
    29     *  decodeStruct API takes as an argument the structure's type representation
    30     *  in the XDC object model, and refers to this object to determine the size 
    31     *  and offsets of the structure's fields.
    32     *
    33     *  The object returned by decodeStruct is not the typed Java representation of
    34     *  the structure, but rather a typeless JavaScript object which simply
    35     *  contains all of the same fields. This allows ROV to control the type of the
    36     *  fields, and specifically to represent arrays as addresses rather than as
    37     *  objects.
    38     *
    39     *  All of the 'decode' methods are essentially private methods. The intended
    40     *  interface to the StructureDecoder is through the 'fetch' APIs.
    41     */
    42    metaonly module StructureDecoder
    43    {
    44        /*!
    45         *  ======== Buffer ========
    46         *  Target buffer
    47         *  
    48         *  This structure encapsulates a buffer of target memory (`buffer`), 
    49         *  the buffer's original target address (`addr`), and a running offset
    50         *  into that buffer (`off`). 
    51         *
    52         *  Decoding a structure is a recursive process, since the structure may
    53         *  include fields which are also structures. As `StructureDecoder` 
    54         *  decodes each field, it updates the `off` field to move to the next
    55         *  field.
    56         *
    57         *  The original address of the buffer is stored as well so that each
    58         *  structure field can be given a `$addr` property with its target 
    59         *  address.
    60         */
    61        metaonly struct Buffer {
    62            Any    buffer;
    63            Int    addr;
    64            Int    off;
    65        }
    66    
    67        /*!
    68         *  @_nodoc
    69         *  ======== FieldType ========
    70         *  Object representing the type of a field.
    71         *
    72         *  An object of this type is returned by the `{@link #parseTypeString}`
    73         *  method.
    74         * 
    75         *  A field can either be a scalar, a structure, or an array.
    76         */
    77        metaonly struct FieldType {
    78            /* Scalar */
    79            Bool    isScalarType;
    80            Bool    signed;
    81            Bool    isEnum;
    82            Bool    isEncoded;
    83            Int     size;
    84            Int     align;
    85            Bool    isAddr;
    86            String  fldType;
    87            
    88            /* Structure */
    89            Bool    isStrType;
    90            Any     strType;
    91            
    92            /* Array */
    93            Bool    isArrType;
    94            Int     len;
    95            String  elemType;
    96        }
    97        
    98    instance:
    99        /*!
   100         *  ======== create ========
   101         *  Create a StructureDecoder instance
   102         *  
   103         *  The StructureDecoder requires a MemoryImage instance and the target
   104         *  configuration object from the ROV recap file; i.e.,
   105         *  recap.build.target.
   106         */
   107        create(Any mem, Any targConfig);
   108        
   109        /*!
   110         *  ======== fetchStruct ========
   111         *  Retrieve and decode a structure from the target
   112         *
   113         *  This method retrieves and decodes a structure of the given type at
   114         *  the given address from the target.
   115         *  @p(dlist)
   116         *     - `structType`
   117         *            Structure type. Not just a string, it is the XDC object
   118         *            model representation of the type.
   119         *     - `addr`
   120         *            Target address of the structure to retrieve.
   121         *     - `addrCheck`
   122         *            Whether to check the memory read against the section map.
   123         *  @p
   124         */
   125        Any fetchStruct(Any structType, Int addr, Bool addrCheck);
   126        
   127        /*!
   128         *  ======== fetchArray ========
   129         *  Retrieve and decode an array of structures from the target
   130         *
   131         *  @p(dlist)
   132         *     - `structType`
   133         *           Structure type. Not just a string, it is the XDC object 
   134         *           model representation of the type.
   135         *     - `addr`
   136         *           Target address of the structure to retrieve.
   137         *     - `len`
   138         *           Number of entries in the array.
   139         *     - `isScalar`
   140         *           Whether it is an array of scalars.
   141         *     - `addrCheck`
   142         *           Whether to check the memory read against the section map.
   143         *  @p
   144         */
   145        Any fetchArray(Any structType, Int addr, Int len, Bool isScalar, 
   146                       Bool addrCheck);
   147        
   148        /*!
   149         *  ======== decodeStruct ========
   150         *  Decode an entire structure by decoding each of the structure's fields
   151         *
   152         *  @p(dlist)
   153         *     - `structType`
   154         *           Structure type. Not just a string, it is the XDC object 
   155         *           model representation of the type.
   156         *     - `buffer`
   157         *           Buffer of target memory containing raw data.
   158         *     - `inStr`
   159         *           Optional structure to fill in. Otherwise decodeStruct will
   160         *           create a new one.
   161         *  @p
   162         */
   163        Any decodeStruct(Any structType, Buffer buffer, Any inStr = null);
   164        
   165        /*!
   166         *  ======== decodeStructArray ========
   167         *  Decode an array of structures
   168         *  
   169         *  This API exists to perform some optimizations when decoding an array
   170         *  of a single type of object.
   171         *
   172         *  @p(dlist)
   173         *     - `structType`
   174         *           Structure type of the elements in the array. Not just a 
   175         *           string, it is the XDC object model representation of the 
   176         *           type.
   177         *     - `buffer`
   178         *           Buffer of target memory containing raw data.
   179         *     - `len`
   180         *           Number of elements in the array.
   181         *  @p
   182         */
   183        Any decodeStructArray(Any structType, Buffer buffer, Int len);
   184        
   185        /*!
   186         *  @_nodoc
   187         *  ======== _parseTypeString ========
   188         *  Convert a type string to a FieldType
   189         *  
   190         *  This method interperets a type string from a $$sizes structure, and
   191         *  returns the interpretation in a FieldType object.
   192         */
   193        FieldType _parseTypeString(String fieldType);
   194        
   195        /*!
   196         *  @_nodoc
   197         *  ======== _decodeField ========
   198         *  Decodes a single field within a structure and returns its value.
   199         *  This API is only called by decodeStruct. It does not take an XDC type
   200         *  object but just a string representing the type of a single field within
   201         *  a structure.
   202         *
   203         *  @p(dlist)
   204         *      - `fieldType`
   205         *            Type info for the field.
   206         *      - `buffer`
   207         *            Buffer of target memory containing raw data.
   208         *  @p
   209         *
   210         *  TODO - This should be spec'd, but currently it can't because it will
   211         *  not properly return an Enum object.
   212         */
   213        //Any _decodeField(String fieldType, Buffer buffer);
   214        function _decodeField(fieldType, buffer);
   215    
   216        /*!
   217         *  @_nodoc
   218         *  ======== _decodeArray ========
   219         *  This API decodes an array of any type of elements given the elements' 
   220         *  type string.
   221         *
   222         *  decodeStructArray takes an XDC OM type object, while decodeArray takes
   223         *  a type string. decodeArray calls down to decodeStructArray if the 
   224         *  element type is a structure.
   225         *
   226         *  @p(dlist)
   227         *      - `elemType`
   228         *            Type info for the elements of the array.
   229         *      - `buffer`
   230         *            Buffer of target memory containing raw data.
   231         *      - `len`
   232         *            Number of elements in the array.
   233         *  @p
   234         */
   235        Any _decodeArray(String elemType, Buffer buffer, Int len);
   236        
   237        /*!
   238         *  @_nodoc
   239         *  ======== _decodeScalar ========
   240         *  Decodes a scalar value of 'type' at the offset specified in
   241         *  'buffer.off'.
   242         *
   243         *  @p(dlist)
   244         *      - `type`
   245         *            Type info for the scalar
   246         *      - `buffer`
   247         *            Buffer of target memory containing raw data.
   248         *  @p
   249         *
   250         *  TODO - This should be spec'd, but currently it can't because it will
   251         *  not properly return an Enum object.
   252         */
   253        //Any _decodeScalar(FieldType type, Buffer buffer);
   254        function _decodeScalar(type, buffer);
   255        
   256    }
   257    /*
   258     *  @(#) xdc.rov; 1, 0, 1,0; 2-20-2019 10:22:32; /db/ztree/library/trees/xdc/xdc-F09/src/packages/
   259     */
   260