1# Copyright (c) 2012 ARM Limited
2# All rights reserved.
3#
4# The license below extends only to copyright in the software and shall
5# not be construed as granting a license to any other intellectual
6# property including but not limited to intellectual property relating
7# to a hardware implementation of the functionality of the software
8# licensed hereunder. You may use the software subject to the license
9# terms below provided that you ensure that this notice is replicated
10# unmodified and in its entirety in all distributions of the software,
11# modified or unmodified, in source code or in binary form.
12#
13# Copyright (c) 2004-2006 The Regents of The University of Michigan
14# Copyright (c) 2010-20013 Advanced Micro Devices, Inc.
15# Copyright (c) 2013 Mark D. Hill and David A. Wood
16# All rights reserved.
17#
18# Redistribution and use in source and binary forms, with or without
19# modification, are permitted provided that the following conditions are
20# met: redistributions of source code must retain the above copyright
21# notice, this list of conditions and the following disclaimer;
22# redistributions in binary form must reproduce the above copyright
23# notice, this list of conditions and the following disclaimer in the
24# documentation and/or other materials provided with the distribution;
25# neither the name of the copyright holders nor the names of its
26# contributors may be used to endorse or promote products derived from
27# this software without specific prior written permission.
28#
29# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
30# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
31# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
32# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
33# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
34# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
35# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
36# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
37# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
38# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
39# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
40#
41# Authors: Steve Reinhardt
42# Nathan Binkert
43# Andreas Hansson
44
45import sys
46from types import FunctionType, MethodType, ModuleType
47
48import m5
49from m5.util import *
50
51# Have to import params up top since Param is referenced on initial
52# load (when SimObject class references Param to create a class
53# variable, the 'name' param)...
54from m5.params import *
55# There are a few things we need that aren't in params.__all__ since
56# normal users don't need them
57from m5.params import ParamDesc, VectorParamDesc, \
58 isNullPointer, SimObjectVector, Port
59
60from m5.proxy import *
61from m5.proxy import isproxy
62
63#####################################################################
64#
65# M5 Python Configuration Utility
66#
67# The basic idea is to write simple Python programs that build Python
68# objects corresponding to M5 SimObjects for the desired simulation
69# configuration. For now, the Python emits a .ini file that can be
70# parsed by M5. In the future, some tighter integration between M5
71# and the Python interpreter may allow bypassing the .ini file.
72#
73# Each SimObject class in M5 is represented by a Python class with the
74# same name. The Python inheritance tree mirrors the M5 C++ tree
75# (e.g., SimpleCPU derives from BaseCPU in both cases, and all
76# SimObjects inherit from a single SimObject base class). To specify
77# an instance of an M5 SimObject in a configuration, the user simply
78# instantiates the corresponding Python object. The parameters for
79# that SimObject are given by assigning to attributes of the Python
80# object, either using keyword assignment in the constructor or in
81# separate assignment statements. For example:
82#
83# cache = BaseCache(size='64KB')
84# cache.hit_latency = 3
85# cache.assoc = 8
86#
87# The magic lies in the mapping of the Python attributes for SimObject
88# classes to the actual SimObject parameter specifications. This
89# allows parameter validity checking in the Python code. Continuing
90# the example above, the statements "cache.blurfl=3" or
91# "cache.assoc='hello'" would both result in runtime errors in Python,
92# since the BaseCache object has no 'blurfl' parameter and the 'assoc'
93# parameter requires an integer, respectively. This magic is done
94# primarily by overriding the special __setattr__ method that controls
95# assignment to object attributes.
96#
97# Once a set of Python objects have been instantiated in a hierarchy,
98# calling 'instantiate(obj)' (where obj is the root of the hierarchy)
99# will generate a .ini file.
100#
101#####################################################################
102
103# list of all SimObject classes
104allClasses = {}
105
106# dict to look up SimObjects based on path
107instanceDict = {}
108
109# Did any of the SimObjects lack a header file?
110noCxxHeader = False
111
112def public_value(key, value):
113 return key.startswith('_') or \
114 isinstance(value, (FunctionType, MethodType, ModuleType,
115 classmethod, type))
116
117# The metaclass for SimObject. This class controls how new classes
118# that derive from SimObject are instantiated, and provides inherited
119# class behavior (just like a class controls how instances of that
120# class are instantiated, and provides inherited instance behavior).
121class MetaSimObject(type):
122 # Attributes that can be set only at initialization time
123 init_keywords = { 'abstract' : bool,
124 'cxx_class' : str,
125 'cxx_type' : str,
126 'cxx_header' : str,
127 'type' : str,
128 'cxx_bases' : list }
129 # Attributes that can be set any time
130 keywords = { 'check' : FunctionType }
131
132 # __new__ is called before __init__, and is where the statements
133 # in the body of the class definition get loaded into the class's
134 # __dict__. We intercept this to filter out parameter & port assignments
135 # and only allow "private" attributes to be passed to the base
136 # __new__ (starting with underscore).
137 def __new__(mcls, name, bases, dict):
138 assert name not in allClasses, "SimObject %s already present" % name
139
140 # Copy "private" attributes, functions, and classes to the
141 # official dict. Everything else goes in _init_dict to be
142 # filtered in __init__.
143 cls_dict = {}
144 value_dict = {}
145 for key,val in dict.items():
146 if public_value(key, val):
147 cls_dict[key] = val
148 else:
149 # must be a param/port setting
150 value_dict[key] = val
151 if 'abstract' not in value_dict:
152 value_dict['abstract'] = False
153 if 'cxx_bases' not in value_dict:
154 value_dict['cxx_bases'] = []
155 cls_dict['_value_dict'] = value_dict
156 cls = super(MetaSimObject, mcls).__new__(mcls, name, bases, cls_dict)
157 if 'type' in value_dict:
158 allClasses[name] = cls
159 return cls
160
161 # subclass initialization
162 def __init__(cls, name, bases, dict):
163 # calls type.__init__()... I think that's a no-op, but leave
164 # it here just in case it's not.
165 super(MetaSimObject, cls).__init__(name, bases, dict)
166
167 # initialize required attributes
168
169 # class-only attributes
170 cls._params = multidict() # param descriptions
171 cls._ports = multidict() # port descriptions
172
173 # class or instance attributes
174 cls._values = multidict() # param values
175 cls._hr_values = multidict() # human readable param values
176 cls._children = multidict() # SimObject children
177 cls._port_refs = multidict() # port ref objects
178 cls._instantiated = False # really instantiated, cloned, or subclassed
179
180 # We don't support multiple inheritance of sim objects. If you want
181 # to, you must fix multidict to deal with it properly. Non sim-objects
182 # are ok, though
183 bTotal = 0
184 for c in bases:
185 if isinstance(c, MetaSimObject):
186 bTotal += 1
187 if bTotal > 1:
188 raise TypeError, "SimObjects do not support multiple inheritance"
189
190 base = bases[0]
191
192 # Set up general inheritance via multidicts. A subclass will
193 # inherit all its settings from the base class. The only time
194 # the following is not true is when we define the SimObject
195 # class itself (in which case the multidicts have no parent).
196 if isinstance(base, MetaSimObject):
197 cls._base = base
198 cls._params.parent = base._params
199 cls._ports.parent = base._ports
200 cls._values.parent = base._values
201 cls._hr_values.parent = base._hr_values
202 cls._children.parent = base._children
203 cls._port_refs.parent = base._port_refs
204 # mark base as having been subclassed
205 base._instantiated = True
206 else:
207 cls._base = None
208
209 # default keyword values
210 if 'type' in cls._value_dict:
211 if 'cxx_class' not in cls._value_dict:
212 cls._value_dict['cxx_class'] = cls._value_dict['type']
213
214 cls._value_dict['cxx_type'] = '%s *' % cls._value_dict['cxx_class']
215
216 if 'cxx_header' not in cls._value_dict:
217 global noCxxHeader
218 noCxxHeader = True
219 warn("No header file specified for SimObject: %s", name)
220
221 # Export methods are automatically inherited via C++, so we
222 # don't want the method declarations to get inherited on the
223 # python side (and thus end up getting repeated in the wrapped
224 # versions of derived classes). The code below basicallly
225 # suppresses inheritance by substituting in the base (null)
226 # versions of these methods unless a different version is
227 # explicitly supplied.
228 for method_name in ('export_methods', 'export_method_cxx_predecls',
229 'export_method_swig_predecls'):
230 if method_name not in cls.__dict__:
231 base_method = getattr(MetaSimObject, method_name)
232 m = MethodType(base_method, cls, MetaSimObject)
233 setattr(cls, method_name, m)
234
235 # Now process the _value_dict items. They could be defining
236 # new (or overriding existing) parameters or ports, setting
237 # class keywords (e.g., 'abstract'), or setting parameter
238 # values or port bindings. The first 3 can only be set when
239 # the class is defined, so we handle them here. The others
240 # can be set later too, so just emulate that by calling
241 # setattr().
242 for key,val in cls._value_dict.items():
243 # param descriptions
244 if isinstance(val, ParamDesc):
245 cls._new_param(key, val)
246
247 # port objects
248 elif isinstance(val, Port):
249 cls._new_port(key, val)
250
251 # init-time-only keywords
252 elif cls.init_keywords.has_key(key):
253 cls._set_keyword(key, val, cls.init_keywords[key])
254
255 # default: use normal path (ends up in __setattr__)
256 else:
257 setattr(cls, key, val)
258
259 def _set_keyword(cls, keyword, val, kwtype):
260 if not isinstance(val, kwtype):
261 raise TypeError, 'keyword %s has bad type %s (expecting %s)' % \
262 (keyword, type(val), kwtype)
263 if isinstance(val, FunctionType):
264 val = classmethod(val)
265 type.__setattr__(cls, keyword, val)
266
267 def _new_param(cls, name, pdesc):
268 # each param desc should be uniquely assigned to one variable
269 assert(not hasattr(pdesc, 'name'))
270 pdesc.name = name
271 cls._params[name] = pdesc
272 if hasattr(pdesc, 'default'):
273 cls._set_param(name, pdesc.default, pdesc)
274
275 def _set_param(cls, name, value, param):
276 assert(param.name == name)
277 try:
278 hr_value = value
279 value = param.convert(value)
280 except Exception, e:
281 msg = "%s\nError setting param %s.%s to %s\n" % \
282 (e, cls.__name__, name, value)
283 e.args = (msg, )
284 raise
285 cls._values[name] = value
286 # if param value is a SimObject, make it a child too, so that
287 # it gets cloned properly when the class is instantiated
288 if isSimObjectOrVector(value) and not value.has_parent():
289 cls._add_cls_child(name, value)
290 # update human-readable values of the param if it has a literal
291 # value and is not an object or proxy.
292 if not (isSimObjectOrVector(value) or\
293 isinstance(value, m5.proxy.BaseProxy)):
294 cls._hr_values[name] = hr_value
295
296 def _add_cls_child(cls, name, child):
297 # It's a little funky to have a class as a parent, but these
298 # objects should never be instantiated (only cloned, which
299 # clears the parent pointer), and this makes it clear that the
300 # object is not an orphan and can provide better error
301 # messages.
302 child.set_parent(cls, name)
303 cls._children[name] = child
304
305 def _new_port(cls, name, port):
306 # each port should be uniquely assigned to one variable
307 assert(not hasattr(port, 'name'))
308 port.name = name
309 cls._ports[name] = port
310
311 # same as _get_port_ref, effectively, but for classes
312 def _cls_get_port_ref(cls, attr):
313 # Return reference that can be assigned to another port
314 # via __setattr__. There is only ever one reference
315 # object per port, but we create them lazily here.
316 ref = cls._port_refs.get(attr)
317 if not ref:
318 ref = cls._ports[attr].makeRef(cls)
319 cls._port_refs[attr] = ref
320 return ref
321
322 # Set attribute (called on foo.attr = value when foo is an
323 # instance of class cls).
324 def __setattr__(cls, attr, value):
325 # normal processing for private attributes
326 if public_value(attr, value):
327 type.__setattr__(cls, attr, value)
328 return
329
330 if cls.keywords.has_key(attr):
331 cls._set_keyword(attr, value, cls.keywords[attr])
332 return
333
334 if cls._ports.has_key(attr):
335 cls._cls_get_port_ref(attr).connect(value)
336 return
337
338 if isSimObjectOrSequence(value) and cls._instantiated:
339 raise RuntimeError, \
340 "cannot set SimObject parameter '%s' after\n" \
341 " class %s has been instantiated or subclassed" \
342 % (attr, cls.__name__)
343
344 # check for param
345 param = cls._params.get(attr)
346 if param:
347 cls._set_param(attr, value, param)
348 return
349
350 if isSimObjectOrSequence(value):
351 # If RHS is a SimObject, it's an implicit child assignment.
352 cls._add_cls_child(attr, coerceSimObjectOrVector(value))
353 return
354
355 # no valid assignment... raise exception
356 raise AttributeError, \
357 "Class %s has no parameter \'%s\'" % (cls.__name__, attr)
358
359 def __getattr__(cls, attr):
360 if attr == 'cxx_class_path':
361 return cls.cxx_class.split('::')
362
363 if attr == 'cxx_class_name':
364 return cls.cxx_class_path[-1]
365
366 if attr == 'cxx_namespaces':
367 return cls.cxx_class_path[:-1]
368
369 if cls._values.has_key(attr):
370 return cls._values[attr]
371
372 if cls._children.has_key(attr):
373 return cls._children[attr]
374
375 raise AttributeError, \
376 "object '%s' has no attribute '%s'" % (cls.__name__, attr)
377
378 def __str__(cls):
379 return cls.__name__
380
381 # See ParamValue.cxx_predecls for description.
382 def cxx_predecls(cls, code):
383 code('#include "params/$cls.hh"')
384
385 # See ParamValue.swig_predecls for description.
386 def swig_predecls(cls, code):
387 code('%import "python/m5/internal/param_$cls.i"')
388
389 # Hook for exporting additional C++ methods to Python via SWIG.
390 # Default is none, override using @classmethod in class definition.
391 def export_methods(cls, code):
392 pass
393
394 # Generate the code needed as a prerequisite for the C++ methods
395 # exported via export_methods() to be compiled in the _wrap.cc
396 # file. Typically generates one or more #include statements. If
397 # any methods are exported, typically at least the C++ header
398 # declaring the relevant SimObject class must be included.
399 def export_method_cxx_predecls(cls, code):
400 pass
401
402 # Generate the code needed as a prerequisite for the C++ methods
403 # exported via export_methods() to be processed by SWIG.
404 # Typically generates one or more %include or %import statements.
405 # If any methods are exported, typically at least the C++ header
406 # declaring the relevant SimObject class must be included.
407 def export_method_swig_predecls(cls, code):
408 pass
409
410 # Generate the declaration for this object for wrapping with SWIG.
411 # Generates code that goes into a SWIG .i file. Called from
412 # src/SConscript.
413 def swig_decl(cls, code):
414 class_path = cls.cxx_class.split('::')
415 classname = class_path[-1]
416 namespaces = class_path[:-1]
417
418 # The 'local' attribute restricts us to the params declared in
419 # the object itself, not including inherited params (which
420 # will also be inherited from the base class's param struct
421 # here).
422 params = cls._params.local.values()
423 ports = cls._ports.local
424
425 code('%module(package="m5.internal") param_$cls')
426 code()
427 code('%{')
428 code('#include "sim/sim_object.hh"')
429 code('#include "params/$cls.hh"')
430 for param in params:
431 param.cxx_predecls(code)
432 code('#include "${{cls.cxx_header}}"')
433 cls.export_method_cxx_predecls(code)
434 code('''\
435/**
436 * This is a workaround for bug in swig. Prior to gcc 4.6.1 the STL
437 * headers like vector, string, etc. used to automatically pull in
438 * the cstddef header but starting with gcc 4.6.1 they no longer do.
439 * This leads to swig generated a file that does not compile so we
440 * explicitly include cstddef. Additionally, including version 2.0.4,
441 * swig uses ptrdiff_t without the std:: namespace prefix which is
442 * required with gcc 4.6.1. We explicitly provide access to it.
443 */
444#include <cstddef>
445using std::ptrdiff_t;
446''')
447 code('%}')
448 code()
449
450 for param in params:
451 param.swig_predecls(code)
452 cls.export_method_swig_predecls(code)
453
454 code()
455 if cls._base:
456 code('%import "python/m5/internal/param_${{cls._base}}.i"')
457 code()
458
459 for ns in namespaces:
460 code('namespace $ns {')
461
462 if namespaces:
463 code('// avoid name conflicts')
464 sep_string = '_COLONS_'
465 flat_name = sep_string.join(class_path)
466 code('%rename($flat_name) $classname;')
467
468 code()
469 code('// stop swig from creating/wrapping default ctor/dtor')
470 code('%nodefault $classname;')
471 code('class $classname')
472 if cls._base:
473 bases = [ cls._base.cxx_class ] + cls.cxx_bases
474 else:
475 bases = cls.cxx_bases
476 base_first = True
477 for base in bases:
478 if base_first:
479 code(' : public ${{base}}')
480 base_first = False
481 else:
482 code(' , public ${{base}}')
483
484 code('{')
485 code(' public:')
486 cls.export_methods(code)
487 code('};')
488
489 for ns in reversed(namespaces):
490 code('} // namespace $ns')
491
492 code()
493 code('%include "params/$cls.hh"')
494
495
496 # Generate the C++ declaration (.hh file) for this SimObject's
497 # param struct. Called from src/SConscript.
498 def cxx_param_decl(cls, code):
499 # The 'local' attribute restricts us to the params declared in
500 # the object itself, not including inherited params (which
501 # will also be inherited from the base class's param struct
502 # here).
503 params = cls._params.local.values()
504 ports = cls._ports.local
505 try:
506 ptypes = [p.ptype for p in params]
507 except:
508 print cls, p, p.ptype_str
509 print params
510 raise
511
512 class_path = cls._value_dict['cxx_class'].split('::')
513
514 code('''\
515#ifndef __PARAMS__${cls}__
516#define __PARAMS__${cls}__
517
518''')
519
520 # A forward class declaration is sufficient since we are just
521 # declaring a pointer.
522 for ns in class_path[:-1]:
523 code('namespace $ns {')
524 code('class $0;', class_path[-1])
525 for ns in reversed(class_path[:-1]):
526 code('} // namespace $ns')
527 code()
528
529 # The base SimObject has a couple of params that get
530 # automatically set from Python without being declared through
531 # the normal Param mechanism; we slip them in here (needed
532 # predecls now, actual declarations below)
533 if cls == SimObject:
534 code('''
535#ifndef PY_VERSION
536struct PyObject;
537#endif
538
539#include <string>
540''')
541 for param in params:
542 param.cxx_predecls(code)
543 for port in ports.itervalues():
544 port.cxx_predecls(code)
545 code()
546
547 if cls._base:
548 code('#include "params/${{cls._base.type}}.hh"')
549 code()
550
551 for ptype in ptypes:
552 if issubclass(ptype, Enum):
553 code('#include "enums/${{ptype.__name__}}.hh"')
554 code()
555
556 # now generate the actual param struct
557 code("struct ${cls}Params")
558 if cls._base:
559 code(" : public ${{cls._base.type}}Params")
560 code("{")
561 if not hasattr(cls, 'abstract') or not cls.abstract:
562 if 'type' in cls.__dict__:
563 code(" ${{cls.cxx_type}} create();")
564
565 code.indent()
566 if cls == SimObject:
567 code('''
568 SimObjectParams() {}
569 virtual ~SimObjectParams() {}
570
571 std::string name;
572 PyObject *pyobj;
573 ''')
574 for param in params:
575 param.cxx_decl(code)
576 for port in ports.itervalues():
577 port.cxx_decl(code)
578
579 code.dedent()
580 code('};')
581
582 code()
583 code('#endif // __PARAMS__${cls}__')
584 return code
585
586
587# This *temporary* definition is required to support calls from the
588# SimObject class definition to the MetaSimObject methods (in
589# particular _set_param, which gets called for parameters with default
590# values defined on the SimObject class itself). It will get
591# overridden by the permanent definition (which requires that
592# SimObject be defined) lower in this file.
593def isSimObjectOrVector(value):
594 return False
595
596# This class holds information about each simobject parameter
597# that should be displayed on the command line for use in the
598# configuration system.
599class ParamInfo(object):
600 def __init__(self, type, desc, type_str, example, default_val, access_str):
601 self.type = type
602 self.desc = desc
603 self.type_str = type_str
604 self.example_str = example
605 self.default_val = default_val
606 # The string representation used to access this param through python.
607 # The method to access this parameter presented on the command line may
608 # be different, so this needs to be stored for later use.
609 self.access_str = access_str
610 self.created = True
611
612 # Make it so we can only set attributes at initialization time
613 # and effectively make this a const object.
614 def __setattr__(self, name, value):
615 if not "created" in self.__dict__:
616 self.__dict__[name] = value
617
618# The SimObject class is the root of the special hierarchy. Most of
619# the code in this class deals with the configuration hierarchy itself
620# (parent/child node relationships).
621class SimObject(object):
622 # Specify metaclass. Any class inheriting from SimObject will
623 # get this metaclass.
624 __metaclass__ = MetaSimObject
625 type = 'SimObject'
626 abstract = True
627
628 cxx_header = "sim/sim_object.hh"
629 cxx_bases = [ "Drainable", "Serializable" ]
630 eventq_index = Param.UInt32(Parent.eventq_index, "Event Queue Index")
631
632 @classmethod
633 def export_method_swig_predecls(cls, code):
634 code('''
635%include <std_string.i>
636
637%import "python/swig/drain.i"
638%import "python/swig/serialize.i"
639''')
640
641 @classmethod
642 def export_methods(cls, code):
643 code('''
644 void init();
645 void loadState(Checkpoint *cp);
646 void initState();
647 void regStats();
648 void resetStats();
649 void regProbePoints();
650 void regProbeListeners();
651 void startup();
652''')
653
654 # Returns a dict of all the option strings that can be
655 # generated as command line options for this simobject instance
656 # by tracing all reachable params in the top level instance and
657 # any children it contains.
658 def enumerateParams(self, flags_dict = {},
659 cmd_line_str = "", access_str = ""):
660 if hasattr(self, "_paramEnumed"):
661 print "Cycle detected enumerating params"
662 else:
663 self._paramEnumed = True
664 # Scan the children first to pick up all the objects in this SimObj
665 for keys in self._children:
666 child = self._children[keys]
667 next_cmdline_str = cmd_line_str + keys
668 next_access_str = access_str + keys
669 if not isSimObjectVector(child):
670 next_cmdline_str = next_cmdline_str + "."
671 next_access_str = next_access_str + "."
672 flags_dict = child.enumerateParams(flags_dict,
673 next_cmdline_str,
674 next_access_str)
675
676 # Go through the simple params in the simobject in this level
677 # of the simobject hierarchy and save information about the
678 # parameter to be used for generating and processing command line
679 # options to the simulator to set these parameters.
680 for keys,values in self._params.items():
681 if values.isCmdLineSettable():
682 type_str = ''
683 ex_str = values.example_str()
684 ptype = None
685 if isinstance(values, VectorParamDesc):
686 type_str = 'Vector_%s' % values.ptype_str
687 ptype = values
688 else:
689 type_str = '%s' % values.ptype_str
690 ptype = values.ptype
691
692 if keys in self._hr_values\
693 and keys in self._values\
694 and not isinstance(self._values[keys], m5.proxy.BaseProxy):
695 cmd_str = cmd_line_str + keys
696 acc_str = access_str + keys
697 flags_dict[cmd_str] = ParamInfo(ptype,
698 self._params[keys].desc, type_str, ex_str,
699 values.pretty_print(self._hr_values[keys]),
700 acc_str)
701 elif not keys in self._hr_values\
702 and not keys in self._values:
703 # Empty param
704 cmd_str = cmd_line_str + keys
705 acc_str = access_str + keys
706 flags_dict[cmd_str] = ParamInfo(ptype,
707 self._params[keys].desc,
708 type_str, ex_str, '', acc_str)
709
710 return flags_dict
711
712 # Initialize new instance. For objects with SimObject-valued
713 # children, we need to recursively clone the classes represented
714 # by those param values as well in a consistent "deep copy"-style
715 # fashion. That is, we want to make sure that each instance is
716 # cloned only once, and that if there are multiple references to
717 # the same original object, we end up with the corresponding
718 # cloned references all pointing to the same cloned instance.
719 def __init__(self, **kwargs):
720 ancestor = kwargs.get('_ancestor')
721 memo_dict = kwargs.get('_memo')
722 if memo_dict is None:
723 # prepare to memoize any recursively instantiated objects
724 memo_dict = {}
725 elif ancestor:
726 # memoize me now to avoid problems with recursive calls
727 memo_dict[ancestor] = self
728
729 if not ancestor:
730 ancestor = self.__class__
731 ancestor._instantiated = True
732
733 # initialize required attributes
734 self._parent = None
735 self._name = None
736 self._ccObject = None # pointer to C++ object
737 self._ccParams = None
738 self._instantiated = False # really "cloned"
739
740 # Clone children specified at class level. No need for a
741 # multidict here since we will be cloning everything.
742 # Do children before parameter values so that children that
743 # are also param values get cloned properly.
744 self._children = {}
745 for key,val in ancestor._children.iteritems():
746 self.add_child(key, val(_memo=memo_dict))
747
748 # Inherit parameter values from class using multidict so
749 # individual value settings can be overridden but we still
750 # inherit late changes to non-overridden class values.
751 self._values = multidict(ancestor._values)
752 self._hr_values = multidict(ancestor._hr_values)
753 # clone SimObject-valued parameters
754 for key,val in ancestor._values.iteritems():
755 val = tryAsSimObjectOrVector(val)
756 if val is not None:
757 self._values[key] = val(_memo=memo_dict)
758
759 # clone port references. no need to use a multidict here
760 # since we will be creating new references for all ports.
761 self._port_refs = {}
762 for key,val in ancestor._port_refs.iteritems():
763 self._port_refs[key] = val.clone(self, memo_dict)
764 # apply attribute assignments from keyword args, if any
765 for key,val in kwargs.iteritems():
766 setattr(self, key, val)
767
768 # "Clone" the current instance by creating another instance of
769 # this instance's class, but that inherits its parameter values
770 # and port mappings from the current instance. If we're in a
771 # "deep copy" recursive clone, check the _memo dict to see if
772 # we've already cloned this instance.
773 def __call__(self, **kwargs):
774 memo_dict = kwargs.get('_memo')
775 if memo_dict is None:
776 # no memo_dict: must be top-level clone operation.
777 # this is only allowed at the root of a hierarchy
778 if self._parent:
779 raise RuntimeError, "attempt to clone object %s " \
780 "not at the root of a tree (parent = %s)" \
781 % (self, self._parent)
782 # create a new dict and use that.
783 memo_dict = {}
784 kwargs['_memo'] = memo_dict
785 elif memo_dict.has_key(self):
786 # clone already done & memoized
787 return memo_dict[self]
788 return self.__class__(_ancestor = self, **kwargs)
789
790 def _get_port_ref(self, attr):
791 # Return reference that can be assigned to another port
792 # via __setattr__. There is only ever one reference
793 # object per port, but we create them lazily here.
794 ref = self._port_refs.get(attr)
795 if ref == None:
796 ref = self._ports[attr].makeRef(self)
797 self._port_refs[attr] = ref
798 return ref
799
800 def __getattr__(self, attr):
801 if self._ports.has_key(attr):
802 return self._get_port_ref(attr)
803
804 if self._values.has_key(attr):
805 return self._values[attr]
806
807 if self._children.has_key(attr):
808 return self._children[attr]
809
810 # If the attribute exists on the C++ object, transparently
811 # forward the reference there. This is typically used for
812 # SWIG-wrapped methods such as init(), regStats(),
813 # resetStats(), startup(), drain(), and
814 # resume().
815 if self._ccObject and hasattr(self._ccObject, attr):
816 return getattr(self._ccObject, attr)
817
818 err_string = "object '%s' has no attribute '%s'" \
819 % (self.__class__.__name__, attr)
820
821 if not self._ccObject:
822 err_string += "\n (C++ object is not yet constructed," \
823 " so wrapped C++ methods are unavailable.)"
824
825 raise AttributeError, err_string
826
827 # Set attribute (called on foo.attr = value when foo is an
828 # instance of class cls).
829 def __setattr__(self, attr, value):
830 # normal processing for private attributes
831 if attr.startswith('_'):
832 object.__setattr__(self, attr, value)
833 return
834
835 if self._ports.has_key(attr):
836 # set up port connection
837 self._get_port_ref(attr).connect(value)
838 return
839
840 param = self._params.get(attr)
841 if param:
842 try:
843 hr_value = value
844 value = param.convert(value)
845 except Exception, e:
846 msg = "%s\nError setting param %s.%s to %s\n" % \
847 (e, self.__class__.__name__, attr, value)
848 e.args = (msg, )
849 raise
850 self._values[attr] = value
851 # implicitly parent unparented objects assigned as params
852 if isSimObjectOrVector(value) and not value.has_parent():
853 self.add_child(attr, value)
854 # set the human-readable value dict if this is a param
855 # with a literal value and is not being set as an object
856 # or proxy.
857 if not (isSimObjectOrVector(value) or\
858 isinstance(value, m5.proxy.BaseProxy)):
859 self._hr_values[attr] = hr_value
860
861 return
862
863 # if RHS is a SimObject, it's an implicit child assignment
864 if isSimObjectOrSequence(value):
865 self.add_child(attr, value)
866 return
867
868 # no valid assignment... raise exception
869 raise AttributeError, "Class %s has no parameter %s" \
870 % (self.__class__.__name__, attr)
871
872
873 # this hack allows tacking a '[0]' onto parameters that may or may
874 # not be vectors, and always getting the first element (e.g. cpus)
875 def __getitem__(self, key):
876 if key == 0:
877 return self
878 raise IndexError, "Non-zero index '%s' to SimObject" % key
879
880 # this hack allows us to iterate over a SimObject that may
881 # not be a vector, so we can call a loop over it and get just one
882 # element.
883 def __len__(self):
884 return 1
885
886 # Also implemented by SimObjectVector
887 def clear_parent(self, old_parent):
888 assert self._parent is old_parent
889 self._parent = None
890
891 # Also implemented by SimObjectVector
892 def set_parent(self, parent, name):
893 self._parent = parent
894 self._name = name
895
896 # Return parent object of this SimObject, not implemented by SimObjectVector
897 # because the elements in a SimObjectVector may not share the same parent
898 def get_parent(self):
899 return self._parent
900
901 # Also implemented by SimObjectVector
902 def get_name(self):
903 return self._name
904
905 # Also implemented by SimObjectVector
906 def has_parent(self):
907 return self._parent is not None
908
909 # clear out child with given name. This code is not likely to be exercised.
910 # See comment in add_child.
911 def clear_child(self, name):
912 child = self._children[name]
913 child.clear_parent(self)
914 del self._children[name]
915
916 # Add a new child to this object.
917 def add_child(self, name, child):
918 child = coerceSimObjectOrVector(child)
919 if child.has_parent():
920 warn("add_child('%s'): child '%s' already has parent", name,
921 child.get_name())
922 if self._children.has_key(name):
923 # This code path had an undiscovered bug that would make it fail
924 # at runtime. It had been here for a long time and was only
925 # exposed by a buggy script. Changes here will probably not be
926 # exercised without specialized testing.
927 self.clear_child(name)
928 child.set_parent(self, name)
929 self._children[name] = child
930
931 # Take SimObject-valued parameters that haven't been explicitly
932 # assigned as children and make them children of the object that
933 # they were assigned to as a parameter value. This guarantees
934 # that when we instantiate all the parameter objects we're still
935 # inside the configuration hierarchy.
936 def adoptOrphanParams(self):
937 for key,val in self._values.iteritems():
938 if not isSimObjectVector(val) and isSimObjectSequence(val):
939 # need to convert raw SimObject sequences to
940 # SimObjectVector class so we can call has_parent()
941 val = SimObjectVector(val)
942 self._values[key] = val
943 if isSimObjectOrVector(val) and not val.has_parent():
944 warn("%s adopting orphan SimObject param '%s'", self, key)
945 self.add_child(key, val)
946
947 def path(self):
948 if not self._parent:
949 return '<orphan %s>' % self.__class__
950 ppath = self._parent.path()
951 if ppath == 'root':
952 return self._name
953 return ppath + "." + self._name
954
955 def __str__(self):
956 return self.path()
957
| 1# Copyright (c) 2012 ARM Limited
2# All rights reserved.
3#
4# The license below extends only to copyright in the software and shall
5# not be construed as granting a license to any other intellectual
6# property including but not limited to intellectual property relating
7# to a hardware implementation of the functionality of the software
8# licensed hereunder. You may use the software subject to the license
9# terms below provided that you ensure that this notice is replicated
10# unmodified and in its entirety in all distributions of the software,
11# modified or unmodified, in source code or in binary form.
12#
13# Copyright (c) 2004-2006 The Regents of The University of Michigan
14# Copyright (c) 2010-20013 Advanced Micro Devices, Inc.
15# Copyright (c) 2013 Mark D. Hill and David A. Wood
16# All rights reserved.
17#
18# Redistribution and use in source and binary forms, with or without
19# modification, are permitted provided that the following conditions are
20# met: redistributions of source code must retain the above copyright
21# notice, this list of conditions and the following disclaimer;
22# redistributions in binary form must reproduce the above copyright
23# notice, this list of conditions and the following disclaimer in the
24# documentation and/or other materials provided with the distribution;
25# neither the name of the copyright holders nor the names of its
26# contributors may be used to endorse or promote products derived from
27# this software without specific prior written permission.
28#
29# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
30# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
31# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
32# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
33# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
34# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
35# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
36# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
37# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
38# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
39# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
40#
41# Authors: Steve Reinhardt
42# Nathan Binkert
43# Andreas Hansson
44
45import sys
46from types import FunctionType, MethodType, ModuleType
47
48import m5
49from m5.util import *
50
51# Have to import params up top since Param is referenced on initial
52# load (when SimObject class references Param to create a class
53# variable, the 'name' param)...
54from m5.params import *
55# There are a few things we need that aren't in params.__all__ since
56# normal users don't need them
57from m5.params import ParamDesc, VectorParamDesc, \
58 isNullPointer, SimObjectVector, Port
59
60from m5.proxy import *
61from m5.proxy import isproxy
62
63#####################################################################
64#
65# M5 Python Configuration Utility
66#
67# The basic idea is to write simple Python programs that build Python
68# objects corresponding to M5 SimObjects for the desired simulation
69# configuration. For now, the Python emits a .ini file that can be
70# parsed by M5. In the future, some tighter integration between M5
71# and the Python interpreter may allow bypassing the .ini file.
72#
73# Each SimObject class in M5 is represented by a Python class with the
74# same name. The Python inheritance tree mirrors the M5 C++ tree
75# (e.g., SimpleCPU derives from BaseCPU in both cases, and all
76# SimObjects inherit from a single SimObject base class). To specify
77# an instance of an M5 SimObject in a configuration, the user simply
78# instantiates the corresponding Python object. The parameters for
79# that SimObject are given by assigning to attributes of the Python
80# object, either using keyword assignment in the constructor or in
81# separate assignment statements. For example:
82#
83# cache = BaseCache(size='64KB')
84# cache.hit_latency = 3
85# cache.assoc = 8
86#
87# The magic lies in the mapping of the Python attributes for SimObject
88# classes to the actual SimObject parameter specifications. This
89# allows parameter validity checking in the Python code. Continuing
90# the example above, the statements "cache.blurfl=3" or
91# "cache.assoc='hello'" would both result in runtime errors in Python,
92# since the BaseCache object has no 'blurfl' parameter and the 'assoc'
93# parameter requires an integer, respectively. This magic is done
94# primarily by overriding the special __setattr__ method that controls
95# assignment to object attributes.
96#
97# Once a set of Python objects have been instantiated in a hierarchy,
98# calling 'instantiate(obj)' (where obj is the root of the hierarchy)
99# will generate a .ini file.
100#
101#####################################################################
102
103# list of all SimObject classes
104allClasses = {}
105
106# dict to look up SimObjects based on path
107instanceDict = {}
108
109# Did any of the SimObjects lack a header file?
110noCxxHeader = False
111
112def public_value(key, value):
113 return key.startswith('_') or \
114 isinstance(value, (FunctionType, MethodType, ModuleType,
115 classmethod, type))
116
117# The metaclass for SimObject. This class controls how new classes
118# that derive from SimObject are instantiated, and provides inherited
119# class behavior (just like a class controls how instances of that
120# class are instantiated, and provides inherited instance behavior).
121class MetaSimObject(type):
122 # Attributes that can be set only at initialization time
123 init_keywords = { 'abstract' : bool,
124 'cxx_class' : str,
125 'cxx_type' : str,
126 'cxx_header' : str,
127 'type' : str,
128 'cxx_bases' : list }
129 # Attributes that can be set any time
130 keywords = { 'check' : FunctionType }
131
132 # __new__ is called before __init__, and is where the statements
133 # in the body of the class definition get loaded into the class's
134 # __dict__. We intercept this to filter out parameter & port assignments
135 # and only allow "private" attributes to be passed to the base
136 # __new__ (starting with underscore).
137 def __new__(mcls, name, bases, dict):
138 assert name not in allClasses, "SimObject %s already present" % name
139
140 # Copy "private" attributes, functions, and classes to the
141 # official dict. Everything else goes in _init_dict to be
142 # filtered in __init__.
143 cls_dict = {}
144 value_dict = {}
145 for key,val in dict.items():
146 if public_value(key, val):
147 cls_dict[key] = val
148 else:
149 # must be a param/port setting
150 value_dict[key] = val
151 if 'abstract' not in value_dict:
152 value_dict['abstract'] = False
153 if 'cxx_bases' not in value_dict:
154 value_dict['cxx_bases'] = []
155 cls_dict['_value_dict'] = value_dict
156 cls = super(MetaSimObject, mcls).__new__(mcls, name, bases, cls_dict)
157 if 'type' in value_dict:
158 allClasses[name] = cls
159 return cls
160
161 # subclass initialization
162 def __init__(cls, name, bases, dict):
163 # calls type.__init__()... I think that's a no-op, but leave
164 # it here just in case it's not.
165 super(MetaSimObject, cls).__init__(name, bases, dict)
166
167 # initialize required attributes
168
169 # class-only attributes
170 cls._params = multidict() # param descriptions
171 cls._ports = multidict() # port descriptions
172
173 # class or instance attributes
174 cls._values = multidict() # param values
175 cls._hr_values = multidict() # human readable param values
176 cls._children = multidict() # SimObject children
177 cls._port_refs = multidict() # port ref objects
178 cls._instantiated = False # really instantiated, cloned, or subclassed
179
180 # We don't support multiple inheritance of sim objects. If you want
181 # to, you must fix multidict to deal with it properly. Non sim-objects
182 # are ok, though
183 bTotal = 0
184 for c in bases:
185 if isinstance(c, MetaSimObject):
186 bTotal += 1
187 if bTotal > 1:
188 raise TypeError, "SimObjects do not support multiple inheritance"
189
190 base = bases[0]
191
192 # Set up general inheritance via multidicts. A subclass will
193 # inherit all its settings from the base class. The only time
194 # the following is not true is when we define the SimObject
195 # class itself (in which case the multidicts have no parent).
196 if isinstance(base, MetaSimObject):
197 cls._base = base
198 cls._params.parent = base._params
199 cls._ports.parent = base._ports
200 cls._values.parent = base._values
201 cls._hr_values.parent = base._hr_values
202 cls._children.parent = base._children
203 cls._port_refs.parent = base._port_refs
204 # mark base as having been subclassed
205 base._instantiated = True
206 else:
207 cls._base = None
208
209 # default keyword values
210 if 'type' in cls._value_dict:
211 if 'cxx_class' not in cls._value_dict:
212 cls._value_dict['cxx_class'] = cls._value_dict['type']
213
214 cls._value_dict['cxx_type'] = '%s *' % cls._value_dict['cxx_class']
215
216 if 'cxx_header' not in cls._value_dict:
217 global noCxxHeader
218 noCxxHeader = True
219 warn("No header file specified for SimObject: %s", name)
220
221 # Export methods are automatically inherited via C++, so we
222 # don't want the method declarations to get inherited on the
223 # python side (and thus end up getting repeated in the wrapped
224 # versions of derived classes). The code below basicallly
225 # suppresses inheritance by substituting in the base (null)
226 # versions of these methods unless a different version is
227 # explicitly supplied.
228 for method_name in ('export_methods', 'export_method_cxx_predecls',
229 'export_method_swig_predecls'):
230 if method_name not in cls.__dict__:
231 base_method = getattr(MetaSimObject, method_name)
232 m = MethodType(base_method, cls, MetaSimObject)
233 setattr(cls, method_name, m)
234
235 # Now process the _value_dict items. They could be defining
236 # new (or overriding existing) parameters or ports, setting
237 # class keywords (e.g., 'abstract'), or setting parameter
238 # values or port bindings. The first 3 can only be set when
239 # the class is defined, so we handle them here. The others
240 # can be set later too, so just emulate that by calling
241 # setattr().
242 for key,val in cls._value_dict.items():
243 # param descriptions
244 if isinstance(val, ParamDesc):
245 cls._new_param(key, val)
246
247 # port objects
248 elif isinstance(val, Port):
249 cls._new_port(key, val)
250
251 # init-time-only keywords
252 elif cls.init_keywords.has_key(key):
253 cls._set_keyword(key, val, cls.init_keywords[key])
254
255 # default: use normal path (ends up in __setattr__)
256 else:
257 setattr(cls, key, val)
258
259 def _set_keyword(cls, keyword, val, kwtype):
260 if not isinstance(val, kwtype):
261 raise TypeError, 'keyword %s has bad type %s (expecting %s)' % \
262 (keyword, type(val), kwtype)
263 if isinstance(val, FunctionType):
264 val = classmethod(val)
265 type.__setattr__(cls, keyword, val)
266
267 def _new_param(cls, name, pdesc):
268 # each param desc should be uniquely assigned to one variable
269 assert(not hasattr(pdesc, 'name'))
270 pdesc.name = name
271 cls._params[name] = pdesc
272 if hasattr(pdesc, 'default'):
273 cls._set_param(name, pdesc.default, pdesc)
274
275 def _set_param(cls, name, value, param):
276 assert(param.name == name)
277 try:
278 hr_value = value
279 value = param.convert(value)
280 except Exception, e:
281 msg = "%s\nError setting param %s.%s to %s\n" % \
282 (e, cls.__name__, name, value)
283 e.args = (msg, )
284 raise
285 cls._values[name] = value
286 # if param value is a SimObject, make it a child too, so that
287 # it gets cloned properly when the class is instantiated
288 if isSimObjectOrVector(value) and not value.has_parent():
289 cls._add_cls_child(name, value)
290 # update human-readable values of the param if it has a literal
291 # value and is not an object or proxy.
292 if not (isSimObjectOrVector(value) or\
293 isinstance(value, m5.proxy.BaseProxy)):
294 cls._hr_values[name] = hr_value
295
296 def _add_cls_child(cls, name, child):
297 # It's a little funky to have a class as a parent, but these
298 # objects should never be instantiated (only cloned, which
299 # clears the parent pointer), and this makes it clear that the
300 # object is not an orphan and can provide better error
301 # messages.
302 child.set_parent(cls, name)
303 cls._children[name] = child
304
305 def _new_port(cls, name, port):
306 # each port should be uniquely assigned to one variable
307 assert(not hasattr(port, 'name'))
308 port.name = name
309 cls._ports[name] = port
310
311 # same as _get_port_ref, effectively, but for classes
312 def _cls_get_port_ref(cls, attr):
313 # Return reference that can be assigned to another port
314 # via __setattr__. There is only ever one reference
315 # object per port, but we create them lazily here.
316 ref = cls._port_refs.get(attr)
317 if not ref:
318 ref = cls._ports[attr].makeRef(cls)
319 cls._port_refs[attr] = ref
320 return ref
321
322 # Set attribute (called on foo.attr = value when foo is an
323 # instance of class cls).
324 def __setattr__(cls, attr, value):
325 # normal processing for private attributes
326 if public_value(attr, value):
327 type.__setattr__(cls, attr, value)
328 return
329
330 if cls.keywords.has_key(attr):
331 cls._set_keyword(attr, value, cls.keywords[attr])
332 return
333
334 if cls._ports.has_key(attr):
335 cls._cls_get_port_ref(attr).connect(value)
336 return
337
338 if isSimObjectOrSequence(value) and cls._instantiated:
339 raise RuntimeError, \
340 "cannot set SimObject parameter '%s' after\n" \
341 " class %s has been instantiated or subclassed" \
342 % (attr, cls.__name__)
343
344 # check for param
345 param = cls._params.get(attr)
346 if param:
347 cls._set_param(attr, value, param)
348 return
349
350 if isSimObjectOrSequence(value):
351 # If RHS is a SimObject, it's an implicit child assignment.
352 cls._add_cls_child(attr, coerceSimObjectOrVector(value))
353 return
354
355 # no valid assignment... raise exception
356 raise AttributeError, \
357 "Class %s has no parameter \'%s\'" % (cls.__name__, attr)
358
359 def __getattr__(cls, attr):
360 if attr == 'cxx_class_path':
361 return cls.cxx_class.split('::')
362
363 if attr == 'cxx_class_name':
364 return cls.cxx_class_path[-1]
365
366 if attr == 'cxx_namespaces':
367 return cls.cxx_class_path[:-1]
368
369 if cls._values.has_key(attr):
370 return cls._values[attr]
371
372 if cls._children.has_key(attr):
373 return cls._children[attr]
374
375 raise AttributeError, \
376 "object '%s' has no attribute '%s'" % (cls.__name__, attr)
377
378 def __str__(cls):
379 return cls.__name__
380
381 # See ParamValue.cxx_predecls for description.
382 def cxx_predecls(cls, code):
383 code('#include "params/$cls.hh"')
384
385 # See ParamValue.swig_predecls for description.
386 def swig_predecls(cls, code):
387 code('%import "python/m5/internal/param_$cls.i"')
388
389 # Hook for exporting additional C++ methods to Python via SWIG.
390 # Default is none, override using @classmethod in class definition.
391 def export_methods(cls, code):
392 pass
393
394 # Generate the code needed as a prerequisite for the C++ methods
395 # exported via export_methods() to be compiled in the _wrap.cc
396 # file. Typically generates one or more #include statements. If
397 # any methods are exported, typically at least the C++ header
398 # declaring the relevant SimObject class must be included.
399 def export_method_cxx_predecls(cls, code):
400 pass
401
402 # Generate the code needed as a prerequisite for the C++ methods
403 # exported via export_methods() to be processed by SWIG.
404 # Typically generates one or more %include or %import statements.
405 # If any methods are exported, typically at least the C++ header
406 # declaring the relevant SimObject class must be included.
407 def export_method_swig_predecls(cls, code):
408 pass
409
410 # Generate the declaration for this object for wrapping with SWIG.
411 # Generates code that goes into a SWIG .i file. Called from
412 # src/SConscript.
413 def swig_decl(cls, code):
414 class_path = cls.cxx_class.split('::')
415 classname = class_path[-1]
416 namespaces = class_path[:-1]
417
418 # The 'local' attribute restricts us to the params declared in
419 # the object itself, not including inherited params (which
420 # will also be inherited from the base class's param struct
421 # here).
422 params = cls._params.local.values()
423 ports = cls._ports.local
424
425 code('%module(package="m5.internal") param_$cls')
426 code()
427 code('%{')
428 code('#include "sim/sim_object.hh"')
429 code('#include "params/$cls.hh"')
430 for param in params:
431 param.cxx_predecls(code)
432 code('#include "${{cls.cxx_header}}"')
433 cls.export_method_cxx_predecls(code)
434 code('''\
435/**
436 * This is a workaround for bug in swig. Prior to gcc 4.6.1 the STL
437 * headers like vector, string, etc. used to automatically pull in
438 * the cstddef header but starting with gcc 4.6.1 they no longer do.
439 * This leads to swig generated a file that does not compile so we
440 * explicitly include cstddef. Additionally, including version 2.0.4,
441 * swig uses ptrdiff_t without the std:: namespace prefix which is
442 * required with gcc 4.6.1. We explicitly provide access to it.
443 */
444#include <cstddef>
445using std::ptrdiff_t;
446''')
447 code('%}')
448 code()
449
450 for param in params:
451 param.swig_predecls(code)
452 cls.export_method_swig_predecls(code)
453
454 code()
455 if cls._base:
456 code('%import "python/m5/internal/param_${{cls._base}}.i"')
457 code()
458
459 for ns in namespaces:
460 code('namespace $ns {')
461
462 if namespaces:
463 code('// avoid name conflicts')
464 sep_string = '_COLONS_'
465 flat_name = sep_string.join(class_path)
466 code('%rename($flat_name) $classname;')
467
468 code()
469 code('// stop swig from creating/wrapping default ctor/dtor')
470 code('%nodefault $classname;')
471 code('class $classname')
472 if cls._base:
473 bases = [ cls._base.cxx_class ] + cls.cxx_bases
474 else:
475 bases = cls.cxx_bases
476 base_first = True
477 for base in bases:
478 if base_first:
479 code(' : public ${{base}}')
480 base_first = False
481 else:
482 code(' , public ${{base}}')
483
484 code('{')
485 code(' public:')
486 cls.export_methods(code)
487 code('};')
488
489 for ns in reversed(namespaces):
490 code('} // namespace $ns')
491
492 code()
493 code('%include "params/$cls.hh"')
494
495
496 # Generate the C++ declaration (.hh file) for this SimObject's
497 # param struct. Called from src/SConscript.
498 def cxx_param_decl(cls, code):
499 # The 'local' attribute restricts us to the params declared in
500 # the object itself, not including inherited params (which
501 # will also be inherited from the base class's param struct
502 # here).
503 params = cls._params.local.values()
504 ports = cls._ports.local
505 try:
506 ptypes = [p.ptype for p in params]
507 except:
508 print cls, p, p.ptype_str
509 print params
510 raise
511
512 class_path = cls._value_dict['cxx_class'].split('::')
513
514 code('''\
515#ifndef __PARAMS__${cls}__
516#define __PARAMS__${cls}__
517
518''')
519
520 # A forward class declaration is sufficient since we are just
521 # declaring a pointer.
522 for ns in class_path[:-1]:
523 code('namespace $ns {')
524 code('class $0;', class_path[-1])
525 for ns in reversed(class_path[:-1]):
526 code('} // namespace $ns')
527 code()
528
529 # The base SimObject has a couple of params that get
530 # automatically set from Python without being declared through
531 # the normal Param mechanism; we slip them in here (needed
532 # predecls now, actual declarations below)
533 if cls == SimObject:
534 code('''
535#ifndef PY_VERSION
536struct PyObject;
537#endif
538
539#include <string>
540''')
541 for param in params:
542 param.cxx_predecls(code)
543 for port in ports.itervalues():
544 port.cxx_predecls(code)
545 code()
546
547 if cls._base:
548 code('#include "params/${{cls._base.type}}.hh"')
549 code()
550
551 for ptype in ptypes:
552 if issubclass(ptype, Enum):
553 code('#include "enums/${{ptype.__name__}}.hh"')
554 code()
555
556 # now generate the actual param struct
557 code("struct ${cls}Params")
558 if cls._base:
559 code(" : public ${{cls._base.type}}Params")
560 code("{")
561 if not hasattr(cls, 'abstract') or not cls.abstract:
562 if 'type' in cls.__dict__:
563 code(" ${{cls.cxx_type}} create();")
564
565 code.indent()
566 if cls == SimObject:
567 code('''
568 SimObjectParams() {}
569 virtual ~SimObjectParams() {}
570
571 std::string name;
572 PyObject *pyobj;
573 ''')
574 for param in params:
575 param.cxx_decl(code)
576 for port in ports.itervalues():
577 port.cxx_decl(code)
578
579 code.dedent()
580 code('};')
581
582 code()
583 code('#endif // __PARAMS__${cls}__')
584 return code
585
586
587# This *temporary* definition is required to support calls from the
588# SimObject class definition to the MetaSimObject methods (in
589# particular _set_param, which gets called for parameters with default
590# values defined on the SimObject class itself). It will get
591# overridden by the permanent definition (which requires that
592# SimObject be defined) lower in this file.
593def isSimObjectOrVector(value):
594 return False
595
596# This class holds information about each simobject parameter
597# that should be displayed on the command line for use in the
598# configuration system.
599class ParamInfo(object):
600 def __init__(self, type, desc, type_str, example, default_val, access_str):
601 self.type = type
602 self.desc = desc
603 self.type_str = type_str
604 self.example_str = example
605 self.default_val = default_val
606 # The string representation used to access this param through python.
607 # The method to access this parameter presented on the command line may
608 # be different, so this needs to be stored for later use.
609 self.access_str = access_str
610 self.created = True
611
612 # Make it so we can only set attributes at initialization time
613 # and effectively make this a const object.
614 def __setattr__(self, name, value):
615 if not "created" in self.__dict__:
616 self.__dict__[name] = value
617
618# The SimObject class is the root of the special hierarchy. Most of
619# the code in this class deals with the configuration hierarchy itself
620# (parent/child node relationships).
621class SimObject(object):
622 # Specify metaclass. Any class inheriting from SimObject will
623 # get this metaclass.
624 __metaclass__ = MetaSimObject
625 type = 'SimObject'
626 abstract = True
627
628 cxx_header = "sim/sim_object.hh"
629 cxx_bases = [ "Drainable", "Serializable" ]
630 eventq_index = Param.UInt32(Parent.eventq_index, "Event Queue Index")
631
632 @classmethod
633 def export_method_swig_predecls(cls, code):
634 code('''
635%include <std_string.i>
636
637%import "python/swig/drain.i"
638%import "python/swig/serialize.i"
639''')
640
641 @classmethod
642 def export_methods(cls, code):
643 code('''
644 void init();
645 void loadState(Checkpoint *cp);
646 void initState();
647 void regStats();
648 void resetStats();
649 void regProbePoints();
650 void regProbeListeners();
651 void startup();
652''')
653
654 # Returns a dict of all the option strings that can be
655 # generated as command line options for this simobject instance
656 # by tracing all reachable params in the top level instance and
657 # any children it contains.
658 def enumerateParams(self, flags_dict = {},
659 cmd_line_str = "", access_str = ""):
660 if hasattr(self, "_paramEnumed"):
661 print "Cycle detected enumerating params"
662 else:
663 self._paramEnumed = True
664 # Scan the children first to pick up all the objects in this SimObj
665 for keys in self._children:
666 child = self._children[keys]
667 next_cmdline_str = cmd_line_str + keys
668 next_access_str = access_str + keys
669 if not isSimObjectVector(child):
670 next_cmdline_str = next_cmdline_str + "."
671 next_access_str = next_access_str + "."
672 flags_dict = child.enumerateParams(flags_dict,
673 next_cmdline_str,
674 next_access_str)
675
676 # Go through the simple params in the simobject in this level
677 # of the simobject hierarchy and save information about the
678 # parameter to be used for generating and processing command line
679 # options to the simulator to set these parameters.
680 for keys,values in self._params.items():
681 if values.isCmdLineSettable():
682 type_str = ''
683 ex_str = values.example_str()
684 ptype = None
685 if isinstance(values, VectorParamDesc):
686 type_str = 'Vector_%s' % values.ptype_str
687 ptype = values
688 else:
689 type_str = '%s' % values.ptype_str
690 ptype = values.ptype
691
692 if keys in self._hr_values\
693 and keys in self._values\
694 and not isinstance(self._values[keys], m5.proxy.BaseProxy):
695 cmd_str = cmd_line_str + keys
696 acc_str = access_str + keys
697 flags_dict[cmd_str] = ParamInfo(ptype,
698 self._params[keys].desc, type_str, ex_str,
699 values.pretty_print(self._hr_values[keys]),
700 acc_str)
701 elif not keys in self._hr_values\
702 and not keys in self._values:
703 # Empty param
704 cmd_str = cmd_line_str + keys
705 acc_str = access_str + keys
706 flags_dict[cmd_str] = ParamInfo(ptype,
707 self._params[keys].desc,
708 type_str, ex_str, '', acc_str)
709
710 return flags_dict
711
712 # Initialize new instance. For objects with SimObject-valued
713 # children, we need to recursively clone the classes represented
714 # by those param values as well in a consistent "deep copy"-style
715 # fashion. That is, we want to make sure that each instance is
716 # cloned only once, and that if there are multiple references to
717 # the same original object, we end up with the corresponding
718 # cloned references all pointing to the same cloned instance.
719 def __init__(self, **kwargs):
720 ancestor = kwargs.get('_ancestor')
721 memo_dict = kwargs.get('_memo')
722 if memo_dict is None:
723 # prepare to memoize any recursively instantiated objects
724 memo_dict = {}
725 elif ancestor:
726 # memoize me now to avoid problems with recursive calls
727 memo_dict[ancestor] = self
728
729 if not ancestor:
730 ancestor = self.__class__
731 ancestor._instantiated = True
732
733 # initialize required attributes
734 self._parent = None
735 self._name = None
736 self._ccObject = None # pointer to C++ object
737 self._ccParams = None
738 self._instantiated = False # really "cloned"
739
740 # Clone children specified at class level. No need for a
741 # multidict here since we will be cloning everything.
742 # Do children before parameter values so that children that
743 # are also param values get cloned properly.
744 self._children = {}
745 for key,val in ancestor._children.iteritems():
746 self.add_child(key, val(_memo=memo_dict))
747
748 # Inherit parameter values from class using multidict so
749 # individual value settings can be overridden but we still
750 # inherit late changes to non-overridden class values.
751 self._values = multidict(ancestor._values)
752 self._hr_values = multidict(ancestor._hr_values)
753 # clone SimObject-valued parameters
754 for key,val in ancestor._values.iteritems():
755 val = tryAsSimObjectOrVector(val)
756 if val is not None:
757 self._values[key] = val(_memo=memo_dict)
758
759 # clone port references. no need to use a multidict here
760 # since we will be creating new references for all ports.
761 self._port_refs = {}
762 for key,val in ancestor._port_refs.iteritems():
763 self._port_refs[key] = val.clone(self, memo_dict)
764 # apply attribute assignments from keyword args, if any
765 for key,val in kwargs.iteritems():
766 setattr(self, key, val)
767
768 # "Clone" the current instance by creating another instance of
769 # this instance's class, but that inherits its parameter values
770 # and port mappings from the current instance. If we're in a
771 # "deep copy" recursive clone, check the _memo dict to see if
772 # we've already cloned this instance.
773 def __call__(self, **kwargs):
774 memo_dict = kwargs.get('_memo')
775 if memo_dict is None:
776 # no memo_dict: must be top-level clone operation.
777 # this is only allowed at the root of a hierarchy
778 if self._parent:
779 raise RuntimeError, "attempt to clone object %s " \
780 "not at the root of a tree (parent = %s)" \
781 % (self, self._parent)
782 # create a new dict and use that.
783 memo_dict = {}
784 kwargs['_memo'] = memo_dict
785 elif memo_dict.has_key(self):
786 # clone already done & memoized
787 return memo_dict[self]
788 return self.__class__(_ancestor = self, **kwargs)
789
790 def _get_port_ref(self, attr):
791 # Return reference that can be assigned to another port
792 # via __setattr__. There is only ever one reference
793 # object per port, but we create them lazily here.
794 ref = self._port_refs.get(attr)
795 if ref == None:
796 ref = self._ports[attr].makeRef(self)
797 self._port_refs[attr] = ref
798 return ref
799
800 def __getattr__(self, attr):
801 if self._ports.has_key(attr):
802 return self._get_port_ref(attr)
803
804 if self._values.has_key(attr):
805 return self._values[attr]
806
807 if self._children.has_key(attr):
808 return self._children[attr]
809
810 # If the attribute exists on the C++ object, transparently
811 # forward the reference there. This is typically used for
812 # SWIG-wrapped methods such as init(), regStats(),
813 # resetStats(), startup(), drain(), and
814 # resume().
815 if self._ccObject and hasattr(self._ccObject, attr):
816 return getattr(self._ccObject, attr)
817
818 err_string = "object '%s' has no attribute '%s'" \
819 % (self.__class__.__name__, attr)
820
821 if not self._ccObject:
822 err_string += "\n (C++ object is not yet constructed," \
823 " so wrapped C++ methods are unavailable.)"
824
825 raise AttributeError, err_string
826
827 # Set attribute (called on foo.attr = value when foo is an
828 # instance of class cls).
829 def __setattr__(self, attr, value):
830 # normal processing for private attributes
831 if attr.startswith('_'):
832 object.__setattr__(self, attr, value)
833 return
834
835 if self._ports.has_key(attr):
836 # set up port connection
837 self._get_port_ref(attr).connect(value)
838 return
839
840 param = self._params.get(attr)
841 if param:
842 try:
843 hr_value = value
844 value = param.convert(value)
845 except Exception, e:
846 msg = "%s\nError setting param %s.%s to %s\n" % \
847 (e, self.__class__.__name__, attr, value)
848 e.args = (msg, )
849 raise
850 self._values[attr] = value
851 # implicitly parent unparented objects assigned as params
852 if isSimObjectOrVector(value) and not value.has_parent():
853 self.add_child(attr, value)
854 # set the human-readable value dict if this is a param
855 # with a literal value and is not being set as an object
856 # or proxy.
857 if not (isSimObjectOrVector(value) or\
858 isinstance(value, m5.proxy.BaseProxy)):
859 self._hr_values[attr] = hr_value
860
861 return
862
863 # if RHS is a SimObject, it's an implicit child assignment
864 if isSimObjectOrSequence(value):
865 self.add_child(attr, value)
866 return
867
868 # no valid assignment... raise exception
869 raise AttributeError, "Class %s has no parameter %s" \
870 % (self.__class__.__name__, attr)
871
872
873 # this hack allows tacking a '[0]' onto parameters that may or may
874 # not be vectors, and always getting the first element (e.g. cpus)
875 def __getitem__(self, key):
876 if key == 0:
877 return self
878 raise IndexError, "Non-zero index '%s' to SimObject" % key
879
880 # this hack allows us to iterate over a SimObject that may
881 # not be a vector, so we can call a loop over it and get just one
882 # element.
883 def __len__(self):
884 return 1
885
886 # Also implemented by SimObjectVector
887 def clear_parent(self, old_parent):
888 assert self._parent is old_parent
889 self._parent = None
890
891 # Also implemented by SimObjectVector
892 def set_parent(self, parent, name):
893 self._parent = parent
894 self._name = name
895
896 # Return parent object of this SimObject, not implemented by SimObjectVector
897 # because the elements in a SimObjectVector may not share the same parent
898 def get_parent(self):
899 return self._parent
900
901 # Also implemented by SimObjectVector
902 def get_name(self):
903 return self._name
904
905 # Also implemented by SimObjectVector
906 def has_parent(self):
907 return self._parent is not None
908
909 # clear out child with given name. This code is not likely to be exercised.
910 # See comment in add_child.
911 def clear_child(self, name):
912 child = self._children[name]
913 child.clear_parent(self)
914 del self._children[name]
915
916 # Add a new child to this object.
917 def add_child(self, name, child):
918 child = coerceSimObjectOrVector(child)
919 if child.has_parent():
920 warn("add_child('%s'): child '%s' already has parent", name,
921 child.get_name())
922 if self._children.has_key(name):
923 # This code path had an undiscovered bug that would make it fail
924 # at runtime. It had been here for a long time and was only
925 # exposed by a buggy script. Changes here will probably not be
926 # exercised without specialized testing.
927 self.clear_child(name)
928 child.set_parent(self, name)
929 self._children[name] = child
930
931 # Take SimObject-valued parameters that haven't been explicitly
932 # assigned as children and make them children of the object that
933 # they were assigned to as a parameter value. This guarantees
934 # that when we instantiate all the parameter objects we're still
935 # inside the configuration hierarchy.
936 def adoptOrphanParams(self):
937 for key,val in self._values.iteritems():
938 if not isSimObjectVector(val) and isSimObjectSequence(val):
939 # need to convert raw SimObject sequences to
940 # SimObjectVector class so we can call has_parent()
941 val = SimObjectVector(val)
942 self._values[key] = val
943 if isSimObjectOrVector(val) and not val.has_parent():
944 warn("%s adopting orphan SimObject param '%s'", self, key)
945 self.add_child(key, val)
946
947 def path(self):
948 if not self._parent:
949 return '<orphan %s>' % self.__class__
950 ppath = self._parent.path()
951 if ppath == 'root':
952 return self._name
953 return ppath + "." + self._name
954
955 def __str__(self):
956 return self.path()
957
|