Skip to content

Document bank's set, get, unmapped_get -- SIMICS-23287 #404

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
lwaern-intel wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Document bank's set, get, unmapped_get -- SIMICS-23287 #404

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
44 changes: 41 additions & 3 deletions lib/1.4/dml-builtins.dml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1803,11 +1803,49 @@ of `unmapped_read` if the access is not fully
mapped.
</dd><dt>

<small>unmapped\_read(uint64 offset, uint64 bits, void \*aux) throws</small>
<small>unmapped\_read(uint64 offset, uint64 bits, void \*aux) -> (uint64) throws</small>
</dt><dd>

Like `unmapped_write` but for reads. The default
implementation unconditionally throws an exception.
Like `unmapped_write` but for reads. The default implementation unconditionally
throws an exception, which causes the read access to be rejected. However, the
method may be overridden to instead return a value specifying the read bits
corresponding to the unmapped bytes, which will then be composed together with
the values read from the accessed registers.
</dd><dt>

<small>set(uint64 offset, uint64 size, uint64 value)</small>
</dt><dd>
A simpler variant of `write()` used exclusively for inquiry write accesses to
the bank. Unlike `write()`, `set()` unconditionally operates over an entire
range of bytes (hence `size` rather than `enabled_bytes`), does not have an
`aux` parameter, and cannot throw. Any invocation of `write` is considered
valid, even if some part of the access is not covered by mapped registers (in
which case no action should be taken for those bytes.)

The default implementation invokes `set()` of the accessed registers rather
than `write_register()`, and instead of calling to something similar to
`unmapped_write()`, the default implementation simply logs a low-level `info`
message about unmapped accesses.
</dd><dt>

<small>get(uint64 offset, uint64 size) -> (uint64) throws</small>
</dt><dd>
A simpler variant of `read()` used exclusively for inquiry read accesses to
the bank. Unlike `read`, `get()` unconditionally operates over an entire
range of bytes (hence `size` rather than `enabled_bytes`) and does not have an
Copy link
Contributor

@mandolaerik mandolaerik Dec 16, 2025

Choose a reason for hiding this comment

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

consider something like , ..., or , ...; also, instead of (...) (and same thing in set). Parentheses are generally harmful for text flow, so it's good to avoid them if that's easy.

`aux` parameter. Unlike `set()`, invocations to `get()` may throw, in
particular when some part of the access is not covered by mapped registers.
Comment on lines +1836 to +1837
Copy link
Contributor

@mandolaerik mandolaerik Dec 16, 2025

Choose a reason for hiding this comment

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

it could be worth mentioning something about the semantics of an exception, which for many years was not obvious to me. An exception indicates that some part of the accessed bytes is not mapped, and this is used by Simics in inspection commands such as x/examine-memory..


The default implementation invokes `get()` of the accessed registers rather
than `read_register()`, and calls to `unmapped_get()` upon unmapped accesses
rather than `unmapped_read()`.
</dd></dt>

<small>unmapped\_get(uint64 offset, uint64 bits) -> (uint64) throws</small>
</dt><dd>

Like `unmapped_read` but for inquiry reads. The default implementation
unconditionally throws an exception.
</dd></dl>

The `bank` template contains the following parameters:
Expand Down