probe.hh revision 10023
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 * This class is a minimal wrapper around SimObject. It is used to declare 77 * a python derived object that can be added as a ProbeListener to any other 78 * SimObject. 79 * 80 * It instantiates manager from a call to Parent.any. 81 * The vector of listeners is used simply to hold onto listeners until the 82 * ProbeListenerObject is destroyed. 83 */ 84class ProbeListenerObject : public SimObject 85{ 86 protected: 87 ProbeManager *manager; 88 std::vector<ProbeListener *> listeners; 89 90 public: 91 ProbeListenerObject(const ProbeListenerObjectParams *params); 92 virtual ~ProbeListenerObject(); 93 ProbeManager* getProbeManager() { return manager; } 94}; 95 96/** 97 * ProbeListener base class; here to simplify things like containers 98 * containing multiple types of ProbeListener. 99 * 100 * Note a ProbeListener is added to the ProbePoint in constructor by 101 * using the ProbeManager passed in. 102 */ 103class ProbeListener 104{ 105 public: 106 ProbeListener(ProbeManager *manager, const std::string &name); 107 virtual ~ProbeListener() {} 108}; 109 110/** 111 * ProbeListener base class; again used to simplify use of ProbePoints 112 * in containers and used as to define interface for adding removing 113 * listeners to the ProbePoint. 114 */ 115class ProbePoint 116{ 117 protected: 118 const std::string name; 119 public: 120 ProbePoint(ProbeManager *manager, const std::string &name); 121 virtual ~ProbePoint() {} 122 123 virtual void addListener(ProbeListener *listener) = 0; 124 virtual void removeListener(ProbeListener *listener) = 0; 125 std::string getName() const { return name; } 126}; 127 128/** 129 * ProbeManager is a conduit class that lives on each SimObject, 130 * and is used to match up probe listeners with probe points. 131 */ 132class ProbeManager 133{ 134 private: 135 /** Required for sensible debug messages.*/ 136 const SimObject *object; 137 /** Vector for name look-up. */ 138 std::vector<ProbePoint *> points; 139 140 public: 141 ProbeManager(SimObject *obj) 142 : object(obj) 143 {} 144 virtual ~ProbeManager() {} 145 146 /** 147 * @brief Add a ProbeListener to the ProbePoint named by pointName. 148 * If the name doesn't resolve a ProbePoint return false. 149 * @param pointName the name of the ProbePoint to add the ProbeListener to. 150 * @param listener the ProbeListener to add. 151 * @return true if added, false otherwise. 152 */ 153 bool addListener(std::string pointName, ProbeListener &listener); 154 155 /** 156 * @brief Remove a ProbeListener from the ProbePoint named by pointName. 157 * If the name doesn't resolve a ProbePoint return false. 158 * @param pointName the name of the ProbePoint to remove the ProbeListener 159 * from. 160 * @param listener the ProbeListener to remove. 161 * @return true if removed, false otherwise. 162 */ 163 bool removeListener(std::string pointName, ProbeListener &listener); 164 165 /** 166 * @brief Add a ProbePoint to this SimObject ProbeManager. 167 * @param point the ProbePoint to add. 168 */ 169 void addPoint(ProbePoint &point); 170}; 171 172/** 173 * ProbeListenerArgBase is used to define the base interface to a 174 * ProbeListenerArg (i.e the notify method on specific type). 175 * 176 * It is necessary to split this out from ProbeListenerArg, as that 177 * templates off the class containing the function that notify calls. 178 */ 179template <class Arg> 180class ProbeListenerArgBase : public ProbeListener 181{ 182 public: 183 ProbeListenerArgBase(ProbeManager *pm, const std::string &name) 184 : ProbeListener(pm, name) 185 {} 186 virtual void notify(const Arg &val) = 0; 187}; 188 189/** 190 * ProbeListenerArg generates a listener for the class of Arg and the 191 * class type T which is the class containing the function that notify will 192 * call. 193 * 194 * Note that the function is passed as a pointer on construction. 195 */ 196template <class T, class Arg> 197class ProbeListenerArg : public ProbeListenerArgBase<Arg> 198{ 199 private: 200 T *object; 201 void (T::* function)(const Arg &); 202 203 public: 204 /** 205 * @param obj the class of type Tcontaining the method to call on notify. 206 * @param name the name of the ProbePoint to add this listener to. 207 * @param func a pointer to the function on obj (called on notify). 208 */ 209 ProbeListenerArg(T *obj, const std::string &name, void (T::* func)(const Arg &)) 210 : ProbeListenerArgBase<Arg>(obj->getProbeManager(), name), 211 object(obj), 212 function(func) 213 {} 214 215 /** 216 * @brief called when the ProbePoint calls notify. This is a shim through to 217 * the function passed during construction. 218 * @param val the argument value to pass. 219 */ 220 virtual void notify(const Arg &val) { (object->*function)(val); } 221}; 222 223/** 224 * ProbePointArg generates a point for the class of Arg. As ProbePointArgs talk 225 * directly to ProbeListenerArgs of the same type, we can store the vector of 226 * ProbeListeners as their Arg type (and not as base type). 227 * 228 * Methods are provided to addListener, removeListener and notify. 229 */ 230template <typename Arg> 231class ProbePointArg : public ProbePoint 232{ 233 /** The attached listeners. */ 234 std::vector<ProbeListenerArgBase<Arg> *> listeners; 235 236 public: 237 ProbePointArg(ProbeManager *manager, std::string name) 238 : ProbePoint(manager, name) 239 { 240 } 241 242 /** 243 * @brief adds a ProbeListener to this ProbePoints notify list. 244 * @param l the ProbeListener to add to the notify list. 245 */ 246 void addListener(ProbeListener *l) 247 { 248 // check listener not already added 249 if (std::find(listeners.begin(), listeners.end(), l) == listeners.end()) { 250 listeners.push_back(static_cast<ProbeListenerArgBase<Arg> *>(l)); 251 } 252 } 253 254 /** 255 * @brief remove a ProbeListener from this ProbePoints notify list. 256 * @param l the ProbeListener to remove from the notify list. 257 */ 258 void removeListener(ProbeListener *l) 259 { 260 listeners.erase(std::remove(listeners.begin(), listeners.end(), l), 261 listeners.end()); 262 } 263 264 /** 265 * @brief called at the ProbePoint call site, passes arg to each listener. 266 * @param arg the argument to pass to each listener. 267 */ 268 void notify(const Arg &arg) 269 { 270 for (auto l = listeners.begin(); l != listeners.end(); ++l) { 271 (*l)->notify(arg); 272 } 273 } 274}; 275#endif//__SIM_PROBE_PROBE_HH__ 276