[otbn] Specify the OTBN side of the KMAC interface

[etterli]

The last commit of this PR specifies the CSR/WSR based KMAC interface which OTBN SW can make use of to offload hashing operations.

Only the last commit is relevant. All other commits are part of #30141 (RTL of KMAC side of interface) or #30143 (required DV changes and RTL changes of IPs already using the app interface). Changes are expected for these PRs.

[etterli]

Thank you for the fast review @rswarbrick . Your feedback is incorporated.

[etterli]

I don't understand this question. What do you mean with 0x3f? There is no value which is 63.

[etterli]

The KMAC_STATUS.RSP_VALID bit shows the validity of the current response. But the hardware / interface uses it to drive the ready signal of the response channel. Obviously its inverted value; if it is cleared because the current response has been consumed then we can accept the next response.

[rswarbrick]

Thank you for all the changes!

[rswarbrick]

Damn! I meant to give the hex value that corresponds to '1, which I assumed had every bit set. Rather stupidly, I then calculated 2*32 - 1, rather than 2^32-1...

[rswarbrick]

Oh, good point! If we don't have a use for the feature, this seems perfectly sensible.

[rswarbrick]

Oh, sorry! I think I've got confused.

At the moment, the text says "the interface clears KMAC_STATUS.RSP_VALID". Do you mean that the OTBN hardware notices that the two WSRs have been read, then clears the RSP_VALID flag? (That's what I took the text to mean)

Or do you mean that the SW should clear the RSP_VALID flag to accept the data? That would be a back-pressure signal, but I think the active party needs changing: maybe "the OTBN code clears" or something?

[etterli]

Thank you @andrea-caforio for the questions. I have answered them and also redesigned the interface such that a process command is always required (a partial message no longer issues a process command).

[etterli]

Thanks @nasahlpa. I fixed your findings.

[etterli]

The latest version features:

• Rebased on the newest version of [kmac] Extend KMAC app interface with a dynamic interface type #30143 (minimized DV changes and squashed everything).
• The KMAC_CTRL CSR is now split into KMAC_CTRL and KMAC_CFG.
• Introduced a new command CLOSE which OTBN SW must issue after the finish response was checked for errors.
  • This is required to have a way to signal to the interface when OTBN SW has handled the finish response and a new session can be started.
• Improved the secure wipe behaviour description.

[vogelpi]

Why do we only get this error after sending the PROCESS command? Already when sending the START command we should know whether the config is valid.

[etterli]

Inside the KMAC the invalid config is detected immediately but the interface still goes to the "message absorb" phase. But no data is forwarded to the actual SHA3 core. I designed the interface this way because:

• For the static interface this behaviour is required for compatibility reasons. I wanted to keep the dynamic behaviour similar. I aggree, this is not a strong argument. We can relatively easily extend the dynamic interface such that it reports this after the START command. This extension is foreseen like the option to send a prefix.
• This behaviour simplifies the implementation of on application side. There is one state less to implement and verify. And we would need a way that OTBN SW can signal to the interface that it has checked the response. See also answer regarding why the CLOSE command is required.
• Knowing that the configuration was invalid directly after sending the configuration speeds up only the error case. Usually we can assume OTBN SW send a valid configuration and system SW did setup the KMAC properly. Having to check a response after the START command adds actually latency for the happy case.

I agree, delaying the error response until the full message has been sent is not the cleanest. However, I think this is acceptable. Does this clarify your question and do you accept it like this?
If not, I'm also happy to extend the app interface with such an immediate response.

[vogelpi]

No, that's all perfect and reasonable. Thanks for explaining! Let's leave this one open for the future.

[vogelpi]

This sentence is ambiguous because it suggests that there is a hardware timeout. I don't think you need this sentence and can instead just say: If any of these errors happens, OTBN SW needs to abort the execution and system SW then has to take care of recovering the KMAC HWIP.

[etterli]

The problem is that the 1st error (KMAC_STATUS.READY remains low after..) is non recoverable. And the interface can also not send any PRCOESS/DONE command. This error case happens only if the KMAC fails to accept a request. In this case, OTBN must abort the program execution and system SW must somehow start a recovery on the KMAC side. This is currently not yet supported by KMAC. But this feature then should somehow accept the pending requests such that the "recovery mode" of the OTBN side can end the session.

In contrast, if any of the other two errors occurs, OTBN SW can still end the session regularly (it must).

I will try to rewrite this distinction.

[etterli]

The latest push now cleans up this section.

[vogelpi]

Thanks, this section much clearer now!

My point regarding the timeout is that waiting even longer will not help. If the bit remains low for say more than 100 clock cycles, KMAC is dead. But I agree that this is different from the other two errors.

[vogelpi]

The latest version features:

* Rebased on the newest version of [[kmac] Extend KMAC app interface with a dynamic interface type #30143](https://github.com/lowRISC/opentitan/pull/30143) (minimized DV changes and squashed everything).

* The KMAC_CTRL CSR is now split into KMAC_CTRL and KMAC_CFG.

* Introduced a new command `CLOSE` which OTBN SW must issue after the finish response was checked for errors.
  
  * This is required to have a way to signal to the interface when OTBN SW has handled the finish response and a new session can be started.

Question: why is it not sufficient to just perform the finish response handshake (IIRC a result of sending the DONE command) and then free the session?

* Improved the secure wipe behaviour description.

Thanks, this is a lot simpler now and much easier to understand in my view.

[etterli]

• Introduced a new command CLOSE which OTBN SW must issue after the finish response was checked for errors.

  • This is required to have a way to signal to the interface when OTBN SW has handled the finish response and a new session can be started.

Question: why is it not sufficient to just perform the finish response handshake (IIRC a result of sending the DONE command) and then free the session?

The flow is:

• OTBN SW issues the DONE command, signalling that it has read the amount of digest it requires.
• This triggers the OTBN interface side to send the termination request. It then waits for the finish response.
• Once the finish response arrives, the RSP_VALID flag is set and the RSP_ERROR flag is updated.
• In parallel the OTBN SW polls the RSP_VALID flag.
• Once RSP_VALID = 1, OTBN SW can read the RSP_ERROR flag and handle accordingly (This RSP_ERROR flag must be checked and may not be set, otherwise all digest data must be considered as invalid).

Now the problem is that the interface does not know when OTBN SW did read the RSP_ERROR flag. And thus it does not know when it can clear the RSP_VALID and all other error flags. And this is required to be ready for the next session. The CLOSE command is a clean way how OTBN SW can signal to the interface that it has read all flags and now longer needs the information.

Note that once the finish response arrived, the session is fully terminated on the KMAC side. It is just a OTBN side problem.

I thought about two approaches how to avoid a CLOSE command. But both have awkward consequences.

• Reading KMAC_STATUS after issuing the DONE command when RSP_VALID is 1 signals the end of the session.
  • I dislike introducing any read side-effects for CSRs. This is very uncommon and error prone.
  • Concretely, this is ugly because it limits the OTBN SW to read the result of the response exactly once. So any polling loop must check the RSP_VALID flag and also temporary store the value of the RSP_ERROR flag. This makes writing SW challenging.
• Flags in KMAC_STATUS (except READY) keep their value until another START command is issued.
  • This would work but I don't like it that KMAC_STATUS does not have a well defined state after a session.

[vogelpi]

Thanks @etterli for the latest updates including the reasoning of the DONE command. I wasn't aware that this is an OTBN-only thing (I thought you would send this also across to KMAC). But like you explained it, it makes sense.

[nasahlpa]

Thanks Pascal - I had a look into the updates spec and it looks good to me.

[etterli]

Rebased on master to include the now merged KMAC interface implementation.

[etterli]

It now also specifies that KMAC_CFG has duplicated fields.

[etterli]

In theory all config bits would fit within 12 bits and we could use one ADDI to load the config. But to be prepared for eventual onehot encodings and for better SW code readability I chose a power of two offset. One instruction and one cycle more should not make the difference.