This PR introduces the soft yield runtime config, it's a new kind of yield with the purpose of stopping the interpreter main loop immediately, to execute external code outside the machine.
This feature is only useful when using libcartesi library in applications that uses cartesi machine in its frontend, and has no use in the cartesi-machine cli or in the rollups backend, and it's disabled by default.
A soft yield happens when soft yield runtime config is true and the instruction SRAIW x0, x31, shamt is executed for any given shamt (32 possible values), the main interpreter loop will break with CM_BREAK_REASON_YIELDED_SOFTLY reason, and the programmer of the cartesi machine can handle this situation to perform operations in the outside.
When this instruction is executed in the rollups backend, it works as a NOP operation, while being a valid RISC-V instruction. SRAIW was chosen from the list of HINT instructions reserved from custom use in the RISC-V specification. Only shift instructions have HINTs available reserved for custom use, I choose SRAIW because I think it's the most uncommon one among the available shift instructions, to impact less the additional branching.
The main advantage of the soft yield when comparing with automatic yields are:
It's faster, the interpreter breaks immediately when this instruction is reached, while the automatic yield takes a few thousands cycles
The yield can happen in U-mode, this allows to read user space virtual memory from outside with read_virtual_memory, so there is no need to reserve fixed physical memory for reading user space memory from outside
It performs as a lightweight no-op in the rollup backend, this can be useful for dapps that want to have a frontend emulator spitting out data (such as graphics, audio, text) in the frontend, while in the backend this is silently ignored because there is no frontend attached.
It's unprivileged, there is no need to switch to M-mode or special devices to perform the soft yield, meaning no TLB flushes will happen
It's a way to implement custom instructions in the frontend for users of the libcartesi
This is a solution for #134 , more disadvantages of automatic yields were also described there
This PR introduces the soft yield runtime config, it's a new kind of yield with the purpose of stopping the interpreter main loop immediately, to execute external code outside the machine.
This feature is only useful when using libcartesi library in applications that uses cartesi machine in its frontend, and has no use in the cartesi-machine cli or in the rollups backend, and it's disabled by default.
A soft yield happens when soft yield runtime config is true and the instruction
SRAIW x0, x31, shamt
is executed for any givenshamt
(32 possible values), the main interpreter loop will break withCM_BREAK_REASON_YIELDED_SOFTLY
reason, and the programmer of the cartesi machine can handle this situation to perform operations in the outside.When this instruction is executed in the rollups backend, it works as a NOP operation, while being a valid RISC-V instruction. SRAIW was chosen from the list of HINT instructions reserved from custom use in the RISC-V specification. Only shift instructions have HINTs available reserved for custom use, I choose SRAIW because I think it's the most uncommon one among the available shift instructions, to impact less the additional branching.
The main advantage of the soft yield when comparing with automatic yields are:
read_virtual_memory
, so there is no need to reserve fixed physical memory for reading user space memory from outsideThis is a solution for #134 , more disadvantages of automatic yields were also described there
Depends on