blob: 053cd1c08b73efa1e2780cdc2490d599a9d83f32 [file] [log] [blame]
Zane Shelley7bf1f6d2019-10-18 16:03:51 -05001#pragma once
2
3#include <hei_includes.hpp>
4#include <hei_isolation_data.hpp>
Zane Shelleye8dc72c2020-05-14 16:40:52 -05005#include <register/hei_hardware_register.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 Shelleye8dc72c2020-05-14 16:40:52 -050088 * The list of register to capture and add to the log for additional
89 * debugging.
90 */
91 std::vector<HardwareRegister::ConstPtr> iv_capRegs;
92
93 /**
Zane Shelley7bf1f6d2019-10-18 16:03:51 -050094 * This register could report multiple types of attentions. We can use a
95 * register 'rule' (value) to find any active attentions for each attention
96 * type (key). A 'rule', like "register & ~mask", is a combination of
97 * HardwareRegister objects and virtual operator registers (all children
Zane Shelley6eb61902020-05-15 22:25:58 -050098 * of the Register class). Note that all registers referenced by these rules
99 * must be the same type as iv_regType.
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500100 */
Zane Shelley4de8ff82020-05-14 15:39:01 -0500101 std::map<AttentionType_t, const Register::ConstPtr> iv_rules;
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500102
103 /**
104 * Each bit (key) in this map indicates that an attention was driven from
105 * another register (value).
106 */
Zane Shelley4de8ff82020-05-14 15:39:01 -0500107 std::map<BitPosition_t, const ConstPtr> iv_children;
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500108
109 public: // Member functions
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500110 /**
Zane Shelley6722b5b2020-05-12 22:09:04 -0500111 * @brief Finds all active attentions on this node. If an active bit is a
112 * leaf in the isolation tree, the bit's signature is added to the
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500113 * isolation data. Otherwise, this function is recursively called
Zane Shelley6722b5b2020-05-12 22:09:04 -0500114 * to analyze the child node that is driving the attention in this
115 * node.
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500116 * @param i_chip The target chip for isolation.
117 * @param i_attnType The target attention type to analyze on this register.
118 * Will assert a rule must exist for this attention type.
119 * @param io_isoData The isolation data returned back to the user
120 * application.
121 * @return True, if any active attentions found on this register.
122 * False, otherwise.
123 */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500124 bool analyze(const Chip& i_chip, AttentionType_t i_attnType,
125 IsolationData& io_isoData) const;
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500126
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500127 /**
Zane Shelleye8dc72c2020-05-14 16:40:52 -0500128 * @brief Adds a hardware register to the list of registers that will be
129 * captured for additional debugging. See iv_capRegs for details.
130 *
131 * This is only intended to be used during initialization of the isolator.
132 * Duplicate registers will be ignored.
133 *
134 * @param The target hardware register.
135 */
136 void addCaptureRegister(HardwareRegister::ConstPtr i_hwReg);
137
138 /**
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500139 * @brief Adds a register rule for the given attention type. See iv_rules
140 * for details.
141 *
142 * This is only intended to be used during initialization of the isolator.
Zane Shelley6722b5b2020-05-12 22:09:04 -0500143 * Will assert that a rule has not already been defined for this type.
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500144 *
145 * @param The target attention type.
146 * @param The rule for this attention type.
147 */
Zane Shelley4de8ff82020-05-14 15:39:01 -0500148 void addRule(AttentionType_t i_attnType, Register::ConstPtr i_rule);
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500149
150 /**
Zane Shelley6722b5b2020-05-12 22:09:04 -0500151 * @brief Adds a child node to analyze for the given bit position in this
152 * node. See iv_children for details.
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500153 *
154 * This is only intended to be used during initialization of the isolator.
155 * Will assert that nothing has already been defined for this bit.
156 *
Zane Shelley6722b5b2020-05-12 22:09:04 -0500157 * @param The target bit on this node.
158 * @param The child node to analyze for the given bit.
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500159 */
Zane Shelley4de8ff82020-05-14 15:39:01 -0500160 void addChild(BitPosition_t i_bit, ConstPtr i_child);
Zane Shelley6722b5b2020-05-12 22:09:04 -0500161
162 /** @return The node ID. */
163 NodeId_t getId() const
164 {
165 return iv_id;
166 }
167
168 /** @return The node instance. */
169 Instance_t getInstance() const
170 {
171 return iv_instance;
172 }
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500173
Zane Shelley4de8ff82020-05-14 15:39:01 -0500174 /** @return The node/instance key. */
175 Key getKey() const
176 {
177 return {iv_id, iv_instance};
178 }
179
Zane Shelley6eb61902020-05-15 22:25:58 -0500180 /** @return This node's register type.. */
181 RegisterType_t getRegisterType() const
182 {
183 return iv_regType;
184 }
185
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500186 private: // Isolation stack and supporting functions.
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500187 /** When analyze() is called at the tree root, all recursive calls to
188 * analyze() will target the same chip and attention type. So we only need
189 * to keep track of the nodes that have been analyzed to avoid cyclic
190 * isolation (an infinite loop). In fact, we only need to keep track of the
191 * nodes directly from this node to the root node. As long as this node
192 * does not already exist in the list, we can be sure there will not be a
193 * loop. So the list can be treated as a stack. When analyze() is called on
194 * a node, that node is pushed to the top of the stack (as long as it
195 * doesn't already exist in the stack). Then, just before analyze() exits,
196 * this node can be popped off the top of the stack. Once all the recursive
197 * calls have returned back to the root node the stack should be empty.
198 */
Zane Shelley2467db82020-05-18 19:56:30 -0500199 static std::vector<const IsolationNode*> cv_isolationStack;
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500200
201 /**
202 * @brief Pushes this node to the top of the stack. Will assert that this
203 * node does not already exist in cv_isolationStack.
204 */
205 void pushIsolationStack() const;
206
207 /** @brief Pops the top node off of cv_isolationStack. */
Zane Shelley7f7a42d2019-10-28 13:28:31 -0500208 void popIsolationStack() const
209 {
210 cv_isolationStack.pop_back();
211 }
Zane Shelley7bf1f6d2019-10-18 16:03:51 -0500212};
213
214} // end namespace libhei