1//===-- mem_map_base.h ------------------------------------------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8
9#ifndef SCUDO_MEM_MAP_BASE_H_
10#define SCUDO_MEM_MAP_BASE_H_
11
12#include "common.h"
13
14namespace scudo {
15
16// In Scudo, every memory operation will be fulfilled through a
17// platform-specific `MemMap` instance. The essential APIs are listed in the
18// `MemMapBase` below. This is implemented in CRTP, so for each implementation,
19// it has to implement all of the 'Impl' named functions.
20template <class Derived> class MemMapBase {
21public:
22 constexpr MemMapBase() = default;
23
24 // This is used to map a new set of contiguous pages. Note that the `Addr` is
25 // only a suggestion to the system.
26 bool map(uptr Addr, uptr Size, const char *Name, uptr Flags = 0) {
27 DCHECK(!isAllocated());
28 return invokeImpl(&Derived::mapImpl, Addr, Size, Name, Flags);
29 }
30
31 // This is used to unmap partial/full pages from the beginning or the end.
32 // I.e., the result pages are expected to be still contiguous.
33 void unmap(uptr Addr, uptr Size) {
34 DCHECK(isAllocated());
35 DCHECK((Addr == getBase()) || (Addr + Size == getBase() + getCapacity()));
36 invokeImpl(&Derived::unmapImpl, Addr, Size);
37 }
38 // A default implementation to unmap all pages.
39 void unmap() { unmap(getBase(), getCapacity()); }
40
41 // This is used to remap a mapped range (either from map() or dispatched from
42 // ReservedMemory). For example, we have reserved several pages and then we
43 // want to remap them with different accessibility.
44 bool remap(uptr Addr, uptr Size, const char *Name, uptr Flags = 0) {
45 DCHECK(isAllocated());
46 DCHECK((Addr >= getBase()) && (Addr + Size <= getBase() + getCapacity()));
47 return invokeImpl(&Derived::remapImpl, Addr, Size, Name, Flags);
48 }
49
50 // This is used to update the pages' access permission. For example, mark
51 // pages as no read/write permission.
52 void setMemoryPermission(uptr Addr, uptr Size, uptr Flags) {
53 DCHECK(isAllocated());
54 DCHECK((Addr >= getBase()) && (Addr + Size <= getBase() + getCapacity()));
55 return invokeImpl(&Derived::setMemoryPermissionImpl, Addr, Size, Flags);
56 }
57
58 // Suggest releasing a set of contiguous physical pages back to the OS. Note
59 // that only physical pages are supposed to be released. Any release of
60 // virtual pages may lead to undefined behavior.
61 void releasePagesToOS(uptr From, uptr Size) {
62 DCHECK(isAllocated());
63 DCHECK((From >= getBase()) && (From + Size <= getBase() + getCapacity()));
64 invokeImpl(&Derived::releasePagesToOSImpl, From, Size);
65 }
66 // This is similar to the above one except that any subsequent access to the
67 // released pages will return with zero-filled pages.
68 void releaseAndZeroPagesToOS(uptr From, uptr Size) {
69 DCHECK(isAllocated());
70 DCHECK((From >= getBase()) && (From + Size <= getBase() + getCapacity()));
71 invokeImpl(&Derived::releaseAndZeroPagesToOSImpl, From, Size);
72 }
73
74 // Get the total number of resident pages for From to From + Size.
75 // This function can run slowly, and is only expected to be called
76 // from getStats functions where performance does not matter. From represents
77 // the absolute address of the start of a memory region, not a relative offset
78 // from getBase().
79 s64 getResidentPages(uptr From, uptr Size) {
80 if (!isAllocated()) {
81 return 0;
82 }
83 DCHECK((From >= getBase()) && (From + Size <= getBase() + getCapacity()));
84 return invokeImpl(&Derived::getResidentPagesImpl, From, Size);
85 }
86
87 s64 getResidentPages() { return getResidentPages(getBase(), getCapacity()); }
88
89 uptr getBase() { return invokeImpl(&Derived::getBaseImpl); }
90 uptr getCapacity() { return invokeImpl(&Derived::getCapacityImpl); }
91
92 bool isAllocated() { return getBase() != 0U; }
93
94protected:
95 template <typename R, typename... Args>
96 R invokeImpl(R (Derived::*MemFn)(Args...), Args... args) {
97 return (static_cast<Derived *>(this)->*MemFn)(args...);
98 }
99};
100
101// `ReservedMemory` is a special memory handle which can be viewed as a page
102// allocator. `ReservedMemory` will reserve a contiguous pages and the later
103// page request can be fulfilled at the designated address. This is used when
104// we want to ensure the virtual address of the MemMap will be in a known range.
105// This is implemented in CRTP, so for each
106// implementation, it has to implement all of the 'Impl' named functions.
107template <class Derived, typename MemMapTy> class ReservedMemory {
108public:
109 using MemMapT = MemMapTy;
110 constexpr ReservedMemory() = default;
111
112 // Reserve a chunk of memory at a suggested address.
113 bool create(uptr Addr, uptr Size, const char *Name, uptr Flags = 0) {
114 DCHECK(!isCreated());
115 return invokeImpl(&Derived::createImpl, Addr, Size, Name, Flags);
116 }
117
118 // Release the entire reserved memory.
119 void release() {
120 DCHECK(isCreated());
121 invokeImpl(&Derived::releaseImpl);
122 }
123
124 // Dispatch a sub-range of reserved memory. Note that any fragmentation of
125 // the reserved pages is managed by each implementation.
126 MemMapT dispatch(uptr Addr, uptr Size) {
127 DCHECK(isCreated());
128 DCHECK((Addr >= getBase()) && (Addr + Size <= getBase() + getCapacity()));
129 return invokeImpl(&Derived::dispatchImpl, Addr, Size);
130 }
131
132 uptr getBase() { return invokeImpl(&Derived::getBaseImpl); }
133 uptr getCapacity() { return invokeImpl(&Derived::getCapacityImpl); }
134
135 bool isCreated() { return getBase() != 0U; }
136
137protected:
138 template <typename R, typename... Args>
139 R invokeImpl(R (Derived::*MemFn)(Args...), Args... args) {
140 return (static_cast<Derived *>(this)->*MemFn)(args...);
141 }
142};
143
144} // namespace scudo
145
146#endif // SCUDO_MEM_MAP_BASE_H_
147