Debian Codegraph @

upstream/debian-unstable/man2/PR_RISCV_SET_ICACHE_FLUSH_CTX.2const

raw
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)