diff --git a/doc/1.4/language.md b/doc/1.4/language.md index 31039c43..c0078167 100644 --- a/doc/1.4/language.md +++ b/doc/1.4/language.md @@ -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. @@ -3722,7 +3722,7 @@ after: method(e1, ... eN); 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. @@ -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 — in such cases the -simulated processor may progress indefinitely without the posted callback being +that of the CPU currently under simulation — 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 diff --git a/lib/1.4/dml-builtins.dml b/lib/1.4/dml-builtins.dml index 12d96e31..d082741b 100644 --- a/lib/1.4/dml-builtins.dml +++ b/lib/1.4/dml-builtins.dml @@ -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. The following methods are specific to the `simple_time_event`, @@ -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. +
posted() -> (bool), posted(uint64 value) -> (bool)