| 1 |
.\" Copyright 2024, Rivos, Inc. |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH PR_RISCV_SET_ICACHE_FLUSH_CTX 2const 2026-02-08 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
PR_RISCV_SET_ICACHE_FLUSH_CTX |
| 9 |
\- |
| 10 |
enable/disable icache flushing instructions in userspace |
| 11 |
.SH LIBRARY |
| 12 |
Standard C library |
| 13 |
.RI ( libc ,\~ \-lc ) |
| 14 |
.SH SYNOPSIS |
| 15 |
.nf |
| 16 |
.BR "#include <linux/prctl.h>" " /* Definition of " PR_* " constants */" |
| 17 |
.B #include <sys/prctl.h> |
| 18 |
.P |
| 19 |
.BI "int prctl(PR_RISCV_SET_ICACHE_FLUSH_CTX, unsigned long " ctx, |
| 20 |
.BI " unsigned long " scope ); |
| 21 |
.fi |
| 22 |
.SH DESCRIPTION |
| 23 |
The context and the scope can be provided using |
| 24 |
.I ctx |
| 25 |
and |
| 26 |
.I scope |
| 27 |
respectively. |
| 28 |
.P |
| 29 |
When |
| 30 |
.I scope |
| 31 |
is set to |
| 32 |
.B PR_RISCV_SCOPE_PER_PROCESS |
| 33 |
all threads in the process are permitted to emit icache flushing instructions. |
| 34 |
Whenever any thread in the process is migrated, |
| 35 |
the corresponding hart's icache will be |
| 36 |
guaranteed to be consistent with instruction storage. |
| 37 |
This does not enforce any guarantees outside of migration. |
| 38 |
If a thread modifies an instruction that another thread may attempt to execute, |
| 39 |
the other thread must still emit an icache flushing instruction |
| 40 |
before attempting to execute the potentially modified instruction. |
| 41 |
This must be performed by the user-space program. |
| 42 |
.P |
| 43 |
In per-thread context |
| 44 |
(i.e., |
| 45 |
.I scope |
| 46 |
is set to |
| 47 |
.BR PR_RISCV_SCOPE_PER_THREAD ) |
| 48 |
only the thread calling this function is permitted to |
| 49 |
emit icache flushing instructions. |
| 50 |
When the thread is migrated, |
| 51 |
the corresponding hart's icache will be |
| 52 |
guaranteed to be consistent with instruction storage. |
| 53 |
.P |
| 54 |
On kernels configured without SMP, this prctl |
| 55 |
.B PR_RISCV_SET_ICACHE_FLUSH_CTX |
| 56 |
is a nop as migrations across harts will not occur. |
| 57 |
.P |
| 58 |
The following values for |
| 59 |
.I ctx |
| 60 |
can be specified: |
| 61 |
.TP |
| 62 |
.BR PR_RISCV_CTX_SW_FENCEI_ON " (since Linux 6.10)" |
| 63 |
Allow fence.i in user space. |
| 64 |
.TP |
| 65 |
.BR PR_RISCV_CTX_SW_FENCEI_OFF " (since Linux 6.10)" |
| 66 |
Disallow fence.i in user space. |
| 67 |
All threads in a process will be affected when |
| 68 |
.I scope |
| 69 |
is set to |
| 70 |
.BR PR_RISCV_SCOPE_PER_PROCESS . |
| 71 |
Therefore, caution must be taken; |
| 72 |
use this flag only when you can guarantee that |
| 73 |
no thread in the process will emit fence.i from this point onward. |
| 74 |
.P |
| 75 |
The following values for |
| 76 |
.I scope |
| 77 |
can be specified: |
| 78 |
.TP |
| 79 |
.BR PR_RISCV_SCOPE_PER_PROCESS " (since Linux 6.10)" |
| 80 |
Ensure the icache of any thread in this process is coherent with instruction |
| 81 |
storage upon migration. |
| 82 |
.TP |
| 83 |
.BR PR_RISCV_SCOPE_PER_THREAD " (since Linux 6.10)" |
| 84 |
Ensure the icache of the current thread is coherent with instruction storage |
| 85 |
upon migration. |
| 86 |
.SH EXAMPLES |
| 87 |
The following files are meant to be compiled and linked with each other. |
| 88 |
The modify_instruction() function |
| 89 |
replaces an add with zero with an add with one, |
| 90 |
causing the instruction sequence in get_value() to change from |
| 91 |
returning a zero to returning a one. |
| 92 |
.SS Program source: cmodx.c |
| 93 |
.\" SRC BEGIN (cmodx.c) |
| 94 |
.EX |
| 95 |
#include <stdio.h> |
| 96 |
#include <sys/prctl.h> |
| 97 |
\& |
| 98 |
extern int get_value(void); |
| 99 |
extern void modify_instruction(void); |
| 100 |
\& |
| 101 |
int |
| 102 |
main(void) |
| 103 |
{ |
| 104 |
int value = get_value(); |
| 105 |
\& |
| 106 |
printf("Value before cmodx: %d\[rs]n", value); |
| 107 |
\& |
| 108 |
// Call prctl before first fence.i is called |
| 109 |
prctl(PR_RISCV_SET_ICACHE_FLUSH_CTX, PR_RISCV_CTX_SW_FENCEI_ON, |
| 110 |
PR_RISCV_SCOPE_PER_PROCESS); |
| 111 |
\& |
| 112 |
modify_instruction(); |
| 113 |
\& |
| 114 |
// Call prctl after final fence.i is called in process |
| 115 |
prctl(PR_RISCV_SET_ICACHE_FLUSH_CTX, PR_RISCV_CTX_SW_FENCEI_OFF, |
| 116 |
PR_RISCV_SCOPE_PER_PROCESS); |
| 117 |
\& |
| 118 |
value = get_value(); |
| 119 |
printf("Value after cmodx: %d\[rs]n", value); |
| 120 |
return 0; |
| 121 |
} |
| 122 |
.EE |
| 123 |
.\" SRC END |
| 124 |
.SS Program source: cmodx.S |
| 125 |
.EX |
| 126 |
\&.option norvc |
| 127 |
\& |
| 128 |
\&.text |
| 129 |
\&.global modify_instruction |
| 130 |
modify_instruction: |
| 131 |
lw a0, new_insn |
| 132 |
lui a5,%hi(old_insn) |
| 133 |
sw a0,%lo(old_insn)(a5) |
| 134 |
fence.i |
| 135 |
ret |
| 136 |
\& |
| 137 |
\&.section modifiable, "awx" |
| 138 |
\&.global get_value |
| 139 |
get_value: |
| 140 |
li a0, 0 |
| 141 |
old_insn: |
| 142 |
addi a0, a0, 0 |
| 143 |
ret |
| 144 |
\& |
| 145 |
\&.data |
| 146 |
new_insn: |
| 147 |
addi a0, a0, 1 |
| 148 |
.EE |
| 149 |
.SS Expected result |
| 150 |
.EX |
| 151 |
Value before cmodx: 0 |
| 152 |
Value after cmodx: 1 |
| 153 |
.EE |
| 154 |
.SH STANDARDS |
| 155 |
Linux. |
| 156 |
RISC-V only. |
| 157 |
.SH HISTORY |
| 158 |
.TP |
| 159 |
Linux 6.10 (RISC-V). |
| 160 |
.SH SEE ALSO |
| 161 |
.BR prctl (2) |