uniregs_registration_event.h

realview22.rar

/*
 * Copyright (C) ARM Ltd. 2002. All rights reserved.
 *
 * $Revision: 1.1.2.10.4.2 $
 * $Author: dsinclai $
 * $Date: 2003/07/07 15:46:12 $
 *
 * Uniregs are explained in DS024-GENC-001255 (RV-msg ARM extensions),
 * they are standard numbers for ARM core and coprocessor registers.
 * 
 * ARMulator allows extra registers to be added by models as
 * pseudo-uniregs numbers.  True uniregs numbers are 16 bits long, the
 * top 5 bits are the block number and the bottom 11 the register
 * within the block number.  ARMulator extends this by allowing
 * register numbers to be 32 bits long, however, only block numbers 32
 * to 64 are reserved for ARMulator and it's models' use.
 *
 * NOTE: the methods in this file are useful only if you are
 * implementing a standard ARM coprocessor, if you want to add new
 * simulator-defined registers then you need mini_simrdi_manager.h.
 *
 * UniregsRegistration
 *
 * Allows coprocessors, etc. to register with a debug controller and
 * give it pointers to functions that understand the uniregs register
 * numbers.  The unireg is a 16 bit quantity (top 16 bits are
 * reservered and should be zero).  A uniregs handler for a standard
 * block number (0--31) should normally to ignore all but the bottom
 * 11 bits.
 *
 * A uniregs handler should return non-zero if it can't handle
 * the unireg passed to it.  The uniregs handler will chain through
 * handlers for that block until it finds an appropriate one.  For
 * this reason, if a large number of handlers register for a block
 * then some other mechanism should be used to handle those uniregs.
 *
 * Coprocessors offering more complex debug options would probably
 * want access to the SimRdi_Manager and should advertise their
 * capabilities directly to the SimRdi_Manager.
 *
 * An object that uses the UniregsRegistration object should use its
 * version information to ensure that it doesn't try passing it an
 * advert that it wouldn't understand.
 *
 * The advert is converted by uniregs_advertise_proxy in
 * SimRdi_Manager into a proper uniregs advert.
 *
 * The use of config_flags is not specified at the moment.  It could
 * be a bit field or it could simply be a number.  It is up to the
 * uniregs that register for a particular block to cooperate and
 * intepret it consistently.  As always, the SimRdi_Manager will
 * arrange to make available the bitwise OR of config_flags for each
 * block (0--31) in the SimRdiProcVec.  */

#ifndef UNIREGS_REGISTRATION_EVENT_H
#define UNIREGS_REGISTRATION_EVENT_H

#include "simrdi_registration_event.h"


/*
 * Uniregs debug access functions
 *
 * Debug access functions should obey the following prototypes.
 *
 * These access functions are for standard uniregs access.  Registers
 * added by the simulator should use SimRdi_Uniregs_Advert in
 * mini_simrdi_manager.h which provides a superset of the
 * functionality of this advert.
 *
 * Unlike the non-standard uniregs (simulator added ones) the unireg
 * is the standard unireg number and has not been mangled.
 *
 * Chunk is currently unused.  If you are exporting doubles then you
 * will be called with a 64 bit location in pvalue to write to.
 *
 * (Simulator-added registers, NOT uniregs, are limited to 4 bytes).
 *
 * Return 0 on no error.  It is currently unclear what error messages
 * are useful.  So for the moment stick to 1 for an error. */
typedef uint32 DebugRead ( void *voidstate, uint32 unireg, unsigned chunk, ARMword *pvalue );
typedef uint32 DebugWrite( void *voidstate, uint32 unireg, unsigned chunk, ARMword *pvalue );

/*
 * Uniregs_Advert
 *
 * This is the advert that gets passed to simrdi_manager_proxy in
 * SimRdi_Manager.  A full uniregs advert is then constructed based on
 * the information in it.
 *
 * Name and description fields are meant to be a short and long
 * descriptor for the uniregs done by this block.  Note that some
 * copros (CP15) extends over two blocks and will advertise twice,
 * possibly with the same name/description.
 *
 * 'coredesc' is provided for, in the future, multiple processors to
 * be distinguished.  If there is a 'natural' association between the
 * uniregs handler and a core then this should be it, otherwise it
 * should be NULL.
 *
 * 'me' is provided to allow SDM modules that provide a uniregs
 * interface to be distinguished and SimRdi_Manager would not try to
 * automatically generate a uniregs description for them. (Currently
 * SimRdi_Manager completely ignores SDM modules.)  Currently what to
 * put in this member is unclear.  It can't be the module handle that
 * SDM will return as we don't know it.  We also don't know what name
 * the SDM description will have.  This issue is currently unresolved
 * and this member should be NULL.
 *
 * Unregs only defines the first 32 blocks, future expansion will grow
 * into this space.
 *
 * Note the difference to the rest of SimRdi_Manager, the uniregs
 * handler creates the advert then advertises it, the
 * uniregs_advertise_proxy then asks SimRdi_Manager for a
 * SimRdi_Uniregs_Advert, fills it it from the Uniregs_Advert and
 * advertises that.  Thus a uniregs handler using the Uniregs_Advert
 * mechanism creates and initialises (for example) and auto
 * Uniregs_Advert to pass to the advertise method in
 * UniregsRegistration (which will usually be pointing to the
 * uniregs_advertise_proxy). */

