blob: fb39d1ed9482097306ed0b25dcd5c4652d3e507e [file] [log] [blame]
Zane Shelley871adec2019-07-30 11:01:39 -05001#pragma once
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -05002
Zane Shelleyc888dff2021-01-14 12:45:02 -06003#include <hei_bit_string.hpp>
Zane Shelley52cb1a92019-08-21 14:38:31 -05004#include <register/hei_register.hpp>
Zane Shelleyd5073512021-01-14 12:51:18 -06005#include <util/hei_includes.hpp>
Zane Shelley52cb1a92019-08-21 14:38:31 -05006
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{
Zane Shelley4de8ff82020-05-14 15:39:01 -050039 public: // Aliases
40 using Ptr = std::shared_ptr<HardwareRegister>;
41 using ConstPtr = std::shared_ptr<const HardwareRegister>;
42
43 using Key = std::pair<RegisterId_t, Instance_t>;
44
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -050045 public:
Zane Shelley8deb0902019-10-14 15:52:27 -050046 /** @brief Pure virtual destructor. */
47 virtual ~HardwareRegister() = 0;
48
49 protected:
Zane Shelley8deb0902019-10-14 15:52:27 -050050 /**
51 * @brief Constructor from components.
Zane Shelley7667b712020-05-11 20:45:40 -050052 * @param i_id Unique ID for this register.
53 * @param i_instance Instance of this register
54 * @param i_flags Attribute flags for this register.
Zane Shelley8deb0902019-10-14 15:52:27 -050055 */
Zane Shelley5ec88102020-05-11 21:08:25 -050056 HardwareRegister(RegisterId_t i_id, Instance_t i_instance,
57 RegisterAttributeFlags_t i_flags) :
Zane Shelley7f7a42d2019-10-28 13:28:31 -050058 Register(),
Zane Shelley5ec88102020-05-11 21:08:25 -050059 iv_id(i_id), iv_instance(i_instance), iv_flags(i_flags)
Zane Shelley8deb0902019-10-14 15:52:27 -050060 {}
61
62 private: // Instance variables
Zane Shelley8deb0902019-10-14 15:52:27 -050063 /** The unique ID for this register. */
64 const RegisterId_t iv_id;
65
66 /** A register may have multiple instances. All of which will have the same
67 * ID. This variable is used to distinguish between each instance of the
68 * register. */
Zane Shelley13b182b2020-05-07 20:23:45 -050069 const Instance_t iv_instance;
Zane Shelley8deb0902019-10-14 15:52:27 -050070
71 /** The hardware access level of this register (read/write, read-only,
72 * write-only, etc.). */
Zane Shelley7667b712020-05-11 20:45:40 -050073 const RegisterAttributeFlags_t iv_flags;
Zane Shelley8deb0902019-10-14 15:52:27 -050074
75 public: // Accessor functions
Zane Shelley8deb0902019-10-14 15:52:27 -050076 /* @return The unique ID for this register. */
Zane Shelley7f7a42d2019-10-28 13:28:31 -050077 RegisterId_t getId() const
78 {
79 return iv_id;
80 }
Zane Shelley8deb0902019-10-14 15:52:27 -050081
82 /* @return The instance of this register. */
Zane Shelley13b182b2020-05-07 20:23:45 -050083 Instance_t getInstance() const
Zane Shelley7f7a42d2019-10-28 13:28:31 -050084 {
85 return iv_instance;
86 }
Zane Shelley8deb0902019-10-14 15:52:27 -050087
Zane Shelley4de8ff82020-05-14 15:39:01 -050088 /** @return The register/instance key. */
89 Key getKey() const
90 {
91 return {iv_id, iv_instance};
92 }
93
Zane Shelley7667b712020-05-11 20:45:40 -050094 /** @return True if given flag is enabled, false if disabled. */
95 bool queryAttrFlag(RegisterAttributeFlags_t i_flag) const
Zane Shelley7f7a42d2019-10-28 13:28:31 -050096 {
Zane Shelley7667b712020-05-11 20:45:40 -050097 return (0 != (iv_flags & i_flag));
Zane Shelley7f7a42d2019-10-28 13:28:31 -050098 }
Zane Shelley8deb0902019-10-14 15:52:27 -050099
100 // NOTE: The following are determined by child classes.
101
102 /** @return This register's type. */
Zane Shelley5ec88102020-05-11 21:08:25 -0500103 virtual RegisterType_t getType() const = 0;
Zane Shelley8deb0902019-10-14 15:52:27 -0500104
105 /** @return The address of this register. */
106 virtual RegisterAddress_t getAddress() const = 0;
107
108 /** @return The size (in bytes) of this register. */
109 virtual size_t getSize() const = 0;
110
Zane Shelley75e68e92019-10-18 16:16:23 -0500111 public: // Operators
Zane Shelley75e68e92019-10-18 16:16:23 -0500112 /** @brief Equals operator. */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500113 bool operator==(const HardwareRegister& i_r) const
Zane Shelley75e68e92019-10-18 16:16:23 -0500114 {
Zane Shelley981e56a2020-05-11 21:24:20 -0500115 // In general, comparing the ID and instance should be enough. However,
116 // no error will be thrown when adding the register to the flyweights
Zane Shelley4de8ff82020-05-14 15:39:01 -0500117 // and any other field differs. Therefore, all fields will be used and
Zane Shelley981e56a2020-05-11 21:24:20 -0500118 // invalid duplicates will be found when adding the register pointers
119 // to the IsolationChip objects.
120 return (getAddress() == i_r.getAddress()) && (getId() == i_r.getId()) &&
121 (getInstance() == i_r.getInstance()) &&
Zane Shelley4de8ff82020-05-14 15:39:01 -0500122 (getType() == i_r.getType()) && (iv_flags == i_r.iv_flags);
Zane Shelley75e68e92019-10-18 16:16:23 -0500123 }
124
125 /** @brief Less than operator. */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500126 bool operator<(const HardwareRegister& i_r) const
Zane Shelley75e68e92019-10-18 16:16:23 -0500127 {
Zane Shelley981e56a2020-05-11 21:24:20 -0500128 // In general, comparing the ID and instance should be enough. However,
129 // no error will be thrown when adding the register to the flyweights
Zane Shelley4de8ff82020-05-14 15:39:01 -0500130 // and any other field differs. Therefore, all fields will be used and
Zane Shelley981e56a2020-05-11 21:24:20 -0500131 // invalid duplicates will be found when adding the register pointers
132 // to the IsolationChip objects.
Zane Shelley5ec88102020-05-11 21:08:25 -0500133 if (getAddress() < i_r.getAddress())
Zane Shelley75e68e92019-10-18 16:16:23 -0500134 {
135 return true;
136 }
Zane Shelley5ec88102020-05-11 21:08:25 -0500137 else if (getAddress() == i_r.getAddress())
Zane Shelley75e68e92019-10-18 16:16:23 -0500138 {
Zane Shelley981e56a2020-05-11 21:24:20 -0500139 if (getId() < i_r.getId())
140 {
141 return true;
142 }
143 else if (getId() == i_r.getId())
144 {
145 if (getInstance() < i_r.getInstance())
146 {
147 return true;
148 }
149 else if (getInstance() == i_r.getInstance())
150 {
Zane Shelley4de8ff82020-05-14 15:39:01 -0500151 if (getType() < i_r.getType())
152 {
153 return true;
154 }
155 else if (getType() == i_r.getType())
156 {
157 return (iv_flags < i_r.iv_flags);
158 }
Zane Shelley981e56a2020-05-11 21:24:20 -0500159 }
160 }
Zane Shelley75e68e92019-10-18 16:16:23 -0500161 }
162
163 return false;
164 }
165
Zane Shelley8deb0902019-10-14 15:52:27 -0500166 public:
Zane Shelley65ed96a2019-10-14 13:06:11 -0500167 /** Function overloaded from parent Register class. */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500168 const BitString* getBitString(const Chip& i_chip) const;
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500169
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500170 /**
Zane Shelley61565dc2019-09-18 21:57:10 -0500171 * @brief Reads a register from hardware via the user interface APIs.
Zane Shelley53efc352019-10-03 21:46:39 -0500172 * @param i_chip The target chip in which this register belongs.
Zane Shelley61565dc2019-09-18 21:57:10 -0500173 * @param i_force When false, this function will only read from hardware if
174 * an entry for this instance does not already exist in the
175 * register cache. When true, the entry in the register
176 * cache is flushed, if it exists. Then this function will
177 * read from hardware and update the cache.
178 * @return See the return code from the registerRead() user interface API.
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500179 */
Zane Shelley2f4aa912020-05-08 14:28:18 -0500180 bool read(const Chip& i_chip, bool i_force = false) const;
Zane Shelley61565dc2019-09-18 21:57:10 -0500181
Ben Tyner7b3420b2020-05-11 10:52:07 -0500182#ifdef __HEI_ENABLE_HW_WRITE
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500183
184 /**
Zane Shelley61565dc2019-09-18 21:57:10 -0500185 * @brief Writes the value stored in the register cache to hardware via the
186 * user interface APIs.
Zane Shelley53efc352019-10-03 21:46:39 -0500187 * @param i_chip The target chip in which this register belongs.
Zane Shelley61565dc2019-09-18 21:57:10 -0500188 * @return See the return code from the registerWrite() user interface API.
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500189 */
Zane Shelley2f4aa912020-05-08 14:28:18 -0500190 bool write(const Chip& i_chip) const;
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500191
Ben Tyner7b3420b2020-05-11 10:52:07 -0500192#endif // __HEI_ENABLE_HW_WRITE
Zane Shelley61565dc2019-09-18 21:57:10 -0500193
Zane Shelleyafa669a2019-10-15 13:23:17 -0500194 protected:
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500195 /**
Zane Shelleyafa669a2019-10-15 13:23:17 -0500196 * @brief Provides access to this register's BitString.
197 *
198 * WARNING: Allowing public access to this function may be dangerous. For
199 * now it should be left as protected.
200 *
Zane Shelley53efc352019-10-03 21:46:39 -0500201 * @param i_chip The target chip in which this register belongs.
Zane Shelleyafa669a2019-10-15 13:23:17 -0500202 * @return A reference to the BitString.
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500203 */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500204 BitString& accessBitString(const Chip& i_chip);
Zane Shelley61565dc2019-09-18 21:57:10 -0500205
Zane Shelleyd0af3582019-09-19 10:48:59 -0500206 private: // Register cache class variable
Zane Shelleyd0af3582019-09-19 10:48:59 -0500207 /**
208 * @brief Caches the contents of registers read from hardware.
209 *
210 * The goal is to create a snapshot of the hardware register contents as
211 * close to the reported attention as possible. This snapshot is then used
212 * for additional analysis/debug when needed.
213 */
214 class Cache
215 {
216 public:
Zane Shelleyd0af3582019-09-19 10:48:59 -0500217 /** @brief Default constructor. */
218 Cache() = default;
219
220 /** @brief Destructor. */
221 ~Cache() = default;
222
223 /** @brief Copy constructor. */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500224 Cache(const Cache&) = delete;
Zane Shelleyd0af3582019-09-19 10:48:59 -0500225
226 /** @brief Assignment operator. */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500227 Cache& operator=(const Cache&) = delete;
Zane Shelleyd0af3582019-09-19 10:48:59 -0500228
229 /**
230 * @brief Queries if a specific entry exists in the cache.
231 * @param i_chip The target chip.
232 * @param i_hwReg The target register.
233 * @return True if the entry exists, false otherwise.
234 */
Zane Shelley7f7a42d2019-10-28 13:28:31 -0500235 bool query(const Chip& i_chip, const HardwareRegister* i_hwReg) const;
Zane Shelleyd0af3582019-09-19 10:48:59 -0500236
237 /**
238 * @brief Returns the data buffer for the given chip and register.
239 * @param i_chip The target chip.
240 * @param i_hwReg The target register.
241 * @return A reference to the BitString containing the register data.
242 * @note If an entry does not exist in the cache, an entry will be
243 * created and the BitString will be initialized to 0.
244 */
Zane Shelley7f7a42d2019-10-28 13:28:31 -0500245 BitString& access(const Chip& i_chip, const HardwareRegister* i_hwReg);
Zane Shelleyd0af3582019-09-19 10:48:59 -0500246
247 /** @brief Flushes entire contents from cache. */
248 void flush();
249
250 /**
251 * @brief Removes a single register from the cache.
252 * @param i_chip The target chip.
253 * @param i_hwReg The target register.
254 */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500255 void flush(const Chip& i_chip, const HardwareRegister* i_hwReg);
Zane Shelleyd0af3582019-09-19 10:48:59 -0500256
257 private:
Zane Shelleyd0af3582019-09-19 10:48:59 -0500258 /**
259 * @brief Stores a BitStringBuffer for each HardwareRegister per Chip.
260 *
261 * The HardwareRegister keys will just be pointers to the isolation
262 * objects created in the main initialize() API. Those should exist
263 * until the main uninitialize() API is called. It is important that the
264 * cache is flushed at the beginning of the uninitialize() API before
265 * the rest of the isolation objects are deleted.
266 *
267 * The Chip keys are copies of the objects passed to the isolator
268 * because the user application is responsible for storage of the
269 * objects passed to the isolator. We don't want to chance a Chip was
270 * created as a local variable that goes out of scope, or other similar
271 * situations.
272 */
273 std::map<Chip, std::map<const HardwareRegister*, BitString*>> iv_cache;
274 };
275
276 /** This allows all HardwareRegister objects access to the cache. */
277 static Cache cv_cache;
278
279 public: // Register cache management functions.
Zane Shelleyd0af3582019-09-19 10:48:59 -0500280 /** @brief Flushes the entire register cache. */
Zane Shelley7f7a42d2019-10-28 13:28:31 -0500281 static void flushAll()
282 {
283 cv_cache.flush();
284 }
Zane Shelleyd0af3582019-09-19 10:48:59 -0500285
Zane Shelley53efc352019-10-03 21:46:39 -0500286 /**
287 * @brief Flushes this register from the cache.
288 * @param i_chip The target chip in which this register belongs.
289 */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500290 void flush(const Chip& i_chip) const
Zane Shelleyd0af3582019-09-19 10:48:59 -0500291 {
Zane Shelley83da2452019-10-25 15:45:34 -0500292 cv_cache.flush(i_chip, this);
Zane Shelleyd0af3582019-09-19 10:48:59 -0500293 }
294
Zane Shelley53efc352019-10-03 21:46:39 -0500295 private: // Register cache management functions.
Zane Shelley53efc352019-10-03 21:46:39 -0500296 /**
297 * @param i_chip The target chip in which this register belongs.
298 * @return True if an entry for this register exist in this cache.
299 */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500300 bool queryCache(const Chip& i_chip) const
Zane Shelleyd0af3582019-09-19 10:48:59 -0500301 {
Zane Shelley83da2452019-10-25 15:45:34 -0500302 return cv_cache.query(i_chip, this);
Zane Shelley53efc352019-10-03 21:46:39 -0500303 }
304
305 /**
306 * @param i_chip The target chip in which this register belongs.
307 * @return A reference to this register's BitString in cache.
308 */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500309 BitString& accessCache(const Chip& i_chip) const
Zane Shelley53efc352019-10-03 21:46:39 -0500310 {
Zane Shelley83da2452019-10-25 15:45:34 -0500311 return cv_cache.access(i_chip, this);
Zane Shelleyd0af3582019-09-19 10:48:59 -0500312 }
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500313};
314
Zane Shelley871adec2019-07-30 11:01:39 -0500315} // end namespace libhei