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 <[email protected]> 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. 138 */ 139 void kmsan_vmap_pages_range_noflush(unsigned long start, unsigned long end, 140 pgprot_t prot, struct page **pages, 141 unsigned int page_shift); 142 143 /** 144 * kmsan_vunmap_kernel_range_noflush() - Notify KMSAN about a vunmap. 145 * @start: start of vunmapped range. 146 * @end: end of vunmapped range. 147 * 148 * KMSAN unmaps the contiguous metadata ranges created by 149 * kmsan_map_kernel_range_noflush(). 150 */ 151 void kmsan_vunmap_range_noflush(unsigned long start, unsigned long end); 152 153 /** 154 * kmsan_ioremap_page_range() - Notify KMSAN about a ioremap_page_range() call. 155 * @addr: range start. 156 * @end: range end. 157 * @phys_addr: physical range start. 158 * @prot: page protection flags used for ioremap_page_range(). 159 * @page_shift: page_shift argument passed to vmap_range_noflush(). 160 * 161 * KMSAN creates new metadata pages for the physical pages mapped into the 162 * virtual memory. 163 */ 164 void kmsan_ioremap_page_range(unsigned long addr, unsigned long end, 165 phys_addr_t phys_addr, pgprot_t prot, 166 unsigned int page_shift); 167 168 /** 169 * kmsan_iounmap_page_range() - Notify KMSAN about a iounmap_page_range() call. 170 * @start: range start. 171 * @end: range end. 172 * 173 * KMSAN unmaps the metadata pages for the given range and, unlike for 174 * vunmap_page_range(), also deallocates them. 175 */ 176 void kmsan_iounmap_page_range(unsigned long start, unsigned long end); 177 178 /** 179 * kmsan_handle_dma() - Handle a DMA data transfer. 180 * @page: first page of the buffer. 181 * @offset: offset of the buffer within the first page. 182 * @size: buffer size. 183 * @dir: one of possible dma_data_direction values. 184 * 185 * Depending on @direction, KMSAN: 186 * * checks the buffer, if it is copied to device; 187 * * initializes the buffer, if it is copied from device; 188 * * does both, if this is a DMA_BIDIRECTIONAL transfer. 189 */ 190 void kmsan_handle_dma(struct page *page, size_t offset, size_t size, 191 enum dma_data_direction dir); 192 193 /** 194 * kmsan_handle_dma_sg() - Handle a DMA transfer using scatterlist. 195 * @sg: scatterlist holding DMA buffers. 196 * @nents: number of scatterlist entries. 197 * @dir: one of possible dma_data_direction values. 198 * 199 * Depending on @direction, KMSAN: 200 * * checks the buffers in the scatterlist, if they are copied to device; 201 * * initializes the buffers, if they are copied from device; 202 * * does both, if this is a DMA_BIDIRECTIONAL transfer. 203 */ 204 void kmsan_handle_dma_sg(struct scatterlist *sg, int nents, 205 enum dma_data_direction dir); 206 207 /** 208 * kmsan_handle_urb() - Handle a USB data transfer. 209 * @urb: struct urb pointer. 210 * @is_out: data transfer direction (true means output to hardware). 211 * 212 * If @is_out is true, KMSAN checks the transfer buffer of @urb. Otherwise, 213 * KMSAN initializes the transfer buffer. 214 */ 215 void kmsan_handle_urb(const struct urb *urb, bool is_out); 216 217 /** 218 * kmsan_unpoison_entry_regs() - Handle pt_regs in low-level entry code. 219 * @regs: struct pt_regs pointer received from assembly code. 220 * 221 * KMSAN unpoisons the contents of the passed pt_regs, preventing potential 222 * false positive reports. Unlike kmsan_unpoison_memory(), 223 * kmsan_unpoison_entry_regs() can be called from the regions where 224 * kmsan_in_runtime() returns true, which is the case in early entry code. 225 */ 226 void kmsan_unpoison_entry_regs(const struct pt_regs *regs); 227 228 #else 229 230 static inline void kmsan_init_shadow(void) 231 { 232 } 233 234 static inline void kmsan_init_runtime(void) 235 { 236 } 237 238 static inline bool kmsan_memblock_free_pages(struct page *page, 239 unsigned int order) 240 { 241 return true; 242 } 243 244 static inline void kmsan_task_create(struct task_struct *task) 245 { 246 } 247 248 static inline void kmsan_task_exit(struct task_struct *task) 249 { 250 } 251 252 static inline int kmsan_alloc_page(struct page *page, unsigned int order, 253 gfp_t flags) 254 { 255 return 0; 256 } 257 258 static inline void kmsan_free_page(struct page *page, unsigned int order) 259 { 260 } 261 262 static inline void kmsan_copy_page_meta(struct page *dst, struct page *src) 263 { 264 } 265 266 static inline void kmsan_slab_alloc(struct kmem_cache *s, void *object, 267 gfp_t flags) 268 { 269 } 270 271 static inline void kmsan_slab_free(struct kmem_cache *s, void *object) 272 { 273 } 274 275 static inline void kmsan_kmalloc_large(const void *ptr, size_t size, 276 gfp_t flags) 277 { 278 } 279 280 static inline void kmsan_kfree_large(const void *ptr) 281 { 282 } 283 284 static inline void kmsan_vmap_pages_range_noflush(unsigned long start, 285 unsigned long end, 286 pgprot_t prot, 287 struct page **pages, 288 unsigned int page_shift) 289 { 290 } 291 292 static inline void kmsan_vunmap_range_noflush(unsigned long start, 293 unsigned long end) 294 { 295 } 296 297 static inline void kmsan_ioremap_page_range(unsigned long start, 298 unsigned long end, 299 phys_addr_t phys_addr, 300 pgprot_t prot, 301 unsigned int page_shift) 302 { 303 } 304 305 static inline void kmsan_iounmap_page_range(unsigned long start, 306 unsigned long end) 307 { 308 } 309 310 static inline void kmsan_handle_dma(struct page *page, size_t offset, 311 size_t size, enum dma_data_direction dir) 312 { 313 } 314 315 static inline void kmsan_handle_dma_sg(struct scatterlist *sg, int nents, 316 enum dma_data_direction dir) 317 { 318 } 319 320 static inline void kmsan_handle_urb(const struct urb *urb, bool is_out) 321 { 322 } 323 324 static inline void kmsan_unpoison_entry_regs(const struct pt_regs *regs) 325 { 326 } 327 328 #endif 329 330 #endif /* _LINUX_KMSAN_H */ 331