1 /* SPDX-License-Identifier: GPL-2.0 */
2 /*
3 * KMSAN API for subsystems.
4 *
5 * Copyright (C) 2017-2022 Google LLC
6 * Author: Alexander Potapenko <glider@google.com>
7 *
8 */
9 #ifndef _LINUX_KMSAN_H
10 #define _LINUX_KMSAN_H
11
12 #include <linux/dma-direction.h>
13 #include <linux/gfp.h>
14 #include <linux/kmsan-checks.h>
15 #include <linux/types.h>
16
17 struct page;
18 struct kmem_cache;
19 struct task_struct;
20 struct scatterlist;
21 struct urb;
22
23 #ifdef CONFIG_KMSAN
24
25 /**
26 * kmsan_task_create() - Initialize KMSAN state for the task.
27 * @task: task to initialize.
28 */
29 void kmsan_task_create(struct task_struct *task);
30
31 /**
32 * kmsan_task_exit() - Notify KMSAN that a task has exited.
33 * @task: task about to finish.
34 */
35 void kmsan_task_exit(struct task_struct *task);
36
37 /**
38 * kmsan_init_shadow() - Initialize KMSAN shadow at boot time.
39 *
40 * Allocate and initialize KMSAN metadata for early allocations.
41 */
42 void __init kmsan_init_shadow(void);
43
44 /**
45 * kmsan_init_runtime() - Initialize KMSAN state and enable KMSAN.
46 */
47 void __init kmsan_init_runtime(void);
48
49 /**
50 * kmsan_memblock_free_pages() - handle freeing of memblock pages.
51 * @page: struct page to free.
52 * @order: order of @page.
53 *
54 * Freed pages are either returned to buddy allocator or held back to be used
55 * as metadata pages.
56 */
57 bool __init kmsan_memblock_free_pages(struct page *page, unsigned int order);
58
59 /**
60 * kmsan_alloc_page() - Notify KMSAN about an alloc_pages() call.
61 * @page: struct page pointer returned by alloc_pages().
62 * @order: order of allocated struct page.
63 * @flags: GFP flags used by alloc_pages()
64 *
65 * KMSAN marks 1<<@order pages starting at @page as uninitialized, unless
66 * @flags contain __GFP_ZERO.
67 */
68 void kmsan_alloc_page(struct page *page, unsigned int order, gfp_t flags);
69
70 /**
71 * kmsan_free_page() - Notify KMSAN about a free_pages() call.
72 * @page: struct page pointer passed to free_pages().
73 * @order: order of deallocated struct page.
74 *
75 * KMSAN marks freed memory as uninitialized.
76 */
77 void kmsan_free_page(struct page *page, unsigned int order);
78
79 /**
80 * kmsan_copy_page_meta() - Copy KMSAN metadata between two pages.
81 * @dst: destination page.
82 * @src: source page.
83 *
84 * KMSAN copies the contents of metadata pages for @src into the metadata pages
85 * for @dst. If @dst has no associated metadata pages, nothing happens.
86 * If @src has no associated metadata pages, @dst metadata pages are unpoisoned.
87 */
88 void kmsan_copy_page_meta(struct page *dst, struct page *src);
89
90 /**
91 * kmsan_slab_alloc() - Notify KMSAN about a slab allocation.
92 * @s: slab cache the object belongs to.
93 * @object: object pointer.
94 * @flags: GFP flags passed to the allocator.
95 *
96 * Depending on cache flags and GFP flags, KMSAN sets up the metadata of the
97 * newly created object, marking it as initialized or uninitialized.
98 */
99 void kmsan_slab_alloc(struct kmem_cache *s, void *object, gfp_t flags);
100
101 /**
102 * kmsan_slab_free() - Notify KMSAN about a slab deallocation.
103 * @s: slab cache the object belongs to.
104 * @object: object pointer.
105 *
106 * KMSAN marks the freed object as uninitialized.
107 */
108 void kmsan_slab_free(struct kmem_cache *s, void *object);
109
110 /**
111 * kmsan_kmalloc_large() - Notify KMSAN about a large slab allocation.
112 * @ptr: object pointer.
113 * @size: object size.
114 * @flags: GFP flags passed to the allocator.
115 *
116 * Similar to kmsan_slab_alloc(), but for large allocations.
117 */
118 void kmsan_kmalloc_large(const void *ptr, size_t size, gfp_t flags);
119
120 /**
121 * kmsan_kfree_large() - Notify KMSAN about a large slab deallocation.
122 * @ptr: object pointer.
123 *
124 * Similar to kmsan_slab_free(), but for large allocations.
125 */
126 void kmsan_kfree_large(const void *ptr);
127
128 /**
129 * kmsan_map_kernel_range_noflush() - Notify KMSAN about a vmap.
130 * @start: start of vmapped range.
131 * @end: end of vmapped range.
132 * @prot: page protection flags used for vmap.
133 * @pages: array of pages.
134 * @page_shift: page_shift passed to vmap_range_noflush().
135 *
136 * KMSAN maps shadow and origin pages of @pages into contiguous ranges in
137 * vmalloc metadata address range. Returns 0 on success, callers must check
138 * for non-zero return value.
139 */
140 int kmsan_vmap_pages_range_noflush(unsigned long start, unsigned long end,
141 pgprot_t prot, struct page **pages,
142 unsigned int page_shift);
143
144 /**
145 * kmsan_vunmap_kernel_range_noflush() - Notify KMSAN about a vunmap.
146 * @start: start of vunmapped range.
147 * @end: end of vunmapped range.
148 *
149 * KMSAN unmaps the contiguous metadata ranges created by
150 * kmsan_map_kernel_range_noflush().
151 */
152 void kmsan_vunmap_range_noflush(unsigned long start, unsigned long end);
153
154 /**
155 * kmsan_ioremap_page_range() - Notify KMSAN about a ioremap_page_range() call.
156 * @addr: range start.
157 * @end: range end.
158 * @phys_addr: physical range start.
159 * @prot: page protection flags used for ioremap_page_range().
160 * @page_shift: page_shift argument passed to vmap_range_noflush().
161 *
162 * KMSAN creates new metadata pages for the physical pages mapped into the
163 * virtual memory. Returns 0 on success, callers must check for non-zero return
164 * value.
165 */
166 int kmsan_ioremap_page_range(unsigned long addr, unsigned long end,
167 phys_addr_t phys_addr, pgprot_t prot,
168 unsigned int page_shift);
169
170 /**
171 * kmsan_iounmap_page_range() - Notify KMSAN about a iounmap_page_range() call.
172 * @start: range start.
173 * @end: range end.
174 *
175 * KMSAN unmaps the metadata pages for the given range and, unlike for
176 * vunmap_page_range(), also deallocates them.
177 */
178 void kmsan_iounmap_page_range(unsigned long start, unsigned long end);
179
180 /**
181 * kmsan_handle_dma() - Handle a DMA data transfer.
182 * @page: first page of the buffer.
183 * @offset: offset of the buffer within the first page.
184 * @size: buffer size.
185 * @dir: one of possible dma_data_direction values.
186 *
187 * Depending on @direction, KMSAN:
188 * * checks the buffer, if it is copied to device;
189 * * initializes the buffer, if it is copied from device;
190 * * does both, if this is a DMA_BIDIRECTIONAL transfer.
191 */
192 void kmsan_handle_dma(struct page *page, size_t offset, size_t size,
193 enum dma_data_direction dir);
194
195 /**
196 * kmsan_handle_dma_sg() - Handle a DMA transfer using scatterlist.
197 * @sg: scatterlist holding DMA buffers.
198 * @nents: number of scatterlist entries.
199 * @dir: one of possible dma_data_direction values.
200 *
201 * Depending on @direction, KMSAN:
202 * * checks the buffers in the scatterlist, if they are copied to device;
203 * * initializes the buffers, if they are copied from device;
204 * * does both, if this is a DMA_BIDIRECTIONAL transfer.
205 */
206 void kmsan_handle_dma_sg(struct scatterlist *sg, int nents,
207 enum dma_data_direction dir);
208
209 /**
210 * kmsan_handle_urb() - Handle a USB data transfer.
211 * @urb: struct urb pointer.
212 * @is_out: data transfer direction (true means output to hardware).
213 *
214 * If @is_out is true, KMSAN checks the transfer buffer of @urb. Otherwise,
215 * KMSAN initializes the transfer buffer.
216 */
217 void kmsan_handle_urb(const struct urb *urb, bool is_out);
218
219 /**
220 * kmsan_unpoison_entry_regs() - Handle pt_regs in low-level entry code.
221 * @regs: struct pt_regs pointer received from assembly code.
222 *
223 * KMSAN unpoisons the contents of the passed pt_regs, preventing potential
224 * false positive reports. Unlike kmsan_unpoison_memory(),
225 * kmsan_unpoison_entry_regs() can be called from the regions where
226 * kmsan_in_runtime() returns true, which is the case in early entry code.
227 */
228 void kmsan_unpoison_entry_regs(const struct pt_regs *regs);
229
230 #else
231
kmsan_init_shadow(void)232 static inline void kmsan_init_shadow(void)
233 {
234 }
235
kmsan_init_runtime(void)236 static inline void kmsan_init_runtime(void)
237 {
238 }
239
kmsan_memblock_free_pages(struct page * page,unsigned int order)240 static inline bool kmsan_memblock_free_pages(struct page *page,
241 unsigned int order)
242 {
243 return true;
244 }
245
kmsan_task_create(struct task_struct * task)246 static inline void kmsan_task_create(struct task_struct *task)
247 {
248 }
249
kmsan_task_exit(struct task_struct * task)250 static inline void kmsan_task_exit(struct task_struct *task)
251 {
252 }
253
kmsan_alloc_page(struct page * page,unsigned int order,gfp_t flags)254 static inline int kmsan_alloc_page(struct page *page, unsigned int order,
255 gfp_t flags)
256 {
257 return 0;
258 }
259
kmsan_free_page(struct page * page,unsigned int order)260 static inline void kmsan_free_page(struct page *page, unsigned int order)
261 {
262 }
263
kmsan_copy_page_meta(struct page * dst,struct page * src)264 static inline void kmsan_copy_page_meta(struct page *dst, struct page *src)
265 {
266 }
267
kmsan_slab_alloc(struct kmem_cache * s,void * object,gfp_t flags)268 static inline void kmsan_slab_alloc(struct kmem_cache *s, void *object,
269 gfp_t flags)
270 {
271 }
272
kmsan_slab_free(struct kmem_cache * s,void * object)273 static inline void kmsan_slab_free(struct kmem_cache *s, void *object)
274 {
275 }
276
kmsan_kmalloc_large(const void * ptr,size_t size,gfp_t flags)277 static inline void kmsan_kmalloc_large(const void *ptr, size_t size,
278 gfp_t flags)
279 {
280 }
281
kmsan_kfree_large(const void * ptr)282 static inline void kmsan_kfree_large(const void *ptr)
283 {
284 }
285
kmsan_vmap_pages_range_noflush(unsigned long start,unsigned long end,pgprot_t prot,struct page ** pages,unsigned int page_shift)286 static inline int kmsan_vmap_pages_range_noflush(unsigned long start,
287 unsigned long end,
288 pgprot_t prot,
289 struct page **pages,
290 unsigned int page_shift)
291 {
292 return 0;
293 }
294
kmsan_vunmap_range_noflush(unsigned long start,unsigned long end)295 static inline void kmsan_vunmap_range_noflush(unsigned long start,
296 unsigned long end)
297 {
298 }
299
kmsan_ioremap_page_range(unsigned long start,unsigned long end,phys_addr_t phys_addr,pgprot_t prot,unsigned int page_shift)300 static inline int kmsan_ioremap_page_range(unsigned long start,
301 unsigned long end,
302 phys_addr_t phys_addr, pgprot_t prot,
303 unsigned int page_shift)
304 {
305 return 0;
306 }
307
kmsan_iounmap_page_range(unsigned long start,unsigned long end)308 static inline void kmsan_iounmap_page_range(unsigned long start,
309 unsigned long end)
310 {
311 }
312
kmsan_handle_dma(struct page * page,size_t offset,size_t size,enum dma_data_direction dir)313 static inline void kmsan_handle_dma(struct page *page, size_t offset,
314 size_t size, enum dma_data_direction dir)
315 {
316 }
317
kmsan_handle_dma_sg(struct scatterlist * sg,int nents,enum dma_data_direction dir)318 static inline void kmsan_handle_dma_sg(struct scatterlist *sg, int nents,
319 enum dma_data_direction dir)
320 {
321 }
322
kmsan_handle_urb(const struct urb * urb,bool is_out)323 static inline void kmsan_handle_urb(const struct urb *urb, bool is_out)
324 {
325 }
326
kmsan_unpoison_entry_regs(const struct pt_regs * regs)327 static inline void kmsan_unpoison_entry_regs(const struct pt_regs *regs)
328 {
329 }
330
331 #endif
332
333 #endif /* _LINUX_KMSAN_H */
334