Hi Charlie, On Tue, Jul 09, 2024 at 10:56:52AM 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> Thanks! I've applied the patch, with some minor changes: diff --git c/man/man2const/PR_RISCV_SET_ICACHE_FLUSH_CTX.2const i/man/man2const/PR_RISCV_SET_ICACHE_FLUSH_CTX.2const index 138e45e0b..a0f0c736d 100644 --- c/man/man2const/PR_RISCV_SET_ICACHE_FLUSH_CTX.2const +++ i/man/man2const/PR_RISCV_SET_ICACHE_FLUSH_CTX.2const @@ -29,8 +29,8 @@ .SH DESCRIPTION .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. +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 @@ -46,13 +46,12 @@ .SH DESCRIPTION guaranteed to be consistent with instruction storage. .P On kernels configured without SMP, this prctl -.BR PR_RISCV_SET_ICACHE_FLUSH_CTX +.B 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. @@ -64,12 +63,10 @@ .SH DESCRIPTION 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 +.P 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 @@ -78,7 +75,6 @@ .SH DESCRIPTION .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 .SH EXAMPLES The following files are meant to be compiled and linked with each other. The modify_instruction() function @@ -94,7 +90,8 @@ .SS Program source: cmodx.c extern int get_value(void); extern void modify_instruction(void); \& -int main(void) +int +main(void) { int value = get_value(); \& Have a lovely night! Alex > --- > Changes in v5: > - Change "." to "\&" for newlines in example > - Fix whitespace > - Link to v4: https://lore.kernel.org/r/20240701-fencei_prctl-v4-1-9e181287d872@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 | 155 +++++++++++++++++++++ > 2 files changed, 158 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..138e45e0b > --- /dev/null > +++ b/man/man2const/PR_RISCV_SET_ICACHE_FLUSH_CTX.2const > @@ -0,0 +1,155 @@ > +.\" 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. > +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 > +.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> > +\& > +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> > -- <https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature