blob: 2a4dcfe3626d1234f72a55f219a8388ba56b7f77 [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.
46 * @param i_chipType Type of chip associated with this register.
47 * @param i_id Unique ID for this register.
48 * @param i_instance Instance of this register
49 * @param i_accessLevel Hardware access level for this register.
50 */
Zane Shelley83da2452019-10-25 15:45:34 -050051 HardwareRegister(ChipType_t i_chipType, RegisterId_t i_id,
52 RegisterInstance_t i_instance,
53 RegisterAccessLevel_t i_accessLevel) :
Zane Shelley7f7a42d2019-10-28 13:28:31 -050054 Register(),
55 iv_chipType(i_chipType), iv_id(i_id), iv_instance(i_instance),
56 iv_accessLevel(i_accessLevel)
Zane Shelley8deb0902019-10-14 15:52:27 -050057 {}
58
59 private: // Instance variables
Zane Shelley8deb0902019-10-14 15:52:27 -050060 /** The type of chip associated with register. */
61 const ChipType_t iv_chipType;
62
63 /** 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. */
69 const RegisterInstance_t iv_instance;
70
71 /** The hardware access level of this register (read/write, read-only,
72 * write-only, etc.). */
73 const RegisterAccessLevel_t iv_accessLevel;
74
75 public: // Accessor functions
Zane Shelley8deb0902019-10-14 15:52:27 -050076 /** @return The type of chip associated with this register. */
Zane Shelley7f7a42d2019-10-28 13:28:31 -050077 ChipType_t getChipType() const
78 {
79 return iv_chipType;
80 }
Zane Shelley8deb0902019-10-14 15:52:27 -050081
82 /* @return The unique ID for this register. */
Zane Shelley7f7a42d2019-10-28 13:28:31 -050083 RegisterId_t getId() const
84 {
85 return iv_id;
86 }
Zane Shelley8deb0902019-10-14 15:52:27 -050087
88 /* @return The instance of this register. */
Zane Shelley7f7a42d2019-10-28 13:28:31 -050089 RegisterInstance_t getInstance() const
90 {
91 return iv_instance;
92 }
Zane Shelley8deb0902019-10-14 15:52:27 -050093
94 /** @return The hardware access level of this register. */
Zane Shelley7f7a42d2019-10-28 13:28:31 -050095 RegisterAccessLevel_t getAccessLevel() const
96 {
97 return iv_accessLevel;
98 }
Zane Shelley8deb0902019-10-14 15:52:27 -050099
100 // NOTE: The following are determined by child classes.
101
102 /** @return This register's type. */
103 virtual RegisterType_t getRegisterType() const = 0;
104
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 {
115 // Comparing register type, chip type, and address should be sufficient.
Zane Shelley83da2452019-10-25 15:45:34 -0500116 return (getRegisterType() == i_r.getRegisterType()) &&
Zane Shelley7c8faa12019-10-28 22:26:28 -0500117 (getChipType() == i_r.getChipType()) &&
118 (getAddress() == i_r.getAddress());
Zane Shelley75e68e92019-10-18 16:16:23 -0500119 }
120
121 /** @brief Less than operator. */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500122 bool operator<(const HardwareRegister& i_r) const
Zane Shelley75e68e92019-10-18 16:16:23 -0500123 {
124 // Comparing register type, chip type, and address should be sufficient.
Zane Shelley83da2452019-10-25 15:45:34 -0500125 if (getRegisterType() < i_r.getRegisterType())
Zane Shelley75e68e92019-10-18 16:16:23 -0500126 {
127 return true;
128 }
Zane Shelley83da2452019-10-25 15:45:34 -0500129 else if (getRegisterType() == i_r.getRegisterType())
Zane Shelley75e68e92019-10-18 16:16:23 -0500130 {
Zane Shelley83da2452019-10-25 15:45:34 -0500131 if (getChipType() < i_r.getChipType())
Zane Shelley75e68e92019-10-18 16:16:23 -0500132 {
133 return true;
134 }
Zane Shelley83da2452019-10-25 15:45:34 -0500135 else if (getChipType() == i_r.getChipType())
Zane Shelley75e68e92019-10-18 16:16:23 -0500136 {
Zane Shelley83da2452019-10-25 15:45:34 -0500137 return (getAddress() < i_r.getAddress());
Zane Shelley75e68e92019-10-18 16:16:23 -0500138 }
139 }
140
141 return false;
142 }
143
Zane Shelley8deb0902019-10-14 15:52:27 -0500144 public:
Zane Shelley65ed96a2019-10-14 13:06:11 -0500145 /** Function overloaded from parent Register class. */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500146 const BitString* getBitString(const Chip& i_chip) const;
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500147
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500148 /**
Zane Shelley61565dc2019-09-18 21:57:10 -0500149 * @brief Reads a register from hardware via the user interface APIs.
Zane Shelley53efc352019-10-03 21:46:39 -0500150 * @param i_chip The target chip in which this register belongs.
Zane Shelley61565dc2019-09-18 21:57:10 -0500151 * @param i_force When false, this function will only read from hardware if
152 * an entry for this instance does not already exist in the
153 * register cache. When true, the entry in the register
154 * cache is flushed, if it exists. Then this function will
155 * read from hardware and update the cache.
156 * @return See the return code from the registerRead() user interface API.
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500157 */
Zane Shelley2f4aa912020-05-08 14:28:18 -0500158 bool read(const Chip& i_chip, bool i_force = false) const;
Zane Shelley61565dc2019-09-18 21:57:10 -0500159
Zane Shelley83da2452019-10-25 15:45:34 -0500160#ifndef __HEI_READ_ONLY
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500161
162 /**
Zane Shelley61565dc2019-09-18 21:57:10 -0500163 * @brief Writes the value stored in the register cache to hardware via the
164 * user interface APIs.
Zane Shelley53efc352019-10-03 21:46:39 -0500165 * @param i_chip The target chip in which this register belongs.
Zane Shelley61565dc2019-09-18 21:57:10 -0500166 * @return See the return code from the registerWrite() user interface API.
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500167 */
Zane Shelley2f4aa912020-05-08 14:28:18 -0500168 bool write(const Chip& i_chip) const;
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500169
Zane Shelley83da2452019-10-25 15:45:34 -0500170#endif // __HEI_READ_ONLY
Zane Shelley61565dc2019-09-18 21:57:10 -0500171
Zane Shelleyafa669a2019-10-15 13:23:17 -0500172 protected:
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500173 /**
Zane Shelleyafa669a2019-10-15 13:23:17 -0500174 * @brief Provides access to this register's BitString.
175 *
176 * WARNING: Allowing public access to this function may be dangerous. For
177 * now it should be left as protected.
178 *
Zane Shelley53efc352019-10-03 21:46:39 -0500179 * @param i_chip The target chip in which this register belongs.
Zane Shelleyafa669a2019-10-15 13:23:17 -0500180 * @return A reference to the BitString.
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500181 */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500182 BitString& accessBitString(const Chip& i_chip);
Zane Shelley61565dc2019-09-18 21:57:10 -0500183
Zane Shelley61565dc2019-09-18 21:57:10 -0500184 private: // Hardware accessor management functions.
Zane Shelley53efc352019-10-03 21:46:39 -0500185 /** @brief Asserts this register belongs on the target accessor chip. */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500186 void verifyAccessorChip(const Chip& i_chip) const
Zane Shelley61565dc2019-09-18 21:57:10 -0500187 {
Zane Shelley83da2452019-10-25 15:45:34 -0500188 HEI_ASSERT(getChipType() == i_chip.getType());
Zane Shelley61565dc2019-09-18 21:57:10 -0500189 }
Zane Shelleyd0af3582019-09-19 10:48:59 -0500190
191 private: // Register cache class variable
Zane Shelleyd0af3582019-09-19 10:48:59 -0500192 /**
193 * @brief Caches the contents of registers read from hardware.
194 *
195 * The goal is to create a snapshot of the hardware register contents as
196 * close to the reported attention as possible. This snapshot is then used
197 * for additional analysis/debug when needed.
198 */
199 class Cache
200 {
201 public:
Zane Shelleyd0af3582019-09-19 10:48:59 -0500202 /** @brief Default constructor. */
203 Cache() = default;
204
205 /** @brief Destructor. */
206 ~Cache() = default;
207
208 /** @brief Copy constructor. */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500209 Cache(const Cache&) = delete;
Zane Shelleyd0af3582019-09-19 10:48:59 -0500210
211 /** @brief Assignment operator. */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500212 Cache& operator=(const Cache&) = delete;
Zane Shelleyd0af3582019-09-19 10:48:59 -0500213
214 /**
215 * @brief Queries if a specific entry exists in the cache.
216 * @param i_chip The target chip.
217 * @param i_hwReg The target register.
218 * @return True if the entry exists, false otherwise.
219 */
Zane Shelley7f7a42d2019-10-28 13:28:31 -0500220 bool query(const Chip& i_chip, const HardwareRegister* i_hwReg) const;
Zane Shelleyd0af3582019-09-19 10:48:59 -0500221
222 /**
223 * @brief Returns the data buffer for the given chip and register.
224 * @param i_chip The target chip.
225 * @param i_hwReg The target register.
226 * @return A reference to the BitString containing the register data.
227 * @note If an entry does not exist in the cache, an entry will be
228 * created and the BitString will be initialized to 0.
229 */
Zane Shelley7f7a42d2019-10-28 13:28:31 -0500230 BitString& access(const Chip& i_chip, const HardwareRegister* i_hwReg);
Zane Shelleyd0af3582019-09-19 10:48:59 -0500231
232 /** @brief Flushes entire contents from cache. */
233 void flush();
234
235 /**
236 * @brief Removes a single register from the cache.
237 * @param i_chip The target chip.
238 * @param i_hwReg The target register.
239 */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500240 void flush(const Chip& i_chip, const HardwareRegister* i_hwReg);
Zane Shelleyd0af3582019-09-19 10:48:59 -0500241
242 private:
Zane Shelleyd0af3582019-09-19 10:48:59 -0500243 /**
244 * @brief Stores a BitStringBuffer for each HardwareRegister per Chip.
245 *
246 * The HardwareRegister keys will just be pointers to the isolation
247 * objects created in the main initialize() API. Those should exist
248 * until the main uninitialize() API is called. It is important that the
249 * cache is flushed at the beginning of the uninitialize() API before
250 * the rest of the isolation objects are deleted.
251 *
252 * The Chip keys are copies of the objects passed to the isolator
253 * because the user application is responsible for storage of the
254 * objects passed to the isolator. We don't want to chance a Chip was
255 * created as a local variable that goes out of scope, or other similar
256 * situations.
257 */
258 std::map<Chip, std::map<const HardwareRegister*, BitString*>> iv_cache;
259 };
260
261 /** This allows all HardwareRegister objects access to the cache. */
262 static Cache cv_cache;
263
264 public: // Register cache management functions.
Zane Shelleyd0af3582019-09-19 10:48:59 -0500265 /** @brief Flushes the entire register cache. */
Zane Shelley7f7a42d2019-10-28 13:28:31 -0500266 static void flushAll()
267 {
268 cv_cache.flush();
269 }
Zane Shelleyd0af3582019-09-19 10:48:59 -0500270
Zane Shelley53efc352019-10-03 21:46:39 -0500271 /**
272 * @brief Flushes this register from the cache.
273 * @param i_chip The target chip in which this register belongs.
274 */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500275 void flush(const Chip& i_chip) const
Zane Shelleyd0af3582019-09-19 10:48:59 -0500276 {
Zane Shelley83da2452019-10-25 15:45:34 -0500277 cv_cache.flush(i_chip, this);
Zane Shelleyd0af3582019-09-19 10:48:59 -0500278 }
279
Zane Shelley53efc352019-10-03 21:46:39 -0500280 private: // Register cache management functions.
Zane Shelley53efc352019-10-03 21:46:39 -0500281 /**
282 * @param i_chip The target chip in which this register belongs.
283 * @return True if an entry for this register exist in this cache.
284 */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500285 bool queryCache(const Chip& i_chip) const
Zane Shelleyd0af3582019-09-19 10:48:59 -0500286 {
Zane Shelley83da2452019-10-25 15:45:34 -0500287 return cv_cache.query(i_chip, this);
Zane Shelley53efc352019-10-03 21:46:39 -0500288 }
289
290 /**
291 * @param i_chip The target chip in which this register belongs.
292 * @return A reference to this register's BitString in cache.
293 */
Zane Shelleyfe27b652019-10-28 11:33:07 -0500294 BitString& accessCache(const Chip& i_chip) const
Zane Shelley53efc352019-10-03 21:46:39 -0500295 {
Zane Shelley83da2452019-10-25 15:45:34 -0500296 return cv_cache.access(i_chip, this);
Zane Shelleyd0af3582019-09-19 10:48:59 -0500297 }
Zane Shelleyfd3f9cc2019-07-29 15:02:24 -0500298};
299
Zane Shelley871adec2019-07-30 11:01:39 -0500300} // end namespace libhei