include/linux/kmsan.h

   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.
 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 */