probe.hh revision 10460:20443473c68a
1/* 2 * Copyright (c) 2013 ARM Limited 3 * All rights reserved 4 * 5 * The license below extends only to copyright in the software and shall 6 * not be construed as granting a license to any other intellectual 7 * property including but not limited to intellectual property relating 8 * to a hardware implementation of the functionality of the software 9 * licensed hereunder. You may use the software subject to the license 10 * terms below provided that you ensure that this notice is replicated 11 * unmodified and in its entirety in all distributions of the software, 12 * modified or unmodified, in source code or in binary form. 13 * 14 * Redistribution and use in source and binary forms, with or without 15 * modification, are permitted provided that the following conditions are 16 * met: redistributions of source code must retain the above copyright 17 * notice, this list of conditions and the following disclaimer; 18 * redistributions in binary form must reproduce the above copyright 19 * notice, this list of conditions and the following disclaimer in the 20 * documentation and/or other materials provided with the distribution; 21 * neither the name of the copyright holders nor the names of its 22 * contributors may be used to endorse or promote products derived from 23 * this software without specific prior written permission. 24 * 25 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 26 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 27 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 28 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 29 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 30 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 31 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 32 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 33 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 34 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 35 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 36 * 37 * Authors: Matt Horsnell 38 */ 39 40/** 41 * @file This file describes the base components used for the probe system. 42 * There are currently 3 components: 43 * 44 * ProbePoint: an event probe point i.e. send a notify from the point 45 * at which an instruction was committed. 46 * 47 * ProbeListener: a listener provide a notify method that is called when 48 * a probe point event occurs. Multiple ProbeListeners 49 * can be added to each ProbePoint. 50 * 51 * ProbeListenerObject: a wrapper around a SimObject that can connect to another 52 * SimObject on which is will add ProbeListeners. 53 * 54 * ProbeManager: used to match up ProbeListeners and ProbePoints. 55 * At <b>simulation init</b> this is handled by regProbePoints 56 * followed by regProbeListeners being called on each 57 * SimObject in hierarchical ordering. 58 * ProbeListeners can be added/removed dynamically at runtime. 59 */ 60 61#ifndef __SIM_PROBE_PROBE_HH__ 62#define __SIM_PROBE_PROBE_HH__ 63 64#include <string> 65#include <vector> 66 67#include "base/trace.hh" 68#include "params/ProbeListenerObject.hh" 69#include "sim/sim_object.hh" 70 71/** Forward declare the ProbeManager. */ 72class ProbeManager; 73class ProbeListener; 74 75/** 76 * Name space containing shared probe point declarations. 77 * 78 * Probe types that are shared between multiple types of SimObjects 79 * should live in this name space. This makes it possible to use a 80 * common instrumentation interface for devices such as PMUs that have 81 * different implementations in different ISAs. 82 */ 83namespace ProbePoints { 84/* Note: This is only here for documentation purposes, new probe 85 * points should normally be declared in their own header files. See 86 * for example pmu.hh. 87 */ 88} 89 90/** 91 * This class is a minimal wrapper around SimObject. It is used to declare 92 * a python derived object that can be added as a ProbeListener to any other 93 * SimObject. 94 * 95 * It instantiates manager from a call to Parent.any. 96 * The vector of listeners is used simply to hold onto listeners until the 97 * ProbeListenerObject is destroyed. 98 */ 99class ProbeListenerObject : public SimObject 100{ 101 protected: 102 ProbeManager *manager; 103 std::vector<ProbeListener *> listeners; 104 105 public: 106 ProbeListenerObject(const ProbeListenerObjectParams *params); 107 virtual ~ProbeListenerObject(); 108 ProbeManager* getProbeManager() { return manager; } 109}; 110 111/** 112 * ProbeListener base class; here to simplify things like containers 113 * containing multiple types of ProbeListener. 114 * 115 * Note a ProbeListener is added to the ProbePoint in constructor by 116 * using the ProbeManager passed in. 117 */ 118class ProbeListener 119{ 120 public: 121 ProbeListener(ProbeManager *manager, const std::string &name); 122 virtual ~ProbeListener(); 123 124 protected: 125 ProbeManager *const manager; 126 const std::string name; 127}; 128 129/** 130 * ProbeListener base class; again used to simplify use of ProbePoints 131 * in containers and used as to define interface for adding removing 132 * listeners to the ProbePoint. 133 */ 134class ProbePoint 135{ 136 protected: 137 const std::string name; 138 public: 139 ProbePoint(ProbeManager *manager, const std::string &name); 140 virtual ~ProbePoint() {} 141 142 virtual void addListener(ProbeListener *listener) = 0; 143 virtual void removeListener(ProbeListener *listener) = 0; 144 std::string getName() const { return name; } 145}; 146 147/** 148 * ProbeManager is a conduit class that lives on each SimObject, 149 * and is used to match up probe listeners with probe points. 150 */ 151class ProbeManager 152{ 153 private: 154 /** Required for sensible debug messages.*/ 155 const M5_CLASS_VAR_USED SimObject *object; 156 /** Vector for name look-up. */ 157 std::vector<ProbePoint *> points; 158 159 public: 160 ProbeManager(SimObject *obj) 161 : object(obj) 162 {} 163 virtual ~ProbeManager() {} 164 165 /** 166 * @brief Add a ProbeListener to the ProbePoint named by pointName. 167 * If the name doesn't resolve a ProbePoint return false. 168 * @param pointName the name of the ProbePoint to add the ProbeListener to. 169 * @param listener the ProbeListener to add. 170 * @return true if added, false otherwise. 171 */ 172 bool addListener(std::string pointName, ProbeListener &listener); 173 174 /** 175 * @brief Remove a ProbeListener from the ProbePoint named by pointName. 176 * If the name doesn't resolve a ProbePoint return false. 177 * @param pointName the name of the ProbePoint to remove the ProbeListener 178 * from. 179 * @param listener the ProbeListener to remove. 180 * @return true if removed, false otherwise. 181 */ 182 bool removeListener(std::string pointName, ProbeListener &listener); 183 184 /** 185 * @brief Add a ProbePoint to this SimObject ProbeManager. 186 * @param point the ProbePoint to add. 187 */ 188 void addPoint(ProbePoint &point); 189}; 190 191/** 192 * ProbeListenerArgBase is used to define the base interface to a 193 * ProbeListenerArg (i.e the notify method on specific type). 194 * 195 * It is necessary to split this out from ProbeListenerArg, as that 196 * templates off the class containing the function that notify calls. 197 */ 198template <class Arg> 199class ProbeListenerArgBase : public ProbeListener 200{ 201 public: 202 ProbeListenerArgBase(ProbeManager *pm, const std::string &name) 203 : ProbeListener(pm, name) 204 {} 205 virtual void notify(const Arg &val) = 0; 206}; 207 208/** 209 * ProbeListenerArg generates a listener for the class of Arg and the 210 * class type T which is the class containing the function that notify will 211 * call. 212 * 213 * Note that the function is passed as a pointer on construction. 214 */ 215template <class T, class Arg> 216class ProbeListenerArg : public ProbeListenerArgBase<Arg> 217{ 218 private: 219 T *object; 220 void (T::* function)(const Arg &); 221 222 public: 223 /** 224 * @param obj the class of type Tcontaining the method to call on notify. 225 * @param name the name of the ProbePoint to add this listener to. 226 * @param func a pointer to the function on obj (called on notify). 227 */ 228 ProbeListenerArg(T *obj, const std::string &name, void (T::* func)(const Arg &)) 229 : ProbeListenerArgBase<Arg>(obj->getProbeManager(), name), 230 object(obj), 231 function(func) 232 {} 233 234 /** 235 * @brief called when the ProbePoint calls notify. This is a shim through to 236 * the function passed during construction. 237 * @param val the argument value to pass. 238 */ 239 virtual void notify(const Arg &val) { (object->*function)(val); } 240}; 241 242/** 243 * ProbePointArg generates a point for the class of Arg. As ProbePointArgs talk 244 * directly to ProbeListenerArgs of the same type, we can store the vector of 245 * ProbeListeners as their Arg type (and not as base type). 246 * 247 * Methods are provided to addListener, removeListener and notify. 248 */ 249template <typename Arg> 250class ProbePointArg : public ProbePoint 251{ 252 /** The attached listeners. */ 253 std::vector<ProbeListenerArgBase<Arg> *> listeners; 254 255 public: 256 ProbePointArg(ProbeManager *manager, std::string name) 257 : ProbePoint(manager, name) 258 { 259 } 260 261 /** 262 * @brief adds a ProbeListener to this ProbePoints notify list. 263 * @param l the ProbeListener to add to the notify list. 264 */ 265 void addListener(ProbeListener *l) 266 { 267 // check listener not already added 268 if (std::find(listeners.begin(), listeners.end(), l) == listeners.end()) { 269 listeners.push_back(static_cast<ProbeListenerArgBase<Arg> *>(l)); 270 } 271 } 272 273 /** 274 * @brief remove a ProbeListener from this ProbePoints notify list. 275 * @param l the ProbeListener to remove from the notify list. 276 */ 277 void removeListener(ProbeListener *l) 278 { 279 listeners.erase(std::remove(listeners.begin(), listeners.end(), l), 280 listeners.end()); 281 } 282 283 /** 284 * @brief called at the ProbePoint call site, passes arg to each listener. 285 * @param arg the argument to pass to each listener. 286 */ 287 void notify(const Arg &arg) 288 { 289 for (auto l = listeners.begin(); l != listeners.end(); ++l) { 290 (*l)->notify(arg); 291 } 292 } 293}; 294#endif//__SIM_PROBE_PROBE_HH__ 295