/* RDI Properties access
   Copyright (C) 2001 Free Software Foundation, Inc.


This file is part of GDB.


GDB is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2, or (at your option) any later
version.


GDB is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.


You should have received a copy of the GNU General Public License
along with GDB; see the file COPYING.  If not, write to the Free
Software Foundation, 59 Temple Place - Suite 330, Boston, MA
02111-1307, USA.  */

/* -*-C-*-
 *
 * $Revision: 1.4 $
 *   $Author: aberent $
 *     $Date: 2000/01/10 16:19:26 $
 */

#ifndef rdi_prop_h
#define rdi_prop_h

/*
 * RDI Properties - target specific properties, controlled over RDI
 *
 * RDI Properties are new in RDI 1.51
 */

/*
 * Typedef: RDIProperty_GroupDesc
 * Purpose: Each module (processor or agent) can have a separate set or
 *          groups associated with it.  Each set of groups can be arranged as
 *          a non cyclic tree.
 */
typedef struct RDIProperty_GroupDesc {
  unsigned id;              /* ID must be unique over all groups in a module */
  char name[60];            /* Brief name of the group */
  char description[128];    /* Slightly longer description of group */
  int numProperties;        /* number of properties in this group */
  int numSubGroups;         /* number of subgroups in this group */
} RDIProperty_GroupDesc;

/*
 * Certain group IDs are pre-defined (and used by the debug controller to
 * extract further group IDs)
 */
#define RDIPropertyGroup_SuperGroup 0
#define RDIPropertyGroup_TopLevelGroup 1

/*
 * Typedef: RDIProperty_DisplayType
 * Purpose: These are display oriented types, which allow a GUI debugger to
 *          display suitable properties in a user friendly GUI way.  A
 *          debug controller can always ignore this and just display as the
 *          fundamental type instead.
 *
 * RDIProprty_PDT_Standard: no special GUI method can be used for this property
 *                          RDIProperty_GetPropertyDisplayDetails returns no
 *                          data, and the value RDIError_NoError.
 *
 * No other cases are defined yet.

 */
typedef enum RDIProperty_DisplayType
{
  RDIProperty_PDT_Standard = 0     /* No special display options possible */
} RDIProperty_DisplayType;


/* Property description structure
 *
 * Note that a property can be treated, as either numeric or a string or
 * even both! (Both is intended as a useful feature not just an oddity, eg.
 * for a variable which holds the type of a Cache (I or D), both numeric
 * (0, 1) and string ("I-Cache", "D-Cache") may be appropriate.  If a
 * variable advertises the capability of both string and numerical visibility,
 * the debug controller should by default use the string view if it is able to.
 *
 * This property description contains an ID which both uniquely identifies
 * a property, and distinguishes between "RDI defined" (or standard) 
 * and "RDI extension" (or non-standard) properties, as defined below:
 *
 * RDI defined properties are these are ones which
 * need to be understood by a debug controller eg. the command line
 * property needs to be understood by a debug controller (whereas most
 * properties mean nothing to the debug controller, (only to the debug agent
 * and user).
 *
 * RDI extension properties have the top bit set, and are intended for use
 * by 3rd parties to add new properties without having to
 * refer to ARM to do so.  Should one of these ever need to be known
 * about by a debug controller then the 3rd party should contact ARM and get
 * an RDI property allocated, since only then is it certain that a
 * debugger which uses that id will always be referring to the
 * intended property (rather than something another third party
 * has added).
 *
 * Note also that the id of a property must be unique for the module
 * handle.  The property names must also be unique within a group.
 * An implication of this is that in order for a debugger to be able
 * to use the "flat" list of properties provided when asking for all
 * the properites in the supergroup, the Debug Agent should ensure
 * that all property names in the "supergroup" are unique, which could
 * mean pre / post fixing to some of the names which would otherwise
 * have been identical.
 */
