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