simrdi_registration_event.h

realview22.rar

/* Copyright (C) 2002 ARM Limited. All rights reserved.
 *
 * $Revision: 1.1.2.6.4.1 $
 * $Author: dsinclai $
 * $Date: 2003/04/30 13:46:37 $
 *
 * SimRdi_Manager mediates the interface between RealView Debugger
 * and the ARMulator target.  However mostly this interaction goes
 * through RDI, but we need a mechanism for components within
 * ARMulator to know that there is a SimRdi_Manager and to get
 * accesses to its interfaces.
 *
 * The procedure for doing this is that the SimRdi_Manager constructs
 * a SimRdiRegistrationProcVec.  This it then broadcasts to all the
 * modules in the target by calling
 * ARMulif_BroadcastSimRdiRegistration.  The procvec contains points
 * to more procvecs that have methods that allow SimRdi_Manager-aware
 * components to register themselves.
 *
 * On the other side, a component during its initialisation should
 * call ARMulif_InstallSimRdiRegistration that installs a listener to
 * capture the SimRdi_Manager's broadcast.
 *
 * The broadcasting and listening is done through
 * RDIInfo#RDIInfo_SimRdiRegistration, though by insulating the
 * mechanism by using the functions here, then other methods can be
 * used if they are found to be more appropriate.
 *
 * You should also be aware that multiple debuggers may request
 * connections so be prepared for them. */

#ifndef SIMRDI_REGISTRATION_EVENT_H
#define SIMRDI_REGISTRATION_EVENT_H

#include "toolconf.h"

#define SIMRDI_REGISTRATION_SIGNATURE ((uint32)(0xcafebabe))
/* signature is used to try and prevent anyone accidentally allocating
   the same info call without us detecting it.  Modules should not
   advertise any capabilities if they have discovered a conflicting
   event.  Mulitple info calls may be made from different debug
   controllers, etc. might be made so be prepared for them. */

/*
 * List of ProcVecs to put in the SimRdiRegistrationProcVec
 *
 */
typedef struct tag_simrdiprocvec        SimRdiProcVec;
typedef struct tag_uniregsregistration  UniregsRegistration;

/*
 * SimRdi_Manager provides some config flags that are interpreted
 * according to what is being advertised
 */
typedef uint32 SimRdi_Config_Flags;

/*
 * SimRdiRegistrationProcVec
 *
 * This is a a growable structure that contains some procvecs for
 * registering against.
 *
 * The number member should give the number of members in the procvec
 * after that one.  (Thus it is 2 if only simrdiprocvec and
 * uniregsprocvec are there).
 *
 * The signature need not be checked by the listener -- control will
 * only get to the listener if it has been checked.  However,
 * listeners should make sure they use 'number' to check that the
 * procvec they want is there, and should also check any version
 * information in the procvec to make sure they talk the right
 * version.
 *
 * The rendez_vous toolconf is to allow a generic mechanism for
 * passing unspecified data between objects.  It is labelled as a
 * 'minority interface' as heavily-used interfaces will be added to
 * the end of SimRdiRegistrationProcVec.  You may use this to
 * negotiate interfaces between different parts of your models, or
 * pass configuration information or provide experimental services,
 * etc.  rendez_vous will be NULL to start with so if you use it then
 * you must first see if it is NULL and initialise it if it is.  Note
 * that the toolconf in current implementations will never be
 * destroyed, however, its lifetime is guaranteed to be at least that
 * of the simulation (SimDisconnectTarget).
 *
 * To avoid conflict of names, then create an entry with some
 * identifier unique to your organisation and put all your entries in
 * that. (toolconf is a hierarchical database structure.) */
typedef struct tag_registrationprocvec {

  uint32 signature; /* == SIMRDI_REGISTRATION_SIGNATURE */

  toolconf                        rendez_vous;    /* minority-interface */

  unsigned number;  /* number of members following this one    */

  SimRdiProcVec*                  simrdiprocvec;  /* SimRdi_Manager-aware */
  UniregsRegistration*            uniregsprocvec; /* Uniregs-aware */

} SimRdiRegistrationProcVec;

/*
 * Listener functions should conform to this prototype.
 *
 * srpv is guaranteed to be non-NULL.
 */
typedef void SimRdiRegistrationListener( SimRdiRegistrationProcVec* srpv,
                                         void* handle );

/*
 * ARMulif_InstallSimRdiRegistration
 *
 * Use to install a listener.  Once installed, you cannot deinstall.
 * The return value is a pointer to a small amount of memory,
 * which should be freed on exit from ARMulator.
 */

void* ARMulif_InstallSimRdiRegistration( RDI_ModuleDesc* coredesc,
                                        SimRdiRegistrationListener* func,
                                        void* handle_to_pass_to_listener );

/*
 * ARMulif_BroadcastSimRdiRegistration
 *
 * Broadcasts the SimRdiRegistrationProcVec to all installed listeners.
 *
 * Guarantees that SimRdiRegistrationProcVec is only manipulated
 * through pointers -- so it will not be truncated if you add extra
 * members to it that we are not aware of, (though they must come
 * after all the other procvecs and they may collide with future
 * versions). */

void ARMulif_BroadcastSimRdiRegistration( RDI_AgentHandle agent,
                                          RDI_ProcVec*    agentprocvec,
                                          SimRdiRegistrationProcVec* srpv );

#endif /* SIMRDI_REGISTRATION_EVENT_H */