#define UNIREGS_REGISTRATION_SIGNATURE ((uint32)0x38d9ea25)

typedef struct tag_uniregs_advert {
  /* to be filled out by the uniregs provider */
  
  const char* name;
  const char* description;

  RDI_ModuleDesc* coredesc; /* for a coprocessor this will be the core
                               it is attached to, this will be needed
                               to be provided if you are on a
                               multi-core system */
  void* sdm_me;             /* set to NULL */

  uint32          block_num;
  /* 0-31 are the block numbers in the uniregs scheme.  Coprocessor 0
     is in block 16, Coprocessor 14 is in block 30. Coprocessor 15 is
     in block 31 with an extension space in Coprocessor 15 that should
     be registered separately.  Other block numbers are defined in the
     enum Uniregs_Block_Numbers */

  void*           voidstate;
  /* state given to 'read' and 'write' */

  SimRdi_Config_Flags    config_flags;
  /* different blocks can interpret this differently. You should
     describe at the end of this file the interpretation chosen for
     the block. */

  DebugRead*  read;
  DebugWrite* write;

} Uniregs_Advert; /* note that this gets converted to a
                     SimRdi_Uniregs_Advert by
                     uniregs_advertise_proxy */

/*
 * Uniregs block number
 *
 * Standard uniregs block numbers are 0--31, above this are
 * simulator-added ones.  Some of the block numbers have special
 * meaning for negotiating things like cycle counters. */

#define NUMBER_OF_UNIREGS_BLOCKS 64

enum Uniregs_Block_Numbers {
  uniregs_core_registers = 0,
  uniregs_mcrr_mrrc_extension_space_0_7  = 1,
  uniregs_mcrr_mrrc_extension_space_8_15 = 2,
  uniregs_cp15_extended_register_space   = 15,
  uniregs_cp0 = 16,
  uniregs_cp1 = 17,
  uniregs_cp2 = 18,
  uniregs_cp3 = 19,
  uniregs_cp4 = 20,
  uniregs_cp5 = 21,
  uniregs_cp6 = 22,
  uniregs_cp7 = 23,
  uniregs_cp8 = 24,
  uniregs_cp9 = 25,
  uniregs_cp10 = 26,
  uniregs_cp11 = 27,
  uniregs_cp12 = 28,
  uniregs_cp13 = 29,
  uniregs_cp14 = 30,
  uniregs_cp15 = 31,

  /*
   * Simulator-added registers (non-standard uniregs)
   *
   * These registers are not known about in the TABS (part of RVD) and
   * so the only information that the debugger will know about these
   * registers is the information you give it.
   *
   * To define these registers you will need to use
   * mini_simrdi_manager.h and use a SimRdi_Uniregs_Advert.
   *
   * Which of these blocks are exported to the debugger is given in
   * SimRdiProcVec by an array of block numbers (member
   * blocks_to_export).  It is possible for a module to modify this
   * list but generally it is discouraged as it may become a
   * configuration option.
   *
   * Note also that also the sorting of the registers also occurs and
   * that if an advert says that it is definitive then adverts after
   * it in the chain will *not* be exported to the debugger.  This is
   * a partial solution to cope with more than one things advertising
   * a particular variable and having the same name (see notes on
   * cycle counters later) */

  /* this block is reserved */
  uniregs_armulator = 32,

  /* useful registers for the user to have access to can be put in
     this block. */
  uniregs_general_regs_export = 33,

  /* model debugging registers -- useful for developers of models, but
     in general not useful to the end user.  SimRdi_Manager reserves
     the right not to export this block. */
  uniregs_model_debugging_registers = 34,
     
  /* a special block reserved for cycle counters.
   * Mapfile can add regions to this.
   */
  uniregs_cycle_counter = 35,

  /* peripherals section -- if you have memory-mapped
     peripherals that you want to display put them here.  These are if
     they belong to a single core */
  uniregs_peripherals = 36,

  /* peripherals section -- if a peripheral is shared between many
     cores then put it here */
  uniregs_shared_peripherals = 37,

  /* buses -- if you have special registers relating to busses then
     put them here, however, if they are cycle counters relating to
     one core only then put them in the cycle_counter block */
  uniregs_shared_buses = 38,
     
  /* extensions -- those modules that are not considered 'peripherals'
     can put their registers here */
  uniregs_extensions = 39,
  uniregs_shared_extensions = 40,