1 | /* |
2 | * Copyright (c) 2022 Apple Computer, Inc. All rights reserved. |
3 | * |
4 | * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ |
5 | * |
6 | * This file contains Original Code and/or Modifications of Original Code |
7 | * as defined in and that are subject to the Apple Public Source License |
8 | * Version 2.0 (the 'License'). You may not use this file except in |
9 | * compliance with the License. The rights granted to you under the License |
10 | * may not be used to create, or enable the creation or redistribution of, |
11 | * unlawful or unlicensed copies of an Apple operating system, or to |
12 | * circumvent, violate, or enable the circumvention or violation of, any |
13 | * terms of an Apple operating system software license agreement. |
14 | * |
15 | * Please obtain a copy of the License at |
16 | * http://www.opensource.apple.com/apsl/ and read it before using this file. |
17 | * |
18 | * The Original Code and all software distributed under the License are |
19 | * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER |
20 | * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, |
21 | * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, |
22 | * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. |
23 | * Please see the License for the specific language governing rights and |
24 | * limitations under the License. |
25 | * |
26 | * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ |
27 | */ |
28 | #ifndef _MACH_VM_MEMTAG_H_ |
29 | #define _MACH_VM_MEMTAG_H_ |
30 | |
31 | #ifdef KERNEL |
32 | |
33 | #include <mach/vm_types.h> |
34 | |
35 | #if CONFIG_KERNEL_TAGGING |
36 | |
37 | /* Zero-out a tagged memory region. */ |
38 | extern void vm_memtag_bzero(void *tagged_buf, vm_size_t n); |
39 | |
40 | /* Retrieve the tag metadata associated to the target memory address */ |
41 | extern uint8_t vm_memtag_get_tag(vm_offset_t address); |
42 | |
43 | /* |
44 | * Given a naked address, extract the metadata from memory and add it to |
45 | * the correct pointer metadata. |
46 | */ |
47 | extern vm_offset_t vm_memtag_fixup_ptr(vm_offset_t naked_address); |
48 | |
49 | /* |
50 | * Given a tagged pointer and a size, update the associated backing metadata |
51 | * to match the pointer metadata. |
52 | */ |
53 | extern void |
54 | vm_memtag_set_tag(vm_offset_t tagged_address, vm_offset_t size); |
55 | |
56 | /* |
57 | * Randomly assign a tag to the current chunk of memory. Memory metadata is |
58 | * not updated yet and must be committed through a call to vm_memtag_set_tag(). |
59 | * This helper will implement a basic randomization algorithm that picks a |
60 | * random valid value for the tagging mechanism excluding the current and |
61 | * left/right adjacent metadata value. This approach is fault-conservative and |
62 | * only checks the adjacent memory locations if they fit within the same page. |
63 | */ |
64 | extern vm_offset_t |
65 | vm_memtag_assign_tag(vm_offset_t address, vm_size_t size); |
66 | |
67 | /* |
68 | * When passed a tagged pointer, verify that the pointer metadata matches |
69 | * the backing storage metadata. |
70 | */ |
71 | extern void |
72 | vm_memtag_verify_tag(vm_offset_t tagged_address); |
73 | |
74 | /* |
75 | * Temporarily enable/disable memtag checking. |
76 | */ |
77 | extern void |
78 | vm_memtag_enable_checking(void); |
79 | extern void |
80 | vm_memtag_disable_checking(void); |
81 | |
82 | /* |
83 | * Helper functions to manipulate tagged pointers. If more implementors of |
84 | * the vm_memtag interface beyond KASAN-TBI were to come, then these definitions |
85 | * should be ifdef guarded properly. |
86 | */ |
87 | #define VM_MEMTAG_PTR_SIZE 56 |
88 | #define VM_MEMTAG_TAG_SIZE 4 |
89 | #define VM_MEMTAG_UPPER_SIZE 4 |
90 | |
91 | union vm_memtag_ptr { |
92 | long value; |
93 | |
94 | struct { |
95 | long ptr_bits: VM_MEMTAG_PTR_SIZE; |
96 | uint8_t ptr_tag: VM_MEMTAG_TAG_SIZE; |
97 | long ptr_upper: VM_MEMTAG_UPPER_SIZE; |
98 | }; |
99 | }; |
100 | |
101 | static inline vm_offset_t |
102 | vm_memtag_add_ptr_tag(vm_offset_t naked_ptr, uint8_t tag) |
103 | { |
104 | union vm_memtag_ptr p = { |
105 | .value = (long)naked_ptr, |
106 | }; |
107 | |
108 | p.ptr_tag = tag; |
109 | return (vm_offset_t)p.value; |
110 | } |
111 | |
112 | static inline uint8_t |
113 | vm_memtag_extract_tag(vm_offset_t tagged_ptr) |
114 | { |
115 | union vm_memtag_ptr p = { |
116 | .value = (long)tagged_ptr, |
117 | }; |
118 | |
119 | return p.ptr_tag; |
120 | } |
121 | |
122 | /* |
123 | * when passed a tagged pointer, strip away the tag bits and return the |
124 | * canonical address. Since it's used in a number of frequently called checks |
125 | * (e.g. when packing VM pointers), the following definition hardcodes the |
126 | * tag value to achieve optimal codegen and no external calls. |
127 | */ |
128 | #define vm_memtag_canonicalize_address(addr) vm_memtag_add_ptr_tag(addr, 0xF) |
129 | #define vm_memtag_canonicalize_user_address(addr) vm_memtag_add_ptr_tag(addr, 0x0) |
130 | |
131 | #else /* CONFIG_KERNEL_TAGGING */ |
132 | |
133 | #define vm_memtag_bzero(p, s) bzero(p, s) |
134 | #define vm_memtag_get_tag(a) (0xF) |
135 | #define vm_memtag_fixup_ptr(a) (a) |
136 | #define vm_memtag_set_tag(a, s) do { } while (0) |
137 | #define vm_memtag_assign_tag(a, s) (a) |
138 | #define vm_memtag_add_ptr_tag(p, t) (p) |
139 | #define (p) (0xF) |
140 | #define vm_memtag_canonicalize_address(a) (a) |
141 | #define vm_memtag_enable_checking() do { } while (0) |
142 | #define vm_memtag_disable_checking() do { } while (0) |
143 | |
144 | |
145 | #endif /* CONFIG_KERNEL_TAGGING */ |
146 | |
147 | #endif /* KERNEL */ |
148 | |
149 | #endif /* _MACH_VM_MEMTAG_H_ */ |
150 | |