Skip to content

[otbn] Add masking accelerator interface to OTBN simulator #29109

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

Draft
etterli wants to merge 4 commits into
base: master
Choose a base branch
from
+899 −5
Draft

[otbn] Add masking accelerator interface to OTBN simulator #29109

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6667371
[otbn,sim] Clean up WSR trace
etterli Feb 10, 2026
95005ae
[otbn,sim] Add CSRs and WSRs for the masking accelerator interface
etterli Feb 10, 2026
f34a664
[otbn,sim] Add masking accelerator interface simulator implementation
etterli Feb 10, 2026
eac4fd0
[otbn,sw] Add simple program showcasing how to use the MAI
etterli Feb 10, 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
137 changes: 135 additions & 2 deletions hw/ip/otbn/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,8 +109,8 @@ CSRs can be accessed through dedicated instructions, {{#otbn-insn-ref CSRRS}} an
Writes to read-only (RO) registers are ignored; they do not signal an error.
All read-write (RW) CSRs are set to 0 when OTBN starts an operation (when 1 is written to [`CMD.start`](doc/registers.md#cmd)).

<!-- This list of CSRs is replicated in otbn_env_cov.sv, wsr.py, the
RTL and in rig/model.py. If editing one, edit the other four as well. -->
<!-- This list of CSRs is replicated in otbn_env_cov.sv, csr.py, wsr.py, the
RTL and in rig/model.py. If editing one, edit the other five as well. -->
<!-- BEGIN CMDGEN ./hw/ip/otbn/util/docs/md_isrs.py hw/ip/otbn/data/csr.yml -->
<table>
<thead>
Expand Down Expand Up @@ -565,6 +565,44 @@ All read-write (RW) CSRs are set to 0 when OTBN starts an operation (when 1 is w
</table>
</td>
</tr>
<tr>
<td>0x7F0</td>
<td>RW</td>
<td>MAI_CTRL</td>
<td>
The MAI control register. This is used to start MAI operations as well as configuring the accelerators.
<table>
<thead>
<tr><th>Bit</th><th>Description</th></tr>
</thead>
<tbody>
<tr>
<td>0</td>
<td>
MAI_START: Writing 1 to this bit starts the MAI operation. Writing it when MAI is busy will cause a MAI_ERROR software error.
</td>
</tr>
<tr>
<td>2:1</td>
<td>
The MAI_OPERATION field defines which accelerator is used for the next operation. Invalid values and writing to these bits when MAI is busy will cause a MAI_ERROR software error.
<p>Values:</p><ul>
<li>0: A2B</li>
<li>1: B2A</li>
<li>2: secAdd</li>
</ul>
</td>
</tr>
<tr>
<td>31:3</td>
<td>
Reserved. Any write is ignored. Always reads as 0.
</td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr>
<td>0xFC0</td>
<td>RO</td>
Expand Down Expand Up @@ -659,6 +697,39 @@ All read-write (RW) CSRs are set to 0 when OTBN starts an operation (when 1 is w
</table>
</td>
</tr>
<tr>
<td>0xFE0</td>
<td>RO</td>
<td>MAI_STATUS</td>
<td>
The MAI status register.
<table>
<thead>
<tr><th>Bit</th><th>Description</th></tr>
</thead>
<tbody>
<tr>
<td>0</td>
<td>
MAI_BUSY: This bit is set to 1 when an MAI operation is in progress. If reset, the MAI accepts new configuration values and a new execution can be started by writing to the MAI_START bit in the MAI_CTRL CSR.
</td>
</tr>
<tr>
<td>1</td>
<td>
MAI_READY: This bit is set to 1 when the MAI_INx_Sx WSRs are ready to accept new values for the next execution.
</td>
</tr>
<tr>
<td>31:2</td>
<td>
Reserved. Always reads as 0.
</td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>

Expand Down Expand Up @@ -858,6 +929,68 @@ All read-write (RW) WSRs are set to 0 when OTBN starts an operation (when 1 is w
</table>
</td>
</tr>
<tr>
<td>0xA</td>
<td>RO</td>
<td><a name="mai-res-s0">MAI_RES_S0</a></td>
<td>
This WSR holds share 0 of the masked results produced by the MAI.
The results are organized as eight 32-bit values.
Results are valid when MAI is not busy anymore.
These values are overwritten when the first results of the next execution are available (this depends on the selected accelerator's latency).
</td>
</tr>
<tr>
<td>0xB</td>
<td>RO</td>
<td><a name="mai-res-s1">MAI_RES_S1</a></td>
<td>
This WSR holds share 1 of the masked results produced by the MAI.
The results are organized as eight 32-bit values.
Results are valid when MAI is not busy anymore.
These values are overwritten when the first results of the next execution are available (this depends on the selected accelerator's latency).
</td>
</tr>
<tr>
<td>0xC</td>
<td>RW</td>
<td><a name="mai-in0-s0">MAI_IN0_S0</a></td>
<td>
This WSR transfers share 0 of the first input secrets towards the MAI.
The inputs are considered as eight 32-bit values.
Writing to this WSR while MAI is not ready will cause a MAI_ERROR software error.
</td>
</tr>
<tr>
<td>0xD</td>
<td>RW</td>
<td><a name="mai-in0-s1">MAI_IN0_S1</a></td>
<td>
This WSR transfers share 1 of the first input secrets towards the MAI.
The inputs are considered as eight 32-bit values.
Writing to this WSR while MAI is not ready will cause a MAI_ERROR software error.
</td>
</tr>
<tr>
<td>0xE</td>
<td>RW</td>
<td><a name="mai-in1-s0">MAI_IN1_S0</a></td>
<td>
This WSR transfers share 0 of the second input secrets towards the MAI.
The inputs are considered as eight 32-bit values.
Writing to this WSR while MAI is not ready will cause a MAI_ERROR software error.
</td>
</tr>
<tr>
<td>0xF</td>
<td>RW</td>
<td><a name="mai-in1-s1">MAI_IN1_S1</a></td>
<td>
This WSR transfers share 1 of the second input secrets towards the MAI.
The inputs are considered as eight 32-bit values.
Writing to this WSR while MAI is not ready will cause a MAI_ERROR software error.
</td>
</tr>
</tbody>
</table>

Expand Down
31 changes: 31 additions & 0 deletions hw/ip/otbn/data/csr.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,24 @@
bits:
31-0: BYTE_STROBE is the KMAC byte strobe field.

- name: mai_ctrl
Copy link
Contributor

@rswarbrick rswarbrick Jan 20, 2026

Choose a reason for hiding this comment

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

Is this register supposed to have swaccess: "wo"?

Copy link
Contributor Author

@etterli etterli Jan 21, 2026

Choose a reason for hiding this comment

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

No, we should also be able to read the currently set operation back.

address: 0x7f0
doc: |
The MAI control register. This is used to start MAI operations as well as configuring the accelerators.
bits:
0: |
MAI_START: Writing 1 to this bit starts the MAI operation.
Writing it when MAI is busy will cause a MAI_ERROR software error.
2-1:
doc: |
The MAI_OPERATION field defines which accelerator is used for the next operation.
Invalid values and writing to these bits when MAI is busy will cause a MAI_ERROR software error.
values:
0: A2B
1: B2A
2: secAdd
31-3: Reserved. Any write is ignored. Always reads as 0.

- name: rnd
address: 0xfc0
read-only: true
Expand Down Expand Up @@ -205,3 +223,16 @@
bits:
7-0: ERROR_CODE contains the error code coming directly from the KMAC HWIP.
31-8: Reserved. Always reads as 0. Any write is ignored.

- name: mai_status
address: 0xfe0
read-only: true
doc: |
The MAI status register.
bits:
0: |
MAI_BUSY: This bit is set to 1 when an MAI operation is in progress.
If reset, the MAI accepts new configuration values and a new execution can be started by writing to the MAI_START bit in the MAI_CTRL CSR.
1: |
MAI_READY: This bit is set to 1 when the MAI_INx_Sx WSRs are ready to accept new values for the next execution.
31-2: Reserved. Always reads as 0.
46 changes: 46 additions & 0 deletions hw/ip/otbn/data/wsr.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,3 +109,49 @@
255-64: |
Write: Words 1-3 of the message share.
Read: Returns `0`. Digest shares are read out via the least significant word only.

- name: mai_res_s0
address: 10
Copy link
Contributor

@rswarbrick rswarbrick Jan 20, 2026

Choose a reason for hiding this comment

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

No big deal, but was there a problem with addresses 8 and 9?

Copy link
Contributor Author

@etterli etterli Jan 20, 2026

Choose a reason for hiding this comment

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

8 and 9 are already reserved for the new KMAC interface. See #29025 . This KMAC interface also has many overlapping stuff, so maybe worth looking at it as well..

read-only: true
doc: |
This WSR holds share 0 of the masked results produced by the MAI.
The results are organized as eight 32-bit values.
Results are valid when MAI is not busy anymore.
Copy link
Contributor

@rswarbrick rswarbrick Jan 20, 2026

Choose a reason for hiding this comment

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

I think you might need something about when they get invalidated too? (the when the next operation starts?)

These values are overwritten when the first results of the next execution are available (this depends on the selected accelerator's latency).

- name: mai_res_s1
address: 11
read-only: true
doc: |
This WSR holds share 1 of the masked results produced by the MAI.
The results are organized as eight 32-bit values.
Results are valid when MAI is not busy anymore.
These values are overwritten when the first results of the next execution are available (this depends on the selected accelerator's latency).

- name: mai_in0_s0
address: 12
doc: |
This WSR transfers share 0 of the first input secrets towards the MAI.
The inputs are considered as eight 32-bit values.
Writing to this WSR while MAI is not ready will cause a MAI_ERROR software error.
Copy link
Contributor

@rswarbrick rswarbrick Jan 20, 2026

Choose a reason for hiding this comment

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

Will there be any effect other than the SW error? (Does the MAI see the write?)

Copy link
Contributor Author

@etterli etterli Jan 20, 2026

Choose a reason for hiding this comment

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

The MAI is tightly integrated into the OTBN. So if there is a SW error, also the MAI will stop working and be cleared/wiped. This needs to be described in the MAI description (todo).


- name: mai_in0_s1
address: 13
doc: |
This WSR transfers share 1 of the first input secrets towards the MAI.
The inputs are considered as eight 32-bit values.
Writing to this WSR while MAI is not ready will cause a MAI_ERROR software error.

- name: mai_in1_s0
address: 14
doc: |
This WSR transfers share 0 of the second input secrets towards the MAI.
The inputs are considered as eight 32-bit values.
Writing to this WSR while MAI is not ready will cause a MAI_ERROR software error.

- name: mai_in1_s1
address: 15
doc: |
This WSR transfers share 1 of the second input secrets towards the MAI.
The inputs are considered as eight 32-bit values.
Writing to this WSR while MAI is not ready will cause a MAI_ERROR software error.
1 change: 1 addition & 0 deletions hw/ip/otbn/dv/otbnsim/sim/constants.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ class ErrBits(IntEnum):
KEY_INVALID = 1 << 5
RND_REP_CHK_FAIL = 1 << 6
RND_FIPS_CHK_FAIL = 1 << 7
MAI_ERROR = 1 << 8
IMEM_INTG_VIOLATION = 1 << 16
DMEM_INTG_VIOLATION = 1 << 17
REG_INTG_VIOLATION = 1 << 18
Expand Down
Loading
Loading