Previous - Up - Next
5.2 Standard Methods
This section describes the built-in methods of the different object
types. Most methods can be redefined by the user, unless otherwise
stated.
5.2.1 Array Methods
- hard_reset()
- Invokes the hard_reset method on each element of the
array.
- soft_reset()
- Invokes the soft_reset method on each element of the
array.
- get_attribute() -> (attr_value_t val)
- Not intended to be used directly. Implements reading of an array
attribute as a Simics vector, by calling the get_attribute
methods on individual elements of the array.
- set_attribute(attr_value_t val) -> (set_error_t err)
- Not intended to be used directly. Implements assignment of a Simics
vector to an array attribute, by calling the set_attribute
methods on individual elements of the array.
5.2.2 Device Methods
- init()
- Called when the device object is loaded, but before its
configuration-object attributes have been initialized.
- post_init()
- Called when the device object is loaded, after its
configuration-object attributes have been initialized.
- hard_reset()
- Called by Simics when a hard reset is performed on the device.
Invokes the hard_reset method on each bank of
the device.
- soft_reset()
- Called by Simics when a soft reset is performed on the device.
Invokes the soft_reset method on each bank of
the device.
5.2.3 Attribute Methods
- get() -> (attr_value_t value)
- Returns the value of the attribute.
- set(attr_value_t value)
- Sets the value of the attribute.
- after_set()
- Called by set_attribute just after the set method
has been called. The default implementation does nothing.
- get_attribute -> (attr_value_t value)
- Not intended to be used directly. Called by Simics for reading the
attribute value. Calls the get method to read the value, and
handles any exceptions that may occur.
- set_attribute(attr_value_t value) -> (set_error_t err)
- Not intended to be used directly. Called by Simics for setting the
attribute value. Calls the set method to set the value, and
afterwards calls the after_set method if set
succeeded. Handles any exceptions that may occur.
5.2.4 Bank Methods
- access(generic_transaction_t *memop, uint32 offset, uint32 size)
- Called when the bank is accessed via the io_memory
interface. Depending on the memop contents, the
read_access or write_access method is called. For a
write access, the method get_write_value is called to extract
the value from the memop. If the access succeeded, the corresponding
finalize_read_access or finalize_read_access method is
called, updating the memop before the access method
returns; otherwise, the miss_read_access or
miss_write_access method, respectively, is called. If this also
fails to handle the access, the generic miss_access method is
called, and gets full responsibility for updating the memop.
To signal a complete failure to handle the access, the access
method (or any method that it calls, such as miss_access)
should raise an exception instead of returning. This will be caught and
handled by the io-memory.dml library.
- read_access(generic_transaction_t *memop, uint32 offset, uint32 size)
-> (bool success, uint64 value)
- Performs a read access by calling the corresponding
read_access method of the addressed register (or registers, for
overlapping accesses). Does not update the memop. If the access
is valid, the success output parameter is set to true,
otherwise to false.
- read(generic_transaction_t *memop, uint32 offset, uint32 size) -> (uint64 value)
- Utility method; equivalent to calling read_access, but does
not return a success flag. E.g., can be used to read directly from a bank
when it is known that the access will always succeed.
- write_access(generic_transaction_t *memop, uint32 offset, uint32 size,
uint64 value) -> (bool success)
- Performs a write access by calling the corresponding
write_access method of the addressed register (or registers,
for overlapping accesses). Does not update the memop. If the
access is valid, the success output parameter is set to
true, otherwise to false.
- write(generic_transaction_t *memop, uint32 offset, uint32 size, uint64 value)
- Utility method; equivalent to calling write_access, but
does not return a success flag. E.g., can be used to write directly to a
bank when it is known that the access will always succeed.
- miss_read_access(uint32 offset, uint32 size) -> (bool success,
uint64 value)
- Called from access upon a missed read access. By default,
this function only sets the success output parameter to
false and returns. Provides a simple hook for handling read
misses.
- miss_write_access(uint32 offset, uint32 size, uint64 value)
-> (bool success)
- Called from access upon a missed write access. By default,
this function only sets the success output parameter to
false and returns. Provides a simple hook for handling write
misses.
- miss_access(generic_transaction_t *memop, uint32 offset, uint32 size)
- Called from access when the access could not be handled.
This method takes over the responsibility for either updating the
memop and returning, or raising an exception; see
access for further details.
By default, an info message will be logged. If the parameter
miss_bank of the bank is not undefined, then the
access is redirected to the bank referred to by miss_bank,
adding the value of the parameter miss_bank_offset (default 0)
to the offset for the access. Otherwise, a specification violation
message is logged and an exception is raised.
- finalize_read_access(generic_transaction_t *memop, uint64 val)
- Called by access when a read access has succeeded. By
default, this method calls set_read_value to update the
memop. This method may also be useful to call when overriding
miss_access.
- finalize_write_access(generic_transaction_t *memop, uint64 val)
- Called by access when a write access has succeeded. By
default it has no effect, since the memop normally does not
need updating after a write; cf. finalize_read_access.
- get_write_value(generic_transaction_t *memop) -> (uint64 writeval)
- Extracts the value to be written from the memop. How this
is done depends on the byte_order parameter.
- set_read_value(generic_transaction_t *memop, uint64 value)
- Stores the read value in the memop. How this is done
depends on the byte_order parameter.
- hard_reset()
- Called automatically from the hard_reset method of the
device. Invokes the hard_reset method on each
register of the bank.
- soft_reset()
- Called automatically from the soft_reset method of the
device. Invokes the soft_reset method on each
register of the bank.
5.2.5 Register Methods
- get() -> (value)
- Returns the value of the register, without any other effects. If the
register contains fields, this is done by calling the get
method on each field of the register and composing the
results into a single value.
- set(value)
- Sets the value of the register, without any other effects. If the
register contains fields, this is done by calling the set
method on each field of the register, for the
corresponding components of the value.
- read_access(generic_transaction_t *memop, msb1, lsb) -> (value)
- Performs a read access by invoking the read method of
the register, or if the register contains fields, by invoking the
read_access method on each of its fields and composing the
results into a single value. For a partial access, only affected
fields are read. The fields are read in order, starting with the
field containing the least significant bits of the register and ending
with the field containing the most significant bits of the
register. Finally, the after_read method of the register is
called. This method is called from the access method of the
bank.
- write_access(generic_transaction_t *memop, msb1, lsb, value)
- Performs a write access by invoking the write method of
the register, or if the register contains fields, by invoking the
write_access method on each of its fields for the
corresponding components of the value. For a partial access, only
affected fields are written. The fields are written in order, starting
with the field containing the least significant bits of the register
and ending with the field containing the most significant bits of the
register. Finally, the after_write method of the register
is called. This method is called from the access method of
the bank.
- read() -> (value)
- Called by read_access for reading the actual value of the
register. This is not used if the register contains fields.
- write(value)
- Called by write_access for performing the actual write to
the register. This is not used if the register contains fields.
- after_read(generic_transaction_t *memop)
- Called at the very end of the read_access method. The
default implementation does nothing.
- after_write(generic_transaction_t *memop)
- Called at the very end of the write_access method. The
default implementation does nothing.
- hard_reset_register()
- Called automatically from the hard_reset method of the
bank. Invokes the hard_reset method of the register, or if the
register contains fields, invokes the hard_reset method on each
of its fields. Finally, the after_hard_reset method of the
register is called.
- soft_reset_register()
- Called automatically from the soft_reset method of the
bank. Invokes the soft_reset method of the register, or if the
register contains fields, invokes the soft_reset method on each
of its fields. Finally, the after_soft_reset method of the
register is called.
- hard_reset()
- Called by hard_reset_register for performing the actual
hard reset. This is not used if the register contains fields.
- soft_reset()
- Called by hard_reset_register for performing the actual
soft reset. This is not used if the register contains fields.
- after_hard_reset()
- Called at the very end of the hard_reset method. The
default implementation does nothing.
- after_soft_reset()
- Called at the very end of the soft_reset method. The
default implementation does nothing.
- get_attribute -> (attr_value_t value)
- Not intended to be used directly. Called by Simics for reading the
value of the register as an attribute. Calls the get method to
read the value, and handles any exceptions that may occur.
- set_attribute(attr_value_t value) -> (set_error_t err)
- Not intended to be used directly. Called by Simics for setting the
value of the register as an attribute. Calls the set method to
set the value, and finally calls the after_set method if
set succeeded. Handles any exceptions that may occur.
- after_set()
- Called by set_attribute just after the set method
has been called, if it succeeded. The default implementation does
nothing.
5.2.6 Field Methods
- get() -> (value)
- Returns the value of the field, without any other effects.
- set(value)
- Sets the value of the field, without any other effects.
- read() -> (value)
- Performs an actual read from the field. Called from the
read_access method.
- write(value)
- Performs an actual write to the field. Called from the
write_access method. The write functions
for the fields in a register are called in a defined order.
The field containing the least significant bits of the register are
called first, and the field containing the most significant bits are
called last. See the documentation for write_access on a
register for more information.
- read_access() -> (value)
- Usually not used directly. Performs a read access on the field by
calling the read method. Called from the read_access
method of the containing register.
- write_access(value)
- Usually not used directly. Performs a write access to the field by
calling the write method. Called from the write_access
method of the containing register.
- hard_reset()
- Performs a hard reset on the field. Called from the
hard_reset_register method of the containing register.
- soft_reset()
- Performs a soft reset on the field. Called from the
soft_reset_register method of the containing register.
5.2.7 Connect Methods
- after_set()
- Called at the very end of the set_attribute method. The
default implementation does nothing.
- get_attribute -> (attr_value_t value)
- Not intended to be used directly. Called by Simics for reading the
value of the connect as an attribute.
- set_attribute(attr_value_t value) -> (set_error_t err)
- Not intended to be used directly. Called by Simics for setting the
value of the connect as an attribute. Afterwards calls the
after_set method. Handles any exceptions that may occur.
5.2.8 Interface Methods
Interfaces have no documented standard methods in DML 1.0.
5.2.9 Event Methods
- event(void *data)
- The method called when the event is triggered. The default event
method logs a short info message noting that the event occurred.
- get_event_info(void *data) -> (attr_value_t info)
- This method is called once for each pending event instance when
saving a checkpoint. It should create an attribute value that can be
used to restore the event. The data parameter is the
user data provided in the post call. The default
implementation always returns a nil value.
- set_event_info(attr_value_t info) -> (void *data)
- This method is used to restore event information when loading a
checkpoint. It should use the attribute value to create a user data
pointer, as if it had been provided in a post. The default
implementation only checks that the checkpointed information is
nil.
- post(time, void *data)
- Posts the event on the associated queue of the device, with the
specified time (relative to the current time, in the unit specified by
the timebase parameter), and additional data.
- post_on_queue(conf_object_t *queue, when, void *data)
- Like post, but posts the event on the specified queue.
This is very rarely needed, since the events should usually always be
posted to the queue that the device belongs to, as configured by the
queue attribute.
- remove(void *data)
- Removes the event from the queue.
- posted(void *data) -> (flag)
- Returns true if the event is in the queue, and
false otherwise.
- next(void *data) -> (time)
- Returns the time to the next occurrence of the event in the queue
(relative to the current time, in the unit specified by the
timebase parameter). If there is no such event in the queue, a
negative value is returned.
5.2.10 Implement Methods
Implements have no documented standard methods in DML 1.0.
Previous - Up - Next