blob: 7ba73467e426000daa0cfd61dff1943a035328f7 [file] [log] [blame]
Zane Shelley508ce582020-05-05 13:47:19 -05001#pragma once
2
3#include <hei_isolation_data.hpp>
4#include <isolator/hei_isolation_node.hpp>
Zane Shelley4caa0432020-05-12 22:29:02 -05005#include <register/hei_hardware_register.hpp>
Zane Shelley508ce582020-05-05 13:47:19 -05006
7namespace libhei
8{
9
10/**
11 * @brief This class contains all information required to isolate attentions on
12 * a specific chip type.
13 *
14 * The primary function of this class is analyze(), which will do a depth-first
15 * search of the hardware attention reporting tree structure (characterized by
16 * IsolationNode objects) to find all active attentions on a chip.
17 *
18 * The data for each chip type is built from information in the Chip Data Files.
19 *
20 * IMPORTANT:
21 * Most of the objects created and referenced by this class are stored in the
22 * flyweight factories, which are used as a space saving mechanism by
23 * preventing duplicate object creation. For example, a large set of the
24 * registers for a specific chip model will likely be common between each of
25 * chip level of that model. It is not necessary to create new objects for
26 * each level when the attributes are all the same. Because the flyweights are
27 * used, it is not possible to remove all of the data for a specific chip
28 * model/level be deleting an IsolationChip object. Instead, you must call the
29 * main uninitialize() function and clear all data for all objects.
30 */
31class IsolationChip
32{
Zane Shelley4de8ff82020-05-14 15:39:01 -050033 public: // Aliases
Zane Shelleyd5d23632022-12-13 09:34:31 -060034 using Ptr = std::shared_ptr<IsolationChip>;
35 using ConstPtr = std::shared_ptr<const IsolationChip>;
Zane Shelley4de8ff82020-05-14 15:39:01 -050036
37 using Map = std::map<ChipType_t, const ConstPtr>;
38
Zane Shelley508ce582020-05-05 13:47:19 -050039 public: // Constructors, destructor, assignment
Zane Shelleydd69c962020-05-05 22:19:11 -050040 /** @brief Constructor. */
41 explicit IsolationChip(ChipType_t i_chipType) : iv_chipType(i_chipType) {}
Zane Shelley508ce582020-05-05 13:47:19 -050042
43 /** @brief Destructor. */
44 ~IsolationChip() = default;
45
46 /** @brief Copy constructor. */
47 IsolationChip(const IsolationChip&) = delete;
48
49 /** @brief Assignment operator. */
50 IsolationChip& operator=(const IsolationChip&) = delete;
51
52 private: // Instance variables
53 /** This chip's type. */
54 const ChipType_t iv_chipType;
55
Zane Shelley4caa0432020-05-12 22:29:02 -050056 /** All hardware registers for this chip type. */
Zane Shelley4de8ff82020-05-14 15:39:01 -050057 std::map<HardwareRegister::Key, const HardwareRegister::ConstPtr> iv_regs;
Zane Shelley4caa0432020-05-12 22:29:02 -050058
59 /** All isolation nodes for this chip type. */
Zane Shelley4de8ff82020-05-14 15:39:01 -050060 std::map<IsolationNode::Key, const IsolationNode::ConstPtr> iv_nodes;
Zane Shelley4caa0432020-05-12 22:29:02 -050061
Zane Shelley508ce582020-05-05 13:47:19 -050062 /** Root nodes for this chip type. */
Zane Shelley4de8ff82020-05-14 15:39:01 -050063 std::map<AttentionType_t, const IsolationNode::ConstPtr> iv_rootNodes;
Zane Shelley508ce582020-05-05 13:47:19 -050064
65 public: // Member functions
66 /**
67 * @brief Finds all active attentions on this chip.
68 * @param i_chip The target chip for isolation. Will assert the given
69 * chip type matches iv_chipType.
70 * @param io_isoData The isolation data returned back to the user
71 * application.
72 * @return True, if any active attentions found on this chip.
73 * False, otherwise.
74 */
75 bool analyze(const Chip& i_chip, IsolationData& io_isoData) const;
76
77 /** @brief Chip type accessor. */
78 ChipType_t getChipType() const
79 {
80 return iv_chipType;
81 }
Zane Shelleydd69c962020-05-05 22:19:11 -050082
83 /**
Zane Shelley4caa0432020-05-12 22:29:02 -050084 * @brief Adds a hardware register to this chip.
85 * @param i_hwReg The target hardware register. Will assert that a different
86 * register with the same ID and instance does not exist.
87 */
Zane Shelley4de8ff82020-05-14 15:39:01 -050088 void addHardwareRegister(HardwareRegister::ConstPtr i_hwReg);
Zane Shelley4caa0432020-05-12 22:29:02 -050089
90 /**
91 * @brief Adds an isolation node to this chip.
92 * @param i_isoNode The target isolation node. Will assert that a different
93 * node with the same ID and instance does not exist.
94 */
Zane Shelley4de8ff82020-05-14 15:39:01 -050095 void addIsolationNode(IsolationNode::ConstPtr i_isoNode);
Zane Shelley4caa0432020-05-12 22:29:02 -050096
97 /**
Zane Shelleydd69c962020-05-05 22:19:11 -050098 * @brief Adds a root node to this chip.
99 * @param i_attnType The target attention type. Will assert this type does
100 * not already exist in iv_rootNodes.
Zane Shelley4caa0432020-05-12 22:29:02 -0500101 * @param i_rootNode The target isolation node for this attention type.
Zane Shelleydd69c962020-05-05 22:19:11 -0500102 */
Zane Shelley4de8ff82020-05-14 15:39:01 -0500103 void addRootNode(AttentionType_t i_attnType,
104 IsolationNode::ConstPtr i_rootNode);
Zane Shelley4caa0432020-05-12 22:29:02 -0500105
106 /**
107 * @brief Retrieves a hardware register from this chip, if it exists.
Zane Shelley4de8ff82020-05-14 15:39:01 -0500108 * @param i_key The register key.
Zane Shelley4caa0432020-05-12 22:29:02 -0500109 * @return The target hardware register. Will assert that the target
110 * register exists in iv_regs.
111 */
Zane Shelley4de8ff82020-05-14 15:39:01 -0500112 HardwareRegister::ConstPtr
113 getHardwareRegister(HardwareRegister::Key i_key) const;
Zane Shelley4caa0432020-05-12 22:29:02 -0500114
115 /**
116 * @brief Retrieves an isolation node from this chip, if it exists.
Zane Shelley4de8ff82020-05-14 15:39:01 -0500117 * @param i_key The node key.
Zane Shelley4caa0432020-05-12 22:29:02 -0500118 * @return The target isolation node. Will assert that the target node
119 * exists in iv_nodes.
120 */
Zane Shelley4de8ff82020-05-14 15:39:01 -0500121 IsolationNode::ConstPtr getIsolationNode(IsolationNode::Key i_key) const;
Zane Shelley508ce582020-05-05 13:47:19 -0500122};
123
Zane Shelley508ce582020-05-05 13:47:19 -0500124} // end namespace libhei