blob: ae7480e401cd3f795704000e8fb4ee4fd2349da5 [file] [log] [blame]
Zane Shelley871adec2019-07-30 11:01:39 -05001#pragma once
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -05002
Zane Shelley52cb1a92019-08-21 14:38:31 -05003#include <hei_includes.hpp>
4#include <register/hei_register.hpp>
5#include <util/hei_bit_string.hpp>
6
Zane Shelley871adec2019-07-30 11:01:39 -05007namespace libhei
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -05008{
9
Zane Shelley61565dc2019-09-18 21:57:10 -050010/**
Zane Shelley8deb0902019-10-14 15:52:27 -050011 * @brief An abstract class containing information (e.g. address, type, length,
12 * etc.) for an actual hardware register.
Zane Shelley61565dc2019-09-18 21:57:10 -050013 *
14 * Hardware access:
15 *
16 * Actual hardware access is defined by the user application via the user
17 * interface APIs. In order to tell the user application which chip to target,
Zane Shelley53efc352019-10-03 21:46:39 -050018 * the user application will give the isolator a list of pointers to its
19 * objects. They will then be passed into the public functions of this class
20 * and eventually given back to the user application when hardware access is
21 * needed.
Zane Shelleyd0af3582019-09-19 10:48:59 -050022 *
23 * Register cache:
24 *
25 * In order to save memory space, each instance of this class does not store
26 * the contents of the target hardware register. Instead, that data is stored
Paul Greenwood6574f6e2019-09-17 09:43:22 -050027 * in a register cache, which is a static variable defined in this class. This
Zane Shelleyd0af3582019-09-19 10:48:59 -050028 * allows us to store only what we need. The cache can also be thought of as a
29 * snapshot of the registers at the time of isolation, which can be useful if
30 * the hardware is still running and register values could change.
31 *
32 * In order to ensure stale data isn't used from the cache, call
33 * HardwareRegister::flushAll() before beginning isolation on a new attention.
34 * Also, HardwareRegister::flushAll() should be called when the isolator is
35 * uninitialized before the rest of the isolation objects are deleted.
Zane Shelley61565dc2019-09-18 21:57:10 -050036 */
Zane Shelleycd36f432019-08-30 21:22:07 -050037class HardwareRegister : public Register
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -050038{
39 public:
Zane Shelley8deb0902019-10-14 15:52:27 -050040 /** @brief Pure virtual destructor. */
41 virtual ~HardwareRegister() = 0;
42
43 protected:
Zane Shelley8deb0902019-10-14 15:52:27 -050044 /**
45 * @brief Constructor from components.
Zane Shelley7667b712020-05-11 20:45:40 -050046 * @param i_id Unique ID for this register.
47 * @param i_instance Instance of this register
48 * @param i_flags Attribute flags for this register.
Zane Shelley8deb0902019-10-14 15:52:27 -050049 */
Zane Shelley5ec88102020-05-11 21:08:25 -050050 HardwareRegister(RegisterId_t i_id, Instance_t i_instance,
51 RegisterAttributeFlags_t i_flags) :
Zane Shelley7f7a42d2019-10-28 13:28:31 -050052 Register(),
Zane Shelley5ec88102020-05-11 21:08:25 -050053 iv_id(i_id), iv_instance(i_instance), iv_flags(i_flags)
Zane Shelley8deb0902019-10-14 15:52:27 -050054 {}
55
56 private: // Instance variables
Zane Shelley8deb0902019-10-14 15:52:27 -050057 /** The unique ID for this register. */
58 const RegisterId_t iv_id;
59
60 /** A register may have multiple instances. All of which will have the same
61 * ID. This variable is used to distinguish between each instance of the
62 * register. */
Zane Shelley13b182b2020-05-07 20:23:45 -050063 const Instance_t iv_instance;
Zane Shelley8deb0902019-10-14 15:52:27 -050064
65 /** The hardware access level of this register (read/write, read-only,
66 * write-only, etc.). */
Zane Shelley7667b712020-05-11 20:45:40 -050067 const RegisterAttributeFlags_t iv_flags;
Zane Shelley8deb0902019-10-14 15:52:27 -050068
69 public: // Accessor functions
Zane Shelley8deb0902019-10-14 15:52:27 -050070 /* @return The unique ID for this register. */
Zane Shelley7f7a42d2019-10-28 13:28:31 -050071 RegisterId_t getId() const
72 {
73 return iv_id;
74 }
Zane Shelley8deb0902019-10-14 15:52:27 -050075
76 /* @return The instance of this register. */
Zane Shelley13b182b2020-05-07 20:23:45 -050077 Instance_t getInstance() const
Zane Shelley7f7a42d2019-10-28 13:28:31 -050078 {
79 return iv_instance;
80 }
Zane Shelley8deb0902019-10-14 15:52:27 -050081
Zane Shelley7667b712020-05-11 20:45:40 -050082 /** @return True if given flag is enabled, false if disabled. */
83 bool queryAttrFlag(RegisterAttributeFlags_t i_flag) const
Zane Shelley7f7a42d2019-10-28 13:28:31 -050084 {
Zane Shelley7667b712020-05-11 20:45:40 -050085 return (0 != (iv_flags & i_flag));
Zane Shelley7f7a42d2019-10-28 13:28:31 -050086 }
Zane Shelley8deb0902019-10-14 15:52:27 -050087
88 // NOTE: The following are determined by child classes.
89
90 /** @return This register's type. */
Zane Shelley5ec88102020-05-11 21:08:25 -050091 virtual RegisterType_t getType() const = 0;
Zane Shelley8deb0902019-10-14 15:52:27 -050092
93 /** @return The address of this register. */
94 virtual RegisterAddress_t getAddress() const = 0;
95
96 /** @return The size (in bytes) of this register. */
97 virtual size_t getSize() const = 0;
98
Zane Shelley75e68e92019-10-18 16:16:23 -050099 public: // Operators
Zane Shelley75e68e92019-10-18 16:16:23 -0500100 /** @brief Equals operator. */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500101 bool operator==(const HardwareRegister& i_r) const
Zane Shelley75e68e92019-10-18 16:16:23 -0500102 {
Zane Shelley5ec88102020-05-11 21:08:25 -0500103 // Comparing register type and address should be sufficient.
104 return (getAddress() == i_r.getAddress()) &&
105 (getType() == i_r.getType());
Zane Shelley75e68e92019-10-18 16:16:23 -0500106 }
107
108 /** @brief Less than operator. */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500109 bool operator<(const HardwareRegister& i_r) const
Zane Shelley75e68e92019-10-18 16:16:23 -0500110 {
Zane Shelley5ec88102020-05-11 21:08:25 -0500111 // Comparing register type and address should be sufficient.
112 if (getAddress() < i_r.getAddress())
Zane Shelley75e68e92019-10-18 16:16:23 -0500113 {
114 return true;
115 }
Zane Shelley5ec88102020-05-11 21:08:25 -0500116 else if (getAddress() == i_r.getAddress())
Zane Shelley75e68e92019-10-18 16:16:23 -0500117 {
Zane Shelley5ec88102020-05-11 21:08:25 -0500118 return (getType() < i_r.getType());
Zane Shelley75e68e92019-10-18 16:16:23 -0500119 }
120
121 return false;
122 }
123
Zane Shelley8deb0902019-10-14 15:52:27 -0500124 public:
Zane Shelley65ed96a2019-10-14 13:06:11 -0500125 /** Function overloaded from parent Register class. */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500126 const BitString* getBitString(const Chip& i_chip) const;
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500127
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500128 /**
Zane Shelley61565dc2019-09-18 21:57:10 -0500129 * @brief Reads a register from hardware via the user interface APIs.
Zane Shelley53efc352019-10-03 21:46:39 -0500130 * @param i_chip The target chip in which this register belongs.
Zane Shelley61565dc2019-09-18 21:57:10 -0500131 * @param i_force When false, this function will only read from hardware if
132 * an entry for this instance does not already exist in the
133 * register cache. When true, the entry in the register
134 * cache is flushed, if it exists. Then this function will
135 * read from hardware and update the cache.
136 * @return See the return code from the registerRead() user interface API.
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500137 */
Zane Shelley2f4aa912020-05-08 14:28:18 -0500138 bool read(const Chip& i_chip, bool i_force = false) const;
Zane Shelley61565dc2019-09-18 21:57:10 -0500139
Ben Tyner7b3420b2020-05-11 10:52:07 -0500140#ifdef __HEI_ENABLE_HW_WRITE
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500141
142 /**
Zane Shelley61565dc2019-09-18 21:57:10 -0500143 * @brief Writes the value stored in the register cache to hardware via the
144 * user interface APIs.
Zane Shelley53efc352019-10-03 21:46:39 -0500145 * @param i_chip The target chip in which this register belongs.
Zane Shelley61565dc2019-09-18 21:57:10 -0500146 * @return See the return code from the registerWrite() user interface API.
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500147 */
Zane Shelley2f4aa912020-05-08 14:28:18 -0500148 bool write(const Chip& i_chip) const;
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500149
Ben Tyner7b3420b2020-05-11 10:52:07 -0500150#endif // __HEI_ENABLE_HW_WRITE
Zane Shelley61565dc2019-09-18 21:57:10 -0500151
Zane Shelleyafa669a2019-10-15 13:23:17 -0500152 protected:
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500153 /**
Zane Shelleyafa669a2019-10-15 13:23:17 -0500154 * @brief Provides access to this register's BitString.
155 *
156 * WARNING: Allowing public access to this function may be dangerous. For
157 * now it should be left as protected.
158 *
Zane Shelley53efc352019-10-03 21:46:39 -0500159 * @param i_chip The target chip in which this register belongs.
Zane Shelleyafa669a2019-10-15 13:23:17 -0500160 * @return A reference to the BitString.
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500161 */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500162 BitString& accessBitString(const Chip& i_chip);
Zane Shelley61565dc2019-09-18 21:57:10 -0500163
Zane Shelleyd0af3582019-09-19 10:48:59 -0500164 private: // Register cache class variable
Zane Shelleyd0af3582019-09-19 10:48:59 -0500165 /**
166 * @brief Caches the contents of registers read from hardware.
167 *
168 * The goal is to create a snapshot of the hardware register contents as
169 * close to the reported attention as possible. This snapshot is then used
170 * for additional analysis/debug when needed.
171 */
172 class Cache
173 {
174 public:
Zane Shelleyd0af3582019-09-19 10:48:59 -0500175 /** @brief Default constructor. */
176 Cache() = default;
177
178 /** @brief Destructor. */
179 ~Cache() = default;
180
181 /** @brief Copy constructor. */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500182 Cache(const Cache&) = delete;
Zane Shelleyd0af3582019-09-19 10:48:59 -0500183
184 /** @brief Assignment operator. */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500185 Cache& operator=(const Cache&) = delete;
Zane Shelleyd0af3582019-09-19 10:48:59 -0500186
187 /**
188 * @brief Queries if a specific entry exists in the cache.
189 * @param i_chip The target chip.
190 * @param i_hwReg The target register.
191 * @return True if the entry exists, false otherwise.
192 */
Zane Shelley7f7a42d2019-10-28 13:28:31 -0500193 bool query(const Chip& i_chip, const HardwareRegister* i_hwReg) const;
Zane Shelleyd0af3582019-09-19 10:48:59 -0500194
195 /**
196 * @brief Returns the data buffer for the given chip and register.
197 * @param i_chip The target chip.
198 * @param i_hwReg The target register.
199 * @return A reference to the BitString containing the register data.
200 * @note If an entry does not exist in the cache, an entry will be
201 * created and the BitString will be initialized to 0.
202 */
Zane Shelley7f7a42d2019-10-28 13:28:31 -0500203 BitString& access(const Chip& i_chip, const HardwareRegister* i_hwReg);
Zane Shelleyd0af3582019-09-19 10:48:59 -0500204
205 /** @brief Flushes entire contents from cache. */
206 void flush();
207
208 /**
209 * @brief Removes a single register from the cache.
210 * @param i_chip The target chip.
211 * @param i_hwReg The target register.
212 */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500213 void flush(const Chip& i_chip, const HardwareRegister* i_hwReg);
Zane Shelleyd0af3582019-09-19 10:48:59 -0500214
215 private:
Zane Shelleyd0af3582019-09-19 10:48:59 -0500216 /**
217 * @brief Stores a BitStringBuffer for each HardwareRegister per Chip.
218 *
219 * The HardwareRegister keys will just be pointers to the isolation
220 * objects created in the main initialize() API. Those should exist
221 * until the main uninitialize() API is called. It is important that the
222 * cache is flushed at the beginning of the uninitialize() API before
223 * the rest of the isolation objects are deleted.
224 *
225 * The Chip keys are copies of the objects passed to the isolator
226 * because the user application is responsible for storage of the
227 * objects passed to the isolator. We don't want to chance a Chip was
228 * created as a local variable that goes out of scope, or other similar
229 * situations.
230 */
231 std::map<Chip, std::map<const HardwareRegister*, BitString*>> iv_cache;
232 };
233
234 /** This allows all HardwareRegister objects access to the cache. */
235 static Cache cv_cache;
236
237 public: // Register cache management functions.
Zane Shelleyd0af3582019-09-19 10:48:59 -0500238 /** @brief Flushes the entire register cache. */
Zane Shelley7f7a42d2019-10-28 13:28:31 -0500239 static void flushAll()
240 {
241 cv_cache.flush();
242 }
Zane Shelleyd0af3582019-09-19 10:48:59 -0500243
Zane Shelley53efc352019-10-03 21:46:39 -0500244 /**
245 * @brief Flushes this register from the cache.
246 * @param i_chip The target chip in which this register belongs.
247 */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500248 void flush(const Chip& i_chip) const
Zane Shelleyd0af3582019-09-19 10:48:59 -0500249 {
Zane Shelley83da2452019-10-25 15:45:34 -0500250 cv_cache.flush(i_chip, this);
Zane Shelleyd0af3582019-09-19 10:48:59 -0500251 }
252
Zane Shelley53efc352019-10-03 21:46:39 -0500253 private: // Register cache management functions.
Zane Shelley53efc352019-10-03 21:46:39 -0500254 /**
255 * @param i_chip The target chip in which this register belongs.
256 * @return True if an entry for this register exist in this cache.
257 */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500258 bool queryCache(const Chip& i_chip) const
Zane Shelleyd0af3582019-09-19 10:48:59 -0500259 {
Zane Shelley83da2452019-10-25 15:45:34 -0500260 return cv_cache.query(i_chip, this);
Zane Shelley53efc352019-10-03 21:46:39 -0500261 }
262
263 /**
264 * @param i_chip The target chip in which this register belongs.
265 * @return A reference to this register's BitString in cache.
266 */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500267 BitString& accessCache(const Chip& i_chip) const
Zane Shelley53efc352019-10-03 21:46:39 -0500268 {
Zane Shelley83da2452019-10-25 15:45:34 -0500269 return cv_cache.access(i_chip, this);
Zane Shelleyd0af3582019-09-19 10:48:59 -0500270 }
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500271};
272
Zane Shelley871adec2019-07-30 11:01:39 -0500273} // end namespace libhei