/* --COPYRIGHT--,EPL
 *  Copyright (c) 2008 Texas Instruments and others.
 *  All rights reserved. This program and the accompanying materials
 *  are made available under the terms of the Eclipse Public License v1.0
 *  which accompanies this distribution, and is available at
 *  http://www.eclipse.org/legal/epl-v10.html
 * 
 *  Contributors:
 *      Texas Instruments - initial implementation
 * 
 * --/COPYRIGHT--
 */
/*
 *  ======== StructureDecoder.xdc ========
 */

package xdc.rov;

/*!
 *  ======== StructureDecoder ========
 *  Module for retrieving and decoding target structures.  
 *
 *  The StructureDecoder is responsible for decoding target data given the
 *  raw target bytes and the data's type as defined in XDC. It also contains
 *  APIs for retrieving data from the target given the data's address.
 *  
 *  The StructureDecoder relies on the TargetDecoder to decode the raw target 
 *  bytes, but is itself responsible for decoding the structure layout. The 
 *  decodeStruct API takes as an argument the structure's type representation
 *  in the XDC object model, and refers to this object to determine the size 
 *  and offsets of the structure's fields.
 *
 *  The object returned by decodeStruct is not the typed Java representation of
 *  the structure, but rather a typeless JavaScript object which simply
 *  contains all of the same fields. This allows ROV to control the type of the
 *  fields, and specifically to represent arrays as addresses rather than as
 *  objects.
 *
 *  All of the 'decode' methods are essentially private methods. The intended
 *  interface to the StructureDecoder is through the 'fetch' APIs.
 */
