pyobj
import pyobj
class pyobj.Attribute(top, up)
A Simics attribute.
The pyobj.Attribute class defines an attribute that will be registered for the containing pyobj.ConfObject class. The attribute will be registered with Simics using the SIM_register_attribute function. See documentation for SIM_register_attribute for detailed information about attributes.
The arguments to SIM_register_attribute is taken from the class members. The attrattr member is an attr_attr_t type and its default value is Sim_Attr_Optional. The attrtype member is a string defining the type of the attribute, default value is ‘a’.
The class methods named getter and setter will be used as get_attr and set_attr functions when registering the attribute. The methods are optional. An attribute without a getter can not be read. An attribute without a setter can not be written.
The attribute description is the same as the Python class description.
The _initialize method can be defined if special initialization behavior is required. This can for instance be used to set the default value.
class wee(pyobj.Attribute):
"""Documentation for the attribute goes here."""
attrattr = simics.Sim_Attr_Pseudo
attrtype = 'i'
def _initialize(self):
self.val = 4711
def getter(self):
self.val += 3
return self.val
def setter(self, val):
self.val = val
pyobj.SimpleAttribute, pyobj.ClassAttribute, pyobj.ConfObject
class pyobj.ClassAttribute(top, up)
A Simics class attribute.
The pyobj.ClassAttribute class defines an attribute that will be registered for the containing pyobj.ConfObject class. The attribute will be registered with Simics using the SIM_register_class_attribute function. See documentation for SIM_register_class_attribute for detailed information about class attributes.
The value stored in the class should always be stored in the attribute named val. This is to avoid problems when a class that defines a pyobj.ClassAttribute class is inherited by more than one class.
The pyobj.ClassAttribute class is very similar to the pyobj.Attribute class. See the documentation for the pyobj.Attribute class for how to use this class.
class wee(pyobj.ClassAttribute):
"""Documentation for the attribute goes here."""
attrtype = 'i'
val = 4711
@classmethod
def getter(cls): return cls.val
@classmethod
def setter(cls, val): cls.val = val
class pyobj.ConfObject()
A Simics configuration object.
The pyobj.ConfObject class defines a new Simics class using the SIM_register_class function. You could call SIM_register_class and all the related functions for attribute and interface registration yourself, but ConfObject will make your code much more concise.
The name of the Simics class is identical to the Python class. The class description is the same as the Python class description.
The class implements the methods _initialize, _finalize, _objects_finalized, _pre_delete, _info, and _status`. All of these methods can be overridden if required.
The _initialize method is called when an object of the class is instantiated, before any attributes have been set. The _finalize and _objects_finalized methods are called in the respective finalization phases as defined by the class_info_t type. The _pre_delete method is called right before an object of the class is deleted. The default behaviour of all four functions is to recursively call the method with the same name in all Python objects in the pyobj hierarchy.
The _info and _status methods provide data for the class’s info and status commands; the format of their return value is documented with cli.new_info_command and cli.new_status_command.
If you need to get hold of the Simics conf_object_t object associated with a ConfObject instance—for example, in order to call a Simics API function—you can find it in the obj member.
The pyobj.ConfObject class can contain inner classes that define attributes, interfaces, etc. See pyobj.Port, pyobj.Attribute, pyobj.ClassAttribute, and pyobj.Interface for more documentation. An inner class has a reference to the class that contains it in its _up member.
By default, a Simics class is registered automatically whenever a subclass of pyobj.ConfObject is declared. Sometimes this is not desirable; e.g., the class may be a base class, or you may want to allow importing the containing Python file without side-effects. The automatic registration of a Simics class can then be suppressed by setting the member _do_not_init to object(). That will cause it to not be registered as a Simics class (but its subclasses will be, unless they too employ the same trick).
The class method register may be called once on each pyobj.ConfObject subclass, to register the Simics class. For a class that doesn’t suppress automatic registration, the method currently does nothing.
In future Simics versions, a Simics class will no longer be registered automatically, and an explicit call to the register method will be required for that.
The _class_kind member tells Simics whether objects of this class should be saved when a checkpoint is created. The value is passed to SIM_register_class, as the kind field of the class_data_t structure. The default value is Sim_Class_Kind_Vanilla. See the documentation of SIM_register_class for details.
class foo(pyobj.ConfObject):
"""This is the long-winded documentation for this Simics class.
It can be as long as you want."""
_class_desc = 'One-line doc for the class'
def _initialize(self):
super()._initialize()
self.my_val = 4711
def _info(self):
return [("Python device info", [("my_val", self.my_val)])]
def _status(self):
return [("Python device status",
[("woot", self.woot.val),
("signal", self.signal.val)])]
class woot(pyobj.SimpleAttribute(0, 'i|n')):
"""A four-letter attribute"""
class lost(pyobj.Attribute):
"""A pseudo attribute"""
attrattr = simics.Sim_Attr_Pseudo
def getter(self):
return self._up.my_val
class signal(pyobj.Interface):
def signal_raise(self):
simics.SIM_log_info(3, self._up.obj, 0, "Signal raised")
self.val = True
def signal_lower(self):
simics.SIM_log_info(3, self._up.obj, 0, "Signal lowered")
self.val = False
def _initialize(self): self.val = False
class pyobj.Event(top, up)
A Simics event.
pyobj.Event defines an event that will be registered for the containing pyobj.ConfObject class. Internally, registration is done with SIM_register_event; see the documentation for that API function for detailed information.
Events are posted with the post(clock, data, <duration>) method. clock determines which clock the event is posted on, and data is the event data. The duration is the number of seconds, cycles, or steps until the event triggers, specified with the appropriate keyword argument:
ev.post(a_clock, some_data, seconds=4.711)
ev.post(a_clock, some_data, cycles=4711)
ev.post(a_clock, some_data, steps=4711)
Events can be cancelled before they trigger with either cancel_time(clock, match_fun) or cancel_step(clock, match_fun) (depending on whether the event duration was specified in steps or not). The match_fun argument is optional: if given, it should be a function that accepts an event data parameter, and returns true for the events that should be cancelled; if not given, all events are cancelled.
A subclass may define the following methods:
callback(data)destroy(data)get_value(data) and set_value(val)attr_value_t value, and the other way around. If the event carries no data that needs checkpointing, you may omit these methods.describe(data)print-event-queue command. If you do not supply this method, the event’s name will be used.Additionally, it may set the flags parameter to Sim_EC_Notsaved, if the event should not be checkpointed. In this case, neither get_value nor set_value should be defined.
class foo(pyobj.ConfObject):
class ev1(pyobj.Event):
def callback(self, data):
do_something(data)
class ev2(pyobj.Event):
def callback(self, data):
self.do_something_else(data)
def get_value(self, data):
return str(data)
def set_value(self, val):
return int(val)
def describe(self, data):
return 'ev2 with %s' % data
class ev3(pyobj.Event):
flags = simics.Sim_EC_Notsaved
def callback(self, data):
self._up.do_this_third_thing(data)
class pyobj.Interface(top, up)
A Simics interface.
The pyobj.Interface class implements a Simics interface for the containing pyobj.ConfObject class. The interface is registered using the SIM_register_interface function. The interface name is taken from the class name.
The _initialize method can be overridden if special initialization behavior is required.
To implement port interfaces instead of regular interfaces, place one or more pyobj.Interface subclasses inside a pyobj.Port class.
class signal(pyobj.Interface):
def signal_raise(self): self.val = True
def signal_lower(self): self.val = False
def _initialize(self): self.val = False
class pyobj.Port(top, up)
A Simics port.
To have your pyobj.ConfObject-based Simics object implement port interfaces, put a subclass of pyobj.Port as an inner class of your pyobj.ConfObject, and put one or more pyobj.Interface subclasses inside it. The pyobj.Interface subclasses will work just as if they were at the top level, except that they will be registered with SIM_register_port_interface instead of SIM_register_interface.
The _initialize method can be overridden if special initialization behavior is required.
class wee(pyobj.Port):
class signal(pyobj.Interface):
def signal_raise(self): self.val = 2
def signal_lower(self): self.val = 1
def _initialize(self): self.val = 0
class pyobj.PortObject(top, up)
A Simics port object.
The pyobj.PortObject class defines a port object class that will be registered as a port object for the containing pyobj.ConfObject class.
The port object will be registered with the name "port.<name>;", but this can be changed by defining namespace to something other than “port”. One possibility is the empty string.
If classname is set, then the port object will be an instance of this external class rather than defining the class locally. The external class cannot be modified by adding e.g. an interface definition inside the PortObject definition.
class portname(pyobj.PortObject):
"""Documentation for the port object goes here."""
class signal(pyobj.Interface):
def signal_raise(self): self.val = 2
def signal_lower(self): self.val = 1
def _initialize(self): self.val = 0
pyobj.SimpleAttribute(init, type='a', attr=1)
A simple Simics attribute.
The pyobj.SimpleAttribute function returns a new subclass of pyobj.Attribute, with predefined getter and setter functions that simply store and retrieve the value without further side effects. The value is stored in the val member.
The init argument is the initial value, type is the attribute type string, attr is the attribute type. If init is callable, it will be called, and the return value is the initial value; otherwise, init itself is the initial value.
The attribute value is stored in the val member of the class.
pyobj.Attribute class
class wee(pyobj.SimpleAttribute(17, 'i')):
"""Documentation for the attribute goes here."""