blob: 858a8c1e11dbc3b4c3ada1cac4df62e640d73d3a [file] [log] [blame]
Zane Shelley7bf1f6d2019-10-18 16:03:51 -05001#pragma once
2
Zane Shelley7bf1f6d2019-10-18 16:03:51 -05003#include <hei_isolation_data.hpp>
Zane Shelleye8dc72c2020-05-14 16:40:52 -05004#include <register/hei_hardware_register.hpp>
Zane Shelleyd5073512021-01-14 12:51:18 -06005#include <util/hei_includes.hpp>
Zane Shelley7bf1f6d2019-10-18 16:03:51 -05006
7namespace libhei
8{
9
10/**
Zane Shelley6722b5b2020-05-12 22:09:04 -050011 * @brief This class contains the isolation rules and bit definition for a node
12 * in a chip's error reporting structure.
Zane Shelley7bf1f6d2019-10-18 16:03:51 -050013 *
Zane Shelley6722b5b2020-05-12 22:09:04 -050014 * These objects are linked together to form a tree with a single root node. Any
15 * active bits found in a node will either indicate an active attention or that
16 * the attention originated in a child node.
Zane Shelley7bf1f6d2019-10-18 16:03:51 -050017 *
18 * The primary function of this class is analyze(), which will do a depth-first
Zane Shelley6722b5b2020-05-12 22:09:04 -050019 * search of the tree to find all active attentions and add their signatures to
20 * the returned isolation data.
Zane Shelley7bf1f6d2019-10-18 16:03:51 -050021 *
22 * The tree structure is built from information in the Chip Data Files. It is
23 * possible that the tree could be built with loop in the isolation. This would
24 * be bug in the Chip Data Files. This class will keep track of all nodes that
25 * have been analyzed to prevent cyclic isolation (an infinite loop).
26 *
Zane Shelley6722b5b2020-05-12 22:09:04 -050027 * Each node instance will represent a register, or set of registers, that can
28 * be configured to represent one or more attention types. These configuration
29 * rules are a combination of hardware register objects and operator registers
30 * objects to define rules like "REG & ~MASK & CNFG", which reads "return all
31 * bits in REG that are not in MASK and set in CNFG". See the definition of the
32 * Register class for details on how this works.
Zane Shelleyd39aa572020-05-14 10:35:57 -050033 *
34 * This class cannot be added to the flyweights. There is no way to easily
35 * distinguish differences between nodes on different chips without comparing
36 * all of the capture registers, rules, and child nodes. Instead, the shared
37 * pointers will be stored in the isolation chip, which will ensure there isn't
38 * an attempt to add two nodes with the same ID and instance.
Zane Shelley7bf1f6d2019-10-18 16:03:51 -050039 */
40class IsolationNode
41{
Zane Shelley4de8ff82020-05-14 15:39:01 -050042 public: // Aliases
43 using Ptr = std::shared_ptr<IsolationNode>;
44 using ConstPtr = std::shared_ptr<const IsolationNode>;
45
46 using Key = std::pair<NodeId_t, Instance_t>;
47
Zane Shelley7bf1f6d2019-10-18 16:03:51 -050048 public: // Constructors, destructor, assignment
Zane Shelley7bf1f6d2019-10-18 16:03:51 -050049 /**
50 * @brief Constructor from components.
Zane Shelley6722b5b2020-05-12 22:09:04 -050051 * @param i_id Unique ID for all instances of this node.
52 * @param i_instance Instance of this node.
Zane Shelley7bf1f6d2019-10-18 16:03:51 -050053 */
Zane Shelley6eb61902020-05-15 22:25:58 -050054 IsolationNode(NodeId_t i_id, Instance_t i_instance,
55 RegisterType_t i_regType) :
56 iv_id(i_id),
57 iv_instance(i_instance), iv_regType(i_regType)
Zane Shelley7bf1f6d2019-10-18 16:03:51 -050058 {}
59
60 /** @brief Destructor. */
61 ~IsolationNode() = default;
62
Zane Shelley981e56a2020-05-11 21:24:20 -050063 /** @brief Copy constructor. */
64 IsolationNode(const IsolationNode&) = delete;
Zane Shelley7bf1f6d2019-10-18 16:03:51 -050065
Zane Shelley981e56a2020-05-11 21:24:20 -050066 /** @brief Assignment operator. */
Zane Shelleyfe27b652019-10-28 11:33:07 -050067 IsolationNode& operator=(const IsolationNode&) = delete;
Zane Shelley7bf1f6d2019-10-18 16:03:51 -050068
69 private: // Instance variables
Zane Shelley6722b5b2020-05-12 22:09:04 -050070 /** The unique ID for all instances of this node. */
71 const NodeId_t iv_id;
72
Zane Shelley7bf1f6d2019-10-18 16:03:51 -050073 /**
Zane Shelley6722b5b2020-05-12 22:09:04 -050074 * A node may have multiple instances. All of which will have the same ID.
75 * This variable is used to distinguish between each instance of the node.
Zane Shelley7bf1f6d2019-10-18 16:03:51 -050076 */
Zane Shelley6722b5b2020-05-12 22:09:04 -050077 const Instance_t iv_instance;
Zane Shelley7bf1f6d2019-10-18 16:03:51 -050078
79 /**
Zane Shelley6eb61902020-05-15 22:25:58 -050080 * A registers referenced by this node's rules must be of this type. No
81 * mixing of register types is allowed because comparing different sized
82 * registers is undefined behavior. Note that it is possible to have capture
83 * registers of mixed types.
84 */
85 const RegisterType_t iv_regType;
86
87 /**
Zane Shelley6b1fe162022-11-18 13:37:42 -060088 * The lists of register to capture and add to the log for additional
89 * debugging. The lists are indexed in a map where the key is a bit
90 * position. All registers that should be captured by default when
91 * isolating to this node will have a bit position of `MAX_BIT_POSITION`.
92 * Otherwise, any other list targeted for a specific bit will only be
93 * captured if there is an active attention on that bit.
Zane Shelleye8dc72c2020-05-14 16:40:52 -050094 */
Zane Shelley6b1fe162022-11-18 13:37:42 -060095 std::map<BitPosition_t, std::vector<HardwareRegister::ConstPtr>> iv_capRegs;
Zane Shelleye8dc72c2020-05-14 16:40:52 -050096
97 /**
Zane Shelley7bf1f6d2019-10-18 16:03:51 -050098 * This register could report multiple types of attentions. We can use a
99 * register 'rule' (value) to find any active attentions for each attention
100 * type (key). A 'rule', like "register & ~mask", is a combination of
101 * HardwareRegister objects and virtual operator registers (all children
Zane Shelley6eb61902020-05-15 22:25:58 -0500102 * of the Register class). Note that all registers referenced by these rules
103 * must be the same type as iv_regType.
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500104 */
Zane Shelley4de8ff82020-05-14 15:39:01 -0500105 std::map<AttentionType_t, const Register::ConstPtr> iv_rules;
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500106
107 /**
108 * Each bit (key) in this map indicates that an attention was driven from
109 * another register (value).
110 */
Zane Shelley4de8ff82020-05-14 15:39:01 -0500111 std::map<BitPosition_t, const ConstPtr> iv_children;
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500112
113 public: // Member functions
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500114 /**
Zane Shelley6722b5b2020-05-12 22:09:04 -0500115 * @brief Finds all active attentions on this node. If an active bit is a
116 * leaf in the isolation tree, the bit's signature is added to the
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500117 * isolation data. Otherwise, this function is recursively called
Zane Shelley6722b5b2020-05-12 22:09:04 -0500118 * to analyze the child node that is driving the attention in this
119 * node.
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500120 * @param i_chip The target chip for isolation.
121 * @param i_attnType The target attention type to analyze on this register.
122 * Will assert a rule must exist for this attention type.
123 * @param io_isoData The isolation data returned back to the user
124 * application.
125 * @return True, if any active attentions found on this register.
126 * False, otherwise.
127 */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500128 bool analyze(const Chip& i_chip, AttentionType_t i_attnType,
129 IsolationData& io_isoData) const;
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500130
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500131 /**
Zane Shelleye8dc72c2020-05-14 16:40:52 -0500132 * @brief Adds a hardware register to the list of registers that will be
133 * captured for additional debugging. See iv_capRegs for details.
134 *
135 * This is only intended to be used during initialization of the isolator.
136 * Duplicate registers will be ignored.
137 *
Zane Shelley6b1fe162022-11-18 13:37:42 -0600138 * @param i_hwReg The target hardware register.
139 * @param i_bit If specified, the given register should only be captured
140 * when there is an active attention on the given bit. If
141 * omitted, the given register will be captured any time
142 * this isolation node is analyzed.
Zane Shelleye8dc72c2020-05-14 16:40:52 -0500143 */
Zane Shelley6b1fe162022-11-18 13:37:42 -0600144 void addCaptureRegister(HardwareRegister::ConstPtr i_hwReg,
145 BitPosition_t i_bit = MAX_BIT_POSITION);
Zane Shelleye8dc72c2020-05-14 16:40:52 -0500146
147 /**
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500148 * @brief Adds a register rule for the given attention type. See iv_rules
149 * for details.
150 *
151 * This is only intended to be used during initialization of the isolator.
Zane Shelley6722b5b2020-05-12 22:09:04 -0500152 * Will assert that a rule has not already been defined for this type.
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500153 *
154 * @param The target attention type.
155 * @param The rule for this attention type.
156 */
Zane Shelley4de8ff82020-05-14 15:39:01 -0500157 void addRule(AttentionType_t i_attnType, Register::ConstPtr i_rule);
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500158
159 /**
Zane Shelley6722b5b2020-05-12 22:09:04 -0500160 * @brief Adds a child node to analyze for the given bit position in this
161 * node. See iv_children for details.
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500162 *
163 * This is only intended to be used during initialization of the isolator.
164 * Will assert that nothing has already been defined for this bit.
165 *
Zane Shelley6722b5b2020-05-12 22:09:04 -0500166 * @param The target bit on this node.
167 * @param The child node to analyze for the given bit.
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500168 */
Zane Shelley4de8ff82020-05-14 15:39:01 -0500169 void addChild(BitPosition_t i_bit, ConstPtr i_child);
Zane Shelley6722b5b2020-05-12 22:09:04 -0500170
171 /** @return The node ID. */
172 NodeId_t getId() const
173 {
174 return iv_id;
175 }
176
177 /** @return The node instance. */
178 Instance_t getInstance() const
179 {
180 return iv_instance;
181 }
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500182
Zane Shelley4de8ff82020-05-14 15:39:01 -0500183 /** @return The node/instance key. */
184 Key getKey() const
185 {
186 return {iv_id, iv_instance};
187 }
188
Zane Shelley6eb61902020-05-15 22:25:58 -0500189 /** @return This node's register type.. */
190 RegisterType_t getRegisterType() const
191 {
192 return iv_regType;
193 }
194
Zane Shelley6b1fe162022-11-18 13:37:42 -0600195 private: // Member functions
196 /**
197 * @param i_chip The target chip for isolation.
198 * @param io_isoData The isolation data returned back to the user
199 * application.
200 * @param i_bit If specified, only the registers specifically
201 * targeted for the given bit are captured. If omitted,
202 * the default list of registers for this isolation node
203 * will be captured.
204 */
205 void captureRegisters(const Chip& i_chip, IsolationData& io_isoData,
206 BitPosition_t i_bit = MAX_BIT_POSITION) const;
207
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500208 private: // Isolation stack and supporting functions.
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500209 /** When analyze() is called at the tree root, all recursive calls to
210 * analyze() will target the same chip and attention type. So we only need
211 * to keep track of the nodes that have been analyzed to avoid cyclic
212 * isolation (an infinite loop). In fact, we only need to keep track of the
213 * nodes directly from this node to the root node. As long as this node
214 * does not already exist in the list, we can be sure there will not be a
215 * loop. So the list can be treated as a stack. When analyze() is called on
216 * a node, that node is pushed to the top of the stack (as long as it
217 * doesn't already exist in the stack). Then, just before analyze() exits,
218 * this node can be popped off the top of the stack. Once all the recursive
219 * calls have returned back to the root node the stack should be empty.
220 */
Zane Shelley2467db82020-05-18 19:56:30 -0500221 static std::vector<const IsolationNode*> cv_isolationStack;
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500222
223 /**
224 * @brief Pushes this node to the top of the stack. Will assert that this
225 * node does not already exist in cv_isolationStack.
226 */
227 void pushIsolationStack() const;
228
229 /** @brief Pops the top node off of cv_isolationStack. */
Zane Shelley7f7a42d2019-10-28 13:28:31 -0500230 void popIsolationStack() const
231 {
232 cv_isolationStack.pop_back();
233 }
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500234};
235
236} // end namespace libhei