typedef struct RDIProperty_Desc
{
  char name[60];          /* The name of the property - no spaces in name */
  char description[128];  /* A short description of the variable's function */
  unsigned32 id;          /* The id of a property is used to identify that
                           * property when setting / getting its value etc.
                           * The property id is a 32 bit unsigned integer
                           * which is split as follows:
                           * id[31] = 0 for RDI defined properies - see above
                           *        = 1 for extension properties - see above
                           * id[30:16] = 0  (currently reserved)
                           * id[15:0] = identifer for this property.  For
                           *            standard properties this value is
                           *            defined by the RDI; for non-standard
                           *            properties it may be any unique value
                           *            for that module handle.
                           */

  bool asString;          /* Can this property be treated as a string ? */
  unsigned maxLen;        /* if asString==1 then the maximum number of
                           * characters the property value may be set to
                           */
  bool asNumeric;         /* Can this property be treated as a numeric ? */
  bool isSigned;          /* if asNumeric==1 whether it is a signed numeric */
  unsigned width;         /* if asNumeric==1 the width in bits of the value
                           * Note that not all debug agents or debug hosts
                           * will be able to cope with all values.  For
                           * standard numeric properties use width=32
                           */
  unsigned readOnly;      /* 0 => read / write, otherwise read only */
  bool monotonicIncreasing;
                          /* 1 => This property is a monotonically
                           * increasing numerical value, and so it
                           * displaying differences between consecutive
                           * reads is useful - eg. time, cycle counts
                           */
  bool traceable;         /* 1 => This property is "traceable" in that it
                           * is useful to display consecutive values of it
                           * next to each other to produce a trace of values.
                           */

  RDIProperty_DisplayType display;
                          /* Display type for this property */
} RDIProperty_Desc;


/*
 * Function: RDI_InfoProc(mh, RDIInfo_Property, arg1, arg2)
 *
 *  Version: RDI 1.51
 *
 *  Purpose: Inquire whether RDI properties are supported by this target
 *
 *           This must be called before any other Property related info
 *           calls are made, and they will only be supported if this returns
 *           RDIError_NoError.
 *
 *  Returns: RDIError_NoError               Properties supported
 *           RDIError_UnimplementedMessage  Properties not supported
 */
#define RDIInfo_Properties 0x700 /* Sanity check - duplicated in rdi_info.h */

/*
 * Function: RDI_InfoProc(mh, RDIProperty_RequestGroups, arg1, arg2)
 *
 *  Version: RDI 1.51
 *
 *  Purpose: Called to get the group descriptions of groups within the
 *           specified group.  The data returned also gives how many properties
 *           and groups are in the requested groups (so that further calls can
 *           be made and buffers of the appropriate sizes passed in.
 *
 *  Params:
 *      Input:  mh     handle identifies the debug agent / processor
 *
 *      Input:  type   RDIProperty_RequestGroups
 *
 *      Input:  arg1   unsigned groupId
 *
 *                     If groupId == RDIPropertyGroup_SuperGroup:
 *                       This is a request for information about the 
 *                       "supergroup", a group which contains ALL properties
 *                       for this module.  It always exists.  Only one
 *                       RDIProperty_GroupDesc is written to in this case.  On
 *                       return this will contain the total number of
 *                       properties for this module.  Additionally, it will
 *                       contain the number of groups there are in the top
 *                       level group (RDIPropertyGroup_TopLevelGroup) for this
 *                       module.
 *
 *                     If groupId == RDIPropertyGroup_TopLevelGroup:
 *                       This is a request for information about the groups
 *                       contained in the top level.  The number of group
 *                       descriptions written to will be the number of groups
 *                       returned when this call was made with a groupId of
 *                       RDIPropertyGroup_SuperGroup.  No properties are
 *                       permitted in the top level group.
 *
 *                     If groupId == something else:
 *                       This is a request for the list of group
 *                       descriptions for the groups which are a subset of the
 *                       specified groupId.  The number of groups which will
 *                       be returned will already be known (from a previous
 *                       call to this fucntion).
 *
 *     In/Out:  arg2   RDIProperty_GroupDesc *descs
 *                     This is a buffer provided by the caller, which is large
 *                     enough to have a number of group descriptions filled
 *                     in, as determined  by the value of groupId and previous
 *                     calls.
 *
 *  Returns:
 *      OK:     RDIError_NoError
 *      OK:     RDIError_UnimplementedMessage - not understood
 *      Error:  RDIError_NoSuchHandle         - bad group id passed in
 */
#define RDIProperty_RequestGroups 0x701


/*
 * Function: RDI_InfoProc(mh, RDIProperty_RequestDescriptions, arg1, arg2)
 *
 *  Version: RDI 1.51
 *
 *  Purpose: Called to find out what RDI properties there are for this
 *           Processor / Debug Agent in the specified group.
 *
 *           Typically RDIProperty_RequestGroups would be called first
 *           to find out how many properties are in this group so that
 *           a buffer of sufficient size can be passed in.
 *
 *  Params:
 *      Input:  mh     handle identifies debug agent / processor for this
 *                     request.
 *
 *      Input:  type   RDIProperty_RequestDescriptions