Hi Charlie, On Mon, Jul 01, 2024 at 03:45:11PM GMT, Charlie Jenkins wrote: > Document the PR_RISCV_SET_ICACHE_FLUSH_CTX flag for prctl(2) that is > supported as of Linux 6.10. > > Signed-off-by: Charlie Jenkins <charlie@xxxxxxxxxxxx> > --- > Changes in v4: > - Move release information to Standards/History > - Fix typo in prctl > - Use semantic newlines > - Add magic comments for code and fix style issues (clang-tidy warns > about prctl flags that are available in the 6.10 rc's) > - Link to v3: https://lore.kernel.org/r/20240628-fencei_prctl-v3-1-56fd31155129@xxxxxxxxxxxx > > Changes in v3: > - Rebase onto master > - Add example usage > - Link to v2: https://lore.kernel.org/r/20240212-fencei_prctl-v2-1-32d940981b05@xxxxxxxxxxxx > > Changes in v2: > - Update formatting (Alejandro) > - Link to v1: https://lore.kernel.org/r/20240124-fencei_prctl-v1-1-0bddafcef331@xxxxxxxxxxxx > --- > man/man2/prctl.2 | 3 + > man/man2const/PR_RISCV_SET_ICACHE_FLUSH_CTX.2const | 157 +++++++++++++++++++++ > 2 files changed, 160 insertions(+) > > diff --git a/man/man2/prctl.2 b/man/man2/prctl.2 > index 6db916587..31a3f9064 100644 > --- a/man/man2/prctl.2 > +++ b/man/man2/prctl.2 > @@ -157,6 +157,8 @@ The first argument can be: > .B PR_SET_MDWE > .TQ > .B PR_GET_MDWE > +.TQ > +.B PR_RISCV_SET_ICACHE_FLUSH_CTX > .SH RETURN VALUE > On success, > a nonnegative value is returned. > @@ -268,4 +270,5 @@ so these operations should be used with care. > .BR PR_GET_AUXV (2const), > .BR PR_SET_MDWE (2const), > .BR PR_GET_MDWE (2const), > +.BR PR_RISCV_SET_ICACHE_FLUSH_CTX (2const), > .BR core (5) > diff --git a/man/man2const/PR_RISCV_SET_ICACHE_FLUSH_CTX.2const b/man/man2const/PR_RISCV_SET_ICACHE_FLUSH_CTX.2const > new file mode 100644 > index 000000000..2fbdd2fb5 > --- /dev/null > +++ b/man/man2const/PR_RISCV_SET_ICACHE_FLUSH_CTX.2const > @@ -0,0 +1,157 @@ > +.\" Copyright 2024 Rivos Inc. > +.\" > +.\" SPDX-License-Identifier: Linux-man-pages-copyleft > +.\" > +.TH PR_RISCV_SET_ICACHE_FLUSH_CTX 2const (date) "Linux man-pages (unreleased)" > +.SH NAME > +PR_RISCV_SET_ICACHE_FLUSH_CTX > +\- > +Enable/disable icache flushing instructions in userspace. > +.SH LIBRARY > +Standard C library > +.RI ( libc ", " \-lc ) > +.SH SYNOPSIS > +.nf > +.BR "#include <linux/prctl.h>" " /* Definition of " PR_* " constants */" > +.B #include <sys/prctl.h> > +.P > +.BI "int prctl(PR_RISCV_SET_ICACHE_FLUSH_CTX, unsigned long " ctx, > +.BI " unsigned long " scope ); > +.fi > +.SH DESCRIPTION > +The context and the scope can be provided using > +.I ctx > +and > +.I scope > +respectively. > +.P > +When scope is set to > +.B PR_RISCV_SCOPE_PER_PROCESS > +all threads in the process are permitted to emit icache flushing instructions. > +Whenever any thread in the process is migrated, > +the corresponding hart's icache will be guaranteed > +to be consistent with instruction storage. > +This does not enforce any guarantees outside of migration. > +If a thread modifies an instruction that another thread may attempt to execute, > +the other thread must still emit an icache flushing instruction > +before attempting to execute the potentially modified instruction. > +This must be performed by the user-space program. > +.P > +In per-thread context (eg. scope is set to > +.BR PR_RISCV_SCOPE_PER_THREAD ) > +only the thread calling this function is permitted to emit icache flushing > +instructions. I'd break the line above before "emit". > +When the thread is migrated, > +the corresponding hart's icache will be > +guaranteed to be consistent with instruction storage. > +.P > +On kernels configured without SMP, this prctl > +.BR PR_RISCV_SET_ICACHE_FLUSH_CTX > +is a nop as migrations across harts will not occur. > +.P > +The following values for > +.I ctx > +can be specified: > +.RS > +.TP > +.BR PR_RISCV_CTX_SW_FENCEI_ON " (since Linux 6.10)" > +Allow fence.i in user space. > +.TP > +.BR PR_RISCV_CTX_SW_FENCEI_OFF " (since Linux 6.10)" > +Disallow fence.i in user space. > +All threads in a process will be affected when scope is set to > +.BR PR_RISCV_SCOPE_PER_PROCESS . > +Therefore, caution must be taken; > +use this flag only when you can guarantee that > +no thread in the process will emit fence.i from this point onward. > +.RE > +.IP > +The following values for > +.I scope > +can be specified: > +.RS > +.TP > +.BR PR_RISCV_SCOPE_PER_PROCESS " (since Linux 6.10)" > +Ensure the icache of any thread in this process is coherent with instruction > +storage upon migration. > +.TP > +.BR PR_RISCV_SCOPE_PER_THREAD " (since Linux 6.10)" > +Ensure the icache of the current thread is coherent with instruction storage > +upon migration. > +.RE > + Blank lines in the source are not allowed. > +.SH EXAMPLES > + > +The following files are meant to be compiled and linked with each other. > +The modify_instruction() function > +replaces an add with zero with an add with one, > +causing the instruction sequence in get_value() to change from > +returning a zero to returning a one. > + > +.SS Program source: cmodx.c > +.\" SRC BEGIN (cmodx.c) > +.EX > +#include <stdio.h> > +#include <sys/prctl.h> > +. This does not create a blank line in the output. For that, you need a source line with a dummy character: \& > +extern int get_value(void); > +extern void modify_instruction(void); > +. > +int main(void) > +{ > + int value = get_value(); > + printf("Value before cmodx: %d\[rs]n", value); > +. > + // Call prctl before first fence.i is called > + prctl(PR_RISCV_SET_ICACHE_FLUSH_CTX, PR_RISCV_CTX_SW_FENCEI_ON, > + PR_RISCV_SCOPE_PER_PROCESS); > + modify_instruction(); > + // Call prctl after final fence.i is called in process > + prctl(PR_RISCV_SET_ICACHE_FLUSH_CTX, PR_RISCV_CTX_SW_FENCEI_OFF, > + PR_RISCV_SCOPE_PER_PROCESS); > +. > + value = get_value(); > + printf("Value after cmodx: %d\[rs]n", value); > + return 0; > +} > +.EE > +.\" SRC END > +.SS Program source: cmodx.S > +.EX > +\&.option norvc > +. > +\&.text > +\&.global modify_instruction > +modify_instruction: > +lw a0, new_insn > +lui a5,%hi(old_insn) > +sw a0,%lo(old_insn)(a5) > +fence.i > +ret > +. > +\&.section modifiable, "awx" > +\&.global get_value > +get_value: > +li a0, 0 > +old_insn: > +addi a0, a0, 0 > +ret > +. > +\&.data > +new_insn: > +addi a0, a0, 1 > +.EE > + > +.SS Expected result > +.EX > +Value before cmodx: 0 > +Value after cmodx: 1 > +.EE > + > +.SH STANDARDS > +Linux. RISC-V only. > +.SH HISTORY > +.TP > +Linux 6.10 (RISC-V). > +.SH SEE ALSO > +.BR prctl (2) > > --- > base-commit: d0621648b4b5a356e86cea23e842f2591461f0cf > change-id: 20240124-fencei_prctl-c24da2643379 > > Best regards, > -- > Charlie Jenkins <charlie@xxxxxxxxxxxx> Have a lovely day! Alex -- <https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
