signal interface is for modeling a logical signal, such
as a reset or interrupt. Signals are always active high in Simics with
respect to their function. This may not correspond to the actual electrical
level in a real system.
A signal connection has one initiator and one target object, where the initiator calls methods the interface implemented by the target.
The initiator object should have a configuration attribute that pointing to the target object or to an interface port of the target. This attribute, like all other attributes representing object connections, should be of the object kind, or a list of two entries where the first is an object and the second a string representing the name of the port.
The initiator should call signal_raise() to raise the signal level to its active level in the target. Once raised, the same initiator may not call signal_raise() again without an intervening call to signal_lower(). Similarly, an already low signal may not be lowered again by a signal_lower() call from the same initiator. The two functions represent the rising and the falling edge of the signal.
The target should handle the case where a signal is lowered directly after it has been raised and treat this call sequence as a valid pulse even within a single clock cycle. The target should also allow the signal to remain raised for some time before it is lowered.
While a target is disconnected, the input signal level is assumed to be low. When an initiator connects to a target by hot plugging, signal_raise() should be called if the output signal from the initiator was high. If the signal was low, then no function in the target should be called.
If the signal level is high on disconnect, then the initiator has to call signal_lower() before disconnecting from the target. Connect and disconnect is typically done by changing the attribute in the initiator that identifies the target object.
When an initiator is reset, it should call signal_lower() if the actual hardware also lowers the output signal on a reset. The target, on the other hand, should not reset its remembered value of the input.
When a connection attribute is restored from a checkpoint or during reverse
execution, no function should be called in the signal
interface of the target since the actual signal level does not change. The
attribute setter code can distinguish between hot-plugging and state
restoring by using SIM_object_is_configured() and
SIM_is_restoring_state. See the latter of the two for more
documentation.
When an object is first created and the initial signal level is high, the initiator has to call the signal_raise() function in the target. This can not be done earlier than in finalize_instance (C/C++) or in post_init() (DML) since the target has to be fully configured. Again, this should not be done when restoring a checkpoint.
There must only be a single initiator connected to a target, with the exception of the signal-bus that may have several initiators.
A target that needs more than one input signal should use ports to implement
several signal interfaces.
SIM_INTERFACE(signal) {
void (*signal_raise)(conf_object_t *NOTNULL obj);
void (*signal_lower)(conf_object_t *NOTNULL obj);
};
#define SIGNAL_INTERFACE "signal"