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
