Browse Source

Merge branch 'develop' of https://git.minres.com/SystemC/SystemC-Components.git into develop

Eyck Jentzsch 3 weeks ago
parent
commit
d334928b36

+ 25
- 4
incl/scc/configurable_tracer.h View File

@@ -38,10 +38,13 @@
38 38
 #include <cci_configuration>
39 39
 
40 40
 namespace scc {
41
-
41
+/**
42
+ *
43
+ */
42 44
 class configurable_tracer : public scc::tracer {
43 45
 public:
44 46
     /**
47
+     * constructs a tracer object
45 48
      *
46 49
      * @param name basename of the trace file(s)
47 50
      * @param type type of trace file for transactions
@@ -49,24 +52,42 @@ public:
49 52
      * @param default value of attribute enableTracing if not defined by module or CCIs
50 53
      */
51 54
     configurable_tracer(const std::string&&, file_type, bool = true, bool = false);
52
-
55
+    /**
56
+     * constructs a tracer object
57
+     *
58
+     * @param name basename of the trace file(s)
59
+     * @param type type of trace file for transactions
60
+     * @param enable enable VCD (signal based) tracing
61
+     * @param default value of attribute enableTracing if not defined by module or CCIs
62
+     */
53 63
     configurable_tracer(const std::string& name, file_type type, bool enable_vcd = true, bool default_enable = false)
54 64
     :configurable_tracer(std::string(name), type, enable_vcd, default_enable)
55 65
     {}
56
-
66
+    /**
67
+     * destructor
68
+     */
57 69
     ~configurable_tracer();
58
-
70
+    /**
71
+     * adds default trace control attribute of name 'enableTracing' to each sc_module in a design hierarchy
72
+     */
59 73
     void add_control() {
60 74
         for (auto *o : sc_core::sc_get_top_level_objects(sc_core::sc_curr_simcontext)) augment_object_hierarchical(o);
61 75
     }
62 76
 
63 77
 protected:
78
+    //! the default for tracing if no attribute is configured
64 79
     const bool default_trace_enable;
80
+    //! depth-first walk thru the design hierarchy and trace signals resp. call trace() function
65 81
     void descend(const sc_core::sc_object *) override;
82
+    //! check for existence of 'enableTracing' attribute and return value of default otherwise
66 83
     bool get_trace_enabled(const sc_core::sc_object *, bool = false);
84
+    //! add the 'enableTracing' attribute to sc_module
67 85
     void augment_object_hierarchical(const sc_core::sc_object *);
86
+    //! the originator of cci values
68 87
     cci::cci_originator cci_originator;
88
+    //! the cci broker
69 89
     cci::cci_broker_handle cci_broker;
90
+    //! array of created cci parameter
70 91
     std::vector<cci::cci_param_untyped *> params;
71 92
 };
72 93
 

+ 64
- 19
incl/scc/configurer.h View File

@@ -13,12 +13,6 @@
13 13
  * See the License for the specific language governing permissions and
14 14
  * limitations under the License.
15 15
  *******************************************************************************/
16
-/*
17
- * configurer.h
18
- *
19
- *  Created on: 27.09.2017
20
- *      Author: eyck
21
- */
22 16
 
23 17
 #ifndef _SYSC_CONFIGURER_H_
24 18
 #define _SYSC_CONFIGURER_H_
@@ -29,29 +23,71 @@
29 23
 #include <json/json.h>
30 24
 
31 25
 namespace scc {
32
-
26
+/**
27
+ * a class to configure a design hierarchy using a JSON input file
28
+ */
33 29
 class configurer : public sc_core::sc_object {
34 30
 public:
35 31
     using base_type = sc_core::sc_object;
36
-
32
+    /**
33
+     * create a configurer using a JSON input file
34
+     * @param filename
35
+     */
37 36
     configurer(const std::string &filename);
38
-
37
+    /**
38
+     * no default constructor
39
+     */
39 40
     configurer() = delete;
40
-
41
+    /**
42
+     * no copy constructor
43
+     *
44
+     * @param
45
+     */
41 46
     configurer(const configurer &) = delete;
42
-
47
+    /**
48
+     * no move constructor
49
+     *
50
+     * @param
51
+     */
43 52
     configurer(configurer &&) = delete;
44
-
53
+    /**
54
+     * no copy assignment
55
+     *
56
+     * @param
57
+     * @return
58
+     */
45 59
     configurer &operator=(const configurer &) = delete;
46
-
60
+    /**
61
+     * no move assignment
62
+     *
63
+     * @param
64
+     * @return
65
+     */
47 66
     configurer &operator=(configurer &&) = delete;
48
-
67
+    /**
68
+     * configure the design hierarchy using the input file
69
+     */
49 70
     void configure();
50
-
71
+    /**
72
+     * dump the design hierarchy as text
73
+     *
74
+     * @param os the output stream, std::cout by default
75
+     * @param obj if not null specifies the root object of the dump
76
+     */
51 77
     void dump_hierarchy(std::ostream &os = std::cout, sc_core::sc_object *obj = nullptr);
52
-
78
+    /**
79
+     * dump the parameters of a design hierarchy to output stream
80
+     *
81
+     * @param os the output stream, std::cout by default
82
+     * @param obj if not null specifies the root object of the dump
83
+     */
53 84
     void dump_configuration(std::ostream &os = std::cout, sc_core::sc_object *obj = nullptr);
54
-
85
+    /**
86
+     * set a value a some attribute (sc_attribute or cci_param)
87
+     *
88
+     * @param hier_name the hierarchical name of the attribute
89
+     * @param value the value to put
90
+     */
55 91
     template <typename T> void set_value(const std::string &hier_name, T value) {
56 92
         cci::cci_param_handle param_handle = cci_broker.get_param_handle(hier_name);
57 93
         if (param_handle.is_valid()) {
@@ -70,9 +106,18 @@ public:
70 106
             }
71 107
         }
72 108
     }
73
-
109
+    /**
110
+     * set a value of an sc_attribute from given configuration
111
+     *
112
+     * @param attr_base
113
+     * @param owner
114
+     */
74 115
     void set_configuration_value(sc_core::sc_attr_base *attr_base, sc_core::sc_object *owner);
75
-
116
+    /**
117
+     * find the configurer in the design hierarchy
118
+     *
119
+     * @return
120
+     */
76 121
     static configurer &instance() {
77 122
         configurer *inst = dynamic_cast<configurer *>(sc_core::sc_find_object("configurer"));
78 123
         sc_assert("No configurer instantiated when using it" && inst != nullptr);

+ 27
- 11
incl/scc/ext_attribute.h View File

@@ -13,12 +13,6 @@
13 13
  * See the License for the specific language governing permissions and
14 14
  * limitations under the License.
15 15
  *******************************************************************************/
16
-/*
17
- * atrribute_mixin.h
18
- *
19
- *  Created on: 27.09.2017
20
- *      Author: eyck
21
- */
22 16
 
23 17
 #ifndef _SCC_EXT_ATTRIBUTE_H_
24 18
 #define _SCC_EXT_ATTRIBUTE_H_
@@ -27,28 +21,50 @@
27 21
 #include "utilities.h"
28 22
 
29 23
 namespace scc {
24
+/**
25
+ * extended attribute inheriting from sc_attribute
26
+ */
30 27
 template <typename T> class ext_attribute : public sc_core::sc_attribute<T> {
31 28
 public:
32 29
     using base_type = sc_core::sc_attribute<T>;
33
-
30
+    /**
31
+     * create an extended attribute based on name and owner with default value
32
+     *
33
+     * @param name_
34
+     * @param owner
35
+     */
34 36
     ext_attribute(const std::string &name_, sc_core::sc_module *owner)
35 37
     : base_type(name_)
36 38
     , owner(owner) {
37 39
         owner->add_attribute(*this);
38 40
         configurer::instance().set_configuration_value(this, owner);
39 41
     }
40
-
42
+    /**
43
+     * create an extended attribute based on name, value and owner
44
+     *
45
+     * @param name_
46
+     * @param value_
47
+     * @param owner
48
+     */
41 49
     ext_attribute(const std::string &name_, const T &value_, sc_core::sc_module *owner)
42 50
     : base_type(name_, value_)
43 51
     , owner(owner) {
44 52
         owner->add_attribute(*this);
45 53
         configurer::instance().set_configuration_value(this, owner);
46 54
     }
47
-
55
+    /**
56
+     * no copy constructor
57
+     *
58
+     * @param a
59
+     */
48 60
     ext_attribute(const ext_attribute<T> &a) = delete;
49
-
61
+    /**
62
+     * a default destructor
63
+     */
50 64
     ~ext_attribute() = default;
51
-
65
+    /**
66
+     * the owner of this attribute (a backward reference)
67
+     */
52 68
     const sc_core::sc_module *owner;
53 69
 };
54 70
 };

+ 17
- 10
incl/scc/initiator_mixin.h View File

@@ -23,7 +23,9 @@
23 23
 #include <tlm>
24 24
 
25 25
 namespace scc {
26
-
26
+/**
27
+ * an initiator socket mixin adding default implementation of callback functions similar to tlm::simple_initiator_socket
28
+ */
27 29
 template <typename BASE_TYPE, typename TYPES = tlm::tlm_base_protocol_types> class initiator_mixin : public BASE_TYPE {
28 30
 public:
29 31
     using transaction_type = typename TYPES::tlm_payload_type;
@@ -33,26 +35,31 @@ public:
33 35
     using bw_interface_type = tlm::tlm_bw_transport_if<TYPES>;
34 36
 
35 37
 public:
38
+    /**
39
+     * the default constructor automatically generating a name
40
+     */
36 41
     initiator_mixin()
37
-    : BASE_TYPE(sc_core::sc_gen_unique_name("initiator_mixin_socket"))
38
-    , bw_if(this->name()) {
39
-        this->m_export.bind(bw_if);
40
-    }
41
-
42
-    explicit initiator_mixin(const char *n)
43
-    : BASE_TYPE(n)
42
+    : initiator_mixin(sc_core::sc_gen_unique_name("initiator_mixin_socket")) {}
43
+    /**
44
+     * constructor with explicit instance name
45
+     *
46
+     * @param name the instance name
47
+     */
48
+    explicit initiator_mixin(const sc_core::sc_module_name &name)
49
+    : BASE_TYPE(name)
44 50
     , bw_if(this->name()) {
45 51
         this->m_export.bind(bw_if);
46 52
     }
47 53
     /**
54
+     * register a non-blocking backward path callback function
48 55
      *
49 56
      * @param cb the callback function
50 57
      */
51
-    void
52
-    register_nb_transport_bw(std::function<sync_enum_type(transaction_type &, phase_type &, sc_core::sc_time &)> cb) {
58
+    void register_nb_transport_bw(std::function<sync_enum_type(transaction_type &, phase_type &, sc_core::sc_time &)> cb) {
53 59
         bw_if.set_transport_function(cb);
54 60
     }
55 61
     /**
62
+     * register an invalidate DMI callback function
56 63
      *
57 64
      * @param cb the callback function
58 65
      */

+ 14
- 9
incl/scc/memory.h View File

@@ -13,12 +13,6 @@
13 13
  * See the License for the specific language governing permissions and
14 14
  * limitations under the License.
15 15
  *******************************************************************************/
16
-/*
17
- * memory.h
18
- *
19
- *  Created on: Nov 4, 2016
20
- *      Author: eyck
21
- */
22 16
 
23 17
 #ifndef _SYSC_MEMORY_H_
24 18
 #define _SYSC_MEMORY_H_
@@ -34,20 +28,31 @@
34 28
 
35 29
 namespace scc {
36 30
 
37
-// simple memory model
38
-// TODO: add attributes/parameters to configure access time and type (DMI allowed, read only, etc)
31
+/**
32
+ *  simple memory model
33
+ *
34
+ *  TODO: add some more attributes/parameters to configure access time and type (DMI allowed, read only, etc)
35
+ */
39 36
 template <unsigned long long SIZE, unsigned BUSWIDTH = 32, bool LOG_ACCESS = false>
40 37
 class memory : public sc_core::sc_module {
41 38
 public:
39
+    //! the target socket to connect to TLM
42 40
     scc::target_mixin<tlm::tlm_target_socket<BUSWIDTH>> target;
43
-
41
+    /**
42
+     * constructor with explicit instance name
43
+     *
44
+     * @param nm
45
+     */
44 46
     memory(const sc_core::sc_module_name &nm);
45 47
 
46 48
 protected:
49
+    //! the real memory structure
47 50
     util::sparse_array<uint8_t, SIZE> mem;
48 51
 
49 52
 private:
53
+    //!! handle the memory operation independent on interface function used
50 54
     int handle_operation(tlm::tlm_generic_payload &trans);
55
+    //! handle the dmi functionality
51 56
     bool handle_dmi(tlm::tlm_generic_payload &gp, tlm::tlm_dmi &dmi_data);
52 57
 };
53 58
 

+ 15
- 2
incl/scc/perf_estimator.h View File

@@ -21,8 +21,13 @@
21 21
 #include <systemc>
22 22
 
23 23
 namespace scc {
24
-
24
+/**
25
+ * a performance estimator
26
+ * it records the time stamps a various time points (start and end of simulation) and calculates
27
+ * some performance figures
28
+ */
25 29
 class perf_estimator : public sc_core::sc_module {
30
+    //! some internal data structure to record a time stamp
26 31
     struct time_stamp {
27 32
         boost::posix_time::ptime wall_clock_stamp;
28 33
         double proc_clock_stamp;
@@ -44,14 +49,22 @@ class perf_estimator : public sc_core::sc_module {
44 49
     };
45 50
 
46 51
 public:
52
+    //! yes, we have some SystemC processes
47 53
     SC_HAS_PROCESS(perf_estimator);// NOLINT
54
+    /**
55
+     * default constructor
56
+     */
48 57
     perf_estimator();
58
+    /**
59
+     * the destructor
60
+     */
49 61
     virtual ~perf_estimator();
50 62
 
51 63
 protected:
64
+    //! SystemC callbacks
52 65
     void start_of_simulation() override;
53 66
     void end_of_simulation() override;
54
-
67
+    //! the recorded time stamps
55 68
     time_stamp sos, eos;
56 69
 };
57 70
 

+ 141
- 64
incl/scc/register.h View File

@@ -13,12 +13,6 @@
13 13
  * See the License for the specific language governing permissions and
14 14
  * limitations under the License.
15 15
  *******************************************************************************/
16
-/*
17
- * register.h
18
- *
19
- *  Created on: Nov 16, 2016
20
- *      Author: developer
21
- */
22 16
 
23 17
 #ifndef _SYSC_REGISTER_H_
24 18
 #define _SYSC_REGISTER_H_
@@ -36,7 +30,9 @@
36 30
 namespace scc {
37 31
 
38 32
 namespace impl {
39
-
33
+/**
34
+ * some template classes and functions to calculate mask values
35
+ */
40 36
 template <typename T, bool = std::is_integral<T>::value> class helper {};
41 37
 
42 38
 template <typename T> class helper<T, true> {
@@ -59,18 +55,24 @@ template <typename Type> constexpr Type get_max_uval() {
59 55
     return std::numeric_limits<Type>::is_signed ? -1 : std::numeric_limits<Type>::max();
60 56
 }
61 57
 
58
+/**
59
+ * a simple register implementation taking a certain data type. The sc_register does not hold the value itself,
60
+ * this needs to be provided. It only provides som resource access interface and handled callbacks for read and
61
+ * write accesses
62
+ */
62 63
 template <typename DATATYPE>
63 64
 class sc_register : public sc_core::sc_object, public resource_access_if, public traceable {
64 65
 public:
65 66
     using this_type = class sc_register<DATATYPE>;
66 67
     /**
68
+     * the constructor
67 69
      *
68
-     * @param nm
69
-     * @param storage
70
-     * @param reset_val
71
-     * @param owner
72
-     * @param rdmask
73
-     * @param wrmask
70
+     * @param nm the instance name
71
+     * @param storage the storage data structure
72
+     * @param reset_val the reset value
73
+     * @param owner the owning object which needs to implement the resettable interface
74
+     * @param rdmask the SW read mask
75
+     * @param wrmask the SW write mask
74 76
      */
75 77
     sc_register(sc_core::sc_module_name nm, DATATYPE &storage, const DATATYPE reset_val, resetable &owner,
76 78
                 DATATYPE rdmask = get_max_uval<DATATYPE>(), DATATYPE wrmask = get_max_uval<DATATYPE>())
@@ -81,7 +83,9 @@ public:
81 83
     , storage(storage) {
82 84
         owner.register_resource(this);
83 85
     }
84
-
86
+    /**
87
+     * the destructor
88
+     */
85 89
     ~sc_register() = default;
86 90
 
87 91
     /**
@@ -90,7 +94,7 @@ public:
90 94
      */
91 95
     size_t size() const override { return sizeof(DATATYPE); }
92 96
     /**
93
-     *
97
+     * reset the register
94 98
      */
95 99
     void reset() override {
96 100
         DATATYPE r(res_val);
@@ -98,11 +102,13 @@ public:
98 102
         storage = r;
99 103
     }
100 104
     /**
105
+     * write function from resource_access_if
101 106
      *
102
-     * @param data
103
-     * @param length
104
-     * @param offset
105
-     * @return
107
+     * @param data data to write
108
+     * @param length size of data to write
109
+     * @param offset offset within register
110
+     * @param d annotated delay if loosly-timed access
111
+     * @return true if access is successful
106 112
      */
107 113
     bool write(const uint8_t *data, size_t length, uint64_t offset, sc_core::sc_time d) override {
108 114
         assert("Access out of range" && offset + length <= sizeof(DATATYPE));
@@ -114,11 +120,13 @@ public:
114 120
         return true;
115 121
     }
116 122
     /**
123
+     * read function from resource_access_if
117 124
      *
118
-     * @param data
119
-     * @param length
120
-     * @param offset
121
-     * @return
125
+     * @param data data buffer to read
126
+     * @param length size of data to read
127
+     * @param offset offset within register
128
+     * @param d annotated delay if loosly-timed access
129
+     * @return true if access is successful
122 130
      */
123 131
     bool read(uint8_t *data, size_t length, uint64_t offset, sc_core::sc_time d) const override {
124 132
         assert("Access out of range" && offset + length <= sizeof(DATATYPE));
@@ -132,11 +140,12 @@ public:
132 140
         return true;
133 141
     }
134 142
     /**
143
+     * debug write function from resource_access_if
135 144
      *
136
-     * @param data
137
-     * @param length
138
-     * @param offset
139
-     * @return
145
+     * @param data data to write
146
+     * @param length size of data to write
147
+     * @param offset offset within register
148
+     * @return true if access is successful
140 149
      */
141 150
     bool write_dbg(const uint8_t *data, size_t length, uint64_t offset) override {
142 151
         assert("Offset out of range" && offset == 0);
@@ -145,11 +154,12 @@ public:
145 154
         return true;
146 155
     }
147 156
     /**
157
+     * debug read function from resource_access_if
148 158
      *
149
-     * @param data
150
-     * @param length
151
-     * @param offset
152
-     * @return
159
+     * @param data data buffer to read
160
+     * @param length size of data to read
161
+     * @param offset offset within register
162
+     * @return true if access is successful
153 163
      */
154 164
     bool read_dbg(uint8_t *data, size_t length, uint64_t offset) const override {
155 165
         assert("Offset out of range" && offset == 0);
@@ -158,22 +168,25 @@ public:
158 168
         return true;
159 169
     }
160 170
     /**
161
-     *
171
+     * cast operator
162 172
      */
163 173
     operator DATATYPE() const { return storage; }
164 174
     /**
175
+     * get the storage
165 176
      *
166
-     * @return
177
+     * @return copy of the underlying datatype
167 178
      */
168 179
     DATATYPE get() const { return storage; }
169 180
     /**
181
+     * put value to storage
170 182
      *
171
-     * @param o
183
+     * @param data the data to store
172 184
      */
173
-    void put(DATATYPE o) const { storage = o; }
185
+    void put(DATATYPE data) const { storage = data; }
174 186
     /**
187
+     * copy assignment
175 188
      *
176
-     * @param other
189
+     * @param other the data
177 190
      * @return
178 191
      */
179 192
     this_type &operator=(DATATYPE other) {
@@ -181,6 +194,7 @@ public:
181 194
         return *this;
182 195
     }
183 196
     /**
197
+     * unary or
184 198
      *
185 199
      * @param other
186 200
      * @return
@@ -190,6 +204,7 @@ public:
190 204
         return *this;
191 205
     }
192 206
     /**
207
+     * unary and
193 208
      *
194 209
      * @param other
195 210
      * @return
@@ -199,6 +214,8 @@ public:
199 214
         return *this;
200 215
     }
201 216
     /**
217
+     * set the read callback triggered upon a read request without forwarding the annotated time
218
+     * this is primary for backward compatibility
202 219
      *
203 220
      * @param read_cb
204 221
      */
@@ -206,11 +223,14 @@ public:
206 223
         rd_cb = [read_cb](const this_type &reg, DATATYPE &data, sc_core::sc_time delay) { return read_cb(reg, data); };
207 224
     }
208 225
     /**
226
+     * set the read callback triggered upon a read request
209 227
      *
210 228
      * @param read_cb
211 229
      */
212 230
     void set_read_cb(std::function<bool(const this_type &, DATATYPE &, sc_core::sc_time)> read_cb) { rd_cb = read_cb; }
213 231
     /**
232
+     * set the write callback triggered upon a write request without forwarding the annotated time
233
+     * this is primary for backward compatibility
214 234
      *
215 235
      * @param write_cb
216 236
      */
@@ -218,18 +238,22 @@ public:
218 238
         wr_cb = [write_cb](this_type &reg, DATATYPE &data, sc_core::sc_time delay) { return write_cb(reg, data); };
219 239
     }
220 240
     /**
241
+     * set the write callback triggered upon a write request
221 242
      *
222 243
      * @param write_cb
223 244
      */
224 245
     void set_write_cb(std::function<bool(this_type &, DATATYPE &, sc_core::sc_time)> write_cb) { wr_cb = write_cb; }
225 246
     /**
247
+     * trace the register value to the given trace file
226 248
      *
227 249
      * @param trf
228 250
      */
229 251
     void trace(sc_core::sc_trace_file *trf) const override { sc_trace(trf, storage, this->name()); }
230
-
252
+    //! the reset value
231 253
     const DATATYPE res_val;
254
+    //! the SW read mask
232 255
     const DATATYPE rdmask;
256
+    //! the SW write mask
233 257
     const DATATYPE wrmask;
234 258
 
235 259
 private:
@@ -241,9 +265,11 @@ private:
241 265
     util::delegate<bool(this_type &, DATATYPE &, sc_core::sc_time)> wr_dlgt;
242 266
 };
243 267
 }
244
-
268
+//! import the implementation into the scc namespace
245 269
 template <typename DATATYPE> using sc_register = impl::sc_register<typename impl::helper<DATATYPE>::Type>;
246
-
270
+/**
271
+ * an indexed register aka a register file of a certain type
272
+ */
247 273
 template <typename DATATYPE, size_t SIZE, size_t START = 0>
248 274
 class sc_register_indexed : public indexed_resource_access_if {
249 275
 public:
@@ -251,7 +277,16 @@ public:
251 277
 
252 278
     using value_type = sc_register<DATATYPE>;
253 279
     using pointer = value_type *;
254
-
280
+    /**
281
+     * the constructor
282
+     *
283
+     * @param nm
284
+     * @param storage
285
+     * @param reset_val
286
+     * @param owner
287
+     * @param rdmask
288
+     * @param wrmask
289
+     */
255 290
     sc_register_indexed(sc_core::sc_module_name nm, std::array<DATATYPE, SIZE> &storage, const DATATYPE reset_val,
256 291
                         resetable &owner,
257 292
                         BASE_DATA_TYPE rdmask = std::numeric_limits<BASE_DATA_TYPE>::is_signed
@@ -265,54 +300,96 @@ public:
265 300
             std::stringstream ss;
266 301
             ss << nm << idx;
267 302
             new (_reg_field + idx)
268
-                sc_register<DATATYPE>(ss.str().c_str(), storage[idx], reset_val, owner, rdmask, wrmask);
303
+                sc_register<DATATYPE>(sc_core::sc_module_name(ss.str().c_str()), storage[idx], reset_val, owner, rdmask, wrmask);
269 304
         }
270 305
     }
271
-
306
+    /**
307
+     * the destructor
308
+     */
272 309
     ~sc_register_indexed() override {
273
-//        for (size_t idx = START; idx < (START + SIZE); ++idx)
274
-//            (_reg_field + idx)->~sc_register<DATATYPE>();
275 310
         free(_reg_field);
276 311
     }
277
-
312
+    /**
313
+     * get the size of the register file
314
+     *
315
+     * @return the size
316
+     */
278 317
     size_t size() override { return SIZE; };
279
-
318
+    /**
319
+     * set the read callback triggered upon a read request without forwarding the annotated time
320
+     * this is primary for backward compatibility
321
+     *
322
+     * @param read_cb
323
+     */
280 324
     void set_read_cb(std::function<bool(const sc_register<DATATYPE> &, DATATYPE &)> read_cb) {
281 325
         for (std::unique_ptr<sc_register<DATATYPE>> reg : *this) reg->add_read_cb(read_cb);
282 326
     }
283
-
327
+    /**
328
+     * set the read callback triggered upon a read request
329
+     *
330
+     * @param read_cb
331
+     */
284 332
     void set_read_cb(std::function<bool(const sc_register<DATATYPE> &, DATATYPE &, sc_core::sc_time)> read_cb) {
285 333
         for (std::unique_ptr<sc_register<DATATYPE>> reg : *this) reg->add_read_cb(read_cb);
286 334
     }
287
-
335
+    /**
336
+     * set the write callback triggered upon a write request without forwarding the annotated time
337
+     * this is primary for backward compatibility
338
+     *
339
+     * @param write_cb
340
+     */
288 341
     void set_write_cb(std::function<bool(sc_register<DATATYPE> &, DATATYPE &)> write_cb) {
289 342
         for (std::unique_ptr<sc_register<DATATYPE>> reg : *this) reg->add_write_cb(write_cb);
290 343
     }
291
-
344
+    /**
345
+     * set the write callback triggered upon a write request
346
+     *
347
+     * @param write_cb
348
+     */
292 349
     void set_write_cb(std::function<bool(sc_register<DATATYPE> &, DATATYPE &, sc_core::sc_time)> write_cb) {
293 350
         for (std::unique_ptr<sc_register<DATATYPE>> reg : *this) reg->add_write_cb(write_cb);
294 351
     }
295
-
296
-    // Element access.
297
-    indexed_resource_access_if::reference operator[](size_t __n) noexcept override { return *(_reg_field + __n); }
298
-
299
-    indexed_resource_access_if::const_reference operator[](size_t __n) const noexcept override {
300
-        return *(_reg_field + __n);
301
-    }
302
-
303
-    reference at(size_t __n) override {
304
-        assert("access out of bound" && __n < SIZE);
305
-        return *(_reg_field + __n);
352
+    /**
353
+     * Element access operator
354
+     *
355
+     * @param idx the index
356
+     * @return the data reference at the index
357
+     */
358
+    reference operator[](size_t idx) noexcept override { return *(_reg_field + idx); }
359
+    /**
360
+     * const element access operator
361
+     *
362
+     * @param idx
363
+     * @return the data reference at the index
364
+     */
365
+    const_reference operator[](size_t idx) const noexcept override { return *(_reg_field + idx); }
366
+    /**
367
+     * Element access operator
368
+     *
369
+     * @param idx the index
370
+     * @return the data reference at the index
371
+     */
372
+    reference at(size_t idx) override {
373
+        assert("access out of bound" && idx < SIZE);
374
+        return *(_reg_field + idx);
306 375
     }
307
-    const_reference at(size_t __n) const override {
308
-        assert("access out of bound" && __n < SIZE);
309
-        return *(_reg_field + __n);
376
+    /**
377
+     * const element access operator
378
+     *
379
+     * @param idx
380
+     * @return the data reference at the index
381
+     */
382
+   const_reference at(size_t idx) const override {
383
+        assert("access out of bound" && idx < SIZE);
384
+        return *(_reg_field + idx);
310 385
     }
311 386
 
312 387
 private:
313 388
     value_type *_reg_field;
314 389
 };
315
-
390
+/**
391
+ * alias class to map template argument read an write mask to constructor arguments
392
+ */
316 393
 template <typename DATATYPE, DATATYPE WRMASK = impl::get_max_uval<DATATYPE>(),
317 394
           DATATYPE RDMASK = impl::get_max_uval<DATATYPE>()>
318 395
 class sc_register_masked : public sc_register<DATATYPE> {

+ 66
- 17
incl/scc/report.h View File

@@ -13,12 +13,6 @@
13 13
  * See the License for the specific language governing permissions and
14 14
  * limitations under the License.
15 15
  *******************************************************************************/
16
-/*
17
- * logging.h
18
- *
19
- *  Created on: Nov 24, 2016
20
- *      Author: developer
21
- */
22 16
 
23 17
 #ifndef _SYSC_REPORT_H_
24 18
 #define _SYSC_REPORT_H_
@@ -37,34 +31,83 @@ namespace scc {
37 31
 
38 32
 /**
39 33
  * initializes the SystemC logging system to use logging::Logger with a particular logging level
34
+ *
35
+ * @param level the logging level
40 36
  */
41 37
 void init_logging(logging::log_level level = logging::WARNING);
42
-
38
+/**
39
+ * the logger class
40
+ */
43 41
 template <sc_core::sc_severity SEVERITY> struct ScLogger {
42
+    /**
43
+     * the constructor
44
+     *
45
+     * @param file file where the log entry originates
46
+     * @param line the line where the log entry originates
47
+     * @param level the log level
48
+     */
44 49
     ScLogger(const char *file, int line, sc_core::sc_verbosity level = sc_core::SC_MEDIUM)
45 50
     : t(nullptr)
46 51
     , file(file)
47 52
     , line(line)
48 53
     , level(level){};
49
-
54
+    /**
55
+     * no default constructor
56
+     */
50 57
     ScLogger() = delete;
51
-
58
+    /**
59
+     * no copy constructor
60
+     * @param
61
+     */
52 62
     ScLogger(const ScLogger &) = delete;
53
-
63
+    /**
64
+     * no move constructor
65
+     * @param
66
+     */
67
+    ScLogger(ScLogger &&) = delete;
68
+    /**
69
+     * no copy assignment
70
+     * @param
71
+     * @return
72
+     */
54 73
     ScLogger &operator=(const ScLogger &) = delete;
55
-
74
+    /**
75
+     * no move assignment
76
+     * @param
77
+     * @return
78
+     */
79
+    ScLogger &operator=(ScLogger &&) = delete;
80
+    /**
81
+     * the destructor generating the SystemC report
82
+     */
56 83
     virtual ~ScLogger() {
57 84
         ::sc_core::sc_report_handler::report(SEVERITY, t ? t : "SystemC", os.str().c_str(), level, file, line);
58 85
     }
59
-
60
-    inline ScLogger &type() { return *this; }
61
-
86
+    /**
87
+     * reset the category of the log entry
88
+     *
89
+     * @return
90
+     */
91
+    inline ScLogger &type() {
92
+        this->t=nullptr;
93
+        return *this;
94
+    }
95
+    /**
96
+     * set the category of the log entry
97
+     *
98
+     * @param t
99
+     * @return
100
+     */
62 101
     inline ScLogger &type(const char *t) {
63 102
         this->t = const_cast<char *>(t);
64 103
         return *this;
65 104
     }
66
-
67
-    inline std::ostringstream &get() { return os; };
105
+    /**
106
+     * return the underlying ostringstream
107
+     *
108
+     * @return the output stream collecting the log message
109
+     */
110
+    inline std::ostream &get() { return os; };
68 111
 
69 112
 protected:
70 113
     std::ostringstream os;
@@ -73,22 +116,28 @@ protected:
73 116
     const int line;
74 117
     const sc_core::sc_verbosity level;
75 118
 };
76
-
119
+//! macro for debug trace lavel output
77 120
 #define SCDBGTRC(...)                                                                                                  \
78 121
     if (::sc_core::sc_report_handler::get_verbosity_level() >= sc_core::SC_DEBUG)                                      \
79 122
     ::scc::ScLogger<::sc_core::SC_INFO>(__FILE__, __LINE__, sc_core::SC_DEBUG).type(__VA_ARGS__).get()
123
+//! macro for trace level output
80 124
 #define SCTRACE(...)                                                                                                   \
81 125
     if (::sc_core::sc_report_handler::get_verbosity_level() >= sc_core::SC_FULL)                                       \
82 126
     ::scc::ScLogger<::sc_core::SC_INFO>(__FILE__, __LINE__, sc_core::SC_FULL).type(__VA_ARGS__).get()
127
+//! macro for debug level output
83 128
 #define SCDEBUG(...)                                                                                                   \
84 129
     if (::sc_core::sc_report_handler::get_verbosity_level() >= sc_core::SC_HIGH)                                       \
85 130
     ::scc::ScLogger<::sc_core::SC_INFO>(__FILE__, __LINE__, sc_core::SC_HIGH).type(__VA_ARGS__).get()
131
+//! macro for info level output
86 132
 #define SCINFO(...)                                                                                                    \
87 133
     if (::sc_core::sc_report_handler::get_verbosity_level() >= sc_core::SC_MEDIUM)                                     \
88 134
     ::scc::ScLogger<::sc_core::SC_INFO>(__FILE__, __LINE__, sc_core::SC_MEDIUM).type(__VA_ARGS__).get()
135
+//! macro for warning level output
89 136
 #define SCWARN(...)                                                                                                    \
90 137
     ::scc::ScLogger<::sc_core::SC_WARNING>(__FILE__, __LINE__, sc_core::SC_MEDIUM).type(__VA_ARGS__).get()
138
+//! macro for error level output
91 139
 #define SCERR(...) ::scc::ScLogger<::sc_core::SC_ERROR>(__FILE__, __LINE__, sc_core::SC_MEDIUM).type(__VA_ARGS__).get()
140
+//! macro for fatal message output
92 141
 #define SCFATAL(...)                                                                                                   \
93 142
     ::scc::ScLogger<::sc_core::SC_FATAL>(__FILE__, __LINE__, sc_core::SC_MEDIUM).type(__VA_ARGS__).get()
94 143
 }

+ 10
- 10
incl/scc/resetable.h View File

@@ -13,12 +13,6 @@
13 13
  * See the License for the specific language governing permissions and
14 14
  * limitations under the License.
15 15
  *******************************************************************************/
16
-/*
17
- * resettable.h
18
- *
19
- *  Created on: Nov 16, 2016
20
- *      Author: developer
21
- */
22 16
 
23 17
 #ifndef _SYSC_RESETTABLE_H_
24 18
 #define _SYSC_RESETTABLE_H_
@@ -31,27 +25,33 @@ namespace scc {
31 25
 class resetable {
32 26
 public:
33 27
     /**
34
-     *
28
+     * the default destructor
35 29
      */
36 30
     virtual ~resetable() = default;
37 31
     /**
38
-     *
32
+     * begin the reset state
39 33
      */
40 34
     void reset_start() {
41 35
         _in_reset = true;
42 36
         for (auto res : resources) res->reset();
43 37
     }
44 38
     /**
45
-     *
39
+     * finish the reset state
46 40
      */
47 41
     void reset_stop() {
48 42
         for (auto res : resources) res->reset();
49 43
         _in_reset = false;
50 44
     }
45
+    /**
46
+     * get the current state of this reset domain
47
+     *
48
+     * @return tru if reset is active
49
+     */
51 50
     bool in_reset() { return _in_reset; }
52 51
     /**
52
+     * register a resource with this reset domain
53 53
      *
54
-     * @param res
54
+     * @param res the resource belonging to this reset domain
55 55
      */
56 56
     void register_resource(resource_access_if *res) { resources.push_back(res); }
57 57
 

+ 50
- 42
incl/scc/resource_access_if.h View File

@@ -13,12 +13,6 @@
13 13
  * See the License for the specific language governing permissions and
14 14
  * limitations under the License.
15 15
  *******************************************************************************/
16
-/*
17
- * resource_access_if.h
18
- *
19
- *  Created on: Nov 16, 2016
20
- *      Author: developer
21
- */
22 16
 
23 17
 #ifndef _SYSC_RESOURCE_ACCESS_IF_H_
24 18
 #define _SYSC_RESOURCE_ACCESS_IF_H_
@@ -28,60 +22,71 @@
28 22
 #include <sysc/kernel/sc_time.h>
29 23
 
30 24
 namespace scc {
31
-
25
+/**
26
+ * interface defining access to a resource
27
+ */
32 28
 class resource_access_if {
33 29
 public:
34 30
     /**
35
-     *
31
+     * the destructor
36 32
      */
37 33
     virtual ~resource_access_if() = default;
38 34
     /**
35
+     * return the size of the resource
39 36
      *
40
-     * @return
37
+     * @return the size
41 38
      */
42 39
     virtual std::size_t size() const = 0;
43 40
     /**
44
-     *
41
+     * reset the resource
45 42
      */
46 43
     virtual void reset() = 0;
47 44
     // functional accesses
48 45
     /**
46
+     * write to the resource
49 47
      *
50
-     * @param data
51
-     * @param length
52
-     * @param offset
53
-     * @return
48
+     * @param data data to write
49
+     * @param length length of data to write
50
+     * @param offset offset of the data to write
51
+     * @param d the annotated delay
52
+     * @return true it the access is successful
54 53
      */
55 54
     virtual bool write(const uint8_t *data, std::size_t length, uint64_t offset = 0,
56 55
                        sc_core::sc_time d = sc_core::SC_ZERO_TIME) = 0;
57 56
     /**
57
+     * read the data from the resource
58 58
      *
59
-     * @param data
60
-     * @param length
61
-     * @param offset
62
-     * @return
59
+     * @param data buffer to read the data into
60
+     * @param length length of data to read
61
+     * @param offset offset of the data to read
62
+     * @param d the annotated delay
63
+     * @return true it the access is successful
63 64
      */
64 65
     virtual bool read(uint8_t *data, std::size_t length, uint64_t offset = 0,
65 66
                       sc_core::sc_time d = sc_core::SC_ZERO_TIME) const = 0;
66 67
     // non-functional/debug accesses
67 68
     /**
69
+     * debug write to the resource
68 70
      *
69
-     * @param data
70
-     * @param length
71
-     * @param offset
72
-     * @return
71
+     * @param data data to write
72
+     * @param length length of data to write
73
+     * @param offset offset of the data to write
74
+     * @return true it the access is successful
73 75
      */
74 76
     virtual bool write_dbg(const uint8_t *data, std::size_t length, uint64_t offset = 0) = 0;
75 77
     /**
78
+     * debug read the data from the resource
76 79
      *
77
-     * @param data
78
-     * @param length
79
-     * @param offset
80
-     * @return
80
+     * @param data buffer to read the data into
81
+     * @param length length of data to read
82
+     * @param offset offset of the data to read
83
+     * @return true it the access is successful
81 84
      */
82 85
     virtual bool read_dbg(uint8_t *data, std::size_t length, uint64_t offset = 0) const = 0;
83 86
 };
84
-
87
+/**
88
+ * interface defining access to an indexed resource
89
+ */
85 90
 class indexed_resource_access_if {
86 91
 public:
87 92
     using value_type = resource_access_if;
@@ -92,39 +97,42 @@ public:
92 97
     using iterator = resource_access_if *;
93 98
     using const_iterator = const resource_access_if *;
94 99
     /**
95
-     *
100
+     * the destructor
96 101
      */
97 102
     virtual ~indexed_resource_access_if() = default;
98 103
     /**
99
-     *
104
+     * get the size of the resource
100 105
      * @return
101 106
      */
102 107
     virtual std::size_t size() = 0;
103
-    // Element access.
104 108
     /**
109
+     * Element access.
105 110
      *
106
-     * @param __n
107
-     * @return
111
+     * @param idx
112
+     * @return the data
108 113
      */
109
-    virtual reference operator[](std::size_t __n) noexcept = 0;
114
+    virtual reference operator[](std::size_t idx) noexcept = 0;
110 115
     /**
116
+     * const element access.
111 117
      *
112
-     * @param __n
113
-     * @return
118
+     * @param idx
119
+     * @return the data
114 120
      */
115
-    virtual const_reference operator[](std::size_t __n) const noexcept = 0;
121
+    virtual const_reference operator[](std::size_t idx) const noexcept = 0;
116 122
     /**
123
+     * Element access.
117 124
      *
118
-     * @param __n
119
-     * @return
125
+     * @param idx
126
+     * @return the data
120 127
      */
121
-    virtual reference at(std::size_t __n) = 0;
128
+    virtual reference at(std::size_t idx) = 0;
122 129
     /**
130
+     * const element access.
123 131
      *
124
-     * @param __n
125
-     * @return
132
+     * @param idx
133
+     * @return the data
126 134
      */
127
-    virtual const_reference at(std::size_t __n) const = 0;
135
+    virtual const_reference at(std::size_t idx) const = 0;
128 136
 };
129 137
 }
130 138
 #endif /* _SYSC_RESOURCE_ACCESS_IF_H_ */

+ 39
- 12
incl/scc/router.h View File

@@ -13,12 +13,6 @@
13 13
  * See the License for the specific language governing permissions and
14 14
  * limitations under the License.
15 15
  *******************************************************************************/
16
-/*
17
- * router.h
18
- *
19
- *  Created on: Nov 5, 2016
20
- *      Author: eyck
21
- */
22 16
 
23 17
 #ifndef _SYSC_ROUTER_H_
24 18
 #define _SYSC_ROUTER_H_
@@ -41,14 +35,15 @@ public:
41 35
     using intor_sckt = scc::initiator_mixin<scv4tlm::tlm_rec_initiator_socket<BUSWIDTH>>;
42 36
     using target_sckt = scc::target_mixin<scv4tlm::tlm_rec_target_socket<BUSWIDTH>>;
43 37
     /**
44
-     *
38
+     * the array of target sockets
45 39
      */
46 40
     sc_core::sc_vector<target_sckt> target;
47 41
     /**
48
-     *
42
+     * the array of initiator sockets
49 43
      */
50 44
     sc_core::sc_vector<intor_sckt> initiator;
51 45
     /**
46
+     * constructs a router
52 47
      *
53 48
      * @param nm
54 49
      * @param slave_cnt
@@ -60,24 +55,55 @@ public:
60 55
      */
61 56
     ~router() = default;
62 57
     /**
58
+     * bind the initiator socket of the router to some target giving a base and size
59
+     *
60
+     * @param socket
61
+     * @param idx
62
+     * @param base
63
+     * @param size
64
+     * @param remap
65
+     */
66
+    template<typename TYPE>
67
+    void bind_target(TYPE& socket, size_t idx, uint64_t base, uint64_t size, bool remap = true){
68
+        set_target_range(idx, base, size, remap);
69
+        initiator[idx].bind(socket);
70
+    }
71
+    /**
72
+     * bind the initiator socket of the router to some target and name it
73
+     *
74
+     * @param socket
75
+     * @param idx
76
+     * @param name
77
+     */
78
+    template<typename TYPE>
79
+    void bind_target(TYPE& socket, size_t idx, std::string name){
80
+        set_target_name(idx, name);
81
+        initiator[idx].bind(socket);
82
+    }
83
+    /**
84
+     * define a base address of a socket. This will be added to the address of each access
85
+     * coming thru this socket
63 86
      *
64 87
      * @param idx
65 88
      * @param base
66 89
      */
67 90
     void set_initiator_base(size_t idx, uint64_t base) { ibases[idx] = base; }
68 91
     /**
92
+     * define the default target socket. If no target address range is hit the access is routed to this socket.
93
+     * If this is not defined a address error response is generated
69 94
      *
70 95
      * @param idx
71 96
      */
72 97
     void set_default_target(size_t idx) { default_idx = idx; }
73 98
     /**
74
-     * establish a mapping between socket naem name and socket index
99
+     * establish a mapping between socket name and socket index
75 100
      *
76 101
      * @param idx
77 102
      * @param name
78 103
      */
79 104
     void set_target_name(size_t idx, std::string name) { target_name_lut.insert(std::make_pair(name, idx)); }
80 105
     /**
106
+     * establish a mapping between a named socket and a target address range
81 107
      *
82 108
      * @param idx
83 109
      * @param base
@@ -86,13 +112,14 @@ public:
86 112
      */
87 113
     void add_target_range(std::string name, uint64_t base, uint64_t size, bool remap = true);
88 114
     /**
115
+     * establish a mapping between a socket and a target address range
89 116
      *
90 117
      * @param name
91 118
      * @param base
92 119
      * @param size
93 120
      * @param remap
94 121
      */
95
-    void add_target_range(size_t idx, uint64_t base, uint64_t size, bool remap = true);
122
+    void set_target_range(size_t idx, uint64_t base, uint64_t size, bool remap = true);
96 123
     /**
97 124
       * tagged blocking transport method
98 125
       *
@@ -110,8 +137,8 @@ public:
110 137
      * @return
111 138
      */
112 139
     bool get_direct_mem_ptr(int i, tlm::tlm_generic_payload &trans, tlm::tlm_dmi &dmi_data);
113
-    // tagged debug transaction method
114 140
     /**
141
+     * tagged debug transaction method
115 142
      *
116 143
      * @param i
117 144
      * @param trans
@@ -171,7 +198,7 @@ router<BUSWIDTH>::router(const sc_core::sc_module_name &nm, unsigned slave_cnt,
171 198
 }
172 199
 
173 200
 template <unsigned BUSWIDTH>
174
-void router<BUSWIDTH>::add_target_range(size_t idx, uint64_t base, uint64_t size, bool remap) {
201
+void router<BUSWIDTH>::set_target_range(size_t idx, uint64_t base, uint64_t size, bool remap) {
175 202
     tranges[idx].base = base;
176 203
     tranges[idx].size = size;
177 204
     tranges[idx].remap = remap;

+ 2
- 2
incl/scc/scv_tr_db.h View File

@@ -22,13 +22,13 @@
22 22
  */
23 23
 void scv_tr_sqlite_init();
24 24
 /**
25
- *initializes the infrastructure to use a compressed text based transaction recording database
25
+ * initializes the infrastructure to use a compressed text based transaction recording database
26 26
  */
27 27
 void scv_tr_compressed_init();
28 28
 
29 29
 #ifdef USE_EXTENDED_DB
30 30
 /**
31
- *initializes the infrastructure to use a binary transaction recording database
31
+ * initializes the infrastructure to use a binary transaction recording database
32 32
  */
33 33
 void scv_tr_binary_init();
34 34
 /**

+ 10
- 2
incl/scc/tagged_initiator_mixin.h View File

@@ -23,7 +23,9 @@
23 23
 #include <tlm>
24 24
 
25 25
 namespace scc {
26
-
26
+/**
27
+ *
28
+ */
27 29
 template <typename BASE_TYPE, typename TYPES = tlm::tlm_base_protocol_types>
28 30
 class tagged_initiator_mixin : public BASE_TYPE {
29 31
 public:
@@ -34,12 +36,18 @@ public:
34 36
     using bw_interface_type = tlm::tlm_bw_transport_if<TYPES>;
35 37
 
36 38
 public:
39
+    /**
40
+     *
41
+     */
37 42
     tagged_initiator_mixin()
38 43
     : BASE_TYPE(sc_core::sc_gen_unique_name("tagged_initiator_socket"))
39 44
     , bw_if(this->name()) {
40 45
         this->m_export.bind(bw_if);
41 46
     }
42
-
47
+    /**
48
+     *
49
+     * @param n
50
+     */
43 51
     explicit tagged_initiator_mixin(const char *n)
44 52
     : BASE_TYPE(n)
45 53
     , bw_if(this->name()) {

+ 18
- 14
incl/scc/target_mixin.h View File

@@ -26,10 +26,12 @@
26 26
 #include <tlm_utils/peq_with_get.h>
27 27
 
28 28
 namespace scc {
29
-
30
-template <typename base_type, typename TYPES = tlm::tlm_base_protocol_types> class target_mixin : public base_type {
31
-    friend class fw_process;
32
-    friend class bw_process;
29
+/**
30
+ * an target socket mixin adding default implementation of callback functions similar to tlm::simple_target_socket
31
+ */
32
+template <typename BASE_TYPE, typename TYPES = tlm::tlm_base_protocol_types> class target_mixin : public BASE_TYPE {
33
+//    friend class fw_process;
34
+//    friend class bw_process;
33 35
 
34 36
 public:
35 37
     using transaction_type = typename TYPES::tlm_payload_type;
@@ -40,32 +42,32 @@ public:
40 42
 
41 43
 public:
42 44
     /**
43
-     *
45
+     * default constructor
44 46
      */
45 47
     target_mixin()
46 48
     : target_mixin(sc_core::sc_gen_unique_name("target_mixin_socket")) {}
47 49
     /**
50
+     * constructor with explicit instance name
48 51
      *
49 52
      * @param n
50 53
      */
51
-    explicit target_mixin(const char *n)
52
-    : base_type(n)
54
+    explicit target_mixin(const sc_core::sc_module_name &n)
55
+    : BASE_TYPE(n)
53 56
     , m_fw_process(this)
54 57
     , m_bw_process(this)
55 58
     , m_current_transaction(nullptr) {
56 59
         bind(m_fw_process);
57 60
     }
58
-
59
-    using base_type::bind;
60
-
61
-    // bw transport must come thru us.
61
+    //! make bind of base class available
62
+    using BASE_TYPE::bind;
62 63
     /**
64
+     * return the bw_process interface
63 65
      *
64 66
      * @return
65 67
      */
66 68
     tlm::tlm_bw_transport_if<TYPES> *operator->() { return &m_bw_process; }
67
-    // REGISTER_XXX
68 69
     /**
70
+     * register a non-blocking forward path callback function
69 71
      *
70 72
      * @param cb
71 73
      */
@@ -75,6 +77,7 @@ public:
75 77
         m_fw_process.set_nb_transport_ptr(cb);
76 78
     }
77 79
     /**
80
+     * register a blocking forward path callback function
78 81
      *
79 82
      * @param cb
80 83
      */
@@ -91,6 +94,7 @@ public:
91 94
         m_fw_process.set_transport_dbg_ptr(cb);
92 95
     }
93 96
     /**
97
+     * register a DMI callback function
94 98
      *
95 99
      * @param cb
96 100
      */
@@ -102,11 +106,11 @@ public:
102 106
 private:
103 107
     // make call on bw path.
104 108
     sync_enum_type bw_nb_transport(transaction_type &trans, phase_type &phase, sc_core::sc_time &t) {
105
-        return base_type::operator->()->nb_transport_bw(trans, phase, t);
109
+        return BASE_TYPE::operator->()->nb_transport_bw(trans, phase, t);
106 110
     }
107 111
 
108 112
     void bw_invalidate_direct_mem_ptr(sc_dt::uint64 s, sc_dt::uint64 e) {
109
-        base_type::operator->()->invalidate_direct_mem_ptr(s, e);
113
+        BASE_TYPE::operator->()->invalidate_direct_mem_ptr(s, e);
110 114
     }
111 115
 
112 116
     // Helper class to handle bw path calls

+ 12
- 2
incl/scc/time2tick.h View File

@@ -20,12 +20,22 @@
20 20
 #include "utilities.h"
21 21
 
22 22
 namespace scc {
23
+/**
24
+ * translate a tick-less clock (sc_time based) to boolean clock
25
+ */
23 26
 struct time2tick : public sc_core::sc_module {
27
+    //! yes, we have processes
24 28
     SC_HAS_PROCESS(time2tick);// NOLINT
29
+    //! the clock input
25 30
     sc_core::sc_in<sc_core::sc_time> clk_i;
31
+    //! the clock output
26 32
     sc_core::sc_out<bool> clk_o;
27
-
28
-    time2tick(sc_core::sc_module_name nm)
33
+    /**
34
+     * the constructor
35
+     *
36
+     * @param nm
37
+     */
38
+    explicit time2tick(sc_core::sc_module_name nm)
29 39
     : sc_core::sc_module(nm) {
30 40
         SC_THREAD(clocker);
31 41
     }

+ 26
- 36
incl/scc/tlm_target.h View File

@@ -13,12 +13,6 @@
13 13
  * See the License for the specific language governing permissions and
14 14
  * limitations under the License.
15 15
  *******************************************************************************/
16
-/*
17
- * tlmtarget.h
18
- *
19
- *  Created on: Nov 16, 2016
20
- *      Author: developer
21
- */
22 16
 
23 17
 #ifndef _SYSC_TLM_TARGET_H_
24 18
 #define _SYSC_TLM_TARGET_H_
@@ -42,43 +36,47 @@ template <unsigned int BUSWIDTH = 32> class tlm_target {
42 36
 public:
43 37
     using this_type = tlm_target<BUSWIDTH>;
44 38
     /**
39
+     * the constructor
45 40
      *
46 41
      * @param clock
47 42
      */
48 43
     tlm_target(sc_core::sc_time &clock);
49 44
     /**
50
-     *
45
+     * the socket
51 46
      */
52 47
     scc::target_mixin<scv4tlm::tlm_rec_target_socket<BUSWIDTH>> socket;
53 48
     /**
49
+     * the blocking transport callback
54 50
      *
55 51
      * @param
56 52
      * @param
57 53
      */
58 54
     void b_tranport_cb(tlm::tlm_generic_payload &, sc_core::sc_time &);
59 55
     /**
56
+     * the debug transport callback
60 57
      *
61 58
      * @param
62 59
      * @return
63 60
      */
64 61
     unsigned int tranport_dbg_cb(tlm::tlm_generic_payload &);
65 62
     /**
63
+     * add a resource to this target at a certain address within the socket address range
66 64
      *
67
-     * @param i
68
-     * @param base_addr
65
+     * @param rai the resource to add
66
+     * @param base_addr the offset of the resource (from address 0)
69 67
      */
70
-    void addResource(resource_access_if &i, uint64_t base_addr) {
71
-        socket_map.addEntry(std::make_pair(&i, base_addr), base_addr, i.size());
68
+    void addResource(resource_access_if &rai, uint64_t base_addr) {
69
+        socket_map.addEntry(std::make_pair(&rai, base_addr), base_addr, rai.size());
72 70
     }
73 71
     /**
74
-     *
75
-     * @param ii
76
-     * @param base_addr
72
+     * add an indexed resource to this target at a certain address within the socket address range
73
+     * @param irai the resource to add
74
+     * @param base_addr the offset of the resource (from address 0)
77 75
      */
78
-    void addResource(indexed_resource_access_if &ii, uint64_t base_addr) {
79
-        for (size_t idx = 0; idx < ii.size(); ++idx) {
80
-            socket_map.addEntry(std::make_pair(&ii[idx], base_addr), base_addr, ii[idx].size());
81
-            base_addr += ii[idx].size();
76
+    void addResource(indexed_resource_access_if &irai, uint64_t base_addr) {
77
+        for (size_t idx = 0; idx < irai.size(); ++idx) {
78
+            socket_map.addEntry(std::make_pair(&irai[idx], base_addr), base_addr, irai[idx].size());
79
+            base_addr += irai[idx].size();
82 80
         }
83 81
     }
84 82
 
@@ -88,29 +86,21 @@ private:
88 86
 protected:
89 87
     util::range_lut<std::pair<resource_access_if *, uint64_t>> socket_map;
90 88
 };
91
-
89
+/**
90
+ * helper structure to define a address range for a socket
91
+ */
92 92
 template <unsigned BUSWIDTH = 32> struct target_memory_map_entry {
93 93
     tlm::tlm_target_socket<BUSWIDTH> &target;
94 94
     sc_dt::uint64 start;
95 95
     sc_dt::uint64 size;
96 96
 };
97
-
98
-template <unsigned int BUSWIDTH = 32, unsigned RANGES = 1> class tlm_multi_rangetarget : public tlm_target<BUSWIDTH> {
99
-public:
100
-    using this_type = tlm_multi_rangetarget<BUSWIDTH, RANGES>;
101
-
102
-    tlm_multi_rangetarget(sc_core::sc_time &clock, std::array<addr_range, RANGES> addr_rngs)
103
-    : tlm_target<BUSWIDTH>(clock)
104
-    , addr_ranges(addr_rngs) {}
105
-
106
-    tlm_multi_rangetarget(sc_core::sc_time &clock)
107
-    : tlm_target<BUSWIDTH>(clock)
108
-    , addr_ranges({}) {}
109
-
110
-    const std::array<addr_range, RANGES> addr_ranges;
111
-
112
-protected:
113
-    util::range_lut<resource_access_if *> socket_map;
97
+/**
98
+ * helper structure to define a named address range
99
+ */
100
+template <unsigned BUSWIDTH = 32> struct target_name_map_entry {
101
+    std::string   name;
102
+    sc_dt::uint64 start;
103
+    sc_dt::uint64 size;
114 104
 };
115 105
 
116 106
 } /* namespace scc */

+ 6
- 8
incl/scc/traceable.h View File

@@ -13,12 +13,6 @@
13 13
  * See the License for the specific language governing permissions and
14 14
  * limitations under the License.
15 15
  *******************************************************************************/
16
-/*
17
- * tracable.h
18
- *
19
- *  Created on: Nov 9, 2016
20
- *      Author: developer
21
- */
22 16
 
23 17
 #ifndef _SCC_TRACABLE_H_
24 18
 #define _SCC_TRACABLE_H_
@@ -28,14 +22,18 @@ class sc_trace_file;
28 22
 }
29 23
 
30 24
 namespace scc {
31
-
25
+/**
26
+ * interface defining a traceable component, this overlaps with the trace function of sc_core::sc_object
27
+ * in fact it is a signalling interface
28
+ */
32 29
 class traceable {
33 30
 public:
34 31
     /**
35
-     *
32
+     * the destructor
36 33
      */
37 34
     virtual ~traceable() = default;
38 35
     /**
36
+     * trace the elements of the object to the trace file
39 37
      *
40 38
      * @param trf the tracefile to use
41 39
      */

+ 8
- 11
incl/scc/tracer.h View File

@@ -13,12 +13,6 @@
13 13
  * See the License for the specific language governing permissions and
14 14
  * limitations under the License.
15 15
  *******************************************************************************/
16
-/*
17
- * tracer.h
18
- *
19
- *  Created on: Nov 9, 2016
20
- *      Author: developer
21
- */
22 16
 
23 17
 #ifndef _SCC_TRACER_H_
24 18
 #define _SCC_TRACER_H_
@@ -36,22 +30,25 @@ class sc_trace_file;
36 30
 }
37 31
 
38 32
 namespace scc {
39
-
33
+/**
34
+ * a component traversing the SystemC object hierarchy and tracing the objects
35
+ */
40 36
 class tracer : public sc_core::sc_module {
41 37
 public:
42 38
     /**
43
-     *
39
+     * enum defining the transaction trace output type
44 40
      */
45 41
     enum file_type { NONE, TEXT, COMPRESSED, SQLITE/*, BINARY, LEVEL*/ };
46 42
     /**
43
+     * the constructor
47 44
      *
48
-     * @param name basename of the trace file(s)
45
+     * @param name base name of the trace file(s)
49 46
      * @param type type of trace file for transactions
50
-     * @param enable enable VCD (signal based) tracing
47
+     * @param enable enable VCD (signal and POD) tracing
51 48
      */
52 49
     tracer(const std::string &&, file_type, bool = true);
53 50
     /**
54
-     *
51
+     * the destructor
55 52
      */
56 53
     virtual ~tracer() override;
57 54
 

+ 46
- 18
incl/scc/utilities.h View File

@@ -41,11 +41,11 @@ template <typename T, typename... Args> std::unique_ptr<T> make_unique(Args &&..
41 41
 }
42 42
 }
43 43
 #endif
44
-
44
+//! macros to simplify constructor lists
45 45
 #define NAMED(X, ...) X(#X, ##__VA_ARGS__)
46 46
 #define NAMEDD(X, T, ...) X(std::make_unique<T>(#X, ##__VA_ARGS__))
47 47
 #define NAMEDC(X, T, I, ...) X(T::create<I>(#X, ##__VA_ARGS__))
48
-
48
+//! macros to simplify declaration of members to trace
49 49
 #define TRACE_VAR(F, X) sc_core::sc_trace(F, X, std::string(this->name()) + "." #X)
50 50
 #define TRACE_ARR(F, X, I)                                                                                             \
51 51
     sc_core::sc_trace(F, X[I], (std::string(this->name()) + "." #X "(" + std::to_string(I) + ")").c_str());
@@ -70,33 +70,32 @@ void sc_trace(sc_trace_file *, const sc_time &, const std::string &);
70 70
 void sc_trace(sc_trace_file *, const sc_time &, const char *);
71 71
 #endif
72 72
 /**
73
+ * trace function for sc_time
73 74
  *
74
- * @param
75
- * @param
76
- * @param
75
+ * @param the trace file
76
+ * @param the data to trace
77
+ * @param the hierarchical name of the data
77 78
  */
78 79
 template <> void sc_trace(sc_trace_file *, const sc_in<sc_time> &, const std::string &);
79 80
 /**
81
+ * trace function for sc_time
80 82
  *
81
- * @param
82
- * @param
83
- * @param
83
+ * @param the trace file
84
+ * @param the port carrying the data to trace
85
+ * @param the hierarchical name of the data
84 86
  */
85 87
 template <> void sc_trace(sc_trace_file *, const sc_inout<sc_time> &, const std::string &);
86
-/**
87
- *
88
- * @param val
89
- * @return
90
- */
91 88
 }
92
-// user-define literals for easy time creation
89
+// user-defined literals for easy time creation
93 90
 /**
91
+ * UDL for second
94 92
  *
95 93
  * @param val
96 94
  * @return
97 95
  */
98 96
 inline sc_core::sc_time operator"" _sec(long double val) { return sc_core::sc_time(val, sc_core::SC_SEC); }
99 97
 /**
98
+ * UDL for second
100 99
  *
101 100
  * @param val
102 101
  * @return
@@ -105,72 +104,90 @@ inline sc_core::sc_time operator"" _sec(unsigned long long val) {
105 104
     return sc_core::sc_time(double(val), sc_core::SC_SEC);
106 105
 }
107 106
 /**
107
+ * UDL for millisecond
108 108
  *
109 109
  * @param val
110 110
  * @return
111 111
  */
112 112
 inline sc_core::sc_time operator"" _ms(long double val) { return sc_core::sc_time(val, sc_core::SC_MS); }
113 113
 /**
114
+ * UDL for millisecond
114 115
  *
115 116
  * @param val
116 117
  * @return
117 118
  */
118 119
 inline sc_core::sc_time operator"" _ms(unsigned long long val) { return sc_core::sc_time(double(val), sc_core::SC_MS); }
119 120
 /**
121
+ * UDL for microsecond
120 122
  *
121 123
  * @param val
122 124
  * @return
123 125
  */
124 126
 inline sc_core::sc_time operator"" _us(long double val) { return sc_core::sc_time(val, sc_core::SC_US); }
125 127
 /**
128
+ * UDL for microsecond
126 129
  *
127 130
  * @param val
128 131
  * @return
129 132
  */
130 133
 inline sc_core::sc_time operator"" _us(unsigned long long val) { return sc_core::sc_time(double(val), sc_core::SC_US); }
131 134
 /**
135
+ * UDL for nanosecond
132 136
  *
133 137
  * @param val
134 138
  * @return
135 139
  */
136 140
 inline sc_core::sc_time operator"" _ns(long double val) { return sc_core::sc_time(val, sc_core::SC_NS); }
137 141
 /**
142
+ * UDL for nanosecond
138 143
  *
139 144
  * @param val
140 145
  * @return
141 146
  */
142 147
 inline sc_core::sc_time operator"" _ns(unsigned long long val) { return sc_core::sc_time(double(val), sc_core::SC_NS); }
143 148
 /**
149
+ * UDL for picosecond
144 150
  *
145 151
  * @param val
146 152
  * @return
147 153
  */
148 154
 inline sc_core::sc_time operator"" _ps(long double val) { return sc_core::sc_time(val, sc_core::SC_PS); }
149 155
 /**
156
+ * UDL for picosecond
150 157
  *
151 158
  * @param val
152 159
  * @return
153 160
  */
154 161
 inline sc_core::sc_time operator"" _ps(unsigned long long val) { return sc_core::sc_time(double(val), sc_core::SC_PS); }
155 162
 /**
163
+ * UDL for femtosecond
156 164
  *
157 165
  * @param val
158 166
  * @return
159 167
  */
160 168
 inline sc_core::sc_time operator"" _fs(long double val) { return sc_core::sc_time(val, sc_core::SC_FS); }
161 169
 /**
170
+ * UDL for femtosecond
162 171
  *
163 172
  * @param val
164 173
  * @return
165 174
  */
166 175
 inline sc_core::sc_time operator"" _fs(unsigned long long val) { return sc_core::sc_time(double(val), sc_core::SC_FS); }
167
-
176
+//! UDL for kilobyte
168 177
 inline constexpr uint64_t operator"" _kB(unsigned long long val) { return val * 1 << 10; }
178
+//! UDL for megabyte
169 179
 inline constexpr uint64_t operator"" _MB(unsigned long long val) { return val * 1 << 20; }
180
+//! UDL for gigabyte
170 181
 inline constexpr uint64_t operator"" _GB(unsigned long long val) { return val * 1 << 30; }
171 182
 
172 183
 namespace scc {
173
-
184
+/**
185
+ * case-insensitive string compare
186
+ *
187
+ * @param a string a
188
+ * @param b string b
189
+ * @return result of std::equal
190
+ */
174 191
 inline bool icompare(std::string const &a, std::string const &b) {
175 192
     if (a.length() == b.length()) {
176 193
         return std::equal(b.begin(), b.end(), a.begin(),
@@ -179,7 +196,13 @@ inline bool icompare(std::string const &a, std::string const &b) {
179 196
         return false;
180 197
     }
181 198
 }
182
-
199
+/**
200
+ * parse a time value from given strings
201
+ *
202
+ * @param value the string to parse
203
+ * @param unit the unit string
204
+ * @return the parsed sc_core::sc_time value
205
+ */
183 206
 inline sc_core::sc_time parse_from_string(std::string value, std::string unit) noexcept {
184 207
     std::string::size_type offs{0};
185 208
     double t_val = std::stod(value, &offs);
@@ -193,7 +216,12 @@ inline sc_core::sc_time parse_from_string(std::string value, std::string unit) n
193 216
     }
194 217
     return sc_core::SC_ZERO_TIME;
195 218
 }
196
-
219
+/**
220
+ * parse a time value from a given string
221
+ *
222
+ * @param value the string to parse
223
+ * @return the parsed sc_core::sc_time value
224
+ */
197 225
 inline sc_core::sc_time parse_from_string(std::string value) noexcept {
198 226
     std::string::size_type offs{0};
199 227
     double t_val = std::stod(value, &offs);

+ 7
- 12
incl/util/ities.h View File

@@ -74,7 +74,13 @@ constexpr size_t bit_count(uint32_t u) {
74 74
     return ((uCount + (uCount >> 3)) & 030707070707) % 63;
75 75
 }
76 76
 #endif
77
-
77
+/**
78
+ * split a given string using specified separator
79
+ *
80
+ * @param s the string to split
81
+ * @param separator the separator char
82
+ * @return vector of splitted strings
83
+ */
78 84
 inline std::vector<std::string> split(const std::string &s, char seperator) {
79 85
     std::vector<std::string> output;
80 86
     std::string::size_type prev_pos = 0, pos = 0;
@@ -86,16 +92,5 @@ inline std::vector<std::string> split(const std::string &s, char seperator) {
86 92
     output.push_back(s.substr(prev_pos, pos - prev_pos)); // Last word
87 93
     return output;
88 94
 }
89
-
90
-// std::vector<std::string> split(std::string& str, char split_char){
91
-//    std::vector<std::string> res;
92
-//    auto split_pos=str.find_first_of(split_char);
93
-//    decltype(split_pos) start{0};
94
-//    while(start!=str.length()){
95
-//        res.push_back(str.substr(start, start-split_pos));
96
-//        start=std::min(split_pos+1, str.length());
97
-//    }
98
-//    return res;
99
-//}
100 95
 }
101 96
 #endif /* _UTIL_ITIES_H_ */

+ 85
- 17
incl/util/logging.h View File

@@ -28,39 +28,70 @@
28 28
 #include <sys/time.h>
29 29
 #include <vector>
30 30
 
31
+//! log level definitions
31 32
 #define LEVELS(L) L(NONE) L(FATAL) L(ERROR) L(WARNING) L(INFO) L(DEBUG) L(TRACE)
32 33
 #define DO_DESCRIPTION(e) #e,
33 34
 #define DO_ENUM(e) e,
34 35
 
35 36
 namespace logging {
36
-
37
+//! array holding string representations of log levels
37 38
 static std::array<const char *const, 7> buffer = {{LEVELS(DO_DESCRIPTION)}};
39
+//! enum defining the log levels
38 40
 enum log_level { LEVELS(DO_ENUM) };
39
-
41
+/**
42
+ * safely convert an integer into a log level
43
+ * @param logLevel the integer
44
+ * @return the log level
45
+ */
40 46
 inline log_level as_log_level(int logLevel) {
41 47
     assert(logLevel >= NONE && logLevel <= TRACE);
42 48
     std::array<const log_level, 7> m = {{NONE, FATAL, ERROR, WARNING, INFO, DEBUG, TRACE}};
43 49
     return m[logLevel];
44 50
 }
45
-
51
+/**
52
+ * get the current host time as string
53
+ * @return
54
+ */
46 55
 inline std::string now_time();
47
-
56
+/**
57
+ * the logger class
58
+ */
48 59
 template <typename T> class Log {
49 60
 public:
61
+    /**
62
+     * default constructor
63
+     */
50 64
     Log() = default;
51
-
65
+    /**
66
+     * no copy constructor
67
+     *
68
+     * @param
69
+     */
52 70
     Log(const Log &) = delete;
53
-
71
+    /**
72
+     * no copy assignment constructor
73
+     *
74
+     * @param
75
+     * @return
76
+     */
54 77
     Log &operator=(const Log &) = delete;
55
-
78
+    /**
79
+     * the destructor
80
+     */
56 81
     virtual ~Log() {
57 82
         os << std::endl;
58 83
         T::output(os.str());
59 84
         // TODO: use a more specific exception
60 85
         if (get_last_log_level() == FATAL) abort();
61 86
     }
62
-
63
-    std::ostringstream &get(log_level level = INFO, const char *category = "") {
87
+    /**
88
+     * get the underlying ostringstream for a certain log level and category
89
+     *
90
+     * @param level the log level
91
+     * @param category the category string
92
+     * @return the underlying output stream
93
+     */
94
+    std::ostream &get(log_level level = INFO, const char *category = "") {
64 95
         if (print_time()) os << "- " << now_time() << " ";
65 96
         if (print_severity()) {
66 97
             os << std::setw(7) << std::left << to_string(level);
@@ -70,14 +101,28 @@ public:
70 101
         get_last_log_level() = level;
71 102
         return os;
72 103
     };
73
-
104
+    /**
105
+     * get a reference to the configured logging level
106
+     *
107
+     * @return the logging level
108
+     */
74 109
     static log_level &reporting_level() {
75 110
         static log_level reportingLevel = WARNING;
76 111
         return reportingLevel;
77 112
     }
78
-
113
+    /**
114
+     * translate a lg level to a string
115
+     *
116
+     * @param level the log level
117
+     * @return the string representing the log level
118
+     */
79 119
     static std::string to_string(log_level level) { return std::string(get_log_level_cstr()[level]); };
80
-
120
+    /**
121
+     * parse a log level from a string
122
+     *
123
+     * @param level the string representing the log level
124
+     * @return the log level
125
+     */
81 126
     static log_level from_string(const std::string &level) {
82 127
         for (unsigned int i = NONE; i <= TRACE; i++)
83 128
             if (!strncasecmp(level.c_str(), (const char *)(get_log_level_cstr() + i),
@@ -86,12 +131,20 @@ public:
86 131
         Log<T>().Get(WARNING) << "Unknown logging level '" << level << "'. Using INFO level as default.";
87 132
         return INFO;
88 133
     }
89
-
134
+    /**
135
+     * get the reference to the flag indicating if the current host time should be part of the log
136
+     *
137
+     * @return the print time flag
138
+     */
90 139
     static bool &print_time() {
91 140
         static bool flag = true;
92 141
         return flag;
93 142
     }
94
-
143
+    /**
144
+     * get the reference to the flag indicating if severity should be part of the log
145
+     *
146
+     * @return the print severity flag
147
+     */
95 148
     static bool &print_severity() {
96 149
         static bool flag = true;
97 150
         return flag;
@@ -105,13 +158,25 @@ protected:
105 158
     static const char *const *get_log_level_cstr() { return buffer.data(); };
106 159
     std::ostringstream os;
107 160
 };
108
-
161
+/**
162
+ * the output writer
163
+ */
109 164
 template <typename CATEGORY> class Output2FILE : CATEGORY {
110 165
 public:
166
+    /**
167
+     * get the file handle of the underlying output file (or stdout)
168
+     *
169
+     * @return the file handle
170
+     */
111 171
     static FILE *&stream() {
112 172
         static FILE *pStream = stdout;
113 173
         return pStream;
114 174
     }
175
+    /**
176
+     * write an output string to the file
177
+     *
178
+     * @param msg the string to write
179
+     */
115 180
     static void output(const std::string &msg) {
116 181
         static std::mutex mtx;
117 182
         std::lock_guard<std::mutex> lock(mtx);
@@ -121,6 +186,7 @@ public:
121 186
         fflush(pStream);
122 187
     }
123 188
 };
189
+//! the default logging category
124 190
 class DEFAULT {};
125 191
 
126 192
 #if defined(WIN32) || defined(_WIN32) || defined(__WIN32__)
@@ -178,12 +244,13 @@ inline std::string now_time() {
178 244
     strftime(buffer.data(), buffer.size(), "%X", localtime_r(&t, &r));
179 245
     struct timeval tv;
180 246
     gettimeofday(&tv, nullptr);
247
+    memset(result.data(), 100, 1);
181 248
     sprintf(result.data(), "%s.%03ld", buffer.data(), (long)tv.tv_usec / 1000);
182 249
     return result.data();
183 250
 }
184 251
 
185 252
 #endif // WIN32
186
-// a print function for a vector
253
+//! a print function for a vector
187 254
 template <typename T> std::ostream &operator<<(std::ostream &stream, const std::vector<T> &vector) {
188 255
     copy(vector.begin(), vector.end(), std::ostream_iterator<T>(stream, ","));
189 256
     return stream;
@@ -194,6 +261,7 @@ template <typename T> std::ostream &operator<<(std::ostream &stream, const std::
194 261
 #undef CAT
195 262
 
196 263
 #ifndef NDEBUG
264
+//! check only in debug mode
197 265
 #define ASSERT(condition, message)                                                                                     \
198 266
     do {                                                                                                               \
199 267
         if (!(condition)) {                                                                                            \
@@ -207,7 +275,7 @@ template <typename T> std::ostream &operator<<(std::ostream &stream, const std::
207 275
     do {                                                                                                               \
208 276
     } while (false)
209 277
 #endif
210
-
278
+//! check always
211 279
 #define CHECK(condition, message)                                                                                      \
212 280
     do {                                                                                                               \
213 281
         if (!(condition)) {                                                                                            \

+ 13
- 8
incl/util/range_lut.h View File

@@ -26,18 +26,21 @@
26 26
 #include <string>
27 27
 
28 28
 namespace util {
29
-
29
+/**
30
+ * range based lookup table
31
+ */
30 32
 template <typename T> class range_lut {
33
+    //! the type of lut entry
31 34
     enum entry_type { BEGIN_RANGE = 1, END_RANGE = 2, SINGLE_BYTE_RANGE = 3 };
32
-
35
+    //! the lut entry
33 36
     struct lut_entry {
34 37
         T index;
35 38
         entry_type type;
36 39
     };
37
-
38 40
 public:
39 41
     /**
40 42
      * constructor or the lookup table
43
+     *
41 44
      * @param null_entry the entry to be used for empty slots
42 45
      */
43 46
     range_lut(T null_entry)
@@ -45,6 +48,7 @@ public:
45 48
     /**
46 49
      * add an T to the lut covering the range starting at base_addr until
47 50
      * base_addr+size-1
51
+     *
48 52
      * @param i the entry
49 53
      * @param base_addr the base address
50 54
      * @param size the size of the occupied range
@@ -52,12 +56,14 @@ public:
52 56
     void addEntry(T i, uint64_t base_addr, uint64_t size);
53 57
     /**
54 58
      * remove an entry with value i of type T
59
+     *
55 60
      * @param i the entry to be found
56 61
      * @return true if the entry is found and removed, false otherwise
57 62
      */
58 63
     bool removeEntry(T i);
59 64
     /**
60 65
      * get number of entries in the lookup table
66
+     *
61 67
      * @return the size of the underlying container
62 68
      */
63 69
     size_t size() { return m_size; }
@@ -67,6 +73,7 @@ public:
67 73
     void clear() { m_lut.clear(); }
68 74
     /**
69 75
      * get the entry T associated with a given address
76
+     *
70 77
      * @param addr the address
71 78
      * @return the entry belonging to the address
72 79
      */
@@ -82,14 +89,12 @@ public:
82 89
     /**
83 90
      * create a textual representation of the address map (address range->entry
84 91
      * association)
92
+     *
85 93
      * @return
86 94
      */
87 95
     std::string toString();
88
-    /**
89
-     * the null entry
90
-     */
96
+    //!the null entry
91 97
     const T null_entry;
92
-
93 98
 protected:
94 99
     // Loki::AssocVector<uint64_t, lut_entry> m_lut;
95 100
     std::map<uint64_t, lut_entry> m_lut;
@@ -98,6 +103,7 @@ protected:
98 103
 
99 104
 /**
100 105
  * overloaded stream operator
106
+ *
101 107
  * @param os the output stream
102 108
  * @return the stream
103 109
  */
@@ -180,7 +186,6 @@ template <typename T> inline std::string range_lut<T>::toString() {
180 186
     }
181 187
     return buf.str();
182 188
 }
183
-
184 189
 } // namespace util
185 190
 
186 191
 #endif /* _RANGE_LUT_H_ */

+ 31
- 8
incl/util/sparse_array.h View File

@@ -23,7 +23,8 @@
23 23
 namespace util {
24 24
 
25 25
 /**
26
- *  a simple array which allocates memory in 16MB chunks
26
+ *  a simple array which allocates memory in configurable chunks (size of 2^lower_width), used for
27
+ *  large sparse arrays. Memory is allocated on demand
27 28
  */
28 29
 template <typename T, uint64_t SIZE, int lower_width = 24> class sparse_array {
29 30
 public:
@@ -36,34 +37,56 @@ public:
36 37
     const uint64_t page_addr_width = lower_width;
37 38
 
38 39
     using page_type = std::array<T, 1 << lower_width>;
39
-
40
+    /**
41
+     * the default constructor
42
+     */
40 43
     sparse_array() { arr.fill(nullptr); }
41
-
44
+    /**
45
+     * the destructor
46
+     */
42 47
     ~sparse_array() {
43 48
         for (auto i : arr) delete i;
44 49
     }
45
-
50
+    /**
51
+     * element access operator
52
+     *
53
+     * @param addr address to access
54
+     * @return the data type reference
55
+     */
46 56
     T &operator[](uint32_t addr) {
47 57
         assert(addr < SIZE);
48 58
         T nr = addr >> lower_width;
49 59
         if (arr[nr] == nullptr) arr[nr] = new page_type();
50 60
         return arr[nr]->at(addr & page_addr_mask);
51 61
     }
52
-
62
+    /**
63
+     * page fetch operator
64
+     *
65
+     * @param page_nr the page number ot fetch
66
+     * @return reference to page
67
+     */
53 68
     page_type &operator()(uint32_t page_nr) {
54 69
         assert(page_nr < page_count);
55 70
         if (arr[page_nr] == nullptr) arr[page_nr] = new page_type();
56 71
         return *(arr[page_nr]);
57 72
     }
58
-
73
+    /**
74
+     * check if page for address is allocated
75
+     *
76
+     * @param addr the address to check
77
+     * @return true if the page is allocated
78
+     */
59 79
     bool is_allocated(uint32_t addr) {
60 80
         assert(addr < SIZE);
61 81
         T nr = addr >> lower_width;
62 82
         return arr[nr] != nullptr;
63 83
     }
64
-
84
+    /**
85
+     * get the size of the array
86
+     *
87
+     * @return the size
88
+     */
65 89
     uint64_t size() { return SIZE; }
66
-
67 90
 protected:
68 91
     std::array<page_type *, SIZE / (1 << lower_width) + 1> arr;
69 92
 };

+ 36
- 10
incl/util/thread_syncronizer.h View File

@@ -21,7 +21,10 @@
21 21
 #include <future>
22 22
 #include <queue>
23 23
 #include <stdexcept>
24
-
24
+namespace util {
25
+/**
26
+ * executes a function in another thread
27
+ */
25 28
 class thread_syncronizer {
26 29
 private:
27 30
     std::queue<std::function<void()>> tasks_;
@@ -30,24 +33,43 @@ private:
30 33
     std::condition_variable condition_;
31 34
 
32 35
 public:
33
-    /// @brief Constructor.
36
+    /**
37
+     * the constructor.
38
+     */
34 39
     thread_syncronizer() = default;
35
-
36
-    /// @brief Destructor.
40
+    /**
41
+     * the destructor
42
+     */
37 43
     ~thread_syncronizer() {
38 44
         // Set running flag to false then notify all threads.
39 45
         condition_.notify_all();
40 46
     }
41
-
47
+    /**
48
+     * check if the synchronizer can handle functions
49
+     *
50
+     * @return true if it can handle a new request
51
+     */
42 52
     bool is_ready() { return ready.load(std::memory_order_acquire); }
43
-
53
+    /**
54
+     * enqueue a function to be executed in the other thread and wait for completion
55
+     *
56
+     * @param f the functor to execute
57
+     * @param args the arguments to pass to the functor
58
+     * @return the result of the function
59
+     */
44 60
     template <class F, class... Args>
45 61
     typename std::result_of<F(Args...)>::type enqueue_and_wait(F &&f, Args &&... args) {
46 62
         auto res = enqueue(f, args...);
47 63
         res.wait();
48 64
         return res.get();
49 65
     }
50
-
66
+    /**
67
+     * enqueue a function to be executed in the other thread
68
+     *
69
+     * @param f the functor to execute
70
+     * @param args the arguments to pass to the functor
71
+     * @return the future holding the result of the execution
72
+     */
51 73
     template <class F, class... Args>
52 74
     auto enqueue(F &&f, Args &&... args) -> std::future<typename std::result_of<F(Args...)>::type> {
53 75
         using return_type = typename std::result_of<F(Args...)>::type;
@@ -62,7 +84,9 @@ public:
62 84
         condition_.notify_one();
63 85
         return res;
64 86
     }
65
-    /// @brief execute the next task in queue but do not wait for the next one
87
+    /**
88
+     * execute the next task in queue but do not wait for the next one
89
+     */
66 90
     void execute() {
67 91
         if (tasks_.empty()) return;
68 92
         {
@@ -81,8 +105,9 @@ public:
81 105
             } // Suppress all exceptions.
82 106
         }
83 107
     }
84
-
85
-    /// @brief execute the next task in queue or wait for the next one
108
+    /**
109
+     *  execute the next task in queue or wait for the next one
110
+     */
86 111
     void executeNext() {
87 112
         ready.store(true, std::memory_order_release);
88 113
         // Wait on condition variable while the task is empty
@@ -95,4 +120,5 @@ public:
95 120
         ready.store(false, std::memory_order_release);
96 121
     }
97 122
 };
123
+}
98 124
 #endif /* _THREAD_SYNCRONIZER_H_ */

+ 2
- 3
src/configurable_tracer.cpp View File

@@ -37,7 +37,7 @@ using namespace scc;
37 37
 
38 38
 configurable_tracer::configurable_tracer(const std::string &&name, file_type type, bool enable_vcd, bool default_enable)
39 39
 : tracer(std::move(name), type, enable_vcd)
40
-, cci_originator("configurable_tracer")
40
+, cci_originator(this->name())
41 41
 , cci_broker(cci::cci_get_global_broker(cci_originator))
42 42
 , default_trace_enable(default_enable)
43 43
 {
@@ -109,8 +109,7 @@ void configurable_tracer::augment_object_hierarchical(const sc_core::sc_object *
109 109
             hier_name += ".enableTracing";
110 110
             auto h = cci_broker.get_param_handle(hier_name);
111 111
             if (!h.is_valid()) // we have no cci_param so create one
112
-                params.push_back(new cci::cci_param<bool>(hier_name, default_trace_enable, "", cci::CCI_ABSOLUTE_NAME,
113
-                                                          cci::cci_originator(obj->name())));
112
+                params.push_back(new cci::cci_param<bool>(hier_name, default_trace_enable, "", cci::CCI_ABSOLUTE_NAME, cci_originator));
114 113
         }
115 114
         for (auto *o : obj->get_child_objects()) augment_object_hierarchical(o);
116 115
     }