1 //===- llvm/Support/Memory.h - Memory Support -------------------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
9 // This file declares the llvm::sys::Memory class.
11 //===----------------------------------------------------------------------===//
13 #ifndef LLVM_SUPPORT_MEMORY_H
14 #define LLVM_SUPPORT_MEMORY_H
16 #include "llvm/Support/DataTypes.h"
18 #include <system_error>
22 // Forward declare raw_ostream: it is used for debug dumping below.
27 /// This class encapsulates the notion of a memory block which has an address
28 /// and a size. It is used by the Memory class (a friend) as the result of
29 /// various memory allocation operations.
31 /// Memory block abstraction.
34 MemoryBlock() : Address(nullptr), AllocatedSize(0) {}
35 MemoryBlock(void *addr, size_t allocatedSize)
36 : Address(addr), AllocatedSize(allocatedSize) {}
37 void *base() const { return Address; }
38 /// The size as it was allocated. This is always greater or equal to the
39 /// size that was originally requested.
40 size_t allocatedSize() const { return AllocatedSize; }
43 void *Address; ///< Address of first byte of memory area
44 size_t AllocatedSize; ///< Size, in bytes of the memory area
49 /// This class provides various memory handling functions that manipulate
50 /// MemoryBlock instances.
52 /// An abstraction for memory operations.
55 enum ProtectionFlags {
59 MF_RWE_MASK = 0x7000000,
61 /// The \p MF_HUGE_HINT flag is used to indicate that the request for
62 /// a memory block should be satisfied with large pages if possible.
63 /// This is only a hint and small pages will be used as fallback.
65 /// The presence or absence of this flag in the returned memory block
66 /// is (at least currently) *not* a reliable indicator that the memory
67 /// block will use or will not use large pages. On some systems a request
68 /// without this flag can be backed by large pages without this flag being
69 /// set, and on some other systems a request with this flag can fallback
70 /// to small pages without this flag being cleared.
71 MF_HUGE_HINT = 0x0000001
74 /// This method allocates a block of memory that is suitable for loading
75 /// dynamically generated code (e.g. JIT). An attempt to allocate
76 /// \p NumBytes bytes of virtual memory is made.
77 /// \p NearBlock may point to an existing allocation in which case
78 /// an attempt is made to allocate more memory near the existing block.
79 /// The actual allocated address is not guaranteed to be near the requested
81 /// \p Flags is used to set the initial protection flags for the block
83 /// \p EC [out] returns an object describing any error that occurs.
85 /// This method may allocate more than the number of bytes requested. The
86 /// actual number of bytes allocated is indicated in the returned
89 /// The start of the allocated block must be aligned with the
90 /// system allocation granularity (64K on Windows, page size on Linux).
91 /// If the address following \p NearBlock is not so aligned, it will be
92 /// rounded up to the next allocation granularity boundary.
94 /// \r a non-null MemoryBlock if the function was successful,
95 /// otherwise a null MemoryBlock is with \p EC describing the error.
97 /// Allocate mapped memory.
98 static MemoryBlock allocateMappedMemory(size_t NumBytes,
99 const MemoryBlock *const NearBlock,
101 std::error_code &EC);
103 /// This method releases a block of memory that was allocated with the
104 /// allocateMappedMemory method. It should not be used to release any
105 /// memory block allocated any other way.
106 /// \p Block describes the memory to be released.
108 /// \r error_success if the function was successful, or an error_code
109 /// describing the failure if an error occurred.
111 /// Release mapped memory.
112 static std::error_code releaseMappedMemory(MemoryBlock &Block);
114 /// This method sets the protection flags for a block of memory to the
115 /// state specified by /p Flags. The behavior is not specified if the
116 /// memory was not allocated using the allocateMappedMemory method.
117 /// \p Block describes the memory block to be protected.
118 /// \p Flags specifies the new protection state to be assigned to the block.
119 /// \p ErrMsg [out] returns a string describing any error that occurred.
121 /// If \p Flags is MF_WRITE, the actual behavior varies
122 /// with the operating system (i.e. MF_READ | MF_WRITE on Windows) and the
123 /// target architecture (i.e. MF_WRITE -> MF_READ | MF_WRITE on i386).
125 /// \r error_success if the function was successful, or an error_code
126 /// describing the failure if an error occurred.
128 /// Set memory protection state.
129 static std::error_code protectMappedMemory(const MemoryBlock &Block,
132 /// InvalidateInstructionCache - Before the JIT can run a block of code
133 /// that has been emitted it must invalidate the instruction cache on some
135 static void InvalidateInstructionCache(const void *Addr, size_t Len);
138 /// Owning version of MemoryBlock.
139 class OwningMemoryBlock {
141 OwningMemoryBlock() = default;
142 explicit OwningMemoryBlock(MemoryBlock M) : M(M) {}
143 OwningMemoryBlock(OwningMemoryBlock &&Other) {
145 Other.M = MemoryBlock();
147 OwningMemoryBlock& operator=(OwningMemoryBlock &&Other) {
149 Other.M = MemoryBlock();
152 ~OwningMemoryBlock() {
153 Memory::releaseMappedMemory(M);
155 void *base() const { return M.base(); }
156 /// The size as it was allocated. This is always greater or equal to the
157 /// size that was originally requested.
158 size_t allocatedSize() const { return M.allocatedSize(); }
159 MemoryBlock getMemoryBlock() const { return M; }
165 /// Debugging output for Memory::ProtectionFlags.
166 raw_ostream &operator<<(raw_ostream &OS, const Memory::ProtectionFlags &PF);
168 /// Debugging output for MemoryBlock.
169 raw_ostream &operator<<(raw_ostream &OS, const MemoryBlock &MB);
170 #endif // ifndef NDEBUG
171 } // end namespace sys
172 } // end namespace llvm