Skip to content

Document explicitly that events can be posted twice, SIMICS-23394 #413

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mandolaerik wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Document explicitly that events can be posted twice, SIMICS-23394 #413

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
abf7247
Document explicitly that events can be posted twice, SIMICS-23394
mandolaerik Feb 15, 2026
05ac3e7
DML 1.4 does not support step events
mandolaerik Feb 17, 2026
9e93867
Consistently use "CPU" instead of "processor"
mandolaerik Feb 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions doc/1.4/language.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -839,7 +839,7 @@ import "simics/devs/ethernet.dml"
### Events

An *event* object is an encapsulation of a Simics event that can
be posted on a processor time or step queue. The location of event
be posted on the time queue of a CPU. The location of event
objects in the object hierarchy of the device is not important, so an
event object can generally be placed wherever it is most convenient.

Expand Down Expand Up @@ -3722,7 +3722,7 @@ after: <em>method</em>(<em>e1</em>, ... <em>eN</em>);
</pre>

In this form, the specified point in the future is when control is given back to
the simulation engine such that the ongoing simulation of the current processor
the simulation engine such that the ongoing simulation of the current CPU
may progress, and would otherwise be ready to move onto the next cycle.
This happens after all entries to devices on the call stack have been completed.

Expand All @@ -3737,8 +3737,8 @@ after statement is designed to execute the callback as promptly as possible
while satisfying the semantics stated above, while `after 0 cycles: ...` is not.
In particular, in Simics, callbacks delayed via `after 0 cycles` are always
bound to the clock associated with the device instance, which is not always
that of the processor currently under simulation &mdash; in such cases the
simulated processor may progress indefinitely without the posted callback being
that of the CPU currently under simulation &mdash; in such cases the
simulated CPU may progress indefinitely without the posted callback being
executed. The immediate after statement does not have this issue.
In addition, if an immediate after statement is executed while the
simulation is stopped (due to a device entry such as an attribute get/set
Expand Down
19 changes: 18 additions & 1 deletion lib/1.4/dml-builtins.dml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3963,7 +3963,13 @@ Non-overrideable method. Posts the event on the associated queue of the
device. The time argument is specified in cycles or seconds, depending on which
template was instantiated. The event will be triggered after the specified
amount of time has elapsed. The data parameter in a `uint64` or
`custom` event will be passed on to the event() method.
`custom` event will be passed on to the `event()` method.

It is allowed to call the `post()` method of an event object again before the
event callback from the previous call has been invoked; in this case, the
event callback will be invoked twice. In the `uint64_*_event` and
`custom_*_event` cases, the event data may or may not be identical between the
two calls.
Copy link
Contributor

@lwaern-intel lwaern-intel Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you should reference remove() parenthetically here:

... , and hence remove() may cancel only one pending callback but not the other.

Copy link
Contributor Author

@mandolaerik mandolaerik Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Except that we haven't mentioned remove yet. I can add a note to remove.

</dd></dl>

The following methods are specific to the `simple_time_event`,
Expand All @@ -3977,6 +3983,17 @@ The following methods are specific to the `simple_time_event`,

Removes all events of this type with matching data from
the queue.

> [!NOTE]
>
> If multiple outstanding events are needed from the same event object, and
> these need to be selectively canceled, then this can only be achieved if the
> event is based on `uint64_*_event`. If more complex event data is required,
> then this can be achieved by assigning a unique integer ID with each
> outstanding event, store the event data of all outstanding events together
> with their IDs in an attribute, and only send the IDs as event data, thus
> allowing `remove` to uniquely identify each posted event.

</dd><dt>

<small>posted() -&gt; (bool), posted(uint64 value) -&gt; (bool)</small>
Expand Down