Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | /* |
2 | * ========== Copyright Header Begin ========================================== | |
3 | * | |
4 | * OpenSPARC T2 Processor File: Signature.h | |
5 | * Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved. | |
6 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES. | |
7 | * | |
8 | * The above named program is free software; you can redistribute it and/or | |
9 | * modify it under the terms of the GNU General Public | |
10 | * License version 2 as published by the Free Software Foundation. | |
11 | * | |
12 | * The above named program is distributed in the hope that it will be | |
13 | * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
15 | * General Public License for more details. | |
16 | * | |
17 | * You should have received a copy of the GNU General Public | |
18 | * License along with this work; if not, write to the Free Software | |
19 | * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. | |
20 | * | |
21 | * ========== Copyright Header End ============================================ | |
22 | */ | |
23 | #ifndef __Signature_h | |
24 | #define __Signature_h | |
25 | ||
26 | #include <iostream> | |
27 | #include <fstream> | |
28 | #include <assert.h> | |
29 | #include "Datatype.h" | |
30 | #include "List.h" | |
31 | #include "Trace.h" | |
32 | using namespace std; | |
33 | ||
34 | /** @file Signature.h | |
35 | * Signature.h defines classes that are used for signatures. | |
36 | * | |
37 | * @sa Signature_Module | |
38 | */ | |
39 | ||
40 | /** @defgroup Signature_Module The Signature Module | |
41 | * Signature.h defines classes that are used for signatures. A signature | |
42 | * is used to specify the fields of a class isntance that are traceable. Once | |
43 | * a signature has been created, the process of tracing that class instance | |
44 | * is fully automated. The main purpose of the Signature mechanism is to | |
45 | * identify the state to be traced, and to provide symbolic names for the | |
46 | * trace. This is currently to trace Register and Transaction instances | |
47 | * with supporting infrastructure in Object, Block, Port and Signal classes. | |
48 | * | |
49 | * @{ | |
50 | */ | |
51 | ||
52 | /** SignType is the base class for types that can be included in a Signature. | |
53 | * This class is derived from Traceable which causes each SignType instance | |
54 | * to have a unique Trace ID. Apart from the constructor, the other methods | |
55 | * of this class are virtual or pure virtual, and provided by sub-classes. */ | |
56 | ||
57 | class SignType : public Traceable | |
58 | { | |
59 | public: | |
60 | /** Constructor for SignType. | |
61 | * @param t the name of this type. | |
62 | * @param p the name of the parent Object containing this data. | |
63 | * @param n the name of this data. | |
64 | */ | |
65 | SignType(string t, string p, string n); | |
66 | ||
67 | /** Destructor for SignType. This is virtual so that the appropriate | |
68 | * destructor for any derived class is used. */ | |
69 | virtual ~SignType() {} | |
70 | ||
71 | /** Convert the value of this data to a string (for tracing). Since | |
72 | * the data is provided by the sub-class, and not by SignType, | |
73 | * this is a pure virtual method. */ | |
74 | virtual string toString() = 0; | |
75 | ||
76 | /** Convert the value of this data to a 64-bit integer. Since | |
77 | * the data is provided by the sub-class, and not by SignType, | |
78 | * this is a pure virtual method. */ | |
79 | virtual Data getValue() = 0; | |
80 | ||
81 | /** Get the name of this type. */ | |
82 | virtual string getType() { return type; } | |
83 | ||
84 | /** Get the basename of the data instance associated with this SignType. */ | |
85 | virtual string getBaseName() { return baseName; } | |
86 | ||
87 | /** Get the full name of the data instance associated with this SignType. */ | |
88 | virtual string getFullName() { return fullName; } | |
89 | ||
90 | protected: | |
91 | string type; | |
92 | string baseName; | |
93 | string fullName; | |
94 | }; | |
95 | ||
96 | /** SignAddr is a specific SignType used for holding the signature for a | |
97 | * piece of data of type Addr. This allows the value of that data to be | |
98 | * traced. */ | |
99 | class SignAddr : public SignType | |
100 | { | |
101 | public: | |
102 | /** Constructor for SignAddr. | |
103 | * @param p the name of the parent Object containing this Addr data. | |
104 | * @param n the name of this Addr data. | |
105 | * @param a a pointer to the Addr data. This is used to retrieve the | |
106 | * value when required for tracing. | |
107 | */ | |
108 | SignAddr(string p, string n, Addr *a) : SignType("addr", p, n) | |
109 | { | |
110 | addr = a; | |
111 | } | |
112 | ||
113 | /** Destructor for SignAddr. */ | |
114 | ~SignAddr() {} | |
115 | ||
116 | /** Convert the value of this data to a string (for tracing). */ | |
117 | string toString(); | |
118 | ||
119 | /** Convert the value of this data to a 64-bit integer. */ | |
120 | Data getValue() { return Data(*addr); } | |
121 | ||
122 | private: | |
123 | Addr *addr; | |
124 | }; | |
125 | ||
126 | /** SignByte is a specific SignType used for holding the signature for a | |
127 | * piece of data of type Byte. This allows the value of that data to be | |
128 | * traced. */ | |
129 | class SignByte : public SignType | |
130 | { | |
131 | public: | |
132 | /** Constructor for SignByte. | |
133 | * @param p the name of the parent Object containing this byte. | |
134 | * @param n the name of this byte. | |
135 | * @param a a pointer to the byte. This is used to retrieve the | |
136 | * value when required for tracing. | |
137 | */ | |
138 | SignByte(string p, string n, Byte *a) : SignType("byte", p, n) | |
139 | { | |
140 | byte = a; | |
141 | } | |
142 | ||
143 | /** Destructor for SignByte. */ | |
144 | ~SignByte() {} | |
145 | ||
146 | /** Convert the value of this data to a string (for tracing). */ | |
147 | string toString(); | |
148 | ||
149 | /** Convert the value of this data to a 64-bit integer. */ | |
150 | Data getValue() { return Data(*byte); } | |
151 | ||
152 | private: | |
153 | Byte *byte; | |
154 | }; | |
155 | ||
156 | /** SignData is a specific SignType used for holding the signature for a | |
157 | * piece of data of type Data. This allows the value of that data to be | |
158 | * traced. By default all 64 bits of the Data will be traced. However, | |
159 | * start and end bit positions can be specified in the constructor so | |
160 | * that a single contiguous bit-field from the Data can be traced. This | |
161 | * is used to support the tracing of a Field inside a Register. */ | |
162 | ||
163 | class SignData : public SignType | |
164 | { | |
165 | public: | |
166 | /** Constructor for SignData. | |
167 | * @param p the name of the parent Object containing this data. | |
168 | * @param n the name of this data. | |
169 | * @param d a pointer to the data. This is used to retrieve the | |
170 | * value when required for tracing. | |
171 | * @param e the end bit position of this field (highest bit number). | |
172 | * @param s the start bit position of this field (lowest bit number). | |
173 | */ | |
174 | SignData(string p, string n, Data *d, uint e=63, uint s=0); | |
175 | ||
176 | /** Destructor for SignData. */ | |
177 | ~SignData() {} | |
178 | ||
179 | /** Convert the value of this data to a string (for tracing). */ | |
180 | string toString(); | |
181 | ||
182 | /** Convert the value of this data to a 64-bit integer. */ | |
183 | Data getValue() { return *data & mask; } | |
184 | ||
185 | /** Get the basename of the data instance associated with this SignData. */ | |
186 | string getBaseName(); | |
187 | ||
188 | /** Get the full name of the data instance associated with this SignData. */ | |
189 | string getFullName(); | |
190 | ||
191 | private: | |
192 | Data *data; | |
193 | Data mask; | |
194 | uint start; | |
195 | uint end; | |
196 | }; | |
197 | ||
198 | /** SignBool is a specific SignType used for holding the signature for a | |
199 | * piece of data of type bool. This allows the value of that data to be | |
200 | * traced. */ | |
201 | ||
202 | class SignBool : public SignType | |
203 | { | |
204 | public: | |
205 | /** Constructor for SignBool. | |
206 | * @param p the name of the parent Object containing this "bool" data. | |
207 | * @param n the name of this "bool" data. | |
208 | * @param b a pointer to the "bool" data. This is used to retrieve the | |
209 | * value when required for tracing. | |
210 | */ | |
211 | SignBool(string p, string n, bool *b) : SignType("bool", p, n) | |
212 | { | |
213 | boolean = b; | |
214 | } | |
215 | ||
216 | /** Destructor for SignBool. */ | |
217 | ~SignBool() {} | |
218 | ||
219 | /** Convert the value of this data to a string (for tracing). */ | |
220 | string toString(); | |
221 | ||
222 | /** Convert the value of this data to a 64-bit integer. */ | |
223 | Data getValue() { return Data(*boolean ? 1 : 0); } | |
224 | ||
225 | private: | |
226 | bool *boolean; | |
227 | }; | |
228 | ||
229 | /** SignEnum is a specific SignType used for holding the signature for a | |
230 | * piece of data which is an enumerated int. This allows the value of | |
231 | * that data to be traced. */ | |
232 | ||
233 | class SignEnum : public SignType | |
234 | { | |
235 | public: | |
236 | /** Constructor for SignEnum. | |
237 | * @param p the name of the parent Object containing this "enum" data. | |
238 | * @param n the name of this "enum" data. | |
239 | * @param e a pointer to the "enum" data. This is used to retrieve the | |
240 | * value when required for tracing. | |
241 | */ | |
242 | SignEnum(string p, string n, int *e) : SignType("enum", p, n) | |
243 | { | |
244 | integer = e; | |
245 | } | |
246 | ||
247 | /** Destructor for SignEnum. */ | |
248 | ~SignEnum() {} | |
249 | ||
250 | /** Convert the value of this data to a string (for tracing). */ | |
251 | string toString(); | |
252 | ||
253 | /** Convert the value of this data to a 64-bit integer. */ | |
254 | Data getValue() { return Data(*integer); } | |
255 | ||
256 | private: | |
257 | int *integer; | |
258 | }; | |
259 | ||
260 | /** SignIdentifier is a specific SignType used for holding the signature for a | |
261 | * piece of data which is an Identifier. This allows the value of | |
262 | * that data to be traced. */ | |
263 | ||
264 | class SignIdentifier : public SignType | |
265 | { | |
266 | public: | |
267 | /** Constructor for SignIdentifier. | |
268 | * @param p the name of the parent Object containing this Identifier data. | |
269 | * @param n the name of this Identifier data. | |
270 | * @param e a pointer to the Identifier data. This is used to retrieve the | |
271 | * value when required for tracing. | |
272 | */ | |
273 | SignIdentifier(string p, string n, Identifier *e) : | |
274 | SignType("id", p, n) | |
275 | { | |
276 | identifier = e; | |
277 | } | |
278 | ||
279 | /** Destructor for SignIdentifier. */ | |
280 | ~SignIdentifier() {} | |
281 | ||
282 | /** Convert the value of this data to a string (for tracing). */ | |
283 | string toString(); | |
284 | ||
285 | /** Convert the value of this data to a 64-bit integer. */ | |
286 | Data getValue() { return Data(*identifier); } | |
287 | ||
288 | private: | |
289 | Identifier *identifier; | |
290 | }; | |
291 | ||
292 | /** The Signature class is used to create and output signatures. | |
293 | * A Signature consists of a list of signatures taken from instances of | |
294 | * classes derived from SignType. Once the signature has been created, | |
295 | * there are two operations that can be performed upon it: | |
296 | * | |
297 | * - sign: this outputs a description of the signature definition | |
298 | * (the parts of the signature that do not vary over time). | |
299 | * - print: this outputs the values associated with the signature | |
300 | * at the current time. | |
301 | * | |
302 | * The sign operations can be used to print out information for a trace | |
303 | * header (listing the static properties of everything that is to be traced), | |
304 | * followed by a trace body (the dynamically varying values of things that | |
305 | * are being traced). The separation ensures that the static parts can | |
306 | * be output once at the beginning of the trace, and not repeated every clock | |
307 | * cycle that an item is traced. This approach reduces trace file size. | |
308 | */ | |
309 | ||
310 | class Signature | |
311 | { | |
312 | public: | |
313 | /** PrintMode is an enumerated type indicating the mode of a print | |
314 | * operation for a signature. | |
315 | */ | |
316 | enum PrintMode { | |
317 | VALUE, /**< print the value of each signature item. */ | |
318 | DONTCARE, /**< ignore values and print "X" to indicate "don't care". */ | |
319 | IMPEDANCE /**< ignore values and print "Z" to indicate "impedance". */ | |
320 | }; | |
321 | ||
322 | /** Constructor for Signature. */ | |
323 | Signature() {} | |
324 | ||
325 | /** Destructor for Signature. */ | |
326 | ~Signature(); | |
327 | ||
328 | /** Add a SignType to this Signature. In fact, it is usually instances of | |
329 | * classes that are derived from SignType. This is necessary because | |
330 | * SignType has no associated data to trace, and also contains pure | |
331 | * virtual functions that must be over-loaded to provide useful | |
332 | * functionality. | |
333 | */ | |
334 | void add(SignType *s); | |
335 | ||
336 | /** Output a textual representation of the signature onto the specified | |
337 | * output file stream. | |
338 | * @param ofs the output file stream. | |
339 | * @param n the name of the scope of this signature (empty string if | |
340 | * no new scope required). | |
341 | * @param k a string containing the name of this kind of trace. | |
342 | * | |
343 | * For each SignType in the signature, the output representation is | |
344 | * as follows: | |
345 | * | |
346 | * DEFN : VAR id kind type name | |
347 | * | |
348 | * where: | |
349 | * - id is the Trace Id of this SignType instance. This unique ID is used | |
350 | * to associate the "DEFN" entries produced by Signature::sign with the | |
351 | * "DATA" entries produced by Signature::print. | |
352 | * - kind is the kind of trace and is given by parameter k (see above). | |
353 | * - type is the type of this SignType instance. | |
354 | * - name is the full-name of this SignType instance. | |
355 | * | |
356 | * If a scope name is specified and if there is more than one SignType in | |
357 | * this Signature, then the output will be bracketed by begin-scope and | |
358 | * end-scope markers. | |
359 | */ | |
360 | void sign(ofstream &ofs, string n, string k); | |
361 | ||
362 | /** Output a textual representation of the values associated with this | |
363 | * signature onto the specified file stream. | |
364 | * @param ofs the output file stream. | |
365 | * @param pm print mode, see @see PrintMode for the available options. | |
366 | * | |
367 | * For each SignType in the signature, the output representation is | |
368 | * as follows: | |
369 | * | |
370 | * DATA clock : type id value | |
371 | * | |
372 | * where: | |
373 | * - clock is the time at which this trace is produced. | |
374 | * - type is the type of this SignType instance. | |
375 | * - id is the Trace Id of this SignType instance. This unique ID is used | |
376 | * to associate the "DEFN" entries produced by Signature::sign with the | |
377 | * "DATA" entries produced by Signature::print. | |
378 | * - value is the value of this SignType instance. This is produced by | |
379 | * calling the "toString" virtual method of SignType. | |
380 | */ | |
381 | void printThis(ofstream &ofs, PrintMode pm=VALUE); | |
382 | ||
383 | /** Output a marker to the output file stream indicating the beginning of | |
384 | * a new scope. | |
385 | * @param ofs the output file stream. | |
386 | * @param s the name of this scope. | |
387 | * | |
388 | * The output representation of a begin scope is: | |
389 | * | |
390 | * DEFN : SCOPE BEGIN scope | |
391 | * | |
392 | * where: | |
393 | * - scope is the name of the new scope. | |
394 | */ | |
395 | static void signScopeBegin(ofstream &ofs, string s); | |
396 | ||
397 | /** Output a marker to the output file stream indicating the end of | |
398 | * the current scope. | |
399 | * @param ofs the output file stream. | |
400 | * @param s the name of this scope. | |
401 | * | |
402 | * The output representation of end scope is: | |
403 | * | |
404 | * DEFN : SCOPE END scope | |
405 | * | |
406 | * where: | |
407 | * - scope is the name of the current scope. | |
408 | */ | |
409 | static void signScopeClose(ofstream &ofs, string s); | |
410 | ||
411 | private: | |
412 | List<SignType> signatures; | |
413 | }; | |
414 | ||
415 | /** @} */ | |
416 | ||
417 | #endif |