Debian Codegraph @

upstream/fedora-44/man2const/PR_RISCV_SET_ICACHE_FLUSH_CTX.2const

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