SST  13.0.0
StructuralSimulationToolkit
simpleMem.h
1 // -*- mode: c++ -*-
2 // Copyright 2009-2023 NTESS. Under the terms
3 // of Contract DE-NA0003525 with NTESS, the U.S.
4 // Government retains certain rights in this software.
5 //
6 // Copyright (c) 2009-2023, NTESS
7 // All rights reserved.
8 //
9 // This file is part of the SST software package. For license
10 // information, see the LICENSE file in the top level directory of the
11 // distribution.
12 //
13 
14 #ifndef SST_CORE_INTERFACES_SIMPLEMEM_H
15 #define SST_CORE_INTERFACES_SIMPLEMEM_H
16 
17 // DEPRECATION NOTICE
18 // This interface is deprecated and will be removed in SST 13.
19 // The StandardMem interface (stdMem.h) provides an expanded set of functionality.
20 // Please use StandardMem instead.
21 
22 #include "sst/core/link.h"
23 #include "sst/core/params.h"
24 #include "sst/core/sst_types.h"
25 #include "sst/core/ssthandler.h"
26 #include "sst/core/subcomponent.h"
27 #include "sst/core/warnmacros.h"
28 
29 #include <atomic>
30 #include <map>
31 #include <string>
32 #include <utility>
33 
34 namespace SST {
35 
36 class Component;
37 class Event;
38 
39 namespace Interfaces {
40 
41 /**
42  * Simplified, generic interface to Memory models
43  */
44 class __attribute__((deprecated(
45  "The SimpleMem interface is deprecated in favor of the StandardMem interface (sst/core/interfaces/stdMem.h). "
46  "Please switch interfaces. This interface will be removed in SST 13."))) SimpleMem : public SubComponent
47 {
48 public:
49  class Request; // Needed for HandlerBase definition
50  /**
51  Base handler for request handling.
52  */
54 
55  /**
56  Used to create handlers for request handling. The callback
57  function is expected to be in the form of:
58 
59  void func(Request* event)
60 
61  In which case, the class is created with:
62 
63  new SimpleMem::Handler<classname>(this, &classname::function_name)
64 
65  Or, to add static data, the callback function is:
66 
67  void func(Request* event, dataT data)
68 
69  and the class is created with:
70 
71  new SimpleMem::Handler<classname, dataT>(this, &classname::function_name, data)
72  */
73  template <typename classT, typename dataT = void>
75 
76  DISABLE_WARN_DEPRECATED_DECLARATION
77  SST_ELI_REGISTER_SUBCOMPONENT_API(SST::Interfaces::SimpleMem,TimeConverter*,HandlerBase*)
78  REENABLE_WARNING
79 
80  /** All Addresses can be 64-bit */
81  typedef uint64_t Addr;
82 
83  /**
84  * Represents both memory requests and responses.
85  */
86  class Request
87  {
88  public:
89  typedef uint64_t id_t; /*!< Request ID type */
90  typedef uint32_t flags_t; /*!< Flag type */
91 
92  /**
93  * Commands and responses possible with a Request object
94  */
95  typedef enum {
96  Read, /*!< Issue a Read from Memory */
97  Write, /*!< Issue a Write to Memory */
98  ReadResp, /*!< Response from Memory to a Read */
99  WriteResp, /*!< Response from Memory to a Write */
100  FlushLine, /*!< Cache flush request - writeback specified line throughout memory system */
101  FlushLineInv, /*!< Cache flush request - writeback and invalidate specified line throughout memory system */
102  FlushLineResp, /*!< Response to FlushLine; flag F_FLUSH_SUCCESS indicates success or failure */
103  Inv, /*!< Notification of L1 cache invalidation to core */
104  TxBegin, /*!< Start a new transaction */
105  TxEnd, /*!< End the current lowest transaction */
106  TxResp,
107  TxAbort,
108  TxCommit,
109  CustomCmd /*!< Custom memory command: Must also set custCmd opcode */
110  } Command;
111 
112  /**
113  * Flags to specify conditions on a Request
114  */
115  typedef enum {
116  F_NONCACHEABLE = 1 << 1, /*!< This request should not be cached */
117  F_LOCKED = 1 << 2, /*!< This request should be locked. A LOCKED read should be soon followed by a LOCKED
118  write (to unlock) */
119  F_LLSC = 1 << 3,
120  F_LLSC_RESP = 1 << 4,
121  F_FLUSH_SUCCESS =
122  1 << 5, /*!< This flag is set if the flush was successful. Flush may fail due to LOCKED lines */
123  F_TRANSACTION = 1 << 6
124  } Flags;
125 
126  /** Type of the payload or data */
127  typedef std::vector<uint8_t> dataVec;
128 
129  Command cmd; /*!< Command to issue */
130  std::vector<Addr> addrs; /*!< Target address(es) */
131  Addr addr; /*!< Target address - DEPRECATED but included for backward compatibility, defaults to addrs[0] */
132  size_t size; /*!< Size of this request or response */
133  dataVec data; /*!< Payload data (for Write, or ReadResp) */
134  flags_t flags; /*!< Flags associated with this request or response */
135  flags_t
136  memFlags; /*!< Memory flags - ignored by caches except to be passed through with request to main memory */
137  id_t id; /*!< Unique ID to identify responses with requests */
138  Addr instrPtr; /*!< Instruction pointer associated with the operation */
139  Addr virtualAddr; /*!< Virtual address associated with the operation */
140  uint32_t custOpc; /*!< Custom command opcode for CustomdCmd type commands */
141 
142  /** Constructor */
143  Request(Command cmd, Addr addr, size_t size, dataVec& data, flags_t flags = 0, flags_t memFlags = 0) :
144  cmd(cmd),
145  addr(addr),
146  size(size),
147  data(data),
148  flags(flags),
149  memFlags(memFlags),
150  instrPtr(0),
151  virtualAddr(0),
152  custOpc(0xFFFF)
153  {
154  addrs.push_back(addr);
155  id = main_id++;
156  }
157 
158  /** Constructor */
159  Request(Command cmd, Addr addr, size_t size, flags_t flags = 0, flags_t memFlags = 0) :
160  cmd(cmd),
161  addr(addr),
162  size(size),
163  flags(flags),
164  memFlags(memFlags),
165  instrPtr(0),
166  virtualAddr(0),
167  custOpc(0xFFFF)
168  {
169  addrs.push_back(addr);
170  id = main_id++;
171  }
172 
173  /** Constructor */
175  Command cmd, Addr addr, size_t size, dataVec& data, uint32_t Opc, flags_t flags = 0, flags_t memFlags = 0) :
176  cmd(cmd),
177  addr(addr),
178  size(size),
179  data(data),
180  flags(flags),
181  memFlags(memFlags),
182  instrPtr(0),
183  virtualAddr(0),
184  custOpc(Opc)
185  {
186  addrs.push_back(addr);
187  id = main_id++;
188  }
189 
190  /** Constructor */
191  Request(Command cmd, Addr addr, size_t size, uint32_t Opc, flags_t flags = 0, flags_t memFlags = 0) :
192  cmd(cmd),
193  addr(addr),
194  size(size),
195  flags(flags),
196  memFlags(memFlags),
197  instrPtr(0),
198  virtualAddr(0),
199  custOpc(Opc)
200  {
201  addrs.push_back(addr);
202  id = main_id++;
203  }
204 
205  void addAddress(Addr addr) { addrs.push_back(addr); }
206 
207  /**
208  * @param[in] data_in
209  * @brief Set the contents of the payload / data field.
210  */
211  void setPayload(const std::vector<uint8_t>& data_in) { data = data_in; }
212 
213  /**
214  * @param[in] data_in
215  * @brief Set the contents of the payload / data field.
216  */
217  void setPayload(uint8_t* data_in, size_t len)
218  {
219  data.resize(len);
220  for ( size_t i = 0; i < len; i++ ) {
221  data[i] = data_in[i];
222  }
223  }
224 
225  /**
226  * @param[in] newVA
227  * @brief Set the virtual address associated with the operation
228  */
229  void setVirtualAddress(const Addr newVA) { virtualAddr = newVA; }
230 
231  /**
232  * @returns the virtual address associated with the operation
233  */
234  uint64_t getVirtualAddress() { return (uint64_t)virtualAddr; }
235 
236  /**
237  * @param[in] newIP
238  * @brief Sets the instruction pointer associated with the operation
239  */
240  void setInstructionPointer(const Addr newIP) { instrPtr = newIP; }
241 
242  /**
243  * @returns the instruction pointer associated with the operation
244  */
245  Addr getInstructionPointer() { return instrPtr; }
246 
247  /**
248  * @brief Clears the flags associated with the operation
249  */
250  void clearFlags(void) { flags = 0; }
251 
252  /**
253  * @param[in] inValue Should be one of the flags beginning with F_ in simpleMem
254  */
255  void setFlags(flags_t inValue) { flags = flags | inValue; }
256 
257  /**
258  * @returns the flags associated with the operation
259  */
260  flags_t getFlags(void) { return flags; }
261 
262  /**
263  * @brief Clears the memory flags associated with the operation
264  */
265  void clearMemFlags(void) { memFlags = 0; }
266 
267  /**
268  * @param[in] inValue Should be one of the flags beginning with F_ in simpleMem
269  */
270  void setMemFlags(flags_t inValue) { memFlags = memFlags | inValue; }
271 
272  /**
273  * @returns the memory flags associated with the operation
274  */
275  flags_t getMemFlags(void) { return memFlags; }
276 
277  /**
278  * @returns the custom opcode for custom request types
279  */
280  uint32_t getCustomOpc(void) { return custOpc; }
281 
282  private:
283  static std::atomic<id_t> main_id;
284  };
285 
286  /** Constructor, designed to be used via 'loadUserSubComponent and loadAnonymousSubComponent'. */
287  SimpleMem(SST::ComponentId_t id, Params& UNUSED(params)) : SubComponent(id) {}
288 
289  /** Second half of building the interface.
290  * Initialize with link name name, and handler, if any
291  * @return true if the link was able to be configured.
292  */
293  virtual bool initialize(const std::string& linkName, HandlerBase* handler = nullptr) = 0;
294 
295  /**
296  * Sends a memory-based request during the init() phase
297  */
298  virtual void sendInitData(Request* req) = 0;
299 
300  /**
301  * Sends a generic Event during the init() phase
302  * (Mostly acts as a passthrough)
303  * @see SST::Link::sendInitData()
304  */
305  virtual void sendInitData(SST::Event* ev) { getLink()->sendInitData(ev); }
306 
307  /**
308  * Receive any data during the init() phase.
309  * @see SST::Link::recvInitData()
310  */
311  virtual SST::Event* recvInitData() { return getLink()->recvInitData(); }
312 
313  /**
314  * Returns a handle to the underlying SST::Link
315  */
316  virtual SST::Link* getLink(void) const = 0;
317 
318  /**
319  * Send a Request to the other side of the link.
320  */
321  virtual void sendRequest(Request* req) = 0;
322 
323  /**
324  * Receive a Request response from the side of the link.
325  *
326  * Use this method for polling-based applications.
327  * Register a handler for push-based notification of responses.
328  *
329  * @return nullptr if nothing is available.
330  * @return Pointer to a Request response (that should be deleted)
331  */
332  virtual Request* recvResponse(void) = 0;
333 
334  /**
335  * Get cache/memory line size from the memory system
336  *
337  * The memory system should provide this and it should be
338  * valid after the init() phase is complete, so processors
339  * can call this function during setup().
340  *
341  * For backward compatibiity, the function returns 0 by default.
342  * Eventually, interfaces will be required to implement this
343  * function.
344  *
345  * @return 0 if the interface does not provide this capability
346  * @return line size of the memory system
347  */
348  virtual Addr getLineSize() { return 0; }
349 };
350 
351 } // namespace Interfaces
352 } // namespace SST
353 
354 #endif // SST_CORE_INTERFACES_SIMPLEMEM_H
virtual SST::Event * recvInitData()
Receive any data during the init() phase.
Definition: simpleMem.h:311
size_t size
Definition: simpleMem.h:132
uint32_t flags_t
Definition: simpleMem.h:90
Request(Command cmd, Addr addr, size_t size, uint32_t Opc, flags_t flags=0, flags_t memFlags=0)
Constructor.
Definition: simpleMem.h:191
Addr getInstructionPointer()
Definition: simpleMem.h:245
Handlers with 1 handler defined argument to callback from caller.
Definition: ssthandler.h:170
Command
Commands and responses possible with a Request object.
Definition: simpleMem.h:95
Represents both memory requests and responses.
Definition: simpleMem.h:86
std::vector< Addr > addrs
Definition: simpleMem.h:130
Handler class with user-data argument.
Definition: ssthandler.h:219
DISABLE_WARN_DEPRECATED_DECLARATION REENABLE_WARNING typedef uint64_t Addr
All Addresses can be 64-bit.
Definition: simpleMem.h:81
A class to convert between a component&#39;s view of time and the core&#39;s view of time.
Definition: timeConverter.h:26
uint64_t getVirtualAddress()
Definition: simpleMem.h:234
Command cmd
Definition: simpleMem.h:129
dataVec data
Definition: simpleMem.h:133
Definition: action.cc:18
void setFlags(flags_t inValue)
Definition: simpleMem.h:255
std::vector< uint8_t > dataVec
Type of the payload or data.
Definition: simpleMem.h:127
Request(Command cmd, Addr addr, size_t size, dataVec &data, uint32_t Opc, flags_t flags=0, flags_t memFlags=0)
Constructor.
Definition: simpleMem.h:174
void setInstructionPointer(const Addr newIP)
Sets the instruction pointer associated with the operation.
Definition: simpleMem.h:240
Generic interface to Memory models.
Definition: stdMem.h:69
void setPayload(const std::vector< uint8_t > &data_in)
Set the contents of the payload / data field.
Definition: simpleMem.h:211
Definition: simpleMem.h:103
flags_t flags
Definition: simpleMem.h:134
Simplified, generic interface to Memory models.
Definition: simpleMem.h:44
flags_t getMemFlags(void)
Definition: simpleMem.h:275
void clearFlags(void)
Clears the flags associated with the operation.
Definition: simpleMem.h:250
Addr instrPtr
Definition: simpleMem.h:138
Request(Command cmd, Addr addr, size_t size, dataVec &data, flags_t flags=0, flags_t memFlags=0)
Constructor.
Definition: simpleMem.h:143
virtual Addr getLineSize()
Get cache/memory line size from the memory system.
Definition: simpleMem.h:348
Addr virtualAddr
Definition: simpleMem.h:139
flags_t getFlags(void)
Definition: simpleMem.h:260
virtual void sendInitData(SST::Event *ev)
Sends a generic Event during the init() phase (Mostly acts as a passthrough)
Definition: simpleMem.h:305
void setMemFlags(flags_t inValue)
Definition: simpleMem.h:270
Parameter store.
Definition: params.h:55
void setVirtualAddress(const Addr newVA)
Set the virtual address associated with the operation.
Definition: simpleMem.h:229
uint32_t getCustomOpc(void)
Definition: simpleMem.h:280
void setPayload(uint8_t *data_in, size_t len)
Set the contents of the payload / data field.
Definition: simpleMem.h:217
Base class for Events - Items sent across links to communicate between components.
Definition: event.h:34
SimpleMem(SST::ComponentId_t id, Params &UNUSED(params))
Constructor, designed to be used via &#39;loadUserSubComponent and loadAnonymousSubComponent&#39;.
Definition: simpleMem.h:287
uint32_t custOpc
Definition: simpleMem.h:140
Addr addr
Definition: simpleMem.h:131
SubComponent is a class loadable through the factory which allows dynamic functionality to be added t...
Definition: subcomponent.h:28
uint64_t id_t
Definition: simpleMem.h:89
id_t id
Definition: simpleMem.h:137
void clearMemFlags(void)
Clears the memory flags associated with the operation.
Definition: simpleMem.h:265
Request(Command cmd, Addr addr, size_t size, flags_t flags=0, flags_t memFlags=0)
Constructor.
Definition: simpleMem.h:159
flags_t memFlags
Definition: simpleMem.h:136