metaonly module StructureDecoder
{
    /*!
     *  ======== Buffer ========
     *  Target buffer
     *  
     *  This structure encapsulates a buffer of target memory (`buffer`), 
     *  the buffer's original target address (`addr`), and a running offset
     *  into that buffer (`off`). 
     *
     *  Decoding a structure is a recursive process, since the structure may
     *  include fields which are also structures. As `StructureDecoder` 
     *  decodes each field, it updates the `off` field to move to the next
     *  field.
     *
     *  The original address of the buffer is stored as well so that each
     *  structure field can be given a `$addr` property with its target 
     *  address.
     */
    metaonly struct Buffer {
        Any    buffer;
        Int    addr;
        Int    off;
    }

    /*!
     *  @_nodoc
     *  ======== FieldType ========
     *  Object representing the type of a field.
     *
     *  An object of this type is returned by the `{@link #parseTypeString}`
     *  method.
     * 
     *  A field can either be a scalar, a structure, or an array.
     */
    metaonly struct FieldType {
        /* Scalar */
        Bool    isScalarType;
        Bool    signed;
        Bool    isEnum;
        Bool    isEncoded;
        Int     size;
        Int     align;
        Bool    isAddr;
        String  fldType;
        
        /* Structure */
        Bool    isStrType;
        Any     strType;
        
        /* Array */
        Bool    isArrType;
        Int     len;
        String  elemType;
    }
    
instance:
    /*!
     *  ======== create ========
     *  Create a StructureDecoder instance
     *  
     *  The StructureDecoder requires a MemoryImage instance and the target
     *  configuration object from the ROV recap file; i.e.,
     *  recap.build.target.
     */
    create(Any mem, Any targConfig);
    
    /*!
     *  ======== fetchStruct ========
     *  Retrieve and decode a structure from the target
     *
     *  This method retrieves and decodes a structure of the given type at
     *  the given address from the target.
     *  @p(dlist)
     *     - `structType`
     *            Structure type. Not just a string, it is the XDC object
     *            model representation of the type.
     *     - `addr`
     *            Target address of the structure to retrieve.
     *     - `addrCheck`
     *            Whether to check the memory read against the section map.
     *  @p
     */
    Any fetchStruct(Any structType, Int addr, Bool addrCheck);
    
    /*!
     *  ======== fetchArray ========
     *  Retrieve and decode an array of structures from the target
     *
     *  @p(dlist)
     *     - `structType`
     *           Structure type. Not just a string, it is the XDC object 
     *           model representation of the type.
     *     - `addr`
     *           Target address of the structure to retrieve.
     *     - `len`
     *           Number of entries in the array.
     *     - `isScalar`
     *           Whether it is an array of scalars.
     *     - `addrCheck`
     *           Whether to check the memory read against the section map.
     *  @p
     */
    Any fetchArray(Any structType, Int addr, Int len, Bool isScalar, 
                   Bool addrCheck);
    
    /*!
     *  ======== decodeStruct ========
     *  Decode an entire structure by decoding each of the structure's fields
     *
     *  @p(dlist)
     *     - `structType`
     *           Structure type. Not just a string, it is the XDC object 
     *           model representation of the type.
     *     - `buffer`
     *           Buffer of target memory containing raw data.
     *     - `inStr`
     *           Optional structure to fill in. Otherwise decodeStruct will
     *           create a new one.
     *  @p
     */
    Any decodeStruct(Any structType, Buffer buffer, Any inStr = null);
    
    /*!
     *  ======== decodeStructArray ========
     *  Decode an array of structures
     *  
     *  This API exists to perform some optimizations when decoding an array
     *  of a single type of object.
     *
     *  @p(dlist)
     *     - `structType`
     *           Structure type of the elements in the array. Not just a 
     *           string, it is the XDC object model representation of the 
     *           type.
     *     - `buffer`
     *           Buffer of target memory containing raw data.
     *     - `len`
     *           Number of elements in the array.
     *  @p
     */
    Any decodeStructArray(Any structType, Buffer buffer, Int len);
    
    /*!
     *  @_nodoc
     *  ======== _parseTypeString ========
     *  Convert a type string to a FieldType
     *  
     *  This method interperets a type string from a $$sizes structure, and
     *  returns the interpretation in a FieldType object.
     */
    FieldType _parseTypeString(String fieldType);
    
    /*!
     *  @_nodoc
     *  ======== _decodeField ========
     *  Decodes a single field within a structure and returns its value.
     *  This API is only called by decodeStruct. It does not take an XDC type
     *  object but just a string representing the type of a single field within
     *  a structure.
     *
     *  @p(dlist)
     *      - `fieldType`
     *            Type info for the field.
     *      - `buffer`
     *            Buffer of target memory containing raw data.
     *  @p
     *
     *  TODO - This should be spec'd, but currently it can't because it will
     *  not properly return an Enum object.
     */
    //Any _decodeField(String fieldType, Buffer buffer);
    function _decodeField(fieldType, buffer);

    /*!
     *  @_nodoc
     *  ======== _decodeArray ========
     *  This API decodes an array of any type of elements given the elements' 
     *  type string.
     *
     *  decodeStructArray takes an XDC OM type object, while decodeArray takes
     *  a type string. decodeArray calls down to decodeStructArray if the 
     *  element type is a structure.
     *
     *  @p(dlist)
     *      - `elemType`
     *            Type info for the elements of the array.
     *      - `buffer`
     *            Buffer of target memory containing raw data.
     *      - `len`
     *            Number of elements in the array.
     *  @p
     */
    Any _decodeArray(String elemType, Buffer buffer, Int len);
    
    /*!
     *  @_nodoc
     *  ======== _decodeScalar ========
     *  Decodes a scalar value of 'type' at the offset specified in
     *  'buffer.off'.
     *
     *  @p(dlist)
     *      - `type`
     *            Type info for the scalar
     *      - `buffer`
     *            Buffer of target memory containing raw data.
     *  @p
     *
     *  TODO - This should be spec'd, but currently it can't because it will
     *  not properly return an Enum object.
     */
    //Any _decodeScalar(FieldType type, Buffer buffer);
    function _decodeScalar(type, buffer);
    
}