gem5  v21.1.0.2
gp.hh
Go to the documentation of this file.
1 /*****************************************************************************
2 
3  Licensed to Accellera Systems Initiative Inc. (Accellera) under one or
4  more contributor license agreements. See the NOTICE file distributed
5  with this work for additional information regarding copyright ownership.
6  Accellera licenses this file to you under the Apache License, Version 2.0
7  (the "License"); you may not use this file except in compliance with the
8  License. You may obtain a copy of the License at
9 
10  http://www.apache.org/licenses/LICENSE-2.0
11 
12  Unless required by applicable law or agreed to in writing, software
13  distributed under the License is distributed on an "AS IS" BASIS,
14  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
15  implied. See the License for the specific language governing
16  permissions and limitations under the License.
17 
18  *****************************************************************************/
19 
20 #ifndef __SYSTEMC_EXT_TLM_CORE_2_GENERIC_PAYLOAD_GP_HH__
21 #define __SYSTEMC_EXT_TLM_CORE_2_GENERIC_PAYLOAD_GP_HH__
22 
23 #include <typeinfo> // std::type_info
24 
25 #include "../../../utils/sc_report_handler.hh" // sc_assert
26 #include "array.hh"
27 
28 namespace tlm
29 {
30 
31 class tlm_generic_payload;
32 
33 class tlm_mm_interface
34 {
35  public:
36  virtual void free(tlm_generic_payload *) = 0;
37  virtual ~tlm_mm_interface() {}
38 };
39 
40 //---------------------------------------------------------------------------
41 // Classes and helpers for the extension mechanism
42 //---------------------------------------------------------------------------
43 // Helper function:
44 unsigned int max_num_extensions();
45 
46 // This class can be used for storing pointers to the extension classes, used
47 // in tlm_generic_payload:
48 class tlm_extension_base
49 {
50  public:
51  virtual tlm_extension_base *clone() const = 0;
52  virtual void free() { delete this; }
53  virtual void copy_from(tlm_extension_base const &) = 0;
54  protected:
55  virtual ~tlm_extension_base() {}
56  static unsigned int register_extension(const std::type_info &);
57 };
58 
59 // Base class for all extension classes, derive your extension class in
60 // the following way:
61 // class my_extension : public tlm_extension<my_extension> { ...
62 // This triggers proper extension registration during C++ static
63 // contruction time. my_extension::ID will hold the unique index in the
64 // tlm_generic_payload::m_extensions array.
65 template <typename T>
66 class tlm_extension : public tlm_extension_base
67 {
68  public:
69  virtual tlm_extension_base *clone() const = 0;
70  virtual void copy_from(tlm_extension_base const &ext) = 0;
71  virtual ~tlm_extension() {}
72  const static unsigned int ID;
73 };
74 
75 template <typename T>
76 const unsigned int tlm_extension<T>::ID =
78 
79 //---------------------------------------------------------------------------
80 // enumeration types
81 //---------------------------------------------------------------------------
82 enum tlm_command
83 {
87 };
88 
90 {
91  TLM_OK_RESPONSE = 1,
98 };
99 
100 enum tlm_gp_option
101 {
105 };
106 
107 #define TLM_BYTE_DISABLED 0x0
108 #define TLM_BYTE_ENABLED 0xff
109 
110 //---------------------------------------------------------------------------
111 // The generic payload class:
112 //---------------------------------------------------------------------------
113 
114 extern template class tlm_array<tlm_extension_base *>;
115 
117 {
118  public:
121 
122  void
123  acquire()
124  {
125  sc_assert(m_mm != 0);
126  m_ref_count++;
127  }
128 
129  void
130  release()
131  {
132  sc_assert(m_mm != 0 && m_ref_count > 0);
133  if (--m_ref_count == 0)
134  m_mm->free(this);
135  }
136 
137  int get_ref_count() const { return m_ref_count; }
138 
139  void set_mm(tlm_mm_interface *mm) { m_mm = mm; }
140  bool has_mm() const { return m_mm != 0; }
141 
142  void reset();
143 
144  private:
145  // Disabled copy ctor and assignment operator.
148 
149  public:
150  // Non-virtual deep-copying of the object.
151  void deep_copy_from(const tlm_generic_payload &other);
152 
153  // To update the state of the original generic payload from a deep copy.
154  // Assumes that "other" was created from the original by calling
155  // deep_copy_from Argument use_byte_enable_on_read determines whether to
156  // use or ignores byte enables when copying back the data array on a read
157  // command.
158 
159  void update_original_from(const tlm_generic_payload &other,
160  bool use_byte_enable_on_read=true);
161 
162  void update_extensions_from(const tlm_generic_payload &other);
163 
164  // Free all extensions. Useful when reusing a cloned transaction that
165  // doesn't have memory manager. Normal and sticky extensions are freed and
166  // extension array cleared.
167  void free_all_extensions();
168 
169  virtual ~tlm_generic_payload();
170 
171  //----------------
172  // API (including setters & getters).
173  //---------------
174 
175  // Command related method.
176  bool is_read() const { return (m_command == TLM_READ_COMMAND); }
177  void set_read() { m_command = TLM_READ_COMMAND; }
178  bool is_write() const { return (m_command == TLM_WRITE_COMMAND); }
179  void set_write() { m_command = TLM_WRITE_COMMAND; }
180  tlm_command get_command() const { return m_command; }
181  void set_command(const tlm_command command) { m_command = command; }
182 
183  // Address related methods.
184  sc_dt::uint64 get_address() const { return m_address; }
185  void set_address(const sc_dt::uint64 address) { m_address = address; }
186 
187  // Data related methods.
188  unsigned char *get_data_ptr() const { return m_data; }
189  void set_data_ptr(unsigned char *data) { m_data = data; }
190 
191  // Transaction length (in bytes) related methods.
192  unsigned int get_data_length() const { return m_length; }
193  void set_data_length(const unsigned int length) { m_length = length; }
194 
195  // Response status related methods.
196  bool is_response_ok() const { return (m_response_status > 0); }
197  bool is_response_error() const { return (m_response_status <= 0); }
199  get_response_status() const
200  {
201  return m_response_status;
202  }
203  void
204  set_response_status(const tlm_response_status response_status)
205  {
206  m_response_status = response_status;
207  }
208  std::string get_response_string() const;
209 
210  // Streaming related methods.
211  unsigned int get_streaming_width() const { return m_streaming_width; }
212  void
213  set_streaming_width(const unsigned int streaming_width)
214  {
215  m_streaming_width = streaming_width;
216  }
217 
218  // Byte enable related methods.
219  unsigned char *get_byte_enable_ptr() const { return m_byte_enable; }
220  void
221  set_byte_enable_ptr(unsigned char *byte_enable)
222  {
223  m_byte_enable = byte_enable;
224  }
225  unsigned int
226  get_byte_enable_length() const
227  {
228  return m_byte_enable_length;
229  }
230  void
231  set_byte_enable_length(const unsigned int byte_enable_length)
232  {
233  m_byte_enable_length = byte_enable_length;
234  }
235 
236  // This is the "DMI-hint" a slave can set this to true if it
237  // wants to indicate that a DMI request would be supported:
238  void
239  set_dmi_allowed(bool dmi_allowed)
240  {
241  m_dmi = dmi_allowed;
242  }
243  bool
244  is_dmi_allowed() const
245  {
246  return m_dmi;
247  }
248 
249  // Use full set of attributes in DMI/debug?
250  tlm_gp_option get_gp_option() const { return m_gp_option; }
251  void set_gp_option(const tlm_gp_option gp_opt) { m_gp_option = gp_opt; }
252 
253  private:
254  /* --------------------------------------------------------------------- */
255  /* Generic Payload attributes: */
256  /* --------------------------------------------------------------------- */
257  /* - m_command : Type of transaction. Three values supported: */
258  /* - TLM_WRITE_COMMAND */
259  /* - TLM_READ_COMMAND */
260  /* - TLM_IGNORE_COMMAND */
261  /* - m_address : Transaction base address (byte-addressing). */
262  /* - m_data : When m_command = TLM_WRITE_COMMAND contains a */
263  /* pointer to the data to be written in the target.*/
264  /* When m_command = TLM_READ_COMMAND contains a */
265  /* pointer where to copy the data read from the */
266  /* target. */
267  /* - m_length : Total number of bytes of the transaction. */
268  /* - m_response_status : This attribute indicates whether an error has */
269  /* occurred during the transaction. */
270  /* Values supported are: */
271  /* - TLM_OK_RESP */
272  /* - TLM_INCOMPLETE_RESP */
273  /* - TLM_GENERIC_ERROR_RESP */
274  /* - TLM_ADDRESS_ERROR_RESP */
275  /* - TLM_COMMAND_ERROR_RESP */
276  /* - TLM_BURST_ERROR_RESP */
277  /* - TLM_BYTE_ENABLE_ERROR_RESP */
278  /* */
279  /* - m_byte_enable : It can be used to create burst transfers where */
280  /* the address increment between each beat is greater */
281  /* than the word length of each beat, or to place */
282  /* words in selected byte lanes of a bus. */
283  /* - m_byte_enable_length : For a read or a write command, the target */
284  /* interpret the byte enable length attribute as the */
285  /* number of elements in the bytes enable array. */
286  /* - m_streaming_width : */
287  /* --------------------------------------------------------------------- */
288 
289  sc_dt::uint64 m_address;
290  tlm_command m_command;
291  unsigned char *m_data;
292  unsigned int m_length;
293  tlm_response_status m_response_status;
294  bool m_dmi;
295  unsigned char *m_byte_enable;
296  unsigned int m_byte_enable_length;
297  unsigned int m_streaming_width;
298  tlm_gp_option m_gp_option;
299 
300  public:
301  /* --------------------------------------------------------------------- */
302  /* Dynamic extension mechanism: */
303  /* --------------------------------------------------------------------- */
304  /* The extension mechanism is intended to enable initiator modules to */
305  /* optionally and transparently add data fields to the */
306  /* tlm_generic_payload. Target modules are free to check for extensions */
307  /* and may or may not react to the data in the extension fields. The */
308  /* definition of the extensions' semantics is solely in the */
309  /* responsibility of the user. */
310  /* */
311  /* The following rules apply: */
312  /* */
313  /* - Every extension class must be derived from tlm_extension, e.g.: */
314  /* class my_extension : public tlm_extension<my_extension> { ... } */
315  /* */
316  /* - A tlm_generic_payload object should be constructed after C++ */
317  /* static initialization time. This way it is guaranteed that the */
318  /* extension array is of sufficient size to hold all possible */
319  /* extensions. Alternatively, the initiator module can enforce a valid */
320  /* extension array size by calling the resize_extensions() method */
321  /* once before the first transaction with the payload object is */
322  /* initiated. */
323  /* */
324  /* - Initiators should use the the set_extension(e) or clear_extension(e)*/
325  /* methods for manipulating the extension array. The type of the */
326  /* argument must be a pointer to the specific registered extension */
327  /* type (my_extension in the above example) and is used to */
328  /* automatically locate the appropriate index in the array. */
329  /* */
330  /* - Targets can check for a specific extension by calling */
331  /* get_extension(e). e will point to zero if the extension is not */
332  /* present. */
333  /* */
334  /* --------------------------------------------------------------------- */
335 
336  // Stick the pointer to an extension into the vector, return the
337  // previous value:
338  template <typename T>
339  T *
340  set_extension(T *ext)
341  {
342  return static_cast<T *>(set_extension(T::ID, ext));
343  }
344 
345  // Non-templatized version with manual index:
346  tlm_extension_base *set_extension(
347  unsigned int index, tlm_extension_base *ext);
348 
349  // Stick the pointer to an extension into the vector, return the
350  // previous value and schedule its release.
351  template <typename T>
352  T *
353  set_auto_extension(T *ext)
354  {
355  return static_cast<T *>(set_auto_extension(T::ID, ext));
356  }
357 
358  // Non-templatized version with manual index:
359  tlm_extension_base *set_auto_extension(
360  unsigned int index, tlm_extension_base *ext);
361 
362  // Check for an extension, ext will point to 0 if not present.
363  template <typename T>
364  void get_extension(T *& ext) const { ext = get_extension<T>(); }
365  template <typename T>
366  T *
367  get_extension() const
368  {
369  return static_cast<T*>(get_extension(T::ID));
370  }
371  // Non-templatized version with manual index:
372  tlm_extension_base *get_extension(unsigned int index) const;
373 
374  // This call just removes the extension from the txn but does not
375  // call free() or tells the MM to do so it return false if there was
376  // active MM so you are now in an unsafe situation recommended use:
377  // when 100% sure there is no MM.
378  template <typename T>
379  void clear_extension(const T *ext) { clear_extension<T>(); }
380 
381  // This call just removes the extension from the txn but does not
382  // call free() or tells the MM to do so it return false if there was
383  // active MM so you are now in an unsafe situation recommended use: when
384  // 100% sure there is no MM.
385  template <typename T>
386  void clear_extension() { clear_extension(T::ID); }
387 
388  // This call removes the extension from the txn and does call free() or
389  // tells the MM to do so when the txn is finally done recommended use:
390  // when not sure there is no MM.
391  template <typename T>
392  void release_extension(T *ext)
393  {
394  release_extension<T>();
395  }
396 
397  // This call removes the extension from the txn and does call free() or
398  // tells the MM to do so when the txn is finally done recommended use:
399  // when not sure there is no MM
400  template <typename T>
401  void release_extension()
402  {
403  release_extension(T::ID);
404  }
405 
406  private:
407  // Non-templatized version with manual index
408  void clear_extension(unsigned int index);
409  // Non-templatized version with manual index
410  void release_extension(unsigned int index);
411 
412  public:
413  // Make sure the extension array is large enough. Can be called once by
414  // an initiator module (before issuing the first transaction) to make
415  // sure that the extension array is of correct size. This is only needed
416  // if the initiator cannot guarantee that the generic payload object is
417  // allocated after C++ static construction time.
418  void resize_extensions();
419 
420  private:
421  tlm_array<tlm_extension_base *> m_extensions;
422  tlm_mm_interface *m_mm;
423  unsigned int m_ref_count;
424 };
425 
426 } // namespace tlm
427 
428 #endif /* __SYSTEMC_EXT_TLM_CORE_2_GENERIC_PAYLOAD_GP_HH__ */
tlm::tlm_extension_base::register_extension
static unsigned int register_extension(const std::type_info &)
Definition: gp.cc:108
tlm::tlm_extension::clone
virtual tlm_extension_base * clone() const =0
tlm::TLM_INCOMPLETE_RESPONSE
@ TLM_INCOMPLETE_RESPONSE
Definition: gp.hh:109
tlm::tlm_extension::~tlm_extension
virtual ~tlm_extension()
Definition: gp.hh:88
data
const char data[]
Definition: circlebuf.test.cc:48
gem5::MipsISA::index
Bitfield< 30, 0 > index
Definition: pra_constants.hh:47
tlm::TLM_WRITE_COMMAND
@ TLM_WRITE_COMMAND
Definition: gp.hh:102
tlm::TLM_GENERIC_ERROR_RESPONSE
@ TLM_GENERIC_ERROR_RESPONSE
Definition: gp.hh:110
tlm::TLM_OK_RESPONSE
@ TLM_OK_RESPONSE
Definition: gp.hh:108
tlm::TLM_BYTE_ENABLE_ERROR_RESPONSE
@ TLM_BYTE_ENABLE_ERROR_RESPONSE
Definition: gp.hh:114
tlm::tlm_extension::ID
const static unsigned int ID
Definition: gp.hh:89
tlm::tlm_gp_option
tlm_gp_option
Definition: gp.hh:117
sc_assert
#define sc_assert(expr)
Definition: sc_report_handler.hh:135
tlm::tlm_extension_base::~tlm_extension_base
virtual ~tlm_extension_base()
Definition: gp.hh:72
tlm::TLM_BURST_ERROR_RESPONSE
@ TLM_BURST_ERROR_RESPONSE
Definition: gp.hh:113
tlm::tlm_extension_base
Definition: gp.hh:65
tlm::TLM_FULL_PAYLOAD_ACCEPTED
@ TLM_FULL_PAYLOAD_ACCEPTED
Definition: gp.hh:121
sc_dt::uint64
uint64_t uint64
Definition: sc_nbdefs.hh:206
tlm::TLM_FULL_PAYLOAD
@ TLM_FULL_PAYLOAD
Definition: gp.hh:120
tlm::TLM_MIN_PAYLOAD
@ TLM_MIN_PAYLOAD
Definition: gp.hh:119
tlm::tlm_extension_base::free
virtual void free()
Definition: gp.hh:69
tlm::tlm_command
tlm_command
Definition: gp.hh:99
gem5::statistics::reset
void reset()
Definition: statistics.cc:304
tlm::TLM_READ_COMMAND
@ TLM_READ_COMMAND
Definition: gp.hh:101
array.hh
mm
Definition: mm.h:8
gem5::ArmISA::ext
Bitfield< 12 > ext
Definition: misc_types.hh:427
tlm
Definition: analysis_fifo.hh:27
tlm::tlm_mm_interface::free
virtual void free(tlm_generic_payload *)=0
tlm::TLM_IGNORE_COMMAND
@ TLM_IGNORE_COMMAND
Definition: gp.hh:103
gem5::SparcISA::mm
Bitfield< 7, 6 > mm
Definition: misc.hh:132
tlm::tlm_extension_base::clone
virtual tlm_extension_base * clone() const =0
tlm::max_num_extensions
unsigned int max_num_extensions()
Definition: gp.cc:102
tlm::TLM_COMMAND_ERROR_RESPONSE
@ TLM_COMMAND_ERROR_RESPONSE
Definition: gp.hh:112
tlm::tlm_generic_payload
Definition: gp.hh:133
gem5::RiscvISA::x
Bitfield< 3 > x
Definition: pagetable.hh:73
tlm::tlm_extension
Definition: gp.hh:83
tlm::tlm_array
Definition: array.hh:60
tlm::tlm_extension_base::copy_from
virtual void copy_from(tlm_extension_base const &)=0
tlm::TLM_ADDRESS_ERROR_RESPONSE
@ TLM_ADDRESS_ERROR_RESPONSE
Definition: gp.hh:111
tlm::tlm_mm_interface::~tlm_mm_interface
virtual ~tlm_mm_interface()
Definition: gp.hh:54
tlm::tlm_mm_interface
Definition: gp.hh:50
tlm::tlm_extension::copy_from
virtual void copy_from(tlm_extension_base const &ext)=0
tlm::tlm_response_status
tlm_response_status
Definition: gp.hh:106
gem5::ps2::keyboard::ID
const std::vector< uint8_t > ID
Definition: types.cc:52

Generated on Tue Sep 21 2021 12:25:56 for gem5 by doxygen 1.8.17